Skip Navigation Links www.nws.noaa.gov
NOAA logo - Click to go to the NOAA homepage National Weather Service NWS logo - Click to go to the NWS homepage
EMC Logo
Navigation Bar Left Cap Home News Organization
Navigation Bar End Cap

         MISSION / VISION    |    About EMC

EMC > NEMS > NEMSIO
NOAA Environmental Modeling System

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:

  • Meta1 is fixed to 48 bytes in length and contains variables listed in the table below:
    Variable NameKindDescription
    gtypecharacter(8)NEMSIO file indicator (e.g. 'nemsio')
    gdatatypecharacter(8) data format (e.g. 'grib', 'bin4_be', bin8_be', 'bin4_le', 'bin8_le')
    modelnamecharacter(8)model name (e.g. 'GFS', 'NMMB')
    versionintegerversion number (e.g. 201010)
    nmetaintegernumber 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.
  • Variable NameKindDescription
    nrecintegertotal data fields in data part
    idateinteger(7)starting date contains:
    yyyy/mm/dd/hh/m
    m/ss(numerator)/ss(denominator)
    nfdayintegerforecast days
    nfhourintegerforecast hours
    nfminuteintegerforecast minutes
    nfsecondnintegerforecast seconds (numerator)
    nfseconddintegerforecast seconds (denominator)
    dimxintegerdimension in x-direction (not including halo)
    dimyintegerdimension in y-direction (not including halo)
    dimzintegerdimension in y-direction
    nframeintegerdimension of halo (not zero if output data has halo)
    nsoilintegernumber of soil layers (e.g. 4)
    ntracintegernumber of tracers
    jcapintegerspectral truncation wave number
    ncldtintegernumber of cloud types
    idvcintegervertical coordinate id
    idslintegersemi-Lagrangian id
    idvmintegermass variable id
    idrtintegergrid identifier
    rlon_minreal(4)minimal longitude of regional domain
    rlon_maxreal(4)maximal longitude of regional domain
    rlat_minreal(4)minimal latitude of regional domain
    rlat_maxreal(4)maximal latitude of regional domain
    extrametalogicalextra user-defined meta data flag

Other standard meta data records:

  • 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.
  • Variable NameKindDimensionDescription
    recnamecharacter(16)nrecname for each data field record
    reclevtypcharacter(16)nreclevel type for each data field record
    reclevintegernreclevel for each data field record
    vcoordreal(4)(dimz+1,3,2)vertical coordinator profile
    latreal(4)fieldsizelatitude
    lonreal(4)fieldsizelongitude
    dxreal(4)fieldsizegrid distance in longitude in meters
    dyreal(4)fieldsizegrid distance in latitude in meters
    Cpireal(4)ntracconstant-pressure specific heat capacity for tracers
    Rireal(4)ntracspecific gas constant for tracers

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:
    VariableKindDimensionDescription
    varinamecharacter(16)nmetavarinames of user-defined integer variables
    varivalintegernmetavarivalues of user-defined integer variables
    varrnamecharacter(16)nmetavarrnames of user-defined real variables
    varr8namecharacter(8)nmetavarrnames of user-defined real variables
    varrvalreal(4)nmetavarrvalues of user-defined real variables
    varr8valreal(8)nmetavarrvalues of user-defined real variables
    varlnamecharacter(16)nmetavarlnames of user-defined logical variables
    varlvallogicalnmetavarlvalues of user-defined logical variables
    varcnamecharacter(16)nmetavarcnames of user-defined character variables
    varcvalcharacter(16)nmetavarcvalues of user-defined character variables
    aryinamecharacter(16)nmetaaryinames of user-defined integer arrays
    aryilenintegernmetaaryilengths of user-defined integer arrays
    aryivalinteger(maxval(aryilen),nmetaaryi)values of user-defined integer arrays
    aryrnamecharacter(16)nmetaaryrnames of user-defined real arrays
    aryr8namecharacter(8)nmetaaryrnames of user-defined real arrays
    aryrlenintegernmetaaryrlengths of user-defined real arrays
    aryr8lenintegernmetaaryrlengths of user-defined real arrays
    aryrvalreal(4)(maxval(aryrlen),nmetaaryr)values of user-defined real arrays
    aryr8valreal(8)(maxval(aryrlen),nmetaaryr)values of user-defined real arrays
    arylnamecharacter(16)nmetaarylnames of user-defined logical arrays
    aryllenintegernmetaaryllengths of user-defined logical arrays
    arylvallogical(maxval(aryllen),nmetaaryl)values of user-defined logical arrays
    arycnamecharacter(16)nmetaarycnames of user-defined character arrays
    aryclenintegernmetaaryclengths of user-defined character arrays
    arycvalcharacter(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.

Jump to:


#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


Questions or comments about NEMSIO? Please contact Jun Wang.