NOAA Environmental Modeling System

  NOAA Environmental Modeling System

 

The NOAA Environmental Modeling System (NEMS) is a unified community modeling system that supports multiple modeling applications. This diagram shows the main components in NEMS, including physical components such as atmosphere and ice models, mediators (couplers), and the sub-components of the atmosphere. The NEMS architecture is based on the Earth System Modeling Framework (ESMF).

Image courtesy of the Developmental Testbed Center

NEMS is a shared, portable, high performance software superstructure and infrastructure for use in operational prediction models at the National Centers for Environmental Prediction (NCEP). It is also part of the National Unified Operational Predication Capability (NUOPC) with Navy and the Air Force, and will eventually provide support to the community through the Developmental Test Center (DTC). Currently, the Global Forecast System (GFS, both the earlier spectral model and current FV3GFS) , the Global Ensemble Forecast System (GEFS), the B-grid version of the Nonhydrostatic Multiscale Model (NMM-B), and the Flow-following finite-volume Icosahedral Model (FIM) are placed together within NEMS.

NOTE : As of 2017, EMC ceased development of the Global Spectral Model (GSM) and the NMM-B model, which is used in several NCEP mesoscale modeling systems (NAM, SREF, HIRESW). NOAA has committed to a multi-year plan to use the Next Generation Global Prediction System (NGGPS) as the foundation upon which to build a Unified Forecast Syatem (UFS) for the NCEP Production Suite. The envisioned end state is a simplified production suite under this unified framework using a single dynamic core (the Finite Volume Cubed-Sphere (FV3) for all temporal and spatial model scales which is both fully coupled and ensemble-based, and built within the NEMS framework. The replacement of GSM-based GFS with the FV3 version of the FV3GFS was accomplished in June 2019. 

Past Operational Implementations of NEMS at NCEP

  • NMM-B with nests for operational NAM
  • Global Spectral Model in Global Forecast System
  • Hurricanes in a Multi-scale Ocean coupled Non-hydrostatic model (HMON)
  • NEMS GFS Aerosol Component (NGAC)
  • NMM-B Members of the Short-Range Ensemble Forecast System (SREF)
  • NMM-B members of High-Resolution Ensemble Forecast System (HREF) / HiresW
  • FV3 version of Global Forecast System with NEMS framework (June 2019)
  • FV3 version of the Global Ensemble Forecast System (September 2020)
  • Limited-area FV3 version in the High-Resolution Ensemble Forecast System (HREF, May 2021)

NEMSIO - Introduction


NEMSIO is a package created to support input/output in NEMS. The basic functions it provides are to read and write data sets for all NEMS applications. It currently can handle binary data and GRIB1 data, but in the future will also handle GRIB2 data and NetCDF data. NEMSIO has a serial version and a parallel version (using MPI-II parallel I/O).

NEMSIO files consist of meta data and data fields, with meta data preceding all data fields. Meta data has two parts, standard meta data and user-defined meta data. The standard meta data was designed to contain all information needed by the GSI and NEMS systems. For general NEMSIO files only, the first two meta data records are required, therefore the standard meta data can be minimized by only outputting the first several meta data records. The total number of standard meta data records is controlled by nmeta. Users can define their own meta data, which, if existing, are present after the standard meta data.

A printable (but not recent) version of the NEMSIO user guide can be found in the original NEMSIO Package User Guide document written by Jun Wang.
 

 



Meta Data Structure

 

First two standard meta data records:

Variable Name Kind Description
nrec integer total data fields in data part
idate integer(7) starting date contains:
yyyy/mm/dd/hh/m
m/ss(numerator)/ss(den

  NOAA Environmental Modeling System

ominator)
nfday integer forecast days
nfhour integer forecast hours
nfminute integer forecast minutes
nfsecondn integer forecast seconds (numerator)
nfsecondd integer forecast seconds (denominator)
dimx integer dimension in x-direction (not including halo)
dimy integer dimension in y-direction (not including halo)
dimz integer dimension in y-direction
nframe integer dimension of halo (not zero if output data has halo)
nsoil integer number of soil layers (e.g. 4)
ntrac integer number of tracers
jcap integer spectral truncation wave number
ncldt integer number of cloud types
idvc integer vertical coordinate id
idsl integer semi-Lagrangian id
idvm integer mass variable id
idrt integer grid identifier
rlon_min real(4) minimal longitude of regional domain
rlon_max real(4) maximal longitude of regional domain
rlat_min real(4) minimal latitude of regional domain
rlat_max real(4) maximal latitude of regional domain
extrameta logical extra user-defined meta data flag
  • Meta1 is fixed to 48 bytes in length and contains variables listed in the table below:
    Variable Name Kind Description
    gtype character(8) NEMSIO file indicator (e.g. 'nemsio')
    modelname character(8) model name (e.g. 'GFS', 'NMMB')
    gdatatype character(8) data format (e.g. 'grib', 'bin4_be', bin8_be', 'bin4_le', 'bin8_le')
    version integer version number (e.g. 201010)
    nmeta integer number of standard meta records (<= 12)
  • Meta2 contains some integers, real numbers, and a logic variable. All variables in meta2 have a default value -9999 for integers, -9999. for real numbers, and false for logical variables before initialization.

 

Other standard meta data records:

Variable Name Kind Dimension Description
recname character(16) nrec name for each data field record
reclevtyp character(16) nrec level type for each data field record
reclev integer nrec level for each data field record
vcoord real(4) (dimz+1,3,2) vertical coordinator profile
lat real(4) fieldsize latitude
lon real(4) fieldsize longitude
dx real(4) fieldsize grid distance in longitude in meters
dy real(4) fieldsize grid distance in latitude in meters
Cpi real(4) ntrac constant-pressure specific heat capacity for tracers
Ri real(4) ntrac specific gas constant for tracers
  • fieldsize = (dimx+2*nframe)*(dimy+2*nframe)
  • Users can omit other data records by setting nmeta to 2. Setting nmeta to 3 will keep only recname in the meta data. Setting nmeta to 4 will keep recname and reclevtyp in the meta data, etc.

 

User-defined meta data:

  • Extrameta in second meta data indicates if there are any user-defined meta data (8 categories):
    • Variables: integer, real(4), real(8), logical, and character(16)
    • 1D arrays: integer, real(4), real(8), logical, and character(16)
  • If extrameta is true, meta data record exists and includes the following dimensions: nmetavari, nmetavarr, nmetavarl, nmetavarc, nmetavarr8, nmetaaryi, nmetaaryr, nmetaaryl, nmetaaryc, nmetaaryr8
    • nmetavari, nmetavarr, nmetavarl, nmetavarc and nmetavarr8 specify the number of integer, real, logical, and character variables in extra meta data
    • nmetaaryi, nmetaaryr, nmetaaryl, nmetaaryc, and nmetaaryr8 specify the number of 1-D integer, real, logical, and character arrays in extra meta data
  • If any of the numbers in the above meta data are greater than 0, the corresponding meta data records holding the names, lengths (for arrays), and values will be shown in the meta data
  • Possible extra meta data:
    Variable Kind Dimension Description
    variname character(16) nmetavari names of user-defined integer variables
    varival integer nmetavari values of user-defined integer variables
    varrname character(16) nmetavarr names of user-defined real variables
    varr8name character(8) nmetavarr names of user-defined real variables
    varrval real(4) nmetavarr values of user-defined real variables
    varr8val real(8) nmetavarr values of user-defined real variables
    varlname character(16) nmetavarl names of user-defined logical variables
    varlval logical nmetavarl values of user-defined logical variables
    varcname character(16) nmetavarc names of user-defined character variables
    varcval character(16) nmetavarc values of user-defined character variables
    aryiname character(16) nmetaaryi names of user-defined integer arrays
    aryilen integer nmetaaryi lengths of user-defined integer arrays
    aryival integer (maxval(aryilen),nmetaaryi) values of user-defined integer arrays
    aryrname character(16) nmetaaryr names of user-defined real arrays
    aryr8name character(8) nmetaaryr names of user-defined real arrays
    aryrlen integer nmetaaryr lengths of user-defined real arrays
    aryr8len integer nmetaaryr lengths of user-defined real arrays
    aryrval real(4) (maxval(aryrlen),nmetaaryr) values of user-defined real arrays
    aryr8val real(8) (maxval(aryrlen),nmetaaryr) values of user-defined real arrays
    arylname character(16) nmetaaryl names of user-defined logical arrays
    aryllen integer nmetaaryl lengths of user-defined logical arrays
    arylval logical (maxval(aryllen),nmetaaryl) values of user-defined logical arrays
    arycname character(16) nmetaaryc names of user-defined character arrays
    aryclen integer nmetaaryc lengths of user-defined character arrays
    arycval character(16) (maxval(aryclen),nmetaaryc) values of user-defined character arrays
  • All of the values of 1-D arrays are held in the 2-D array according to their kind. For example, aryival holds all 1-D integer arrays, the first dimension of varival is the maximum length of all the 1-D integer arrays, the second dimension is the total number of integer arrays.
  • However, in the data file, for each 1-D array, it will be written in the file in its own length, the value holder array, such as aryival, will not be written out.

Return to top



Data Fields


NEMSIO supports binary and GRIB1 data formats, the default being GRIB1. For binary data, the gdatatype has to be set to either 'bin4_be' or 'bin4_le' for 4 byte binary data files or 'bin8_be' or 'bin8_le' for 8 byte binary data files. The 'be' in the gdatatype is for big endian files and 'le' is for little endian files. The standard meta data records, recname, reclevtyp, and lev, if existing, record the name, level type, and level for each data field.

The data fields can be read/written/updated by using the data field record number or by giving the name, level type, and level of a data field. For binary data files, users could get/write/update data by only using the variable name. For GRIB1 data, level type and level of a data field are required along with the name.

Return to top



NEMSIO Interfaces


NEMSIO defines a data type called nemsio_gfile which contains all meta data information. All of the variables in meta1 and meta2, other standard meta data, and uer-defined meta data are the components of nemsio_gfile. Besides that, nemsio_gfile holds some file information such as file name and the action to the file (READ/WRITE). For the parallel version, MPI information such as MPI communicator and lead_task is also in nemsio_gfile. All of the components of nemsio_gfile have a private attribute. Users have to call the subroutines nemsio_getfilehead or nemsio_getheadvar to get the values of the components in nemsio_gfile.

NEMSIO provides various interfaces for users to access the NEMSIO data files. The most commonly used interfaces and their functions are described below.

Return to top



NEMSIO Interfaces - Serial Version


 

Initialization and Finalization

Users are required to call nemsio_init before they call any NEMSIO functions (sets up GRIB table) and call nemsio_finalize to end the use of NEMSIO functions. Here are examples on how to use them:
 

  • call nemsio_init(iret)
    • iret output integer return code
    call nemsio_finalize(iret)
    • iret output integer return code

Open NEMSIO File

Nemsio_open must be called when users are ready to read/write/update data. For READ or RDWR (used when users need to update data fields; only for binary files), no optional arguments are needed since all information will be obtained from the file. NEMSIO data type nemsio_gfile will contain all the meta data information after nemsio_open. For WRITE, users need to specify some optional arguments such as dimx, dimy, dimz, idate, nmeta, and nrec, otherwise default initialization will be called to set up the values for those meta data. For the default, standard meta data will be set up, which contains 12 standard meta data records including meta1, meta2, recname, reclevtyp, reclev, vcoord, lat, lon, dx, dy, cpi, and ri. Users can set the optional argument, nmeta, to output fewer standard meta data, however, as specified before, the first two meta data must be written out in any case. Users also need to set extrameta in nemsio_open if they want to output their own meta data.

For read:

call nemsio_open(gfile,gname,'read',iret)

For update:

call nemsio_open(gfile,gname,'rdwr',iret)

For write:

call nemsio_open(gfile,gname,'write',optargs,iret)
 

    • gfile: nemsio_gfile, file meta data holder
    • gfname: file name
    • iret: return code
    • optargs: optional arguments - gdatatype,version, nmeta, lmeta, modelname, nrec, idate, nfday, nfhour, nfminute, nfsecondn, nfsecondd, dimx, dimy, dimz, nframe, nsoil, ntrac, jcap, ncldt, idvc, idsl, idvm, idrt, rlon_min, rlon_max, rlat_min, rlat_max, extrameta, recname, reclevtyp, reclev, vcoord, lat, lon, dx, dy, cpi, ri, nmetavari, nmetavarr, nmetavarl, nmetavarc, nmetaaryi, nmetaaryr, nmetaaryl, nmetaaryc, variname, varival, varrname, varrval, varlname, varlval, varcname, varcval, aryiname, aryilen, aryival, aryrname, aryrlen, aryrval, arylname, aryllen, arylval, arycname, aryclen, arycval

 

Close NEMSIO File

Nemsio_close closes the data file, de-allocates all the meta data arrays, and sets meta data variables into default values in the file meta data holder.
 

  • call nemsio_close(gfile,iret)

After nemsio_close, all variables in NEMSIO data type gfile have a default value of -9999 or false for logical.

 

Read Data Fields

NEMSIO has two read subroutines to read out a data field. One is nemsio_readrec, which will read data fields from the file by order of the data fields. The other is nemsio_readrecv, which allows users to read out the data field by giving the data field's name, level type, and level; levtyp and level are optional for binary data. Only when the recname, possibly reclevtyp and reclev, are set in the standard meta data, can the second function be used. Level type and level are required to exist in the meta data when levtyp and lev are present in the nemsio_readrecv argument list. The output data can either be 4 byte real or 8 byte double precision real no matter whether the data file is 4 byte binary, 8 byte binary, or GRIB1.

call nemsio_readrec(gfile,jrec,data,nframe,iret)
 

    • gfile: input/output nemsio_gfile file metadata
    • jrec: input integer the j-th record in the data fields
    • data: output real(:), 1 data field, could be either real(4) or real(8)
    • nframe: optional, cut off nframe from data domain, nframe must be less than nframe in the data sets
    • iret: output integer return code

call nemsio_readrecv(gfile,name,levtyp,lev,data,nframe,iret)
 

    • gfile: input/output nemsio_gfile file metadata
    • name: input, character(8) name of data field
    • levtyp: optional input, character(16) level type of data field
    • lev: optional input, integer, level of data field
    • data: output, real(:) data, could be either real(4) or real(8)
    • nframe: optional, cut off nframe from data domain, nframe must be less than nframe in the data sets
    • iret: output integer return code

 

Write Data Fields

Similar to READ, NEMSIO has two write functions. One is nemsio_writerec, which will write the data field by order of the data field, and the other is nemsio_writerecv, which allows users to write out data by giving the data field's name, levtyp, and lev; like READ, the recname, reclevtyp, and reclev have to be written out in the standard meta data for this function to be called. Also, the input data can be either 4 byte real or 8 byte double precision real regardless of the data type of the file. Some inner transform will write out the data sets according to the data type of your file. The precision can be defined for a specific field when the field is output to a grib file. The default precision is in the grib table inside nemsio lib.

call nemsio_writerec(gfile,jrec,itr,zhour,data,iret)
 

    • gfile: input/output nemsio_gfile file metadata
    • jrec: input integer the j-th record in the data fields
    • itr: time range flag
    • zhour: time range 1 when time range flag is for average or accumulation
    • data: output, real(:) data, could be either real(4) or real(8)
    • iret: output integer return code

call nemsio_writerecv(gfile,name,levtyp,lev,itr,zhour,data,iret)
 

    • gfile: input/output nemsio_gfile file metadata
    • name: input, character(8) name of data field
    • levtyp: optional input, character(16) level type of data field
    • lev: optional input, integer, level of data field
    • itr: time range flag
    • zhour: time range 1 when time range flag is for average or accumulation
    • data: output, real(:) data, could be either real(4) or real(8)
    • iret: output integer return code

When reading or writing GRIB1 data using NEMSIO, users who use w3_4, rather than w3_d, when compiling their code will need to use different interfaces. This is because NEMSIO has no knowledge which w3 library (w3_4 or w3_d) is used. Below is a list of interfaces to be used instead. Field precision is also an additional optional argument.

call nemsio_readrecw34(gfile,jrec,data,nframe,iret)
call nemsio_writerecw34(gfile,jrec,itr,zhour,data,iret)
call nemsio_readrecvw34(gfile,jrec,levtyp,lev,data,nframe,iret)
call nemsio_writerecvw34(gfile,jrec,levtyp,lev,itr,zhour,data,iret)

The argument lists are the same as in the subroutines using w3_d in compile.

 

Get Meta Data Information

Since the nemsio_gfile has private attribute for its meta data, all meta data has to be obtained through nemsio_getfilehead or nemsio_getheadvar. Users can use nemsio_getfilehead to get all the meta data as variables listed in the above tables or they can get any single meta data variable including any in the user defined meta data arrays.

call nemsio_getfilehead(gfile,optargs,iret,file_endian,do_byteswap,tlmeta)
 

    • gfile: input nemsio_gfile file metadata
    • optargs: output optional arguments
    • iret: output integer return code
    • file_endian: contains information on a nemsio file's endianness
    • do_byteswap: shows if byteswap is used when accessing the data
    • tlmeta: returns total meta data length
    • Optargs includes: gdatatype, version, nmeta, lmeta, modelname, nrec, idate, nfday, nfhour, nfminute, nfsecondn, nfsecondd, dimx, dimy, dimz, nframe, nsoil, ntrac, jcap, ncldt, idvc, idsl, idvm, idrt, rlon_min, rlon_max, rlat_min, rlat_max, extrameta, recname, reclevtyp, reclev, vcoord, lat, lon, dx, dy, cpi, ri, nmetavari, nmetavarr, nmetavarl, nmetavarc, nmetaaryi, nmetaaryr, nmetaaryl, nmetaaryc, variname, varival, varrname, varrval, varlname, varlval, varcname, varcval, aryiname, aryilen, aryival, aryrname, aryrlen, aryrval, arylname, aryllen, arylval, arycname, aryclen, arycval

call nemsio_getheadvar(gfile,argname,argval,iret,file_endian,do_byteswap,tlmeta)
 

    • gfile: input nemsio_gfile file metadata
    • argname: input argument name
    • argval: output argument value
    • iret: output integer return code
    • file_endian: contains information on a nemsio file's endianness
    • do_byteswap: shows if byteswap is used when accessing the data
    • tlmeta: returns total meta data length

Argname can be any meta data variable name, including names in variname, varrname, varlname, varcname, aryiname, aryrname, arylname, and arycname. Users can call nemsio_getfilehead to get variname (or other array names) then call nemsio_getheadvar to get the value of a specific variable or array.

 

Get Data Field Information

Users can get the name, level type, and level of each data field by calling nemsio_getrechead if they need this information. For example, users can obtain the values of data fields by calling nemsio_readrecv or nemsio_writerecv with that information. As specified before, meta data records recname, reclevtyp, and reclev must be present in meta data in order to use this interface.

call nemsio_getrechead(gfile,jrec,vname,vlevtyp,vlev,iret)
 

    • gfile: input/output nemsio_gfile file metadata
    • jrec: input integer the j-th record
    • vname: output data field name
    • vlevtyp: output data field level type
    • vlev: output data field level
    • iret: output integer return code

 

Set Meta Data Information

In some special cases when the meta data information such as lat, lon, dx, and dy cannot be obtained at the time the NEMSIO file is opened, NEMSIO allows users to set these four meta data later. Users need to be careful with the dimension of those four variables since it may destroy the data in the file.

call nemsio_setfilehead(gfile,optarg,iret)
 

    • gfile: input/output nemsio_gfile file metadata
    • optargs: input optional arguments
    • iret: output integer return code

Optargs can only be lat, lon, dx, and dy.

Return to top



NEMSIO Interfaces - Parallel Version


In the parallel version of NEMSIO, MPI-II parallel I/O is used for MPI I/O. For meta data, the read-broadcast method is used, so one processor will read the header information and broadcast it to all the other processors. For data fields, parallel I/O is used so all of the processors will read/write data simultaneously. The user will decide which portion of data will be accessed by each processor. Therefore, the argument lists for interfaces of opening files and reading/writing/updating data fields are different from the serial version.

This version also includes a module, module_nemsio_mpi, that handles endianness, allowing NEMSIO to be used on different machines for files with different endianness. The module will read big or little endian files and write user-specified endianness files. The default endianness for write is the machine endianness. For example, the default for IBM is big endian and the default for Linux is little endian.
 

Interfaces Identical to Serial Version

    • call nemsio_init(iret)
    • call nemsio_finalize(iret)
    • call nemsio_close(gfile, iret)
    • call nemsio_getfilehead(gfile,optargs,iret)
    • call nemsio_getheadvar(gfile,argname,argval,iret)
    • call nemsio_getrechead(gfile,jrec,vname,vlevtyp,vlev,iret)
    • call nemsio_setfilehead(gfile,optarg,iret)

Open NEMSIO File

To open a NEMSIO file, MPI information, such as MPI communicator, is needed. Also, a lead task which will read/write meta data is needed. Following is the interface for opening files:

call nemsio_open(gfile,gfname,gaction,mpi_comm,optargs,iret)
 

    • gfile: input/output nemsio_gfile nemsio_gfile file meta
    • gfname: input character file name
    • gaction: input character, allowed operations: 'READ', 'WRITE', 'RDWR'
    • mpi_comm: input integer MPI communicator
    • optargs: input optional arguments
    • iret: output integer return code

Optargs are the same as in the serial version.

Read Data Field

To read data, users need to provide information on what portion of data each processor deals with. A map array describing the location of each element of the data array for each processor is all that is needed. In NEMSIO, a simplified implementation is to specify four arguments, ista, iend, jsta, and jend. Those four variables will specify the subdomain of the data array for each processor located on the whole data field domain. The figure below shows an example. A 2D data field (global array) is shown in dimension(ISTA_G:IEND_G), (JSTA_G:JEND_G). Each small rectangular box specifies the portion of data (local array) (ISTA:IEND,JSTA:JEND) for each processor. Ista and iend are the starting and ending point in the X-direction and jsta and jend are the starting and ending points in the Y-direction.
 


The interface for reading by using the data field record number is:

call nemsio_readrec(gfile,ista,iend,jsta,jend,jrec,data,iret)
 

    • ista, iend, jsta, jend: input dimension of local array

If calling by data field name, level type, and level, the interface would be:

call nemsio_readrecv(gfile,ista,iend,jsta,jend,jrec,name,levtyp,lev,data,iret)
 

    • ista, iend, jsta, jend: input dimension of local array

Because the parallel I/O works more efficiently for large size data sets, getting out all the data fields by one reading call will save time compared to reading one data field at a time. Therefore, the interface for reading all data fields in a file is:

call nemsio_denseread(gfile,ista,iend,jsta,jend,jrec,data,iret)
 

    • ista, iend, jsta, jend: input dimension of local array
    • data(:): data((iend-ista+1)*(jend-jsta+1)*nrec)

Write Data Field

The interfaces for writing data fields are similar to those for reading data fields.

call nemsio_writerec(gfile,ista,iend,jsta,jend,jrec,data,iret)
 

    • ista, iend, jsta, jend: input dimension of local array

call nemsio_writerecv(gfile,ista,iend,jsta,jend,jrec,name,levtyp,lev,data,iret)
 

    • ista, iend, jsta, jend: input dimension of local array

call nemsio_densewrite(gfile,ista,iend,jsta,jend,jrec,name,levtyp,lev,data,iret)
 

    • ista, iend, jsta, jend: input dimension of local array
    • data(:): data((iend-ista+1)*(jend-jsta+1)*nrec)

Return to top



Examples


Following are a few examples showing how to read and write NEMSIO files and get data from them. Use the menu below to jump to a specific example:

 


#1 - Read a NEMSIO File (Serial Version)

program main

use nemsio_module
implicit none
!
type(nemsio_gfile) :: gfile
integer im,jm,jrec,nframe,nrec,fieldsize,vlev,iret
character(8) vname
character(16) vlevtyp
character(255) cin
real(4),allocatable :: fis(:)
!
!--- Initialize
call nemsio_init(iret=iret)
!
!--- Opean a NEMSIO file
call getarg(1,cin)
call nemsio_open(gfile,trim(cin),'READ',iret=iret)
!
!--- Get dimension
call nemsio_getfilehead(gfile,iret=iret,dimx=im,dimy=jm,nframe=nframe)
!
!---Allocate array
fieldsize=(im+2*nframe)*(jm+2*nframe)
allocate(fix(fieldsize))
!
!--- You could get the name, levtyp, and level of j-th record data field by calling:
jrec=1
call nemsio_getrechead(gfile,jrec,vname,vlevtyp,vlev,iret=iret)
!
!--- Get one data field out by data field record number
call nemsio_readrec(gfile,jrec,fis(:),iret=iret)
!
!--- Get one data field out by giving field name, levtyp, and level
call nemsio_readrecv(gfile,'hgt','sfc',1,fis(:),iret=iret)
!
!--- Close the NEMSIO file
call nemsio_close(gfile,iret=iret)
!
!--- Finalize
call nemsio_finalize()
!
end

Return to top
Return to examples menu


#2 - Write a NEMSIO File(1) (Serial Version)

!--- Set up NEMSIO
call nemsio_init(iret=iret)
print *,'nemsio_init, iret=',iret
!
!--- Open gfile for writing, the default meta data setting for model nmmb contains all the meta data information in NMMB run history plain binary file.

call nemsio_open(gfilew,trim(cout),'write',iret,modelname="NMMB",gdatatype="bin4_be", &
idate=idate,nfhour=nfhour,nfminute=nfminute,nfsecondn=nfsecondn, &
nfsecondd=nfsecondd,dimx=im,dimy=jm,dimz=lm,nframe=nframe,nsoil=nsoil, &
ntrac=3,ncldt=1,rlon_min=minval(glon1d),rlon_max=maxval(glon1d),rlat_max=maxval(glad1d), &
rlat_min=minval(glat1d),extrameta=.true.,nmetavari=10,nmetavarr=12,nmetavarl=2, &
nmetaaryi=1,nmetaaryr=7,variname=variname,varival=varival,varrname=varrname, &
varrval=varrval,varlname=varlname,varlval=varlval,aryiname=aryiname,aryilen=aryilen, &
aryival=aryival,aryrname=aryrname,aryrlen=aryrlen,aryrval=aryrval, &
lat=glat1d,lon=glon1d,dx=dx,dy=dy)
!
!--- Write out data field
call nemsio_writerec(gfilew,jrec,datatmp(:,jrec),iret=iret)
!
!--- Write data field by names
call nemsio_writerecv(gfilew2,'tmp','mid layer',L,tmp(:,L),iret=iret)
!
!--- Close NEMSIO file
call nemsio_close(gfile,iret=iret)
!
!--- Finalize
call nemsio_finalize()

Return to top
Return to examples menu


#3 Write a NEMSIO file(2)

This NEMSIO file just has the first two meta data records. The user can not call nemsio_readrecv or nemsio_writerecv since not enough information is provided in the meta data.

!--- Prepare meta data
cin='nemsio_2meta'
nmeta=2
nrec=60
idate(1:7)=(/2007,05,18,0,0,0,100/)
im=231;jm=141;lm=60;nframe=0
!
!--- Open NEMSIO file for write
call nemsio_open(gfilem2,trim(cin),'write',modelname='NMMB',gdatatype='bin4_be', &
idate=idate,dimx=im,dimy=jm,dimz=lm, &
nmeta=nmeta,nrec=nrec,iret=iret)
print *,'after open write,iret=',iret
!
!--- Allocate array and set data field for write
fieldsize=(im+2*nframe)*(jm+2*nframe)
allocate(tmp(fieldsize,nrec),fis(fieldsize))
fis(1:fieldsize)=1000.
!
!---Write 2 fields: tmp and hgt
do jrec=1,lm

  • tmp(1:fieldsize,jrec)=jrec
    call nemsio_writerec(gfilem2,jrec,tmp(:,jrec),iret=iret)
    print *,'after write,jrec=',jrec,'iret=',iret

enddo
!
!--- Close NEMSIO file
call nemsio_close(gfilem2,iret=iret)

Return to top
Return to examples menu


#4 - Get user-defined meta data

If users do not know which variables are int he meta data part of the file, they can call nemsio_getfilehead.

call nemsio_getfilehead(gfile,iret=iret,nmetavari=nmetavari,nmetavarr=nmetavarr, &
nmetavarl=nmetavarl,nmetaaryi=nmetaaryi,nmetaaryr=nmetaaryr)

allocate(variname(nmetavari),varrname(nmetavarr),varlname(nmetavarl))
allocate(aryiname(nmetaaryi),aryrname(nmetaaryr))
allocate(aryilen(nmetaaryi),aryrlen(nmetaaryr))

call nemsio_getfilehead(gfile,iret=iret,variname=variname,varrname=varrname, &
varlname=varlname,aryiname=aryiname,aryrname=aryrname,aryilen=aryilen,aryrlen=aryrlen)

Then they can call:

call nemsio_getheadvar(gfile,'run',run,iret)

call nemsio_getheadvar(gfile,'DSG1',dsg1,iret)

Return to top
Return to examples menu


#5 - Read data field (MPI version)

This example shows how to read a NMMB NEMSIO data set. It also shows how to set up the dimensions of local arrays.

call nemsio_init(ierr)
!
cin='nemsiowrt'
root=0
print *,'before call nemsio_open'
call nemsio_open(gfile,trim(cin),'READ',mpi_comm_world,iret=iret)
!
call nemsio_getfilehead(gfile,iret=iret,nrec=nrec,dimx=im,nframe=nframe,dimy=jm,dimz=lm,nsoil=nsoil,nrec=nrec)
!
!--- Get fieldsize
im2=im+2*nframe
jm2=jm+2*nframe
fieldsize=im2*jm2
!
!--- Set up the subdomain
inum_base=im2/inpes
in_remain=im2-inpes*inum_base
imype=mod(mype,inpes)
iadd=1
if (imype>=in_remain) iadd=0
if (imyep<=in_remain) then

  • ista=(inum_base+1)*imype+1

else

  • ista=inum_base*imype+in_remain+1

endif
iend=ista+inum_base+iadd-1
!
jnum_base=jm2/jnmpes
jn_remain=jm2-jnpes*jnum_base
jmype=mype/inpes
jadd=1
if (jmype>=jn_remain) jadd=0
if (jmype<=jn_remain) then

  • jsta=(jnum_base+1)*jmype+1

else

  • jsta=jnum_base*jmype+jn_remain+1

endif
jend=jsta+jnum_base+jadd-1
!
!--- Allocate array
subdmfldsize=(iend-ista+1)*(jend-jsta+1)

allocate(data(subdmfldsize,nrec),data1(subdmfldsize,nrec))
allocate(data2(subdmfldsize*nrec))
allocate(tmp(subdmfldsize,lm),tmp1(subdmfldsize,lm))
allocate(fis(subdmfldsize),fis1(subdmfldsize))
!
!--- Read by data filed record number
do jrec=1,nrec

call nemsio_getrechead(gfile,jrec,vname,vlevtyp,vlev,iret=iret)
call nemsio_readrec(gfile,ista,iend,jsta,jend,jrec,data1(:,jrec),iret=iret)
print *,'read,iret=',iret,jrec,vname,vlevtyp,vlev,'data=',maxval(data1(:,jrec)),minval(data1(:,jrec)), &
data1(1,jrec),data1(subdmfldsize,jrec)

enddo
!
!--- Dense read
call nemsio_denseread(gfile,ista,iend,jsta,jend,data2,iret)
!
!--- Read by data field name, level type, and level
do L=1,lm

  • call nemsio_readrecv(gfile,ista,iend,jsta,jend,'tmp','mid layer',L,tmp(:,L),iret=iret)

enddo
!
!--- Close NEMSIO file
call nemsio_close(gfile,iret=iret)
!
!--- Finalize
call nemsio_finalize()

Return to top
Return to examples menu


#6 - Write Data Field (MPI Version)

cout2='nemsio2rec_gfs'
lonb=1152
latb=576
lm=64
root=0
nrec=lm+1
allocate(recname(nrec),reclevtyp(nrec),reclev(nrec))
recname(1:lm)='tmp'
recname(1+lm)='hgt'
reclevtyp(1:lm)='mid layer'
reclevtyp(1+lm)='sfc'
do l=1,lm
reclev(l)=l
enddo
reclev(lm+1)=1
!
!--- Open NEMSIO file
call nemsio_open(gfile,trim(cout2),'write',mpi_comm_world,modelname="GFS", &
gdatatype="bin4_be",idate=idate,nrec=nrec,dimx=lonb, &
dimy=latb,dimz=levs,iret=iret,recname=recname, &
reclevtyp=reclevtyp,reclev=reclev,nmeta=5)
!
!--- Call dense write
call nemsio_densewrite(gfile,ista,iend,jsta,jend,data2,iret=iret)
!
!--- Close NEMSIO file
call nemsio_close(gfile,iret=iret)
!
!--- Finalize
call nemsio_finalize

Return to top
Return to examples menu

Requirement

To read or write a nemsio file, nemsio library is required. Versions of the nemsio library source code are available at:
http://www.nco.ncep.noaa.gov/pmb/codes/nwprod/lib/nemsio