Makef22: An ADCIRC Model Fort.22 Input File Creation Tool for Surface Wind and Pressure Forcing

Transcription

1 Naval Research Laboratory Stennis Space Center, MS NRL/MR/ Makef22: An ADCIRC Model Fort.22 Input File Creation Tool for Surface Wind and Pressure Forcing Cheryl Ann Blain Ocean Dynamics and Prediction Branch Oceanography Division Robert S. Linzell Planning Systems Incorporated Stennis Space Center, Mississippi Brett Estrade Center for Computation and Technology Louisiana State University Baton Rouge, Louisiana December 7, 2007 Approved for public release; distribution is unlimited.

2 Form Approved REPORT DOCUMENTATION PAGE OMB No Public reporting burden for this collection of information is estimated to average 1 hour per response, including the time for reviewing instructions, searching existing data sources, gathering and maintaining the data needed, and completing and reviewing this collection of information. Send comments regarding this burden estimate or any other aspect of this collection of information, including suggestions for reducing this burden to Department of Defense, Washington Headquarters Services, Directorate for Information Operations and Reports ( ), 1215 Jefferson Davis Highway, Suite 1204, Arlington, VA Respondents should be aware that notwithstanding any other provision of law, no person shall be subject to any penalty for failing to comply with a collection of information if it does not display a currently valid OMB control number. PLEASE DO NOT RETURN YOUR FORM TO THE ABOVE ADDRESS. 1. REPORT DATE (DD-MM-YYYY) 2. REPORT TYPE 3. DATES COVERED (From - To) Memorandum Report 4. TITLE AND SUBTITLE 5a. CONTRACT NUMBER Makef22: An ADCIRC Model Fort.22 Input File Creation Tool for Surface Wind and Pressure Forcing 6. AUTHOR(S) Cheryl Ann Blain, Robert S. Linzell,* and Brett Estrade 7. PERFORMING ORGANIZATION NAME(S) AND ADDRESS(ES) Naval Research Laboratory Oceanography Division Stennis Space Center, MS b. GRANT NUMBER 5c. PROGRAM ELEMENT NUMBER N 5d. PROJECT NUMBER 5e. TASK NUMBER 5f. WORK UNIT NUMBER PERFORMING ORGANIZATION REPORT NUMBER NRL/MR/ SPONSORING / MONITORING AGENCY NAME(S) AND ADDRESS(ES) Office of Naval Research One Liberty Center 875 North Randolph Street Arlington, VA SPONSOR / MONITOR S ACRONYM(S) ONR 11. SPONSOR / MONITOR S REPORT NUMBER(S) 12. DISTRIBUTION / AVAILABILITY STATEMENT Approved for public release; distribution is unlimited. 13. SUPPLEMENTARY NOTES *Planning Systems Incorporated, MSAAP Building 9121, Stennis Space Center, MS Center for Computation and Technology, Louisiana State University, Baton Rouge, LA ABSTRACT The User s Manual for the Makef22 software tool, makef22.pl, contains descriptions of the software, including its functionality and usage. The Makef22 software is a Perl-based program that creates an ADvanced CIRCulation (ADCIRC) Model Surface Wind and Pressure Forcing file (fort.22) using the NWS = 2 option. The software was developed for ADCIRC version In addition to the creation of fort.22 files, the Makef22 utility also can read and process an existing fort.22 file in order to 1) elongate the record either by adding zero valued records at the beginning of the fort.22 file or by repeating the first time record a specified number of times, and/or 2) ramp a specified portion of the fort.22 records from zero to full-scale values. This utility was designed so that readers for new data sources can easily be developed and incorporated into the Makef22 utility. Surface wind and pressure data sources on rectangular, regular girds at known times are read and interpolated onto an ADCIRC finite element mesh (FEM) at user-specified times. The results can be stored in an ASCII text, ADCIRC model specific, fort.22 forcing file. 15. SUBJECT TERMS ADCIRC model Makef22 Wind and pressure forcing fort SECURITY CLASSIFICATION OF: a. REPORT b. ABSTRACT c. THIS PAGE Unclassified Unclassified Unclassified 17. LIMITATION OF ABSTRACT i 18. NUMBER OF PAGES UL 41 19a. NAME OF RESPONSIBLE PERSON Cheryl Ann Blain 19b. TELEPHONE NUMBER (include area code) (228) Standard Form 298 (Rev. 8-98) Prescribed by ANSI Std. Z39.18

3

4 TABLE OF CONTENTS 1. Description.. 1 a. Overview b. Methodology.. 1 c. Software Components 3 d. Software Prerequisites... 5 e. Software Installation Fort.22 Creation: Using makef22.pl... 8 a. Execution 8 b. Specifications The Data Reader 11 a. Details b. Creation of a New Reader.. 12 c. Explanation of the Fortran Source Code The NAVO GMT Wind Reader, navo_gmt.pm a. Details b. Adding New Domains to navo_gmt.pm c. Adding New Compilers and Architectures to navo_gmt.pm The NRL COAMPS and NOGAPS readers, nrl_coamps.pm and nrl_nogaps.pm.. 20 a. Details b. Adding New Domains to nrl_coamps.pm and nrl_nogaps.pm.. 23 c. Adding New Compilers and Architectures Fort.22 Processing a. Overview 26 b. Details 26 c. Input Parameters Reference APPENDIX I. ADCIRC fort.22 File Information 29 APPENDIX II. Input Parameter File Example APPENDIX III. Details of the Date Iterator 34 APPENDIX IV. Plug-in Reader Application Program Interface APPENDIX V. Domains Supported by the Data Readers 37 iii

5

6 1. Description a. Overview The makef22 utility is a Perl-based program that creates a surface wind and pressure forcing file in a format appropriate for the ADvanced CIRCulation (ADCIRC) model using the NWS = 2 option, e.g. the fort.22 file (see Appendix I for details on the fort.22 file description and format or the ADCIRC model online manual at The utility also can read and process an existing fort.22 file in order to 1) elongate the record either by adding zero valued records at the beginning of the fort.22 file or by repeating the first time record a specified number of times, and/or 2) ramp a specified portion of the fort.22 records from zero to full-scale values. This utility was designed so that readers for new data sources can easily be developed and incorporated into the makef22 utility. Surface wind and pressure data sources on rectangular, regular grids at known times are read and interpolated onto an ADCIRC finite element mesh (FEM) at user-specified times. The results can be stored in an ASCII text, ADCIRC model specific, fort.22 forcing file. The makef22.pl utility is comprised of five components: the driver (makef22.pl), the date iterator (Iterator.pm), the input parameter file reader (GetUserInput.pm), the reader (e.g., navo_gmt.pm), and the processing program (read_expand_ramp_f22_v3.f). The user executes the driver, the input parameter file reader loads the user-supplied parameters from an ASCII text file (see Appendix II for an example of this file), the date iterator is used to facilitate iteration over a specified range of dates, and the reader facilitates the reading and interpolation of the surface wind and pressure data. The processing program is a standalone program that is invoked by the driver if the user chooses the processing option. b. Methodology The reader, such as navo_gmt.pm, which is used for reading the Generic Mapping Tools (GMT) network Common Data Form (netcdf) file format used by NAVOCEANO, is a Perl script called by the driver, makef22.pl. The reader serves as a wrapper around a data reader written in Fortran 90. While the actual reading of the data is handled by the Fortran 90 code, the wrapper handles the rest of the processing details such as compiling the Fortran 90 code into an executable (done once at the start if no binary executable program is supplied - unsupported at this time), locating the requested data files, and calling the reader executable for each date/hour that is requested. The Perl wrapper also tracks the number of files read, and manages the proper formatting of the data for the fort.22 file based on what record is being written. The reader assumes one time record per file. The Fortran 90 program contained in the reader, e.g. navo_gmt.pm, to be supplied as a standalone binary executable program, reads in surface wind velocity or wind stress components and/or surface pressure for any region supported by the reader (see Appendix V for a list of currently supported atmospheric models and regions). The fields are then passed back to the makef22.pl driver. Wind stress, if computed, is accomplished using the formula of Garratt (1977). Wind stresses are in units of Pressure/Length 2 or in SI, Manuscript approved October 11,

7 N/m 2, and are divided by the reference density of water to get units of Length 2 /Time 2 (SI or metric units are determined by the units of g specified in the ADCIRC fort.15 parameter file). The surface pressure is represented by units of Pressure/Length 2 or in SI, N/m 2. The data are then interpolated onto the ADCIRC mesh contained in a user-supplied fort.14 file. Typically wind and pressure data sources are defined over rectangular regions using regularly-spaced points. The ADCIRC mesh is typically composed of irregularly shaped triangles whose vertices or nodes are also irregularly spaced. Interpolation of the wind and pressure data from a rectangular grid onto the FEM is performed using simple bilinear interpolation. Because of the need to interpolate the data onto the FEM, an existing ADCIRC fort.14 file for the region of interest is required. It is important to note that the Fortran 90 code that forms the data reader contained in navo_gmt.pm is a standalone program that can be copied into its own Fortran 90 source file and compiled using any Fortran 90 compiler. The resulting executable can be used by itself, but the user must provide the required input. A recently added option allows the user to specify an existing, standalone, binary executable program that the reader invokes in place of the reader-contained Fortran 90 source code. This provides a means by which the user can avoid having to modify the Perl source code to add compiler parameters, or determine the correct compiler parameters when invoking the makef22.pl utility. This option also avoids program compilation every time the utility is executed, which occurs if no binary executable is supplied. This option is presently the only supported and recommended mode of operation for the data reader software. Another recently added option allows the user to employ the binary executable processing program, read_expand_ramp_f22_v3, to process an existing fort.22 file. There may be instances where the user wishes to have the non-zero wind and pressure forcing start at a time later than at the start of an ADCIRC model simulation. For example, a long ramp-up period may be necessary for the application of tidal forcing but wind and pressure forcing may not available during the entire ramping phase. In such cases, the wind and atmospheric pressure fields could be initially set to zero or some background value, or the first available wind and pressure record could be repeated for a specified length of time during model spin-up period. This type of accommodation is often necessary when applying wind and pressure forcing within the ADCIRC model (NWS not equal to 0), since the ADCIRC model expects wind and pressure forcing to extend from the start to the end of a simulation. In the above scenario, where non-zero wind and pressure forcing fields are applied after the ramp duration (DRAMP) that occurs internal to the ADCIRC code, the initial meteorological forcing values would also need to be gradually increased to full scale (i.e., ramped ) to avoid the generation of numerical artifacts but must be ramped external to the ADCIRC code; this external ramping is handled by the supplied processing program. Figure 1 is a conceptual sketch illustrating the application of features available in the processing program, read_expand_ramp_f22_v

8 Figure 1. Sketch depicting the extension of meteorological data through the use of zeropadding, repetition of the first data record and then ramping of the extended data records, all accomplished via the read_expand_ramp_f22_v3 utility. In the above figure, the green line represents an idealized time series of a meteorological forcing data value, such as atmospheric pressure. At time T1 (time step N=1), which would correspond to the start time of the model run, the data values are set to zero, zeropadding (or a background value, such as 10 m for atmospheric pressure). This initial value is maintained up to time T2 (time step N=i). From time T2 to T3 (N=j), the first non-zero data value is copied, and a ramp function is applied. Over this time interval, the data gradually increases to full value at the end of the ramp period, T3. In this example, the original fort.22 data values extend from the time step following T3 (N=j+1) to the end of the time series. Thus the original data set has been extended by the sum of the zero-padded interval (T1 to T2, i time steps) and the ramped interval (T2 to T3, j-i time steps). During an ADCIRC model run, the ramp period for the forcing of interest would correspond to the time interval T1 to T3 (j time steps). The time steps in this example refer to the data interval of the original meteorological data, e.g., three hours. The fort.22 files contain no time information but require a constant data interval for the entire record. Hence, input to the processing program, is provided as numbers of time steps instead of hours or some other time increment. c. Components The makef22 utility that creates the fort.22 file is actually composed of eight primary modular parts as depicted in Figure 2: 1. Iterator.pm - a date-iterating Perl module that cycles over a user-specified date range 2. GetUserInput.pm a Perl module that reads the user-supplied input parameter file, makef22.pl.in 3. makef22.pl - the main driver that the user executes 4. navo_gmt.pm - a makef22.pl-compatible data reader specifically designed to read - 3 -

9 NAVO GMT netcdf files. All readers are specified by the reader option of makef22.pl.in 5. nrl_coamps.pm a makef22.pl-compatible data reader specifically designed to read NRL binary COAMPS files. 6. nrl_nogaps.pm a makef22.pl-compatible data reader specifically designed to read NRL binary NOGAPS files. 7. nrl_bin2xyz a standalone data reformatting tool that converts NRL binary COAMPS or NOGAPS output files to ASCII text format. 8. read_expand_ramp_f22_v3 the data processing program for extending and ramping, an existing fort.22 data file. Figure 2. A schematic flow chart depicting the data flow and relationship between the software components comprising the Makef22 tool. If the creation of a new fort.22 file from user-supplied meteorological data is desired, the option to process an existing fort.22 file is disabled (see Table 1). Using the date iterator (Iterator.pm), the main driver (makef22.pl) iterates over a date range specified by userdefined starting and ending dates or a user-defined date range and hourly time increment. The date format is YYYYMMDDHH where YYYY indicates the year, MM the two-digit month, DD the two-digit day, and HH the two-digit hour using a hour range. These input parameters are supplied in the ASCII text file, makef22.pl.in (see Table 1 and Appendix II), which are read at the program startup by the input file reader, GetUserInput.pm. Implementation of the date iterator is hidden from the user except for the initial specification of a date range and increment as indicated above. For each - 4 -

10 date/hour in the range, the reader is called via a standard interface (see Appendix IV). The reader is responsible for returning the data for the requested date/hour in the proper fort.22 format (see Appendix I). If the processing mode is specified, data processing is enabled (see Table 1) and an existing fort.22 file required (see 6). The main driver acquires the user inputs from the makef22.pl.in input parameter file via the input file reader. The data processing program (read_expand_ramp_f22_v3) is invoked to perform the extension and/or ramping of the original data found in the supplied fort.22 file. A new file, named fort.221, is created during processing and is the final result of the fort.22 processing. This file should be renamed to fort.22, after moving or renaming the original fort.22 file, prior to execution by the ADCIRC model code. The user can create more than one processed output file corresponding to different combinations of zero-padded or record repetition extension and ramping, bearing in mind that the output file (fort.221) should be moved or renamed after each execution of the makef22.pl driver. If several processing runs are planned, separate copies of the input parameter file (makef22.pl.in) should be created containing the various processing parameters. Then, for each execution of the driver, the parameter file of interest could be symbolically linked to makef22.pl.in to speed up or automate processing with a shell script. An example below demonstrates this approach: # ls *.in [A listing of three input files to be used for 3 different executions of makef22.] test1.in test2.in test3.in # ln fs test1.in makef22.pl.in [Create symbolic link from test1.in to makef22.pl.in.] # makef22.pl [First execution of makef22.pl using test1.in input.] # ln fs test2.in makef22.pl.in [Create symbolic link from test2.in to makef22.pl.in.] # makef22.pl [Second execution of makef22.pl using test2.in input.] # ln fs test3.in makef22.pl.in [Create symbolic link from test3.in to makef22.pl.in.] # makef22.pl [Third execution of makef22.pl using test3.in input.] d. Software Prerequisites Perl must be installed on the platform on which the Makef22 software will be installed. On Windows-based systems, the latest version of Perl from ActiveState Software Inc. ( is recommended. The Generic Mapping Tools (GMT) freeware package (gmt.soest.hawaii.edu) and the network Common Data Form (netcdf) software ( must be installed for the Fortran programs to correctly operate. An existing ADCIRC Grid and Boundary Information File (fort.14) must also be present in the current working directory

11 An external, standalone, pre-compiled Fortran data reader, such as gmt2f22_navo_gmt, must be present and applicable to data reformatting and interpolation of the desired meteorological data source. Additionally, the NRL Navy Operational Global Atmospheric Prediction System (NOGAPS) and Coupled Ocean/Atmosphere Mesoscale Prediction System (COAMPS ) pre-compiled binary file reformatting program, nrl_bin2xyz, must be present to process those data types. Although the software is platform-independent, the standalone Fortran programs must be compiled for each platform on which they are installed. e. Software Installation The makef22.pl utility is located in the ADCIRC_Utilities repository in the Makef22 directory. The directory has the following contents: CONTENTS (directory) Documentation/ CONTENTS ADCIRC_MANUAL_MakeF22_FINAL_ doc README README_Ramping GetUserInput.pm Iterator.pm Makefile Makefile.MSRC.romulus (directory) Sample_Input_Files/ CONTENTS MASTER_makef22.pl.in makef22.pl.in makef22_generate.pl.in makef22_ramping.pl.in fort22_reformat.awk makef22.pl read_expand_ramp_f22_v3.f (directory) readers/ CONTENTS Makefile Makefile.nrl_bin2xyz cmplrflags.mk config.guess gmt2f22_navo_gmt.f gmt2f22_nrl_coamps.f gmt2f22_nrl_nogaps.f grid2gmt.csh hms2itm.f, idateadd.f, idayyr.f, idcen2idt.f, idt2idcen.f, idt2ymd.f, itm2hms.f, and ymd2idt.f (external source code files for nrl_bin2xyz.f) navo_gmt.pm nrl_coamps.pm - 6 -

12 nrl_nogaps.pm gmt2f22_navo_gmt.f gmt2f22_nrl_coamps.f gmt2f22_nrl_nogaps.f nrl_bin2xyz.f run_cmd.pl Step 1: Pre-Compilation of Fortran Programs a) The Data Reader The currently supported option is to pre-compile the supplied Fortran reader code (gmt2f22_navo_gmt.f) on the platform on which the software has been installed, a makefile has been supplied. The makefile, named Makefile, uses the GNU make program to compile the software on a variety of platforms. The accompanying shell script, config.guess, and the ASCII text compiler flag file, cmplrflags.mk, also are used by make to properly compile the software on any of several tested platforms (e.g., Linux 32-bit, Linux 64-bit, or IBM AIX). The cmplrflags.mk file also contains paths to the NetCDF library and include directories. The user should inspect this file prior to compilation to verify whether the compiler flags and netcdf paths are correct. The file can be edited with a text editor should any of the parameters require modification. To build the standalone binary executable program for the data reader, the following command is used: # make gmt2f22_navo_gmt On the IBM under AIX, the gmake program may be required, instead of make. This procedure should be performed only once after the software has been installed. The binary executable program, gmt2f22_navo_gmt, will then be used when the makef22.pl utility is invoked, so that the Fortran source code will not be compiled each time. b) The NRL Data Reformatting Tool In a similar manner, the standalone NRL binary data reformatting tool, nrl_bin2xyz.f, should be compiled using the supplied makefile using the following syntax: # make -f Makefile.nrl_bin2xyz Note that this tool is required for processing NRL meteorological binary data files, but has been tested only under Linux as of this writing. Users needing to use data types other than the NRL binary or NAVOCEANO GMT netcdf formats can contact the authors for further information. c) The Fort.22 Processing Program The fort.22 processing program, read_expand_ramp_f22_v3.f should be compiled using the supplied Makefile with the system make utility. An alternative makefile, Makefile.MSRC.romulus, also is supplied for use on IBM AIX-based systems

13 Step 2: Configuration of NRL Binary Data Readers If you wish to use the supplied readers for NRL binary COAMPS or NOGAPS data (nrl_coamps.pm or nrl_nogaps.pm, respectively), the readers must be modified to use the correct path to the GMT binary executable program, xyz2grd. These two programs are written in Perl, so they can be modified using any text editor. The lines containing the following code must be modified: $self->{_xyz2grd} = '/common/utilities/gmt3.4.2/bin/xyz2grd'; so that /common/utilities/gmt3.4.2/bin is changed to the correct path for the system on which the software is installed. In nrl_coamps.pm, this code is at line 161, and in nrl_nogaps.pm, line 158. (OPTIONAL) Step 3: An Environmental Variable for Alternative Data Readers You may set an environmental variable, F22_READER_DIR, that specifies a reader directory other than the default location in the ADCIRC_Utilities/Makef22/readers directory. This directory is where all readers could be organized if multiple custom readers are available. Alternatively, one could specify a path for the variable, readerdir, on line 5 of the makef22.pl.in file (see Appendix II). Examples for setting the environmental variable, F22_READER_DIR, in c-shell (csh) and Bourne shell (sh) are as follows: csh: setenv F22_READER_DIR /path/to/readerdir/ sh: set F22_READER_DIR= /path/to/readerdir ;export F22_READER_DIR (OPTIONAL) Step 4: An Environmental Variable for the Date Management Program If you wish to place Iterator.pm in a separate directory, move it there, and specify the new location by including it in the environmental variable called PERL5LIB. For more information regarding PERL5LIB, please consult perlfaq8 which should be accessible on any Unix-like platform with Perl 5 installed. This topic is addressed under the perlfaq8 heading How do I keep my own module/library directory? 2. Fort.22 Creation: Using makef22.pl a. Usage To execute the Makef22 utility, the Perl script makef22.pl is invoked from the command line as: # makef22.pl > fort.22 where output from the makef22.pl code is directed to the file, fort.22, a meteorological forcing file for the ADCIRC code. In the above example, makef22.pl is invoked from the command line using the input parameters specified in the makef22.pl.in file. The result is the creation of an ASCII text fort.22 file containing either NRL or NAVOCEANO meteorological data sources, which are stored in IEEE binary or GMT netcdf format, - 8 -

14 respectively. Within the makef22.pl.in file (included in Appendix II), the start date/hour of the desired wind and pressure data (e.g., ) is first specified followed by information about either the termination date of the data (e.g., ) or the length of the data record to be read. The data to be read in this example will extend for 2 days (e.g., 2d) at 6-hour increments (e.g., 6h). The 6-hour increment corresponds to a wind time increment (WTIMINC) of seconds. The ADCIRC model will read new meteorological data every WTIMINC seconds. The file name for the ADCIRC grid to be used for interpolation is specified next (e.g., fort.14). Then the directory location for the data readers is given (e.g., ~/makef22pl/readers), and the specific data reader is identified. For NAVOCEANO, the appropriate data reader is referred to as navo_gmt (e.g., navo_gmt). On the next line, one should provide the name of the pre-compiled binary file containing the data reader ( e.g., gmt2f22_navo_gmt). Next, the parameter specifications for the meteorological data are passed to the reader through the specified reader options, readeropts. The reader options include data type, (e.g. -O PW to indicate pressure and wind velocities, the alias for the spatial domain that corresponds to a domain definition in the reader (e.g., -domain CENT_AM_New), and the directory location of the meteorological data (e.g., -datadir /u/lev1/common/adcirc- TRAINING-I/NAVO_GMT_DATA). If no precompiled binary reader program is specified, the computer architecture is detected automatically (unsupported at this time), and the appropriate compiler options are extracted from inside the reader source code file (unsupported at this time). However, if a custom setting is added to the compiler database, one can name the architecture using the use the optional arch line specification (e.g., i686) to override the architecture detected by the program. The remaining parameters specified in the makef22.pl.in pertain to the ramping and/or expansion of a fort.22 file. For details on the meaning and use of these parameters, see Table 1 or 6. Note that the number of records required for a simulation is determined by the simulation length (RNDAY) and the wind time interval (WTIMINC), both of which are defined in the fort.15 settings file. For wind and/or pressure-forced ADCIRC simulations, forcing data is required for the entire length of the simulation. To determine the number of records needed, convert RNDAY to seconds (since those are the units of WTIMINC), and use the following formula: num_records = RNDAY sec /WTIMINC sec + 1 If the number is not a whole number, round up to guarantee that the simulation runs to completion. When specifying the date range and increment length, care must be exercised to ensure that enough records are created to span the entire simulation period. A general rule is to convert WTIMINC to hours, then set end to {RNDAY day }d{wtiminc hr }h and inc to {WTIMINC hr }h". Using this approach and rounding up to obtain the required num_records will ensure that a sufficient number of wind/pressure data records are processed to extend for the entire length of the run

15 b. Specifications The file actually executed by the user is the driver, makef22.pl. The input parameters for this program, contained in the input file makef22.pl.in (see Appendix II), are defined in Table 1. All details regarding the meteorological data, such as the location and naming convention of the data files, are handled by the reader software. By design, the reader is relied upon to return a properly formatted fort.22 record (see Appendix I) for the specified date/hour. No validation is done by the driver to ensure a correct data read. The driver simply sends the data returned from the reader directly to standard output. As such, the desired output must be redirected to a file using the operators > or >> (e.g., > fort.22 as shown in the makef22.pl usage example above, 3a). The data can also be redirected into another program using the Unix pipe operator,. Table 1. Input Parameters for makef22.pl (makef22.pl.in) Parameter Req Description Valid values start Y Start date YYYYMMDDHH (required format) end Y End date; an actual date can be specified or a relative period of time after the start date. The values described in the Valid Values column can be combined. For example, 2m3d4h will end 2 months, 3 days, and 4 hours after the start date. YYYYMMDDHH, or #h hours past start, #d days after start, #m months after start, #y years after start inc Y Time increment; the values described in the Valid Values column can be combined. For example, 2m3d4h will increment 2 months 3 days and 4 hours for each iteration. #h hours, #d days, #m months, #y years, reader Y Data reader name. Data reader name is the name of the reader file without the extension (.pl or.pm) readeropts Y Data reader options; options must be enclosed in quotes. readerdir N Reader directory specification; Over-rides the F22_READER_DIR environmental variable. If the environmental variable is not set, and this option is not used, the default directory searched is./readers. Depends on reader. For navo_gmt.pm details, please see 4a; for nrl_coamps.pm and nrl_nogaps.pm, refer to 5a. Any valid Unix directory path readerbin [N] OPTIONAL: Name of binary executable data reader program. gmt2f22_navo_gmt (see 1e), or any valid Unix file name (program must already exist)

16 Parameter Req Description Valid values arch [N] OPTIONAL: Computer architecture specification and associated Fortran compiler information; passed to reader as an option flag of the same name. If set, the specified value will override the auto-detected one. Architecture types as defined internally inside the reader. See 4c for specific details. This option is presently unsupported. f14 Y ADCIRC mesh onto which data is interpolated ramp Y Processing Flag; indicates whether data generation or processing is to be done. Processing is described in 6. Any valid Unix file path to a valid ADCIRC mesh file (fort.14) Zero (0) if no processing will be done (i.e., a new fort.22 file will be generated), or one (1) if processing will be done. norig [N] OPTIONAL: The number of time steps from the original fort.22 file to use. Required only if ramp=1; must be 1 or greater. Enter a large number (e.g., 999) if the number is unknown. nback ncopy nramp nstart [N] OPTIONAL: The number of background/zero-valued time steps that are pre-pended to the output file. [N] OPTIONAL: The number of copies of the first original data record (time step). [N] OPTIONAL: The number of time steps over which to apply the ramping function. [N] OPTIONAL: The time step at which to start applying the ramping function. Required only if ramp=1; 0 for no zerovalued records, or greater than 0 to create zero-valued records. Required only if ramp=1; 0 or greater. If set to 0 and nramp > 0, ramping will be applied to zero-valued records &/or original data, depending on values of nstart & nramp. Required only if ramp=1; set to 0 for no ramping (i.e., zero-valued records &/or extending only), or greater than 0 to apply ramping. Required only if ramp=1; 1 or greater; ignored if nramp=0. One example of the makef22.pl.in file is presented in Appendix II and found in the directory Sample_Input_Files (e.g.,./sample_input_files). 3. The Data Reader a. Details The data reader for the driver makef22.pl is designed so that the data source is accessed

17 and converted to the proper fort.22 format without the driver's intervention. The driver merely makes a standard function call and in return receives some data that is assumed to be in the proper format. The reader is passed a date string by the driver that specifies a particular date/hour and returns data for that date formatted appropriately for an ADCIRC fort.22 file. The makef22.pl takes this data and sends it to standard output. Again, the output must then be directed into a file or piped to another application, otherwise, the resulting data will be written to the terminal screen instead of an output file. For flexibility in accommodating a variety of as of yet unknown data formats, makef22.pl does nothing to verify that the correct data record is being returned or that it is in the correct format. The driver simply facilitates the calling of a generic reader over a specified range of dates. The reader alone is responsible for: 1. Reading the data in its native format for a specified date/hour; the date format passed to the reader can be changed by re-setting a line in makef22.pl, i.e., $CMDLINEOPTS{FORMAT} = '%Y%m%d%k'; Please see Appendix III for other date formatting options. 2. Reading the appropriate data (pressure and/or wind stress, or wind velocity) and processing if required (i.e., convert wind velocity components to wind stress) 3. Interpolating the data values to the specified ADCIRC grid 4. Formatting the data as required for an ADCIRC fort.22 file (see Appendix I) 5. Returning the formatted data for the specified date/time to the driver via standard output b. Creation of a New Reader An application programming interface (API) was created to facilitate the creation of new data readers. There are three requirements that must be followed in order for a data reader to work: 1. The plug-in must be written or contained within a valid Perl file. Note that Fortran or C code can easily be incorporated into a Perl file to facilitate the actual reading of the data files as illustrated in the reader, navo_gmt.pm. Additionally, standalone, binary executable programs can be invoked in any of several ways by Perl. 2. The Perl file must implement the following functions (detailed descriptions are contained in Appendix IV): 3. new(string readeropts) initializes the reader 4. print_info(void) prints reader information 5. get_record(datestring YYYYMMDDHH ) retrieves data record based on the date/hour timestamp 6. finalize(void) performs any final tasks before finishing 7. The reader must return the final data to the driver via standard out Since the navo_gmt.pm reader is already a working reader, it is recommended that the file navo_gmt.pm be used as a basis for creating new reader modules unless the data read procedures are dramatically different. The navo_gmt.pm reader demonstrates how a

18 reader module is to: 1. Handle initialization 2. Compile source code if needed 3. Look for data files 4. Interact with the source code executable if compiled 5. Return data to the driver c. Explanation of the Fortran Source Code The driver, makef22.pl, and the reader, e.g., navo_gmt.pm, are simply wrappers around a Fortran program that creates one fort.22 record each time it is called. Because of this, the Fortran code, which contains all of the data reads and data processing required for the fort.22 file, can be compiled and used external to makef22.pl for other applications if so desired. Should one wish to execute the Fortran program outside of the makef22.pl framework, the user must manually handle details that makef22.pl and the reader handle automatically. These details include: 1. If used, the data file for the desired date/hour containing the U-component of the wind velocity (or stress if used), must be copied to the current working directory (CWD) as a fort.31 file. 2. If used, the data file for the desired date/hour containing the V-component of the wind velocity (or stress if used), must be copied to the CWD as a fort.32 file. 3. If used, the data file for the desired date/hour containing the pressure data must be copied to the CWD as a fort.33 file. 4. An ADCIRC grid file (fort.14) containing the FE mesh that the data is to be interpolated to must be copied into the CWD. Additionally, when the Fortran program is executed, it requires nine values via standard input. The user will need to manually enter in the values at the start of the program, or enter them in an ASCII text file and use input redirection to provide the values to the program. An example of input redirection is as follows: # gmt2f22_navo_gmt < infile The input values are contained in the file named infile, each on a separate line in the order of input. These values, in order with the type of data expected, are as follows: 1. IMAX Number of time records per file; NAVO GMT netcdf files contain a single time record per file, so navo_gmt.pm assumes 1 2. Use Stress Data Instead of Wind Velocity? 1 (yes), use pre-calculated wind stress data; 0 (no) will calculate wind stress from the wind velocity data 3. What record number? Enter an integer for which record is being written; the first two records of the fort.22 file are written in a different format, and this value tells the reader which format to use

19 4. DATE in YYYYMMDD Format Date for which this data file is valid 5. HOUR in HH Format Hour of DATE for which this data file is valid. 6. Use Pressure? 1 (yes), a pressure data file is read; 0 (no) pressure values are set to Pressure File Exists? 1 (yes), this flag tells the reader the pressure file exists; 0 (no), pressure is set to 0.0 at all points. 8. U-Component (wind or stress) File Exists? 1 (yes), this flag tells the reader the u-component wind file exists; 0 (no), the u- component wind file is set to 0.0 at all points. 9. V-Component (wind or stress) File Exists? 1 (yes), this flag tells the reader the v-component wind file exists; 0 (no), the v-component wind file is set to 0.0 at all points. Because makef22.pl and the data reader pass values via standard output, the question prompts written to the screen are suppressed (i.e. commented out) in the Fortran program. It may be more helpful for the user to uncomment the question prompts requesting standard input when the program is run in standalone mode. A Makefile and two accompanying files also are provided to enable the user to create a standalone, binary executable program. Details for creating a standalone, binary executable program are provided in 1e. 4. The NAVO GMT Wind Reader, navo_gmt.pm a. Details The makef22 reader plug-in for the GMT netcdf data file format used by NAVOCEANO is called navo_gmt.pm, and is a Perl file that serves as a wrapper around a data reader written in Fortran 90. The Fortran 90 code for this reader is located at the end of the file, navo_gmt.pm, after the _DATA_ section. While the actual reading of the data is handled by the Fortran 90 code, the wrapper handles the rest of the processing details such as compiling of the Fortran 90 code (done once at the start of each execution) if a binary executable is not specified, locating the requested data files, and calling the Fortran 90 data reader executable (or user-specified binary executable) to read each date/hour of data that is requested. The Perl wrapper also tracks the number of files returned, and manages the proper formatting of the data for the fort.22. Please note that since the NAVO GMT netcdf file contains a single time step of data per file, navo_gmt.pm tracks the number of files read. It assumes that there will be a single time step of data per file, and it uses this method to determine the formatting. (See Appendix I for the format of the fort.22 file) The Fortran 90 executable is designed to read specified data files for pressure or wind, compute wind stress if wind velocity fields are used, and interpolate the resulting values to the ADCIRC mesh contained in the fort.14 file. The processed data is then printed to

20 standard output. The Perl wrapper captures this output, and redirects it to the driver, makef22.pl. In turn, the makef22.pl driver directs the data to its standard output where the user redirects the data to be written to an ADCIRC fort.22 file. It is important to note that the Fortran 90 code contained in navo_gmt.pm serves as a standalone Fortran source file, compiled using any Fortran 90 compiler, and the resulting executable can be used alone to read and process the data. The wrapper merely takes care of the tedious task of running the Fortran 90 executable for each time increment needed to complete specified the time series of data. The driver, makef22.pl, is designed to pass user-supplied options to the reader. These options are read from the makef22.pl.in file (see Table 1, 2b). Since these options can potentially change significantly from reader to reader, makef22.pl treats them as a string passed through the readeropts parameter. This string is then passed to the reader (e.g., navo_gmt.pm) when it is initialized. The reader used for NAVO's GMT wind data requires certain flags as detailed in Table 2. Note that the reader is built for the makef22 utility, thus it is not designed to be used outside of this context. Table 2. Flag Specifications for the Data Reader, navo_gmt.pm Flag Req Description Valid values -O [N] OPTIONAL: Data specification for creation of the fort.22 file P pressure data only PS pressure and pre-calculated wind stress (from a file) W wind velocity data only (wind stress will be computed using Garratt, 1977) S pre-calculated wind stress only (from a file) PW (default) pressure and wind velocity data (wind stress will be computed using Garratt, 1977) -datadir [N] OPTIONAL: Allows directory containing NAVO GMT data to be specified at run time. Any valid Unix file path. -domain Y Geographical domain name associated with data Domain values are defined within the reader. See 4b for more details. A listing of currently supported domains can be seen in Appendix V. -arch [N] OPTIONAL: Computer architecture specification and associated Fortran compiler information; passed onto reader as an option flag of the same name. If set, the specified value will override the auto-detected one. Passed in by makef22.pl Architecture types as defined internally inside the reader. See 4c for specific details. This option is currently unsupported. Passed by makef22.pl

21 Flag Req Description Valid values -f14 Y ADCIRC mesh onto which data is interpolated. Passed in by makef22.pl Any valid Unix file path to a valid ADCIRC mesh file (fort.14). Passed by makef22.pl -help/-? [N] OPTIONAL: Returns help information, then exits N/A b. Adding a New Domain to navo_gmt.pm Domain information is stored locally in the reader, navo_gmt.pm, using a record structure that facilitates the addition of new records. There are several fields required to describe the data: an identifying reference name, the physical location, file naming convention, and dimensional parameters specific to the data domain. Many of these parameters are used to create the input file name based on the date, time, domain, and parameter of interest. Information for each of the supported domains is stored in the subroutine get_domain_info, found in navo_gmt.pm. The record structure has the following form in sub get_domain_info: my %DOMAINS = ( # Record 1 DOMAIN1 => { ABBREV => "CENT_AM", COMMENT => "Gridded Central America kept at NAVO - production settings", NUMTIMEREC_DEFAULT => '1', WLATMIN => '0.0', # south WLATMAX => '32.0', # north WLONMIN => '-120.0',# west WLONMAX => '-60.0', # east DATA_ROOTS => "", SUFFIX => "COAMPS_CENT_AM-fcst_ops-cent_am_nest2_appl-", PRESSURE => "pres-msl ", U_WIND => "wnd_ucmp-ht_sfc ", U_STRESS => "wnd_strs_ucmp-surface ", V_WIND => "wnd_vcmp-ht_sfc ", V_STRESS => "wnd_strs_vcmp-surface ", TYPE => "RAW", }, # end Record 1 # Record 2 DOMAIN2 => {... },# end Record 2 # Record 3 DOMAIN3 => {... }, ); Table 3 outlines the fields defined within the domain record listed above. The NAVO GMT data files are self describing by virtue of their netcdf format thus many of the fields specified in the domain record are unnecessary and not used. Also, some domains

22 present in the Perl source code may not have all of the fields shown above. The domain record attributes are shown as an example of how to include information for data sources that do not contain self-descriptive data like the GMT netcdf files. Please note that the Fortran 90 reader is specifically designed for the GMT netcdf files, and the use of differently formatted data will require modification to the Fortran 90 reader within navo_gmt.pm or the Fortran program, gmt2f22_navo_gmt.f. The most important fields within the domain record for the navo_gmt.pm reader are ones that define the name and location of the data files. Note that all records defining a particular data domain must be contained within the %DOMAINS(... ) record structure. Table 3. Description of the Domain Records Within navo_gmt.pm Key Req Description Valid Value ABBREV Y Data domain name identical to that specified by the -domain flag in navo_gmt.pm COMMENT [N] OPTIONAL: Description of the data, not used NPTAU [N] OPTIONAL: Number of time intervals found in pressure data files, not used NWTAU [N] OPTIONAL: Number of time intervals found in wind velocity/stress data files, not used LAT [N] OPTIONAL: E-W dimension of data grid points in latitude, not used LONG [N] OPTIONAL: N-S dimension of data grid points in longitude, not used WLATMIN [N] OPTIONAL: Minimum latitude of data domain, not used WLATMAX [N] OPTIONAL: Maximum latitude of data domain, not used WLONMIN [N] OPTIONAL: Minimum longitude of data domain, not used WLONMAX [N] OPTIONAL: Maximum longitude of data domain, not used WLATINC [N] OPTIONAL: Latitudinal resolution, not used Any alphanumeric string without spaces Any string of characters Integer Integer Integer Integer Float (deg) Float (deg) Float (deg) Float (deg) Float (deg)

23 Key Req Description Valid Value WLONINC [N] OPTIONAL: Longitudinal resolution, not used Float (deg) WTIMINC [N] Time record increment, not used Integer (seconds) DATA_ROOTS Y Search directories for data files; searched in order of entry; first match will be the data source used. SUFFIX Y File naming convention; assumed common to all data file names in the domain PRESSURE Y String used to identify pressure data files U_WIND Y String used to identify U- component of wind velocity data U_STRESS Y String used to identify U- component of wind stress data V_WIND Y String used to identify V- component of wind velocity data V_STRESS Y String used to identify V- component of wind stress data TYPE [N] OPTIONAL: Identifies data format type, not used Valid file path (may be empty) Alphanumeric string, no spaces Alphanumeric string, no spaces Alphanumeric string, no spaces Alphanumeric string, no spaces Alphanumeric string, no spaces Alphanumeric string, no spaces Any alphanumeric string, no spaces c. Adding New Compilers and Architectures to navo_gmt.pm Some modifications to the data reader may be required to add compatibility for new computer architectures and their Fortran compilers. Additionally, the makefile (Makefile) and the compiler flag file, cmplrflags.mk, for the standalone binary executable program also may require modification to add compatibility with new architectures or compilers. The data reader obtains computer architecture and compiler information from a function called set_compiler_info. The purpose of this function is to obtain information on the computer architecture and Fortran compiler associated with the computer platform specification invoked by the data reader using the reader's arch parameter. The information for each entry is stored in a data structure that is easily extended. Both the standalone reader and the embedded reader have been ported successfully to two computer platforms, the IBM SP4 (romulus), and an I686-Linux machine. These architectures use the Fortran 90 compilers xlf90_r and pgf90, respectively, to compile the Fortran 90 code used to read the netcdf GMT files. The record structure in set_compiler_info has the following format:

24 @COMPILER_LIST = ( # Record 1 [{ ARCH => "", COMPILER => "", FLAGS => "", ENVARS => {ENVAR1=>'value',ENVAR2=>'value2'}, FORMAT => '%c %f %s -o %x', } ], # Record 2 [{ ARCH => "", COMPILER => "", FLAGS => "", ENVARS => {ENVAR1=>'value',ENVAR2=>'value2'}, ) } ], FORMAT => '%c %f %s -o %x', All records must be contained within ) array whose keys are described in Table 4. NOTE: Multiple architecture names may be specified under the ARCH key in a comma delimited list. This is to allow for the same settings to be reused, and is especially helpful for the automatic architecture detection since some platforms use the same settings, but the name derived from the detection routines may differ slightly. Table 4. Description of the Compiler_List Flags in navo_gmt.pm Key Req Description Valid Values ARCH Y Specifies the identifier used to name this architectural configuration. Passed to the reader using the -arch flag. COMPILER Y Specifies the compiler used to create an executable binary. Any Fortran compiler can be used as long as it has a command line interface. FLAGS Y Specifies any compile time flags, libraries, linked files, etc. Alphanumeric string without spaces. Multiple names may be listed here, but must be separated by a comma. Example: archtype1, archtype2, etc The full path of the compiler being used to compile the Fortran code located at the end of navo_gmt.pm under _DATA_. Standard flags specifying library paths (-L), include directories (-I), libraries (-l), object files/source files to link to, etc. These flags are compiler specific

25 Key Req Description Valid Values ENVARS Y For dynamic specification of environmental variables that are required at run time. For example, some compilers require an environmental flag to be set at compilation to indicate if data read/writes are big endian or little endian. FORMAT Y Specify format for the compile command. This allows most any compiler with a command line interface to be used. The most common compilers can be specified using the format: %c %f %s -o %x An anonymous hash must be specified here. Example: { ENVAR1=>'value', ENVAR2=>'value2' }, Creates environmental variables accessible to the compilation process named ENVAR1 and ENVAR2 with their respective values. %c = compiler %s = source file %f = flags %x = executable The best strategy to use when adding new compiler information is to determine how to compile the Fortran code as a standalone file, then use the insight gained on the specification of compiler options to fill in the record for the new compiler/architecture. If the standalone binary executable program is to be used, then modifications to the Perl source code described here would be optional. The modifications would then be applied to cmplrflags.mk and Makefile. For further assistance modifying these files, contact the authors. 5. The NRL COAMPS and NOGAPS Readers, nrl_coamps.pm and nrl_nogaps.pm a. Details The makef22 reader plug-ins for the IEEE binary data file format used by NRL are called nrl_coamps.pm, for data from the Coupled Ocean/Atmosphere Mesoscale Prediction System (COAMPS ), and nrl_nogaps.pm, for data from the Navy Operational Global Atmospheric Prediction System (NOGAPS). These are Perl files that serve as wrappers around a Fortran 90 data reformatting tool, nrl_bin2xyz, the GMT ASCII text-to-netcdf reformatting tool, xyz2grd, and the previously described data reader written in Fortran 90 (see 4). The Fortran 90 code for this reader is located at the end of either Perl file, after the _DATA_ section. While the actual reading of the data is handled by the Fortran 90 code, each wrapper handles the rest of the processing details such as compiling of the Fortran 90 code (done once at the start of each execution if a binary executable is not specified), locating the requested data files, and calling the Fortran 90 data re-formatter executable to reformat each data file that is requested. Each Perl wrapper also invokes