From 866608ac4366d719162f23dbc4bd02e75f04f626 Mon Sep 17 00:00:00 2001 From: Ed Hartnett Date: Fri, 31 May 2019 08:57:56 -0600 Subject: [PATCH 1/3] more documentation changes --- doc/Doxyfile.in | 4 +- doc/source/api.txt | 79 ++++---- src/clib/pio_get_nc.c | 2 +- src/clib/pio_nc.c | 6 +- src/clib/pio_put_nc.c | 2 +- src/clib/pioc.c | 2 +- src/flib/pio.F90 | 4 +- src/flib/pio_nf.F90 | 159 ++++++++-------- src/flib/pio_types.F90 | 65 +++---- src/flib/piodarray.F90.in | 19 +- src/flib/piolib_mod.F90 | 339 ++++++++++++++++++++--------------- src/flib/pionfatt_mod.F90.in | 20 +-- src/flib/pionfget_mod.F90.in | 14 +- src/flib/pionfput_mod.F90.in | 15 +- 14 files changed, 381 insertions(+), 349 deletions(-) diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 6d2684cd385..0f43531ce46 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -771,8 +771,8 @@ WARN_LOGFILE = doxywarn.log INPUT = @CMAKE_CURRENT_SOURCE_DIR@/../doc/source \ @CMAKE_CURRENT_SOURCE_DIR@/../examples/c \ @CMAKE_CURRENT_SOURCE_DIR@/../examples/f03 \ - @C_SRC_FILES@ \ - @FORTRAN_SRC_FILES@ + @FORTRAN_SRC_FILES@ \ + @C_SRC_FILES@ # This tag can be used to specify the character encoding of the source files diff --git a/doc/source/api.txt b/doc/source/api.txt index b6fbed66242..0e36baa82af 100644 --- a/doc/source/api.txt +++ b/doc/source/api.txt @@ -1,57 +1,42 @@ /*! \page api PIO Fortran Interface This is a list of all user interface routines: - \section api_system PIO startup and shutdown routines - - \ref PIO_init - - \ref PIO_finalize - \section api_fileops PIO file Operations - - \ref PIO_openfile - - \ref PIO_createfile - - \ref PIO_syncfile - - \ref PIO_closefile - \section api_decomp PIO decomposition routines - - \ref PIO_initdecomp - - \ref PIO_freedecomp - \section readwrite Reading and Writing distributed variables - - \ref PIO_read_darray - - \ref PIO_write_darray - \section utility Utility routines - - \ref PIO_set_hint - - \ref PIO_setframe - - \ref PIO_advanceframe - - \ref PIO_setdebuglevel - - \ref PIO_seterrorhandling - - \ref PIO_get_local_array_size + \section api_system PIO Startup and Shutdown + - \ref PIO_init + - \ref PIO_finalize - \ref PIO_getnumiotasks - \ref PIO_set_blocksize - \section netcdf NetCDF format specific routines - Also see: http://www.unidata.ucar.edu/software/netcdf/docs/ - \subsection putget Reading/Writing netcdf metadata - - \ref PIO_get_att - - \ref PIO_put_att - - \ref PIO_get_var - - \ref PIO_put_var - \subsection utilnc Netcdf utility routines + - \ref PIO_set_hint + \section api_fileops File Operations + - \ref PIO_openfile + - \ref PIO_createfile + - \ref PIO_syncfile - \ref PIO_enddef - - \ref PIO_redef - - \ref PIO_def_dim - - \ref PIO_def_var - \subsection inqnc NetCDF file inquiry routines + - \ref PIO_closefile + \section inqnc Inquiry - \ref PIO_inquire - - \ref PIO_inq_attname - - \ref PIO_inq_att - - \ref PIO_inq_attlen - - \ref PIO_inquire_variable - - \ref PIO_inq_varid - - \ref PIO_inq_varname - - \ref PIO_inq_vartype - - \ref PIO_inq_varndims - - \ref PIO_inq_vardimid - - \ref PIO_inq_varnatts - - \ref PIO_inq_ndims - - \ref PIO_inq_nvars - - \ref PIO_inq_natts - - \ref PIO_inquire_variable - \ref PIO_inquire_dimension + - \ref PIO_inquire_variable + - \ref PIO_inq_att + \section metadata Defining Metadata + - \ref PIO_def_dim + - \ref PIO_def_var + - \ref PIO_get_att + - \ref PIO_put_att + \section api_decomp Distributed Arrays + - \ref PIO_initdecomp + - \ref PIO_freedecomp + - \ref PIO_setframe + - \ref PIO_read_darray + - \ref PIO_write_darray + - \ref PIO_get_local_array_size + \section standard_arrays Standard Arrays + - \ref PIO_get_var + - \ref PIO_put_var + \section utility Errors + - \ref PIO_seterrorhandling + - \ref PIO_setdebuglevel + +Also see: http://www.unidata.ucar.edu/software/netcdf/docs/ */ diff --git a/src/clib/pio_get_nc.c b/src/clib/pio_get_nc.c index 8b5501ff526..014d523552c 100644 --- a/src/clib/pio_get_nc.c +++ b/src/clib/pio_get_nc.c @@ -12,7 +12,7 @@ #include /** - * @addtogroup PIO_get_var_c Get Data from a Variable + * @addtogroup PIO_get_var_c Get Data from a Variable in C * @{ */ diff --git a/src/clib/pio_nc.c b/src/clib/pio_nc.c index 7e1d077f15d..61d83623600 100644 --- a/src/clib/pio_nc.c +++ b/src/clib/pio_nc.c @@ -2632,7 +2632,8 @@ PIOc_inq_var_fill(int ncid, int varid, int *no_fill, void *fill_valuep) } /** - * @addtogroup PIO_get_att_c Get Attribute Values + * @addtogroup PIO_get_att_c Get Attribute Values in C + * Get the values stored in an attribute. * @{ */ @@ -2924,7 +2925,8 @@ PIOc_get_att_float(int ncid, int varid, const char *name, float *ip) */ /** - * @addtogroup PIO_put_att_c Write an Attribute + * @addtogroup PIO_put_att_c Write an Attribute in C + * Create an attribute. * @{ */ diff --git a/src/clib/pio_put_nc.c b/src/clib/pio_put_nc.c index 6095f33d21f..40285b70109 100644 --- a/src/clib/pio_put_nc.c +++ b/src/clib/pio_put_nc.c @@ -11,7 +11,7 @@ #include /** - * @addtogroup PIO_put_var_c Write Data to a Variable + * @addtogroup PIO_put_var_c Write Data to a Variable in C * @{ */ diff --git a/src/clib/pioc.c b/src/clib/pioc.c index a409bd45a09..7422a45364d 100644 --- a/src/clib/pioc.c +++ b/src/clib/pioc.c @@ -11,7 +11,7 @@ #include /** - * @defgroup PIO_init_c Initialize the IO System + * @defgroup PIO_init_c Initialize the IO System in C * Initialize the IOSystem, including specifying number of IO and * computation tasks. * diff --git a/src/flib/pio.F90 b/src/flib/pio.F90 index 86f2595da49..b4939e29060 100644 --- a/src/flib/pio.F90 +++ b/src/flib/pio.F90 @@ -5,8 +5,8 @@ !< !> -!! @defgroup PIO_set_blocksize PIO_set_blocksize -!! Set the box rearranger blocksize. +!! @defgroup PIO_set_blocksize Box Rearranger Settings +!! Set the box rearranger blocksize in Fortran. module pio ! Package all exposed variables and functions under one roof diff --git a/src/flib/pio_nf.F90 b/src/flib/pio_nf.F90 index 52cf868a874..709cd9a97f5 100644 --- a/src/flib/pio_nf.F90 +++ b/src/flib/pio_nf.F90 @@ -4,53 +4,34 @@ !! @author Jim Edwards !< -!> @defgroup PIO_inquire_dimension Learn About Dimension in Fortran -!! Learn dimension name, ID, or length. +!> @defgroup PIO_inquire_dimension Learn About Dimension +!! Learn dimension name, ID, or length in Fortran. !! -!! @defgroup PIO_inq_ndims PIO_inq_ndims +!! @defgroup PIO_inquire Learn About a File +!! Learn the number of variables, dimensions, global attributes, and +!! the unlimited dimension ID in Fortran. !! -!! @defgroup PIO_inq_nvars PIO_inq_nvars +!! @defgroup PIO_enddef Define Mode +!! End or re-enter define mode in Fortran. !! -!! @defgroup PIO_inq_natts PIO_inq_natts +!! @defgroup PIO_set_log_level Debug Logging +!! Set debugging log level in Fortran. !! -!! @defgroup PIO_inq_unlimdim PIO_inq_unlimdim +!! @defgroup PIO_strerror Error Messages +!! Get the error message from an error in Fortran. !! -!! @defgroup PIO_inquire PIO_inquire +!! @defgroup PIO_def_dim Define a Dimension +!! Define a new dimension, with name and length in Fortran. !! -!! @defgroup PIO_enddef PIO_enddef +!! @defgroup PIO_inquire_variable Learn About a Variable +!! Learn variable name, ID, type, dimensions, compression, chunking in +!! Fortran. !! -!! @defgroup PIO_redef PIO_redef +!! @defgroup PIO_inq_att Learn About an Attribute +!! Learn attribute name, number, type, size in Fortran. !! -!! @defgroup PIO_set_log_level PIO_set_log_level -!! -!! @defgroup PIO_strerror PIO_strerror -!! -!! @defgroup PIO_def_dim PIO_def_dim -!! -!! @defgroup PIO_inquire_variable PIO_inquire_variable -!! -!! @defgroup PIO_inq_vardimid PIO_inq_vardimid -!! -!! @defgroup PIO_inq_varndims PIO_inq_varndims -!! -!! @defgroup PIO_inq_vartype PIO_inq_vartype -!! -!! @defgroup PIO_inq_varnatts PIO_inq_varnatts -!! -!! @defgroup PIO_inq_var_deflate PIO_inq_var_deflate -!! -!! @defgroup PIO_inq_varname PIO_inq_varname -!! -!! @defgroup PIO_inq_varid PIO_inq_varid -!! -!! @defgroup PIO_inq_attlen PIO_inq_attlen -!! -!! @defgroup PIO_inq_att PIO_inq_att -!! -!! @defgroup PIO_inq_attname PIO_inq_attname -!! -!! @defgroup PIO_def_var Define a Variable in Fortran -!! Define a new variable. +!! @defgroup PIO_def_var Define a Variable +!! Define a new variable in Fortran. !< module pio_nf @@ -495,7 +476,7 @@ end function inq_dimname_id !> !! @public - !! @ingroup PIO_inq_ndims + !! @ingroup PIO_inquire !! Get information about the number of dimensions of a file or !! group. !! @@ -512,7 +493,7 @@ end function inq_ndims_desc !> !! @public - !! @ingroup PIO_inq_ndims + !! @ingroup PIO_inquire !! Get information about the number of dimensions of a file or !! group. !! @author Jim Edwards @@ -533,7 +514,7 @@ end function inq_ndims_id !> !! @public - !! @ingroup PIO_inq_nvars + !! @ingroup PIO_inquire !! Get information about the number of variables in a file or group. !! !! @param File @copydoc file_desc_t @@ -548,7 +529,8 @@ integer function inq_nvars_desc(File , nvars) result(ierr) end function inq_nvars_desc !> - !! @ingroup PIO_inq_nvars + !! @public + !! @ingroup PIO_inquire !! Get information about the number of variables in a file or group. !! @author Jim Edwards !< @@ -568,7 +550,7 @@ end function inq_nvars_id !> !! @public - !! @ingroup PIO_inq_natts + !! @ingroup PIO_inquire !! Get information about the number of global attributes in a file !! or group. !! @@ -585,7 +567,7 @@ end function inq_natts_desc !> !! @public - !! @ingroup PIO_inq_natts + !! @ingroup PIO_inquire !! Get information about the number of global attributes in a file !! or group. !! @author Jim Edwards @@ -606,7 +588,7 @@ end function inq_natts_id !> !! @public - !! @ingroup PIO_inq_unlimdm + !! @ingroup PIO_inquire !! Get information about the unlimited dimension in a file. !! !! @param File @copydoc file_desc_t @@ -623,7 +605,7 @@ end function inq_unlimdim_desc !> !! @public - !! @ingroup PIO_inq_unlimdm + !! @ingroup PIO_inquire !! Get information about the unlimited dimension in a file. !! @author Jim Edwards !< @@ -723,7 +705,7 @@ end function enddef_id !> !! @public - !! @ingroup PIO_redef + !! @ingroup PIO_enddef !! Exits netcdf define mode. !! !! @param File @copydoc file_desc_t @@ -786,7 +768,7 @@ end function strerror !> !! @public - !! @ingroup PIO_redef + !! @ingroup PIO_enddef !! Wrapper for the C function \ref PIOc_redef . !! @author Jim Edwards !< @@ -877,6 +859,7 @@ end function PIOc_def_dim end function def_dim_id !> + !! @public !! @ingroup PIO_inquire_variable !! Inquires if a NetCDF variable is present and returns its !! attributes. @@ -905,6 +888,7 @@ integer function inquire_variable_desc(file , vardesc, name, xtype end function inquire_variable_desc !> + !! @public !! @ingroup PIO_inquire_variable !! Inquires if a NetCDF variable is present and returns its !! attributes. @@ -922,6 +906,7 @@ integer function inquire_variable_vid(file , varid, name, xtype, end function inquire_variable_vid !> + !! @public !! @ingroup PIO_inquire_variable !! Inquires if a NetCDF variable is present and returns its !! attributes. @@ -943,7 +928,8 @@ integer function inquire_variable_id(ncid , varid, name, xtype, end function inquire_variable_id !> - !! @ingroup PIO_inq_vardimid + !! @public + !! @ingroup PIO_inquire_variable !! Returns the dimids of the variable as an interger array. !! !! @param File @copydoc file_desc_t @@ -964,7 +950,8 @@ integer function inq_vardimid_desc(File ,vardesc,dimids) resul end function inq_vardimid_desc !> - !! @ingroup PIO_inq_vardimid + !! @public + !! @ingroup PIO_inquire_variable !! Returns the dimids of the variable as an interger array. !! @author Jim Edwards !< @@ -979,7 +966,8 @@ integer function inq_vardimid_vid(File ,varid,dimids) result( end function inq_vardimid_vid !> - !! @ingroup PIO_inq_vardimid + !! @public + !! @ingroup PIO_inquire_variable !! Returns the dimids of the variable as an interger array. !! @author Jim Edwards !< @@ -1011,7 +999,8 @@ end function PIOc_inq_vardimid end function inq_vardimid_id !> - !! @ingroup PIO_inq_varndims + !! @public + !! @ingroup PIO_inquire_variable !! Gets the number of dimension associated with a netcdf variable. !! !! @param File @copydoc file_desc_t @@ -1030,7 +1019,8 @@ integer function inq_varndims_desc(File ,vardesc,ndims) result end function inq_varndims_desc !> - !! @ingroup PIO_inq_varndims + !! @public + !! @ingroup PIO_inquire_variable !! Gets the number of dimension associated with a netcdf variable. !! @author Jim Edwards !< @@ -1044,7 +1034,8 @@ integer function inq_varndims_vid(File ,varid,ndims) result(i end function inq_varndims_vid !> - !! @ingroup PIO_inq_varndims + !! @public + !! @ingroup PIO_inquire_variable !! Gets the number of dimension associated with a netcdf variable. !! @author Jim Edwards !< @@ -1065,7 +1056,8 @@ end function PIOc_inq_varndims end function inq_varndims_id !> - !! @ingroup PIO_inq_vartype + !! @public + !! @ingroup PIO_inquire_variable !! Gets metadata information for netcdf file. !! !! @param File @copydoc file_desc_t @@ -1084,7 +1076,8 @@ integer function inq_vartype_desc(File ,vardesc,type) result( end function inq_vartype_desc !> - !! @ingroup PIO_inq_vartype + !! @public + !! @ingroup PIO_inquire_variable !! Gets metadata information for netcdf file. !! @author Jim Edwards !< @@ -1098,7 +1091,8 @@ integer function inq_vartype_vid(File ,varid,type) result(ie end function inq_vartype_vid !> - !! @ingroup PIO_inq_vartype + !! @public + !! @ingroup PIO_inquire_variable !! Gets metadata information for netcdf file. !! @author Jim Edwards !< @@ -1121,7 +1115,8 @@ end function PIOc_inq_vartype end function inq_vartype_id !> - !! @ingroup PIO_inq_varnatts + !! @public + !! @ingroup PIO_inquire_variable !! Gets metadata information for netcdf file. !! !! @param File @copydoc file_desc_t @@ -1140,7 +1135,8 @@ integer function inq_varnatts_desc(File ,vardesc,natts) result end function inq_varnatts_desc !> - !! @ingroup PIO_inq_varnatts + !! @public + !! @ingroup PIO_inquire_variable !! Gets metadata information for netcdf file. !! @author Jim Edwards !< @@ -1154,7 +1150,8 @@ integer function inq_varnatts_vid(File ,varid,natts) result(i end function inq_varnatts_vid !> - !! @ingroup PIO_inq_varnatts + !! @public + !! @ingroup PIO_inquire_variable !! Gets metadata information for netcdf file. !! @author Jim Edwards !< @@ -1177,7 +1174,8 @@ end function PIOc_inq_varnatts end function inq_varnatts_id !> - !! @ingroup PIO_inq_var_deflate + !! @public + !! @ingroup PIO_inquire_variable !! Gets metadata information for netcdf file. !! !! @param File @copydoc file_desc_t @@ -1201,7 +1199,8 @@ integer function inq_var_deflate_desc(File, vardesc, shuffle, deflate, & end function inq_var_deflate_desc !> - !! @ingroup PIO_inq_var_deflate + !! @public + !! @ingroup PIO_inquire_variable !! Gets metadata information for netcdf file. !! @author Jim Edwards !< @@ -1217,7 +1216,8 @@ integer function inq_var_deflate_vid(File, varid, shuffle, deflate, deflate_leve end function inq_var_deflate_vid !> - !! @ingroup PIO_inq_var_deflate + !! @public + !! @ingroup PIO_inquire_variable !! Gets metadata information for netcdf file. !! @author Jim Edwards !< @@ -1245,7 +1245,8 @@ end function PIOc_inq_var_deflate end function inq_var_deflate_id !> - !! @ingroup PIO_inq_varname + !! @public + !! @ingroup PIO_inquire_variable !! Get the name associated with a variable. !! !! @param File @copydoc file_desc_t @@ -1265,7 +1266,8 @@ integer function inq_varname_desc(File ,vardesc,name) result( end function inq_varname_desc !> - !! @ingroup PIO_inq_varname + !! @public + !! @ingroup PIO_inquire_variable !! Get the name associated with a variable. !! @author Jim Edwards !< @@ -1280,7 +1282,8 @@ integer function inq_varname_vid(File ,varid,name) result(ie end function inq_varname_vid !> - !! @ingroup PIO_inq_varname + !! @public + !! @ingroup PIO_inquire_variable !! Get the name associated with a variable. !! @author Jim Edwards !< @@ -1304,7 +1307,8 @@ end function PIOc_inq_varname end function inq_varname_id !> - !! @ingroup PIO_inq_varid + !! @public + !! @ingroup PIO_inquire_variable !! Returns the ID of a netcdf variable given its name. !! !! @param File @copydoc file_desc_t @@ -1323,7 +1327,8 @@ integer function inq_varid_desc(File,name,vardesc) result(ierr) end function inq_varid_desc !> - !! @ingroup PIO_inq_varid + !! @public + !! @ingroup PIO_inquire_variable !! Returns the ID of a netcdf variable given its name. !! @author Jim Edwards !< @@ -1337,7 +1342,8 @@ integer function inq_varid_vid(File,name,varid) result(ierr) end function inq_varid_vid !> - !! @ingroup PIO_inq_varid + !! @public + !! @ingroup PIO_inquire_variable !! Returns the ID of a netcdf variable given its name. !! @author Jim Edwards !< @@ -1363,7 +1369,8 @@ end function PIOc_inq_varid end function inq_varid_id !> - !! @ingroup PIO_inq_attlen + !! @public + !! @ingroup PIO_inq_att !! Gets the attribute length. !! !! @param File @copydoc file_desc_t @@ -1385,7 +1392,7 @@ integer function inq_attlen_desc(File,vardesc,name,len) result(ierr) end function inq_attlen_desc !> - !! @ingroup PIO_inq_attlen + !! @ingroup PIO_inq_att !! Gets the attribute length. !! @author Jim Edwards !< @@ -1401,7 +1408,7 @@ integer function inq_attlen_vid(File,varid,name,len) result(ierr) end function inq_attlen_vid !> - !! @ingroup PIO_inq_attlen + !! @ingroup PIO_inq_att !! Gets the attribute length. !< integer function inq_attlen_id(ncid,varid,name,len) result(ierr) @@ -1499,7 +1506,7 @@ end function PIOc_inq_att end function inq_att_id !> - !! @ingroup PIO_inq_attname + !! @ingroup PIO_inq_att !! Gets the name of an attribute. !! @author Jim Edwards !< @@ -1514,7 +1521,7 @@ integer function inq_attname_desc(File,vdesc,attnum,name) result(ierr) end function inq_attname_desc !> - !! @ingroup PIO_inq_attname + !! @ingroup PIO_inq_att !! Gets the name of an attribute. !! @author Jim Edwards !< @@ -1529,7 +1536,7 @@ integer function inq_attname_vid(File,varid,attnum,name) result(ierr) end function inq_attname_vid !> - !! @ingroup PIO_inq_attname + !! @ingroup PIO_inq_att !! Gets the name of an attribute. !! @author Jim Edwards !< diff --git a/src/flib/pio_types.F90 b/src/flib/pio_types.F90 index 8e9277e3f22..72c0e3aac4d 100644 --- a/src/flib/pio_types.F90 +++ b/src/flib/pio_types.F90 @@ -3,6 +3,35 @@ !! Derived datatypes and constants for PIO Fortran API. !! !< +!> +!! @private +!! @defgroup iodesc_generate Creating Decompositions +!! Create a decomposition of data from a variable to multiple +!! computation tasks. +!! +!! @public +!! @defgroup PIO_iotype PIO_iotype +!! An integer parameter which controls the iotype. +!! - PIO_iotype_pnetcdf : parallel read/write of pNetCDF files (netcdf3) +!! - PIO_iotype_netcdf : serial read/write of NetCDF files using 'base_node' (netcdf3) +!! - PIO_iotype_netcdf4c : parallel read/serial write of NetCDF4 (HDF5) files with data compression +!! - PIO_iotype_netcdf4p : parallel read/write of NETCDF4 (HDF5) files +!! +!! @defgroup PIO_rearr_method Rearranger Methods +!! Rearranger methods. +!! - PIO_rearr_none : Do not use any form of rearrangement +!! - PIO_rearr_box : Use a PIO internal box rearrangement +!! - PIO_rearr_subset : Use a PIO internal subsetting rearrangement +!! +!! @defgroup PIO_error_method Error Handling Methods +!! The error handling setting controls what happens if errors are +!! encountered by PIO. The three types of error handling methods are: +!! - PIO_INTERNAL_ERROR : abort on error from any task +!! - PIO_BCAST_ERROR : broadcast an error from io_rank 0 to all tasks in comm +!! - PIO_RETURN_ERROR : do nothing - allow the user to handle it +!< +!< + module pio_types use pio_kinds use iso_c_binding @@ -56,14 +85,6 @@ module pio_types end type File_desc_t -!> -!! @private -!! @defgroup iodesc_generate io descriptors, generating -!! @brief The io descriptor structure in defined in this subroutine -!! and subsequently used in @ref PIO_read_darray, @ref PIO_write_darray, -!! @ref PIO_put_var, @ref PIO_get_var calls (see pio_types). -!< - !> !! @public !! @struct io_desc_t @@ -90,16 +111,6 @@ module pio_types integer(i4) :: ncid !< file id end type Var_desc_t -!> -!! @defgroup PIO_iotype PIO_iotype -!! @public -!! @brief An integer parameter which controls the iotype -!! @details -!! - PIO_iotype_pnetcdf : parallel read/write of pNetCDF files (netcdf3) -!! - PIO_iotype_netcdf : serial read/write of NetCDF files using 'base_node' (netcdf3) -!! - PIO_iotype_netcdf4c : parallel read/serial write of NetCDF4 (HDF5) files with data compression -!! - PIO_iotype_netcdf4p : parallel read/write of NETCDF4 (HDF5) files -!> integer(i4), public, parameter :: & PIO_iotype_pnetcdf = 1, & !< parallel read/write of pNetCDF files PIO_iotype_netcdf = 2, & !< serial read/write of NetCDF file using 'base_node' @@ -113,27 +124,9 @@ module pio_types iotype_netcdf = PIO_iotype_netcdf !< netcdf iotype -!> -!! @defgroup PIO_rearr_method PIO_rearr_method -!! @public -!! @brief The three choices to control rearrangement are: -!! @details -!! - PIO_rearr_none : Do not use any form of rearrangement -!! - PIO_rearr_box : Use a PIO internal box rearrangement -!! - PIO_rearr_subset : Use a PIO internal subsetting rearrangement -!< integer(i4), public, parameter :: PIO_rearr_box = 1 !< box rearranger integer(i4), public, parameter :: PIO_rearr_subset = 2 !< subset rearranger -!> -!! @public -!! @defgroup PIO_error_method error_methods -!! @details -!! The three types of error handling methods are: -!! - PIO_INTERNAL_ERROR : abort on error from any task -!! - PIO_BCAST_ERROR : broadcast an error from io_rank 0 to all tasks in comm -!! - PIO_RETURN_ERROR : do nothing - allow the user to handle it -!< integer(i4), public, parameter :: PIO_INTERNAL_ERROR = -51 !< abort on error from any task integer(i4), public, parameter :: PIO_BCAST_ERROR = -52 !< broadcast an error integer(i4), public, parameter :: PIO_RETURN_ERROR = -53 !< do nothing diff --git a/src/flib/piodarray.F90.in b/src/flib/piodarray.F90.in index 2c1ca4115ee..db38e500d68 100644 --- a/src/flib/piodarray.F90.in +++ b/src/flib/piodarray.F90.in @@ -2,6 +2,15 @@ !> !! @file !! Read and write routines for decomposed data. +!> +!! @defgroup PIO_write_darray Write from Distributed Arrays +!! The overloaded PIO_write_darray writes a distributed array to +!! disk in Fortran. +!! +!! @defgroup PIO_read_darray Read to Distributed Arrays +!! The overloaded PIO_read_darray function reads a distributed array +!! from disk in Fortran. +!< module piodarray use pio_types, only : file_desc_t, io_desc_t, var_desc_t use pio_kinds, only : i4, r4, r8, pio_offset_kind @@ -15,11 +24,6 @@ module piodarray private public :: pio_read_darray, pio_write_darray, pio_set_buffer_size_limit - -!> -!! @defgroup PIO_write_darray PIO_write_darray -!! The overloaded PIO_write_darray writes a distributed array to disk. -!< interface PIO_write_darray ! TYPE real,int,double ! DIMS 1,2,3,4,5,6,7 @@ -28,11 +32,6 @@ module piodarray module procedure write_darray_multi_1d_{TYPE} end interface - -!> -!! @defgroup PIO_read_darray PIO_read_darray -!! The overloaded PIO_read_darray function reads a distributed array from disk. -!< interface PIO_read_darray ! TYPE real,int,double ! DIMS 1,2,3,4,5,6,7 diff --git a/src/flib/piolib_mod.F90 b/src/flib/piolib_mod.F90 index 5bfd828f8b3..feb06c83bf5 100644 --- a/src/flib/piolib_mod.F90 +++ b/src/flib/piolib_mod.F90 @@ -6,21 +6,51 @@ !< !> -!! @defgroup PIO_openfile PIO_openfile -!! @defgroup PIO_syncfile PIO_syncfile +!! @defgroup PIO_openfile Open a File +!! Open an existing netCDF file with PIO in Fortran. +!! +!! @defgroup PIO_syncfile Sync File +!! Sync a file to disk, flushing all buffers in Fortran. +!! !! @defgroup PIO_createfile Create a File -!! @defgroup PIO_setframe PIO_setframe -!! @defgroup PIO_advanceframe PIO_advanceframe -!! @defgroup PIO_closefile PIO_closefile -!! @defgroup PIO_freedecomp PIO_freedecomp -!! @defgroup PIO_init PIO_init -!! @defgroup PIO_finalize PIO_finalize -!! @defgroup PIO_initdecomp PIO_initdecomp -!! @defgroup PIO_getnumiotasks PIO_getnumiotasks -!! @defgroup PIO_setdebuglevel PIO_setdebuglevel -!! @defgroup PIO_seterrorhandling PIO_seterrorhandling -!! @defgroup PIO_get_local_array_size PIO_get_local_array_size -!! @defgroup PIO_set_hint PIO_set_hint +!! Create a new netCDF file in Fortran. +!! +!! @defgroup PIO_setframe Set Record Number +!! Set the record number for distributed array reads/writes in +!! Fortran. +!! +!! @defgroup PIO_closefile Close a File +!! Close a netCDF file in Fortran. +!! +!! @defgroup PIO_freedecomp Free a Decomposition +!! Free a decomposition, releasing all resources in Fortran. +!! +!! @defgroup PIO_init Initialize an IOSystem +!! Create a new IO System, designating numbers of I/O and computation +!! tasks in Fortran. +!! +!! @defgroup PIO_finalize Free an IOSystem +!! Free an IO System, releasing all resources in Fortran. +!! +!! @defgroup PIO_initdecomp Define a Decomposition +!! Define a new decomposition of variables to distributed arrays in +!! Fortran. +!! +!! @defgroup PIO_getnumiotasks Get Number IO Tasks +!! Get the number of IO tasks in Fortran. +!! +!! @defgroup PIO_setdebuglevel Internal Debug Settings for Fortran +!! Set the debug level in Fortran. +!! +!! @defgroup PIO_seterrorhandling Error Handling for Fortran +!! Set the behavior if an error is encountered in Fortran. +!! +!! @defgroup PIO_get_local_array_size Get Local Array Size +!! Get the local size of the distributed array in a decomposition in +!! Fortran. +!! +!! @defgroup PIO_set_hint Set MPI Hint +!! Set the MPI hint in Fortran. module piolib_mod use iso_c_binding @@ -28,8 +58,8 @@ module piolib_mod use pio_kinds !-------------- use pio_types, only : file_desc_t, iosystem_desc_t, var_desc_t, io_desc_t, & - pio_iotype_netcdf, pio_iotype_pnetcdf, pio_iotype_netcdf4p, pio_iotype_netcdf4c, & - pio_noerr, pio_rearr_subset, pio_rearr_opt_t + pio_iotype_netcdf, pio_iotype_pnetcdf, pio_iotype_netcdf4p, pio_iotype_netcdf4c, & + pio_noerr, pio_rearr_subset, pio_rearr_opt_t !-------------- use pio_support, only : piodie, debug, debugio, debugasync, checkmpireturn use pio_nf, only : pio_set_log_level @@ -70,10 +100,10 @@ module piolib_mod PIO_set_rearr_opts #ifdef MEMCHK -!> this is an internal variable for memory leak debugging -!! it is used when macro memchk is defined and it causes each task to print the -!! memory resident set size anytime it changes within pio. -!< + !> this is an internal variable for memory leak debugging + !! it is used when macro memchk is defined and it causes each task to print the + !! memory resident set size anytime it changes within pio. + !< integer :: lastrss=0 #endif @@ -87,21 +117,21 @@ module piolib_mod !< interface PIO_openfile module procedure PIO_openfile - end interface + end interface PIO_openfile !> !! Sync the file to disk, flushing all buffers. !< interface PIO_syncfile module procedure syncfile - end interface + end interface PIO_syncfile !> !! Create a new netCDF file with PIO. !< interface PIO_createfile module procedure createfile - end interface + end interface PIO_createfile !> !! Sets the record number for a future read/write of distributed @@ -109,7 +139,7 @@ module piolib_mod !< interface PIO_setframe module procedure setframe - end interface + end interface PIO_setframe !> !! Increment the record number for a future read/write of distributed @@ -117,14 +147,14 @@ module piolib_mod !< interface PIO_advanceframe module procedure advanceframe - end interface + end interface PIO_advanceframe !> !! Close an open file. !< interface PIO_closefile module procedure closefile - end interface + end interface PIO_closefile !> !! Free memory associated with a decomposition. @@ -132,7 +162,7 @@ module piolib_mod interface PIO_freedecomp module procedure freedecomp_ios module procedure freedecomp_file - end interface + end interface PIO_freedecomp !> !! Initializes the PIO subsystem, creating a new IOSystem. @@ -141,14 +171,14 @@ module piolib_mod module procedure init_intracom module procedure init_intercom - end interface + end interface PIO_init !> !! Shuts down an IOSystem and associated resources. !< interface PIO_finalize module procedure finalize - end interface + end interface PIO_finalize !> !! PIO_initdecomp is an overload interface the models decomposition to pio. @@ -168,8 +198,8 @@ module piolib_mod module procedure initdecomp_2dof_bin_i4 module procedure initdecomp_2dof_bin_i8 module procedure PIO_initdecomp_bc -! module procedure PIO_initdecomp_dof_dof - end interface + ! module procedure PIO_initdecomp_dof_dof + end interface PIO_initdecomp !> !! Return the actual number of IO-tasks used. PIO will reset the @@ -177,17 +207,17 @@ module piolib_mod !< interface PIO_get_numiotasks module procedure getnumiotasks - end interface + end interface PIO_get_numiotasks interface PIO_getnumiotasks module procedure getnumiotasks - end interface + end interface PIO_getnumiotasks !> !! Set the level of debug information that PIO will generate. !< interface PIO_setdebuglevel module procedure setdebuglevel - end interface + end interface PIO_setdebuglevel !> !! Set the form of error handling for PIO. @@ -204,7 +234,7 @@ module piolib_mod module procedure seterrorhandlingfile module procedure seterrorhandlingiosystem module procedure seterrorhandlingiosysid - end interface + end interface PIO_seterrorhandling !> !! Get the local size of a distributed array. @@ -242,14 +272,15 @@ end function PIOc_File_is_Open end interface PIO_FILE_IS_OPEN = .false. if(associated(file%iosystem)) then - if(PIOc_File_is_Open(file%fh)==1) then - PIO_FILE_IS_OPEN = .true. - endif + if(PIOc_File_is_Open(file%fh)==1) then + PIO_FILE_IS_OPEN = .true. + endif endif end function PIO_FILE_IS_OPEN !> + !! @public !! @ingroup PIO_get_local_array_size !! Return the expected local size of an array associated with a !! decomposition. @@ -271,7 +302,8 @@ end function PIOc_get_local_array_size end function PIO_get_local_array_size !> - !! @ingroup PIO_advanceframe + !! @public + !! @ingroup PIO_setframe !! Advance the record dimension of a variable in a netcdf format !! file. !! @@ -296,6 +328,7 @@ end function PIOc_advanceframe end subroutine advanceframe !> + !! @public !! @ingroup PIO_setframe !! Set the record dimension of a variable in a netcdf format file !! or the block address in a binary file. @@ -325,6 +358,8 @@ end function PIOc_setframe end subroutine setframe !> + !! @public + !! @public !! @ingroup PIO_setdebuglevel !! Set the level of debug information output to stdout by PIO. !! @@ -365,12 +400,13 @@ subroutine setdebuglevel(level) end if ierr = PIO_set_log_level(level) if(ierr /= PIO_NOERR) then - ! This is not a fatal error - print *, __PIO_FILE__, __LINE__, "Setting log level failed, ierr =",ierr + ! This is not a fatal error + print *, __PIO_FILE__, __LINE__, "Setting log level failed, ierr =",ierr end if end subroutine setdebuglevel !> + !! @public !! @ingroup PIO_seterrorhandling !! Set the pio error handling method for a file. !! @@ -388,6 +424,7 @@ subroutine seterrorhandlingfile(file, method, oldmethod) end subroutine seterrorhandlingfile !> + !! @public !! @ingroup PIO_seterrorhandling !! Set the pio error handling method for a pio system. !! @param iosystem a defined pio system descriptor, see PIO_types @@ -404,6 +441,7 @@ subroutine seterrorhandlingiosystem(iosystem, method, oldmethod) end subroutine seterrorhandlingiosystem !> + !! @public !! @ingroup PIO_seterrorhandling !! Set the pio error handling method for a pio system or globally. !! @@ -435,6 +473,7 @@ end function PIOc_Set_IOSystem_Error_Handling end subroutine seterrorhandlingiosysid !> + !! @public !! @ingroup PIO_initdecomp !! Implements the block-cyclic decomposition for PIO_initdecomp. !! This provides the ability to describe a computational @@ -536,7 +575,7 @@ subroutine initdecomp_2dof_bin_i4(iosystem,basepiotype,dims,lenblocks,compdof,io end subroutine initdecomp_2dof_bin_i4 subroutine initdecomp_2dof_bin_i8(iosystem,basepiotype,dims,lenblocks,compdof,iodofr,iodofw,iodesc) -! use calcdisplace_mod, only : calcdisplace + ! use calcdisplace_mod, only : calcdisplace type (iosystem_desc_t), intent(in) :: iosystem integer(i4), intent(in) :: basepiotype integer(i4), intent(in) :: dims(:) @@ -718,7 +757,6 @@ end subroutine initdecomp_1dof_nf_i8 !> !! @ingroup PIO_initdecomp - !! Implements the degrees of freedom decomposition for !! PIO_initdecomp(). This provides the ability to describe a !! computational decomposition in PIO using degrees of freedom @@ -827,7 +865,7 @@ end function PIOc_InitDecomp maplen, compdof, iodesc%ioid, crearr, C_LOC(cstart), C_LOC(ccount)) deallocate(cstart, ccount) else - ierr = PIOc_InitDecomp(iosystem%iosysid, basepiotype, ndims, cdims, & + ierr = PIOc_InitDecomp(iosystem%iosysid, basepiotype, ndims, cdims, & maplen, compdof, iodesc%ioid, crearr, C_NULL_PTR, C_NULL_PTR) end if @@ -862,6 +900,7 @@ subroutine PIO_initdecomp_dof_i8(iosystem,basepiotype,dims,compdof, iodesc, rear end subroutine PIO_initdecomp_dof_i8 !> + !! @public !! @ingroup PIO_init !! Initialize the pio subsystem. This is a collective call. Input !! parameters are read on comp_rank=0 values on other tasks are @@ -908,7 +947,7 @@ integer(c_int) function PIOc_Init_Intracomm_from_F90(f90_comp_comm, num_iotasks, integer(C_INT), value :: stride integer(C_INT), value :: base integer(C_INT), value :: rearr - type(pio_rearr_opt_t) :: rearr_opts + type(pio_rearr_opt_t) :: rearr_opts integer(C_INT) :: iosysidp end function PIOc_Init_Intracomm_from_F90 end interface @@ -927,6 +966,7 @@ end function PIOc_Init_Intracomm_from_F90 end subroutine init_intracom !> + !! @public !! @ingroup PIO_init !! Initialize the pio subsystem. This is a collective call. Input !! parameters are read on comp_rank=0 values on other tasks are @@ -969,7 +1009,7 @@ subroutine init_intercom(component_count, peer_comm, comp_comms, io_comm, iosyst #endif #if defined(NO_MPI2) || defined(_MPISERIAL) call piodie( __PIO_FILE__,__LINE__, & - 'The PIO async interface requires an MPI2 complient MPI library') + 'The PIO async interface requires an MPI2 complient MPI library') #else do i=1,component_count iosystem(i)%error_handling = PIO_internal_error @@ -1123,16 +1163,16 @@ subroutine init_intercom(component_count, peer_comm, comp_comms, io_comm, iosyst call mpi_info_create(iosystem(i)%info,ierr) ! turn on mpi-io aggregation !DBG print *,'PIO_init: before call to setnumagg' -! itmp = num_aggregator -! call mpi_bcast(itmp, 1, mpi_integer, 0, iosystem%union_comm, ierr) -! if(itmp .gt. 0) then -! write(cb_nodes,('(i5)')) itmp -!#ifdef BGQ -! call PIO_set_hint(iosystem(i),"bgl_nodes_pset",trim(adjustl(cb_nodes))) -!#else -! call PIO_set_hint(iosystem(i),"cb_nodes",trim(adjustl(cb_nodes))) -!#endif -! endif + ! itmp = num_aggregator + ! call mpi_bcast(itmp, 1, mpi_integer, 0, iosystem%union_comm, ierr) + ! if(itmp .gt. 0) then + ! write(cb_nodes,('(i5)')) itmp + !#ifdef BGQ + ! call PIO_set_hint(iosystem(i),"bgl_nodes_pset",trim(adjustl(cb_nodes))) + !#else + ! call PIO_set_hint(iosystem(i),"cb_nodes",trim(adjustl(cb_nodes))) + !#endif + ! endif #ifdef PIO_GPFS_HINTS call PIO_set_hint(iosystem(i),"ibm_largeblock_io","true") @@ -1161,7 +1201,9 @@ subroutine init_intercom(component_count, peer_comm, comp_comms, io_comm, iosyst #endif end subroutine init_intercom - !> @ingroup PIO_set_hint + !> + !! @public + !! @ingroup PIO_set_hint !! Set file system hints using mpi_info_set. This is a collective !! call. !! @@ -1190,6 +1232,7 @@ end function PIOc_set_hint end subroutine PIO_set_hint !> + !! @public !! @ingroup PIO_finalize !! Finalizes an IO System. This is a collective call. !! @@ -1198,8 +1241,8 @@ end subroutine PIO_set_hint !! @author Jim Edwards !< subroutine finalize(iosystem,ierr) - type (iosystem_desc_t), intent(inout) :: iosystem - integer(i4), intent(out) :: ierr + type (iosystem_desc_t), intent(inout) :: iosystem + integer(i4), intent(out) :: ierr interface integer(C_INT) function PIOc_finalize(iosysid) & bind(C,name="PIOc_finalize") @@ -1212,8 +1255,8 @@ end function PIOc_finalize endif end subroutine finalize - !> + !! @public !! @ingroup PIO_getnumiotasks !! Return the number of IO-tasks that PIO is using. !! @@ -1221,52 +1264,53 @@ end subroutine finalize !! @param numiotasks the number of IO-tasks !! @author Jim Edwards !< - subroutine getnumiotasks(iosystem,numiotasks) - type (iosystem_desc_t), intent(in) :: iosystem - integer(i4), intent(out) :: numiotasks - integer :: ierr - interface - integer(C_INT) function PIOc_get_numiotasks(iosysid,numiotasks) & - bind(C,name="PIOc_get_numiotasks") - use iso_c_binding - integer(C_INT), intent(in), value :: iosysid - integer(C_INT), intent(out) :: numiotasks - end function PIOc_get_numiotasks - end interface - ierr = PIOc_get_numiotasks(iosystem%iosysid, numiotasks) - - end subroutine getnumiotasks - - !> Is an iotype available? - logical function pio_iotype_available( iotype) result(available) - integer, intent(in) :: iotype - interface - integer(C_INT) function PIOc_iotype_available(iotype) & - bind(C,name="PIOc_iotype_available") - use iso_c_binding - integer(C_INT), intent(in), value :: iotype - end function PIOc_iotype_available - end interface - available= (PIOc_iotype_available(iotype) == 1) - - end function pio_iotype_available - - !> - !! @ingroup PIO_createfile - !! Create a NetCDF file using PIO. Input parameters are read on - !! comp task 0 and ignored elsewhere. - !! - !! @param iosystem A defined PIO system descriptor created by a - !! call to @ref PIO_init (see PIO_init) - !! @param file The returned file descriptor - !! @param iotype @copydoc PIO_iotype - !! @param fname The name of the file to open - !! @param amode_in The NetCDF creation mode flag - NC_NOWRITE for - !! read-only access or NC_WRITE for read-write access. - !! @retval ierr @copydoc error_return - !! @author Jim Edwards - !< - integer function createfile(iosystem, file,iotype, fname, amode_in) result(ierr) + subroutine getnumiotasks(iosystem,numiotasks) + type (iosystem_desc_t), intent(in) :: iosystem + integer(i4), intent(out) :: numiotasks + integer :: ierr + interface + integer(C_INT) function PIOc_get_numiotasks(iosysid,numiotasks) & + bind(C,name="PIOc_get_numiotasks") + use iso_c_binding + integer(C_INT), intent(in), value :: iosysid + integer(C_INT), intent(out) :: numiotasks + end function PIOc_get_numiotasks + end interface + ierr = PIOc_get_numiotasks(iosystem%iosysid, numiotasks) + + end subroutine getnumiotasks + + !> Is an iotype available? + logical function pio_iotype_available( iotype) result(available) + integer, intent(in) :: iotype + interface + integer(C_INT) function PIOc_iotype_available(iotype) & + bind(C,name="PIOc_iotype_available") + use iso_c_binding + integer(C_INT), intent(in), value :: iotype + end function PIOc_iotype_available + end interface + available= (PIOc_iotype_available(iotype) == 1) + + end function pio_iotype_available + + !> + !! @public + !! @ingroup PIO_createfile + !! Create a NetCDF file using PIO. Input parameters are read on + !! comp task 0 and ignored elsewhere. + !! + !! @param iosystem A defined PIO system descriptor created by a + !! call to @ref PIO_init (see PIO_init) + !! @param file The returned file descriptor + !! @param iotype @copydoc PIO_iotype + !! @param fname The name of the file to open + !! @param amode_in The NetCDF creation mode flag - NC_NOWRITE for + !! read-only access or NC_WRITE for read-write access. + !! @retval ierr @copydoc error_return + !! @author Jim Edwards + !< + integer function createfile(iosystem, file,iotype, fname, amode_in) result(ierr) type (iosystem_desc_t), intent(inout), target :: iosystem type (file_desc_t), intent(out) :: file integer, intent(in) :: iotype @@ -1275,7 +1319,7 @@ integer function createfile(iosystem, file,iotype, fname, amode_in) result(ierr) integer :: mode interface integer(C_INT) function PIOc_createfile(iosysid, fh, iotype, fname,mode) & - bind(C,NAME='PIOc_createfile') + bind(C,NAME='PIOc_createfile') use iso_c_binding implicit none integer(c_int), value :: iosysid @@ -1307,6 +1351,7 @@ end function PIOc_createfile end function createfile !> + !! @public !! @ingroup PIO_openfile !! Open an existing file using PIO. Input parameters are read on !! comp task 0 and ignored elsewhere. @@ -1322,7 +1367,7 @@ end function createfile !< integer function PIO_openfile(iosystem, file, iotype, fname,mode) result(ierr) -! use ifcore, only: tracebackqq + ! use ifcore, only: tracebackqq type (iosystem_desc_t), intent(inout), target :: iosystem type (file_desc_t), intent(out) :: file integer, intent(in) :: iotype @@ -1331,7 +1376,7 @@ integer function PIO_openfile(iosystem, file, iotype, fname,mode) result(ierr) integer :: iorank interface integer(C_INT) function PIOc_openfile(iosysid, fh, iotype, fname,mode) & - bind(C,NAME='PIOc_openfile') + bind(C,NAME='PIOc_openfile') use iso_c_binding implicit none integer(c_int), value :: iosysid @@ -1364,8 +1409,10 @@ end function PIO_openfile !> + !! @public !! @ingroup PIO_syncfile - !! @brief synchronizing a file forces all writes to complete before the subroutine returns. + !! Synchronizing a file, forcing all writes to complete before the + !! subroutine returns. !! !! @param file @copydoc file_desc_t !! @author Jim Edwards @@ -1388,6 +1435,7 @@ end subroutine syncfile !> + !! @public !! @ingroup PIO_freedecomp !! @brief free all allocated storage associated with this decomposition !! @details @@ -1414,9 +1462,10 @@ end subroutine freedecomp_ios !> + !! @public !! @ingroup PIO_freedecomp - !! @brief free all allocated storage associated with this decomposition - !! @details + !! Free all allocated storage associated with this decomposition. + !! !! @param file @copydoc file_desc_t !! @param iodesc : @copydoc io_desc_t !! @retval ierr @copydoc error_return @@ -1435,9 +1484,10 @@ end subroutine freedecomp_file !> + !! @public !! @ingroup PIO_closefile - !! @brief close a disk file - !! @details + !! Close a disk file. + !! !! @param file @copydoc file_desc_t !! @author Jim Edwards !< @@ -1464,9 +1514,10 @@ end subroutine closefile !> + !! @public !! @ingroup PIO_deletefile - !! @brief Delete a file - !! @details + !! Delete a file. + !! !! @param ios a pio system handle !! @param fname a filename !! @author Jim Edwards @@ -1489,6 +1540,7 @@ end function PIOc_deletefile end subroutine pio_deletefile !> + !! @public !! @ingroup PIO_set_rearr_opts !! Set the rerranger options. !! @@ -1507,10 +1559,10 @@ end subroutine pio_deletefile !! @author Jim Edwards !< function pio_set_rearr_opts(ios, comm_type, fcd,& - enable_hs_c2i, enable_isend_c2i,& - max_pend_req_c2i,& - enable_hs_i2c, enable_isend_i2c,& - max_pend_req_i2c) result(ierr) + enable_hs_c2i, enable_isend_c2i,& + max_pend_req_c2i,& + enable_hs_i2c, enable_isend_i2c,& + max_pend_req_i2c) result(ierr) type(iosystem_desc_t), intent(inout) :: ios integer, intent(in) :: comm_type, fcd @@ -1519,34 +1571,33 @@ function pio_set_rearr_opts(ios, comm_type, fcd,& integer, intent(in) :: max_pend_req_c2i, max_pend_req_i2c integer :: ierr interface - integer(c_int) function PIOc_set_rearr_opts(iosysid, comm_type, fcd,& - enable_hs_c2i, enable_isend_c2i,& - max_pend_req_c2i,& - enable_hs_i2c, enable_isend_i2c,& - max_pend_req_i2c)& - bind(C,name="PIOc_set_rearr_opts") - use iso_c_binding - integer(C_INT), intent(in), value :: iosysid - integer(C_INT), intent(in), value :: comm_type - integer(C_INT), intent(in), value :: fcd - logical(C_BOOL), intent(in), value :: enable_hs_c2i - logical(C_BOOL), intent(in), value :: enable_isend_c2i - integer(C_INT), intent(in), value :: max_pend_req_c2i - logical(C_BOOL), intent(in), value :: enable_hs_i2c - logical(C_BOOL), intent(in), value :: enable_isend_i2c - integer(C_INT), intent(in), value :: max_pend_req_i2c - end function PIOc_set_rearr_opts + integer(c_int) function PIOc_set_rearr_opts(iosysid, comm_type, fcd,& + enable_hs_c2i, enable_isend_c2i,& + max_pend_req_c2i,& + enable_hs_i2c, enable_isend_i2c,& + max_pend_req_i2c)& + bind(C,name="PIOc_set_rearr_opts") + use iso_c_binding + integer(C_INT), intent(in), value :: iosysid + integer(C_INT), intent(in), value :: comm_type + integer(C_INT), intent(in), value :: fcd + logical(C_BOOL), intent(in), value :: enable_hs_c2i + logical(C_BOOL), intent(in), value :: enable_isend_c2i + integer(C_INT), intent(in), value :: max_pend_req_c2i + logical(C_BOOL), intent(in), value :: enable_hs_i2c + logical(C_BOOL), intent(in), value :: enable_isend_i2c + integer(C_INT), intent(in), value :: max_pend_req_i2c + end function PIOc_set_rearr_opts end interface ierr = PIOc_set_rearr_opts(ios%iosysid, comm_type, fcd,& - logical(enable_hs_c2i, kind=c_bool),& - logical(enable_isend_c2i, kind=c_bool),& - max_pend_req_c2i,& - logical(enable_hs_i2c, kind=c_bool),& - logical(enable_isend_i2c, kind=c_bool),& - max_pend_req_i2c) + logical(enable_hs_c2i, kind=c_bool),& + logical(enable_isend_c2i, kind=c_bool),& + max_pend_req_c2i,& + logical(enable_hs_i2c, kind=c_bool),& + logical(enable_isend_i2c, kind=c_bool),& + max_pend_req_i2c) end function pio_set_rearr_opts - end module piolib_mod diff --git a/src/flib/pionfatt_mod.F90.in b/src/flib/pionfatt_mod.F90.in index 875779464e0..74b76082ab0 100644 --- a/src/flib/pionfatt_mod.F90.in +++ b/src/flib/pionfatt_mod.F90.in @@ -3,6 +3,15 @@ !! @file !! @brief NetCDF attribute interface to PIO !< +!> +!! @defgroup PIO_put_att Write Attributes +!! Writes an attribute to a file in Fortran. +!< +!> +!! @defgroup PIO_get_att Read Attributes +!! Reads an attribute from a file in Fortran. +!< + module pionfatt_mod use pio_kinds, only : r4, r8, i4, pio_offset_kind use pio_types @@ -36,17 +45,6 @@ module pionfatt_mod module procedure get_att_1d_{TYPE}, get_att_desc_1d_{TYPE}, get_att_1d_id_{TYPE} end interface - !> - !! @public - !! @defgroup PIO_put_att PIO_put_att - !! @brief Writes an netcdf attribute to a file - !< - !> - !! @public - !! @defgroup PIO_get_att PIO_get_att - !! @brief Reads an netcdf attribute from a file - !< - !> @cond doxygen_cant_handle_so_exclude private :: modName character(len=*), parameter :: modName='pionfatt_mod' diff --git a/src/flib/pionfget_mod.F90.in b/src/flib/pionfget_mod.F90.in index f65ebe46687..17fe764b951 100644 --- a/src/flib/pionfget_mod.F90.in +++ b/src/flib/pionfget_mod.F90.in @@ -3,6 +3,13 @@ !! @file !! @brief Read Routines for non-decomposed NetCDF data. !< +!> +!! @defgroup PIO_get_var Read Non-Decomposed Data +!! Reads non-decomposed data from a NetCDF file in Fortran. The +!! get_var interface is provided as a simplified interface to read +!! variables from a NetCDF format file. The variable is read on the +!! root IO task and broadcast in its entirety to all tasks. +!< module pionfget_mod use iso_c_binding #ifdef TIMING @@ -13,13 +20,6 @@ module pionfget_mod use pio_support, only : replace_c_null implicit none private -!> -!! @defgroup PIO_get_var PIO_get_var -!! @brief Reads non-decomposed data from a NetCDF file -!! @details The get_var interface is provided as a simplified interface to -!! read variables from a NetCDF format file. The variable is read on the -!! root IO task and broadcast in its entirety to all tasks. -!< public :: get_var interface get_var module procedure get_var_{DIMS}d_{TYPE}, get_var_vdesc_{DIMS}d_{TYPE} diff --git a/src/flib/pionfput_mod.F90.in b/src/flib/pionfput_mod.F90.in index 81e6661be0f..1ea42af743c 100644 --- a/src/flib/pionfput_mod.F90.in +++ b/src/flib/pionfput_mod.F90.in @@ -3,6 +3,12 @@ !! @file !! @brief Write routines for non-decomposed NetCDF data. !< +!> +!! @defgroup PIO_put_var Write Variable +!! Writes data to a variable. +!! @warning Although this is a collective call the variable is written from the +!! root IO task, no consistancy check is made with data passed on other tasks. +!< module pionfput_mod #ifdef TIMING use perf_mod, only : t_startf, t_stopf ! _EXTERNAL @@ -14,15 +20,6 @@ module pionfput_mod implicit none private -!> -!! @defgroup PIO_put_var PIO_put_var -!! @brief Writes data to a netCDF file. -!! @details The put_var interface is provided as a simplified interface to -!! write variables to a netcdf format file. -!! @warning Although this is a collective call the variable is written from the -!! root IO task, no consistancy check is made with data passed on other tasks. -!! -!< public :: put_var interface put_var ! DIMS 0,1,2,3,4,5 From e901b402d5f4f9c65afabda251a3ec8572b78d54 Mon Sep 17 00:00:00 2001 From: Ed Hartnett Date: Fri, 31 May 2019 10:19:17 -0600 Subject: [PATCH 2/3] more documentation changes --- src/flib/pio_types.F90 | 101 +++++++++++++++++------------------------ 1 file changed, 41 insertions(+), 60 deletions(-) diff --git a/src/flib/pio_types.F90 b/src/flib/pio_types.F90 index 72c0e3aac4d..2519844d8dc 100644 --- a/src/flib/pio_types.F90 +++ b/src/flib/pio_types.F90 @@ -29,7 +29,16 @@ !! - PIO_INTERNAL_ERROR : abort on error from any task !! - PIO_BCAST_ERROR : broadcast an error from io_rank 0 to all tasks in comm !! - PIO_RETURN_ERROR : do nothing - allow the user to handle it -!< +!> +!! @defgroup error_return Error Return Codes +!! The error return code (see @ref PIO_seterrorhandling). +!! +!! @defgroup PIO_kinds PIO Fortran Type Kinds +!! PIO supports different kinds of Fortran types. +!! - PIO_double : 8-byte reals or double precision +!! - PIO_real : 4-byte reals +!! - PIO_int : 4-byte integers +!! - PIO_char : character !< module pio_types @@ -131,37 +140,14 @@ module pio_types integer(i4), public, parameter :: PIO_BCAST_ERROR = -52 !< broadcast an error integer(i4), public, parameter :: PIO_RETURN_ERROR = -53 !< do nothing -!> -!! @public -!! @defgroup PIO_error_method error_methods -!! @details -!! Use this instead of ios to set error handling for the library. -!< integer(i4), public, parameter :: PIO_DEFAULT = -1 !< default error handler -!> -!! @public -!! @defgroup error_return error return codes -!! @brief : The error return code; ierr != PIO_noerr indicates -!! an error. (see @ref PIO_seterrorhandling ) -!> - !> !! @struct use_PIO_kinds !! @brief The type of variable(s) associated with this iodesc. !! @copydoc PIO_kinds !< -!> -!! @public -!! @defgroup PIO_kinds PIO_kinds -!! @brief The base types supported by PIO are: -!! @details -!! - PIO_double : 8-byte reals or double precision -!! - PIO_real : 4-byte reals -!! - PIO_int : 4-byte integers -!! - PIO_char : character -!< #ifdef _PNETCDF #include /* _EXTERNAL */ integer, public, parameter :: PIO_global = nf_global !< global atts @@ -228,54 +214,35 @@ module pio_types #endif integer, public, parameter :: PIO_num_OST = 16 !< num ost -!> -!! @defgroup PIO_rearr_comm_t PIO_rearr_comm_t -!! @public -!! @brief The two choices for rearranger communication -!! @details -!! - PIO_rearr_comm_p2p : Point to point -!! - PIO_rearr_comm_coll : Collective -!> enum, bind(c) enumerator :: PIO_rearr_comm_p2p = 0 enumerator :: PIO_rearr_comm_coll end enum +!> +!! @defgroup PIO_rearr_comm_t Rearranger Communication +!! @public +!! There are two choices for rearranger communication. +!! - PIO_rearr_comm_p2p : Point to point +!! - PIO_rearr_comm_coll : Collective +!> !> !! @defgroup PIO_rearr_comm_dir PIO_rearr_comm_dir !! @public -!! @brief The four choices for rearranger communication direction -!! @details +!! There are four choices for rearranger communication direction. !! - PIO_rearr_comm_fc_2d_enable : COMM procs to IO procs and vice versa !! - PIO_rearr_comm_fc_1d_comp2io: COMM procs to IO procs only !! - PIO_rearr_comm_fc_1d_io2comp: IO procs to COMM procs only !! - PIO_rearr_comm_fc_2d_disable: Disable flow control -!> - enum, bind(c) - enumerator :: PIO_rearr_comm_fc_2d_enable = 0 - enumerator :: PIO_rearr_comm_fc_1d_comp2io - enumerator :: PIO_rearr_comm_fc_1d_io2comp - enumerator :: PIO_rearr_comm_fc_2d_disable - end enum - -!> -!! @defgroup PIO_rearr_comm_fc_options PIO_rearr_comm_fc_options -!! @brief Type that defines the PIO rearranger options -!! @details +!! +!! @defgroup PIO_rearr_comm_fc_options Rearranger Flow Control Options +!! Type that defines the PIO rearranger options. !! - enable_hs : Enable handshake (true/false) !! - enable_isend : Enable Isends (true/false) !! - max_pend_req : Maximum pending requests (To indicated unlimited !! number of requests use PIO_REARR_COMM_UNLIMITED_PEND_REQ) -!> - type, bind(c), public :: PIO_rearr_comm_fc_opt_t - logical(c_bool) :: enable_hs !< Enable handshake? - logical(c_bool) :: enable_isend !< Enable isends? - integer(c_int) :: max_pend_req !< Maximum pending requests - end type PIO_rearr_comm_fc_opt_t - - integer, public, parameter :: PIO_REARR_COMM_UNLIMITED_PEND_REQ = -1 !< unlimited requests -!> -!! @defgroup PIO_rearr_options PIO_rearr_options +!! +!! @defgroup PIO_rearr_options Rearranger Options !! @brief Type that defines the PIO rearranger options !! @details !! - comm_type : @copydoc PIO_rearr_comm_t @@ -283,11 +250,25 @@ module pio_types !! - comm_fc_opts_comp2io : @copydoc PIO_rearr_comm_fc_options !! - comm_fc_opts_io2comp : @copydoc PIO_rearr_comm_fc_options !> + enum, bind(c) + enumerator :: PIO_rearr_comm_fc_2d_enable = 0 !< COMM procs to IO procs and vice versa. + enumerator :: PIO_rearr_comm_fc_1d_comp2io !< COMM procs to IO procs only. + enumerator :: PIO_rearr_comm_fc_1d_io2comp !< IO procs to COMM procs only. + enumerator :: PIO_rearr_comm_fc_2d_disable !< Disable flow control. + end enum + + type, bind(c), public :: PIO_rearr_comm_fc_opt_t + logical(c_bool) :: enable_hs !< Enable handshake. + logical(c_bool) :: enable_isend !< Enable isends. + integer(c_int) :: max_pend_req !< Maximum pending requests (PIO_REARR_COMM_UNLIMITED_PEND_REQ for unlimited). + end type PIO_rearr_comm_fc_opt_t + + integer, public, parameter :: PIO_REARR_COMM_UNLIMITED_PEND_REQ = -1 !< unlimited requests type, bind(c), public :: PIO_rearr_opt_t - integer(c_int) :: comm_type !< comm type - integer(c_int) :: fcd !< Flow control direction - type(PIO_rearr_comm_fc_opt_t) :: comm_fc_opts_comp2io !< comp2io - type(PIO_rearr_comm_fc_opt_t) :: comm_fc_opts_io2comp !< io2comp + integer(c_int) :: comm_type !< Rearranger communication. + integer(c_int) :: fcd !< Communication direction. + type(PIO_rearr_comm_fc_opt_t) :: comm_fc_opts_comp2io !< The comp2io options. + type(PIO_rearr_comm_fc_opt_t) :: comm_fc_opts_io2comp !< The io2comp options. end type PIO_rearr_opt_t public :: PIO_rearr_comm_p2p, PIO_rearr_comm_coll,& From 9b12c1cfee86304b80beedbc3c54284f7e0569ff Mon Sep 17 00:00:00 2001 From: Ed Hartnett Date: Fri, 31 May 2019 10:25:37 -0600 Subject: [PATCH 3/3] gettng closer! --- src/clib/pio_darray.c | 9 +++--- src/clib/pio_file.c | 16 +++++----- src/clib/pio_get_nc.c | 3 +- src/clib/pio_nc.c | 68 +++++++++++++++++++++---------------------- src/clib/pio_put_nc.c | 3 +- src/clib/pioc.c | 42 +++++++++++++------------- 6 files changed, 71 insertions(+), 70 deletions(-) diff --git a/src/clib/pio_darray.c b/src/clib/pio_darray.c index 08316134317..0689634bd1f 100644 --- a/src/clib/pio_darray.c +++ b/src/clib/pio_darray.c @@ -14,12 +14,11 @@ #include /** - * @defgroup PIO_read_darray_c Reading Distributes Arrays in C - * Read data from a netCDF file to a distributed array with the C API. + * @defgroup PIO_read_darray_c Reading Distributes Arrays + * Read data from a netCDF file to a distributed array in C. * - * @defgroup PIO_write_darray_c Writing Distributes Arrays in C - * Write data from a distributed array to a netCDF file with the C - * API. + * @defgroup PIO_write_darray_c Writing Distributes Arrays + * Write data from a distributed array to a netCDF file in C. */ /** 10MB default limit. */ diff --git a/src/clib/pio_file.c b/src/clib/pio_file.c index e3cff3b78fd..f9703a21835 100644 --- a/src/clib/pio_file.c +++ b/src/clib/pio_file.c @@ -8,17 +8,17 @@ #include /** - * @defgroup PIO_open_file_c Open a File in C - * Open an existing netCDF file with PIO with the C API. + * @defgroup PIO_open_file_c Open a File + * Open an existing netCDF file with PIO in C. * - * @defgroup PIO_create_file_c Create a File in C - * Create a new netCDF file with PIO with the C API. + * @defgroup PIO_create_file_c Create a File + * Create a new netCDF file with PIO in C. * - * @defgroup PIO_sync_file_c Sync a File in C - * Flush buffers and sync data to disk with the C API. + * @defgroup PIO_sync_file_c Sync a File + * Flush buffers and sync data to disk in C. * - * @defgroup PIO_close_file_c Close a File in C - * Close a file with the C API. + * @defgroup PIO_close_file_c Close a File + * Close a file in C. * */ diff --git a/src/clib/pio_get_nc.c b/src/clib/pio_get_nc.c index 014d523552c..7b05fe5f607 100644 --- a/src/clib/pio_get_nc.c +++ b/src/clib/pio_get_nc.c @@ -12,7 +12,8 @@ #include /** - * @addtogroup PIO_get_var_c Get Data from a Variable in C + * @addtogroup PIO_get_var_c Read Data + * Read data from a variable in C. * @{ */ diff --git a/src/clib/pio_nc.c b/src/clib/pio_nc.c index 61d83623600..854e943391b 100644 --- a/src/clib/pio_nc.c +++ b/src/clib/pio_nc.c @@ -19,51 +19,51 @@ #include /** - * @defgroup PIO_inq_c Learn About File in C + * @defgroup PIO_inq_c Learn About File * Learn the number of variables, dimensions, and global atts, and the - * unlimited dimension. + * unlimited dimension in C. * - * @defgroup PIO_typelen_c Learn Aboue a Data Type in C - * Learn the length of a data type. + * @defgroup PIO_typelen_c Learn Aboue a Data Type + * Learn the length of a data type in C. * - * @defgroup PIO_inq_format_c Learn About Binary Format in C - * Learn about the binary format. + * @defgroup PIO_inq_format_c Learn About Binary Format + * Learn about the binary format in C. * - * @defgroup PIO_inq_dim_c Learn About a Dimension in C - * Learn dimension name and length. + * @defgroup PIO_inq_dim_c Learn About a Dimension + * Learn dimension name and length in C. * - * @defgroup PIO_inq_var_c Learn About a Variable in C - * Learn variable name, dimensions, and type. + * @defgroup PIO_inq_var_c Learn About a Variable + * Learn variable name, dimensions, and type in C. * - * @defgroup PIO_inq_att_c Learn About an Attribute in C - * Learn length, type, and name of an attribute. + * @defgroup PIO_inq_att_c Learn About an Attribute + * Learn length, type, and name of an attribute in C. * - * @defgroup PIO_rename_dim_c Rename a Dimension in C - * Rename a dimension. + * @defgroup PIO_rename_dim_c Rename a Dimension + * Rename a dimension in C. * - * @defgroup PIO_rename_var_c Rename a Variable in C - * Rename a variable. + * @defgroup PIO_rename_var_c Rename a Variable + * Rename a variable in C. * - * @defgroup PIO_rename_att_c Rename an Attribute in C - * Rename an attribute. + * @defgroup PIO_rename_att_c Rename an Attribute + * Rename an attribute in C. * - * @defgroup PIO_del_att_c Delete an Attribute in C - * Delete an attribute. + * @defgroup PIO_del_att_c Delete an Attribute + * Delete an attribute in C. * - * @defgroup PIO_set_fill_c Set Fill Value in C - * Set the fill value for a variable. + * @defgroup PIO_set_fill_c Set Fill Value + * Set the fill value for a variable in C. * - * @defgroup PIO_enddef_c End Define Mode in C - * End define mode. + * @defgroup PIO_enddef_c End Define Mode + * End define mode in C. * - * @defgroup PIO_redef_c Re-enter Define Mode in C - * Re-enter Define Mode. + * @defgroup PIO_redef_c Re-enter Define Mode + * Re-enter Define Mode in C. * - * @defgroup PIO_def_dim_c Define a Dimension in C - * Define a new dimension in the file. + * @defgroup PIO_def_dim_c Define a Dimension + * Define a new dimension in the file in C. * - * @defgroup PIO_def_var_c Define a Variable in C - * Define a new variable in the file. + * @defgroup PIO_def_var_c Define a Variable + * Define a new variable in the file in C. */ /** @@ -2632,8 +2632,8 @@ PIOc_inq_var_fill(int ncid, int varid, int *no_fill, void *fill_valuep) } /** - * @addtogroup PIO_get_att_c Get Attribute Values in C - * Get the values stored in an attribute. + * @addtogroup PIO_get_att_c Get Attribute Values + * Get the values stored in an attribute in C. * @{ */ @@ -2925,8 +2925,8 @@ PIOc_get_att_float(int ncid, int varid, const char *name, float *ip) */ /** - * @addtogroup PIO_put_att_c Write an Attribute in C - * Create an attribute. + * @addtogroup PIO_put_att_c Write an Attribute + * Create an attribute in C. * @{ */ diff --git a/src/clib/pio_put_nc.c b/src/clib/pio_put_nc.c index 40285b70109..9835f067f84 100644 --- a/src/clib/pio_put_nc.c +++ b/src/clib/pio_put_nc.c @@ -11,7 +11,8 @@ #include /** - * @addtogroup PIO_put_var_c Write Data to a Variable in C + * @addtogroup PIO_put_var_c Write Data + * Write data to a Variable in C. * @{ */ diff --git a/src/clib/pioc.c b/src/clib/pioc.c index 7422a45364d..5e7b51fa895 100644 --- a/src/clib/pioc.c +++ b/src/clib/pioc.c @@ -11,40 +11,40 @@ #include /** - * @defgroup PIO_init_c Initialize the IO System in C + * @defgroup PIO_init_c Initialize the IO System * Initialize the IOSystem, including specifying number of IO and - * computation tasks. + * computation tasks in C. * - * @defgroup PIO_finalize_c Shut Down the IO System in C - * Shut down an IOSystem, freeing all associated resources. + * @defgroup PIO_finalize_c Shut Down the IO System + * Shut down an IOSystem, freeing all associated resources in C. * * @defgroup PIO_initdecomp_c Initialize a Decomposition - * Intiailize a decomposition of data into distributed arrays. + * Intiailize a decomposition of data into distributed arrays in C. * - * @defgroup PIO_freedecomp_c Free a Decomposition in C - * Free a decomposition, and associated resources. + * @defgroup PIO_freedecomp_c Free a Decomposition + * Free a decomposition, and associated resources in C. * - * @defgroup PIO_setframe_c Set the Record Number in C + * @defgroup PIO_setframe_c Set the Record Number * Set the record number for a future call to PIOc_write_darray() or - * PIOc_read_darray(). + * PIOc_read_darray() in C. * - * @defgroup PIO_set_hint_c Set a Hint in C - * Set an MPI Hint. + * @defgroup PIO_set_hint_c Set a Hint + * Set an MPI Hint in C. * - * @defgroup PIO_error_method_c Set Error Handling in C - * Set the error handling method in case error is encountered. + * @defgroup PIO_error_method_c Set Error Handling + * Set the error handling method in case error is encountered in C. * - * @defgroup PIO_get_local_array_size_c Get the Local Size in C - * Get the local size of a distributed array. + * @defgroup PIO_get_local_array_size_c Get the Local Size + * Get the local size of a distributed array in C. * - * @defgroup PIO_iosystem_is_active_c Check IOSystem in C - * Is the IO system active? + * @defgroup PIO_iosystem_is_active_c Check IOSystem + * Is the IO system active (in C)? * - * @defgroup PIO_getnumiotasks_c Get Number IO Tasks in C - * Get the Number of IO Tasks. + * @defgroup PIO_getnumiotasks_c Get Number IO Tasks + * Get the Number of IO Tasks in C. * - * @defgroup PIO_set_blocksize_c Set Blocksize in C - * Set the Blocksize. + * @defgroup PIO_set_blocksize_c Set Blocksize + * Set the Blocksize in C. */ /** The default error handler used when iosystem cannot be located. */