update fms2_io docs by rem1776 · Pull Request #1840 · NOAA-GFDL/FMS

rem1776 · 2026-02-12T15:20:52Z

Description
updates for fms2_io docs (WIP)

Fixes # (issue)

How Has This Been Tested?
Please describe the tests that you ran to verify your changes. Please also note
any relevant details for your test configuration (e.g. compiler, OS). Include
enough information so someone can reproduce your tests.

Checklist:

My code follows the style guidelines of this project
I have performed a self-review of my own code
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation
My changes generate no new warnings
Any dependent changes have been merged and published in downstream modules
New check tests, if applicable, are included
make distcheck passes

fms2_io/fms2_io.F90

mlee03 · 2026-03-03T13:49:12Z

fms2_io/fms2_io.F90

+!! Besides standard open/close/read/write operations, this module also provides interfaces for writing and reading
+!! restart files via the blackboxio module. Restart files can be created and read for both structured and unstructured
+!! domain netcdf files and utilize the same unified interface calls (write_restart, read_restart, etc), but contain
+!! specific metadata and grid information to facilitate model restarts.


@uramirez8707, just checking lines 49-52 are correct

i think the difference is that the blackbox io creates diskless files:

FMS/fms2_io/blackboxio.F90

Lines 146 to 147 in 957b7c9

cmode = ior(nf90_noclobber, nf90_classic_model)

cmode = ior(cmode, nf90_diskless)

mlee03 · 2026-03-03T14:15:46Z

fms2_io/fms2_io.F90

+!! Besides NetCDF io, this module also provides an interface for common utility routines used in FMS I/O operations,
+!! such as checking for file existence, reading ascii files, parsing mask tables, and generating instance filenames.
+!!
+!! If converting legacy code from fms_io/mpp_io to fms2_io, please refer to the migration guide at fms2_io/readme.md.


reworded it a little for better organization, what do you think?
!> @brief This module aims support I/O operations for 3 types of netcdf files within the FMS framework:
!!
!! 1) Generic netcdf files via the netcdf_io_mod module.
!! 2) Netcdf files with structured grid domains via the fms_netcdf_domain_io_mod module.
!! 3) Netcdf files with unstructured grid domains via the fms_netcdf_unstructured_domain_io_mod module.

!! fms2_io_mod is the top level module that provides open, close, read, and write interfaces to the NetCDF package.
!! This module defines public "aliases" to select procedures in fms_netcdf_domain_io_mod for reading/writing data on
!! structured grid domains; fms_netcdf_unstructured_domain_io_mod for reading/writing data on unstructured grid domains;
!! netcdf_io_mod for reading/writing generic netcdf files [what is generic?]. Subroutines and functions in the latter
!! mentioned modules (fms_netcdf_domain_io_mod, fms_netcdf_unstructured_domain_io_mod, and netcdf_io_mod) are intended
!! for internally use only. We highly recommended to only call public interfaces defined in this module.

!! Before any fms2_io_mod I/O operations, a file derived type must be declared first before reading and/or
!! writing NetCDF files. Three file derived types are currently available and are described below. Any instances
!! of these three file types are referred to as "fileobj" in this module.
!!
!! - FmsNetcdfFile_t: provides limited number of wrapper procedures to the netCDF4 library. If the
!! user provides a pelist to procedures compatible with this type, only the root rank of the pelist
!! performs I/O operations by calling the NetCDF library: the root rank either boradcasts the read-in
!! in data to the remaining ranks in the pelist, or gathers data from the remaining ranks in the peist before writing.
!!
!! - FmsNetcdfDomainFile_t: extends upon FmsNetcdfFile_t and adds supports for "domain-decomposed" reads and writes.
!! Here, "domain decomposed" refers to data that is partitioned into subdomains of the decomposed global domain,
!! and each MPI rank holds its portion of the global data. The users must provide a domain of type Domain2D from
!! mpp_domains_mod when initializing this file object.
!!
!! - FmsNetcdfUnstructuredDomainFile_t: extends upon FmsNetcdfUnstructuredDomainFile_t and adds support for
!! “domain-decomposed” reads/writes for data decomposed on subdomains of unstructured grids
!! The users must provide a domain of type DomainUG from mpp_domains_mod when initializing this file object.
!!
!! See mpp_domains_mod documentation for more information on domain decomposition with FMS.
!!
!! This module also provides the blackboxio module to read and write restart files for data on both structured and
!! unstructured domains. This module utilize the same, unified interface calls (write_restart, read_restart, etc),
!! but in addition, automatically handles variable and global metadata for writing restart files
!!
!! Utility routines for checking for file existence, reading ascii file, parsing maskfiles, and generating
!! filenames consistent with GFDL conventions are also available.

!! Users can specify I/O specifications with the fms2_io_nml namelist which allows users to specify the following
!! NetCDF library parameters: Netcdf file format, chunk_size, deflate_level, shuffle. Note, fms2_io accepts the following
!! Netcdf file format namelist values:"64bit", "class", and "netcdf4". For more information on optimizing NetCDF writing
!! operation, see https://docs.unidata.ucar.edu/netcdf-c/current/file_format_specifications.html
!!
!! Note, the legacy fms2_io and mpp_io modules are no longer supported. We urge users to transition to the newest
!! fms2_io. Please see fms2_io/readme.md for guidance on migration.

mlee03

let's talk later today :)

mlee03 · 2026-03-03T14:16:27Z

fms2_io/fms2_io.F90

+!! fms_netcdf_unstructured_domain_io_mod) but are made public here for user access.
+public :: FmsNetcdfFile_t, FmsNetcdfDomainFile_t, FmsNetcdfUnstructuredDomainFile_t
+
+!> interfaces that are defined below but utilize helper module routines.


!> interface "aliases" for procedures in helper module routines

mlee03 · 2026-03-03T14:16:35Z

fms2_io/fms2_io.F90

 public :: read_restart
 public :: read_new_restart
+
+!> Routines/Interfaces from netcdf_io_mod to make public


!> interface "aliases" for procedures in netcdf_io_mod

mlee03 · 2026-03-03T14:16:53Z

fms2_io/fms2_io.F90

+public :: get_valid
+public :: is_valid
+
+!> Routines/Interfaces from fms_netcdf_domain_io_mod to make public


!> interface "aliases" for procedures in fms_netcdf_domain_io_mod

mlee03 · 2026-03-03T14:16:59Z

fms2_io/fms2_io.F90

+public :: get_unlimited_dimension_name
+public :: get_variable_unlimited_dimension_index
+
+!> Routines/Interfaces from fms_io_utils_mod to make public


!> interface "aliases" for procedures in fms_io_utils_mod

mlee03 · 2026-03-03T14:18:37Z

fms2_io/fms2_io.F90

 !> @}

-!> @brief Opens a given netcdf or domain file.
+!> @brief Opens a netcdf dataset on disk and initializes the file object.


!> @brief Opens a netcdf dataset on disk. The file object is initialized
!! with this function
!!
!>
Example usage for FmsNetcdfFile_t
!!
!! io_success = open_file(fileobj, "filename", "write")
!!
!! where
!! - fileobj is an instance of FmsNetcdfFile_t
!! - filename is the filename string without the ".nc" suffix
!! - file mode that can take on values "read", "write", "overwrite", and "append"
!!
!>
Example usage for FmsNetcdfDomainFile_t or FmsNetcdfUnstructuredDomainFile_t
!!
!! io_success = open_file(fileobj, "filename", "overwrite", domain)
!!
!! where
!! - fileobj is an instance of FmsNetcdfDomainFile_t or FmsNetcdfUnstructuredDomainFile_t
!! - filename is the filename string. For any tiled files, the filename should not contain the "tile#"
!! information, but contain the ".nc" suffix. For example, filename = "atmos_daily.nc"
!! - domain is an instance of type Domain2D or DomainUG
!! @note For details, see the linked documentation for the appropriate helper module:
!! @ref netcdf_io_mod for open_file with FmsNetcdfFile_t
!! @ref fms_netcdf_domain_io_mod for open_file with FmsNetcdfDomain_File_t
!! @ref fms_netcdf_unstructured_domain_io_mod for open_file with FmsNetcdfUnstructuredDomainFile_t

mlee03 · 2026-03-04T13:42:59Z

fms2_io/fms2_io.F90

-!> @brief An updated library for parallel IO to replace @ref mpp_io_mod. This module contains
-!! the public API for fms2 I/O interfaces and routines defined throughout this directory.
-!! A conversion guide for replacing mpp/fms_io code with this module is available below.
+!> @brief This module aims support netCDF I/O operations for 3 use-cases within the FMS framework:


Let's talk again later. Looking through the module, I think we got things incorrect

mlee03 · 2026-03-09T16:06:31Z

@rem1776 is this ready for re-review?

rem1776 · 2026-03-09T21:11:35Z

@mlee03 Yeah this should be ready

mlee03 · 2026-03-12T11:21:43Z

fms2_io/fms2_io.F90

+!!   “domain-decomposed” reads/writes for data decomposed on subdomains of unstructured grids
+!!   The users must provide a domain of type DomainUG from mpp_domains_mod when initializing this file object.
+!!
+!! See mpp_domains_mod documentation for more information on creating a domain decomposition using FMS.


"...more information on domain decomposition with FMS"

mlee03 · 2026-03-12T11:22:08Z

fms2_io/fms2_io.F90

+!! See mpp_domains_mod documentation for more information on creating a domain decomposition using FMS.
+!!
+!! These types correspond to 3 use-cases within the FMS framework.
+!!


remove lines 50 - 54?

fms2_io/fms2_io.F90

mlee03 · 2026-03-12T11:50:13Z

fms2_io/fms2_io.F90

+!! Netcdf file format namelist values:"64bit", "class", and "netcdf4". For more information on optimizing NetCDF writing
+!! operation, see https://docs.unidata.ucar.edu/netcdf-c/current/file_format_specifications.html
+!!
+!! @note The legacy IO modules, fms_io_mod and mpp_io_mod, are


missing deprecated

mlee03 · 2026-03-12T11:52:11Z

fms2_io/fms2_io.F90

+!! Opens a netcdf file for a standard data, domain decomposed data, or unstructured domain decomposed data based off
+!! the fileobj used, and also intializes the fileobj for subsequent IO operations.
+!!
+!! File mode is set to one of "read"/"write"/"overwrite"/"append":


Accepted values for file mode are:

mlee03 · 2026-03-12T11:55:06Z

fms2_io/fms_io_utils.F90

+!!
+!! The logical array created will be the same shape as the domain layout, with each index representing a specific pe
+!! within the decomposition. This array is intended to be used as input for the mpp_define_domain routines maskmap
+!! argument, to essentially exclude certain pe's from a domain decomposition.


This array is intended to be used as input... argument. A mask value of 1 (or 0?) will exclude the pe from ..?

mlee03 · 2026-03-12T11:56:38Z

fms2_io/fms_io_utils.F90

+!! 1,1
+!! 4,4
+!!
+!! For this mask table, 2 rank's would be masked: the top right corner (1,1) and the bottom left corner (4,4)


Not sure what this sentence means.. 😁

so if your layout is 4,4, typically you will need 16 ranks to run.
The grid is divided by 4 in the x direction and 4 in y direction:

|---------------------------------| (1,4)| (2,4)| (3,4)| (4,4)| |---------------------------------| (1,3)| (2,3)| (3,3)| (4,3)| |---------------------------------| (1,2)| (2,2)| (3,2)| (4,2)| |---------------------------------| (1,1)| (2,1)| (3,1) |(4,1)| |---------------------------------|

Sometimes a whole section of a rank's data can be covered in land (i.e the bottom left which is labeled as 1,1 and the top right which is labeled as 4,4) those areas do not do anything for the ocean. So rather than running with 16 pes having those two pes do nothing, they get masked out so you only need 14 ranks

fms2_io/fms_netcdf_domain_io.F90

mlee03 · 2026-03-12T12:15:50Z

fms2_io/fms_netcdf_domain_io.F90

-!> @brief Domain-specific I/O wrappers.
-
+!> @brief This module defines a derived type, FmsNetcdfDomainFile_t, and routines
+!! to handle calls to the netcdf library when using domain decomposition for a standard


calls to the netcdf library for data on a decomposed domain of a standard rectangular grid? I don't know if that sounds better

mlee03 · 2026-03-12T12:16:26Z

fms2_io/fms_netcdf_domain_io.F90

+!! to handle calls to the netcdf library when using domain decomposition for a standard
+!! rectangular grid. See mpp_domains_mod for more information on domain decomposition.
+!!
+!! This module is not intended to be used externally, fms2_io_mod is intended to publicize the routines


...externally. Please use the public interfaces and types in fms2_io_mod

mlee03 · 2026-03-12T12:23:53Z

fms2_io/fms_netcdf_domain_io.F90



-!> @brief netcdf domain file type.
+!> @brief Type to represent a netCDF file when using a domain decomposition on a


Type to represent netCDF file for parallel reading/writing data on a rectangular grid that has been partitioned into subdomains with domain decomposition

the io_layout part is not clear..

mlee03 · 2026-03-12T12:26:27Z

fms2_io/fms_netcdf_unstructured_domain_io.F90

 !> @defgroup fms_netcdf_unstructured_domain_io_mod fms_netcdf_unstructured_domain_io_mod
 !> @ingroup fms2_io
-!> @brief Handles netcdf I/O for unstructured domains
+!> @brief This module defines a derived type, FmsNetcdfUnstructuredDomainFile_t, and routines to handle


I'm assuming the changes made in fms_netcdf_domain_io can be "copied and pasted" here

uramirez8707

Minor comment + I tried to explain how the mask work ...

uramirez8707 · 2026-03-19T14:24:14Z

fms2_io/fms2_io.F90

+!! fms2_io_mod is the top level module that provides open, close, read, and write interfaces to the NetCDF package.
+!! This module defines public "aliases"(interfaces) to select procedures in fms_netcdf_domain_io_mod for reading/writing
+!! structured grid domains; fms_netcdf_unstructured_domain_io_mod for reading/writing data on unstructured grid domains;
+!! netcdf_io_mod for reading/writing netcdf files on a single core. Subroutines and functions in the latter


i think this
"netcdf_io_mod for reading/writing netcdf files on a single core"

should say something like
`netcdf_io_mod for reading/writing netcdf files that are not in any domain"

uramirez8707 · 2026-03-19T14:45:14Z

fms2_io/fms_io_utils.F90

+!! 1,1
+!! 4,4
+!!
+!! For this mask table, 2 rank's would be masked: the top right corner (1,1) and the bottom left corner (4,4)


so if your layout is 4,4, typically you will need 16 ranks to run.
The grid is divided by 4 in the x direction and 4 in y direction:

|---------------------------------| (1,4)| (2,4)| (3,4)| (4,4)| |---------------------------------| (1,3)| (2,3)| (3,3)| (4,3)| |---------------------------------| (1,2)| (2,2)| (3,2)| (4,2)| |---------------------------------| (1,1)| (2,1)| (3,1) |(4,1)| |---------------------------------|

Sometimes a whole section of a rank's data can be covered in land (i.e the bottom left which is labeled as 1,1 and the top right which is labeled as 4,4) those areas do not do anything for the ocean. So rather than running with 16 pes having those two pes do nothing, they get masked out so you only need 14 ranks

Updated module documentation to clarify usage and purpose.

Updated comments for clarity and consistency in netcdf_io_mod.

update fms2_io module description

f497a21

mlee03 reviewed Feb 19, 2026

View reviewed changes

fms2_io/fms2_io.F90 Outdated Show resolved Hide resolved

rem1776 added 2 commits February 24, 2026 13:16

add some expanded descriptions and mask_table description

2c79793

add some more information for the types, domains, and helper modules

7b79684

rem1776 marked this pull request as ready for review February 27, 2026 22:01

rem1776 requested review from bensonr and vithikashah001 as code owners February 27, 2026 22:01

rem1776 changed the title ~~update fms2_io module description~~ update fms2_io docs Feb 27, 2026

mlee03 reviewed Mar 3, 2026

View reviewed changes

mlee03 suggested changes Mar 3, 2026

View reviewed changes

address review comments and clean up for linter

088e46f

mlee03 reviewed Mar 4, 2026

View reviewed changes

rem1776 added 2 commits March 5, 2026 13:04

move around module description, add note for collective io in open_file

5760e80

whitespace

7783e2f

mlee03 reviewed Mar 12, 2026

View reviewed changes

mlee03 suggested changes Mar 12, 2026

View reviewed changes

uramirez8707 reviewed Mar 19, 2026

View reviewed changes

rem1776 added 5 commits March 24, 2026 16:35

Fix grammar and clarity in fms2_io comments

1a09206

Refine comments in fms_io_utils.F90 for mask table

3f1e504

Refine documentation for fms_netcdf_domain_io_mod

bde19f8

Revise documentation for fms_netcdf_unstructured_domain_io_mod

5588785

Updated module documentation to clarify usage and purpose.

Refine comments in netcdf_io.F90

3215bb0

Updated comments for clarity and consistency in netcdf_io_mod.

mlee03 approved these changes Mar 26, 2026

View reviewed changes

line length fixes

cc02d32

	cmode = ior(nf90_noclobber, nf90_classic_model)
	cmode = ior(cmode, nf90_diskless)



		!> @brief netcdf domain file type.
		!> @brief Type to represent a netCDF file when using a domain decomposition on a

Conversation

rem1776 commented Feb 12, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mlee03 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mlee03 commented Mar 9, 2026

Uh oh!

rem1776 commented Mar 9, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

uramirez8707 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants