PUBLIC INTERFACE ~ PUBLIC DATA ~ PUBLIC ROUTINES ~ NAMELIST ~ DIAGNOSTIC FIELDS ~ ERROR MESSAGES ~ REFERENCES ~ NOTES

Module fms_io_mod

Contact:  G.T. Nong ,  M.J. Harrison
Reviewers:  M.J. Harrison ,  B. Wyman
Change History: WebCVS Log

OVERVIEW

This module is for writing and reading restart data in NetCDF format. fms_io_init must be called before the first write_data/read_data call For writing, fms_io_exit must be called after ALL write calls have been made. Typically, fms_io_init and fms_io_exit are placed in the main (driver) program while read_data and write_data can be called where needed. Presently, two combinations of threading and fileset are supported, users can choose one line of the following by setting namelist:

With the introduction of netCDF restart files, there is a need for a global switch to turn on/off netCDF restart options in all of the modules that deal with restart files. Here two more namelist variables (logical type) are introduced to fms_io

fms_netcdf_override fms_netcdf_restart

because default values of both flags are .true., the default behavior of the entire model is to use netCDF IO mode. To turn off netCDF restart, simply set fms_netcdf_restart to .false.

Fei.Liu@noaa.gov 
threading_read='multi', fileset_read='single', threading_write='multi', fileset_write='multi' (default)
threading_read='multi', fileset_read='single', threading_write='single', fileset_write='single'

OTHER MODULES USED

     mpp_io_mod
mpp_domains_mod
        mpp_mod
   platform_mod

PUBLIC INTERFACE

get_restart_io_mode:
fms_io_init:
fms_io_exit:
write_data:
field_size:
read_data:
open_namelist_file:
open_restart_file:
open_direct_file:
open_ieee32_file:
close_file:
set_domain:
nullify_domain:
return_domain:
get_domain_decomp:

PUBLIC DATA

None.

PUBLIC ROUTINES

  1. get_restart_io_mode

    call get_restart_io_mode
    DESCRIPTION
    With the introduction of netCDF restart files, there is a need for a global switch to turn on/off netCDF restart options in all of the modules that deal with restart files. Here two more namelist variables (logical type) are introduced to fms_io

    fms_netcdf_override fms_netcdf_restart

    because default values of both flags are .true., the default behavior of the entire model is to use netCDF IO mode. To turn off netCDF restart, simply set fms_netcdf_restart to .false.



    INPUT/OUTPUT
    do_netcdf_restart    This the input argument that contains the individual module setting of restart IO mode. Upon return from this subroutine, this output argument contains the actual setting of restart IO mode the calling module will be using
       [logical]

  2. fms_io_init

    call fms_io_init ()
    DESCRIPTION
    Initialize fms_io module


  3. fms_io_exit

    call fms_io_exit
    DESCRIPTION
    This routine is called after ALL fields have been written to temporary files The result NETCDF files are created here.


  4. write_data

    call write_data (filename, fieldname, data, domain)
    DESCRIPTION
    This subroutine performs writing "fieldname" to file "filename". All values of "fieldname" will be written to a temporary file. The final NETCDF file will be created only at a later step when the user calls fms_io_exit. Therefore, make sure that fms_io_exit is called after all fields have been written by this subroutine.


    INPUT
    filename    File name
       [character, dimension(*)]
    fieldname    Field name
       [character, dimension(*)]
    data    array containing data of fieldname
       [real]
    domain    domain of fieldname
       [domain, optional]

  5. field_size

    call field_size (filename, fieldname, siz)
    DESCRIPTION
    Given filename and fieldname, this subroutine returns the size of field


    INPUT
    filename    File name
       [character, dimension(*)]
    fieldname    Field name
       [character, dimension(*)]

    OUTPUT
    siz    siz must be a dimension(4) array to retrieve the size of the field
       [integer, dimension(*)]
    field_found    if this flag is present, field_size will not abort if called for a non-existent field. Instead it will return T or F depending on whether or not the field was found.
       [logical, optional]

  6. read_data

    call read_data (filename,fieldname,data,domain,timelevel)
    DESCRIPTION
    This routine performs reading "fieldname" stored in "filename". The data values of fieldname will be stored in "data" at the end of this routine. For fieldname with multiple timelevel just repeat the routine with explicit timelevel in each call.


    INPUT
    filename    File name
       [character, dimension(*)]
    fieldname    Field name
       [character, dimension(*)]
    domain    domain of fieldname
       [domain, optional]
    timelevel    time level of fieldname
       [integer, optional]

    OUTPUT
    data    array containing data of fieldname
       [real]

  7. open_namelist_file

    DESCRIPTION
    Opens single namelist file for reading only by all PEs the default file opened is called "input.nml".


    INPUT
    file    name of the file to be opened
       [character]

    OUTPUT
    unit    unit number returned by this function
       [integer]

  8. open_restart_file

    DESCRIPTION
    Opens single restart file for reading by all PEs or writing by root PE only the file has native format and no mpp header records.


    INPUT
    file    name of the file to be opened
       [character]
    action    action to be performed: can be 'read' or 'write'
       [character]

    OUTPUT
    unit    unit number returned by this function
       [integer]

  9. open_direct_file

    DESCRIPTION
    Opens single direct access file for reading by all PEs or writing by root PE only the file has native format and no mpp header records.


  10. open_ieee32_file

    DESCRIPTION
    Opens single 32-bit ieee file for reading by all PEs or writing by root PE only (writing is not recommended) the file has no mpp header records.


    INPUT
    file    name of the file to be opened
       [character]
    action    action to be performed: can be 'read' or 'write'
       [character]

    OUTPUT
    unit    unit number returned by this function
       [integer]

  11. close_file

    DESCRIPTION
    Closes files that are opened by: open_namelist_file, open restart_file, and open_ieee32_file. Users should use mpp_close for other cases.


    INPUT
    unit    unit number of the file to be closed
       [integer]
    status    action to be performed: can be 'delete'
       [character, optional]

  12. set_domain

    DESCRIPTION
    set_domain is called to save the domain2d data type prior to calling the distributed data I/O routines, read_data and write_data.


    INPUT
    Domain2    domain to be passed to routines in fms_io_mod, Current_domain will point to this Domain2
       [domain2D]

  13. nullify_domain

    DESCRIPTION
    Use to nulify domain that has been assigned by set_domain.


  14. return_domain

    DESCRIPTION
    This routine is the reverse of set_domain above. This routine is called when users want to retrieve the domain2d that is used in fms_io_mod


    OUTPUT
    domain2    domain returned from fms_io_mod.
       [domain2D]

  15. get_domain_decomp

    DESCRIPTION
    This will be a private routine with the next release. Users should get the domain decomposition from the domain2d data type.


    OUTPUT
    x    array containing beginning and ending indices of global and compute domain in x direction
       [integer]
    y    array containing beginning and ending indices of global and compute domain in y direction
       [integer]

NAMELIST

&fms_io_nml

threading_read
threading_read can be 'single' or 'multi'
[character]
threading_write
threading_write can be 'single' or 'multi'
[character]
fileset_read
fileset_read can be 'single' or 'multi'
[character]
fileset_write
fileset_write can be 'single' or 'multi'
[character]
fms_netcdf_override
.true. : fms_netcdf_restart overrides individual do_netcdf_restart value (default behavior) .false.: individual module settings has a precedence over the global setting, therefore fms_netcdf_restart is ignored
[logical]
fms_netcdf_restart
.true. : all modules deal with restart files will operate under netCDF mode (default behavior) .false.: all modules deal with restart files will operate under binary mode This flag is effective only when fms_netcdf_override is .true. When fms_netcdf_override is .false., individual module setting takes over.
[logical]

DATA SETS

None.

ERROR MESSAGES

None.

top