From 1db4b77b2f569d335bf794c62d43191f25cd9207 Mon Sep 17 00:00:00 2001 From: Ryan Mulhall <35538242+rem1776@users.noreply.github.com> Date: Wed, 8 Jun 2022 17:32:18 -0400 Subject: [PATCH] docs: documentation updates (#935) Reorganizes the doxygen site and adds missing pages for certain routines/files --- .github/workflows/update_docs.yml | 8 +- affinity/affinity.c | 9 +- affinity/fms_affinity.F90 | 8 +- amip_interp/amip_interp.F90 | 110 +++-- ...nterp.rey_oi.txt => amip_interp.rey_oi.md} | 7 +- astronomy/astronomy.F90 | 4 - axis_utils/axis_utils.F90 | 6 +- axis_utils/axis_utils2.F90 | 6 +- block_control/block_control.F90 | 3 - column_diagnostics/column_diagnostics.F90 | 3 - constants/constants.F90 | 26 +- coupler/atmos_ocean_fluxes.F90 | 3 - coupler/coupler_types.F90 | 3 - coupler/ensemble_manager.F90 | 3 - data_override/data_override.F90 | 3 - data_override/get_grid_version.F90 | 7 +- diag_integral/diag_integral.F90 | 37 +- diag_manager/diag_axis.F90 | 3 - diag_manager/diag_data.F90 | 3 - diag_manager/diag_grid.F90 | 4 - diag_manager/diag_manager.F90 | 4 +- diag_manager/diag_output.F90 | 3 - diag_manager/diag_table.F90 | 3 - diag_manager/diag_util.F90 | 3 - docs/Doxyfile.in | 23 +- docs/doxygenGuide.md | 29 +- docs/grouping.h | 316 +++++++------- docs/landingPage.md | 22 +- docs/layout.xml | 10 +- drifters/cloud_interpolator.F90 | 6 - drifters/drifters.F90 | 4 - drifters/drifters_comm.F90 | 3 - drifters/drifters_core.F90 | 9 - drifters/drifters_input.F90 | 3 - drifters/drifters_io.F90 | 3 - drifters/quicksort.F90 | 5 +- exchange/stock_constants.F90 | 3 - exchange/xgrid.F90 | 3 - field_manager/field_manager.F90 | 3 - field_manager/fm_util.F90 | 3 - fms/fms.F90 | 3 - fms/fms_io.F90 | 3 - fms/fms_io_unstructured_field_exist.inc | 9 +- fms/fms_io_unstructured_file_unit.inc | 7 +- fms/fms_io_unstructured_get_field_size.inc | 6 +- fms/fms_io_unstructured_get_file_name.inc | 7 +- fms/fms_io_unstructured_get_file_unit.inc | 7 +- fms/fms_io_unstructured_read.inc | 7 +- ..._io_unstructured_register_restart_axis.inc | 9 +- ...io_unstructured_register_restart_field.inc | 9 +- fms/fms_io_unstructured_save_restart.inc | 7 +- fms/fms_io_unstructured_setup_one_field.inc | 7 +- fms2_io/blackboxio.F90 | 3 - fms2_io/fms2_io.F90 | 45 +- fms2_io/fms_io_utils.F90 | 3 - fms2_io/fms_netcdf_domain_io.F90 | 3 - fms2_io/fms_netcdf_unstructured_domain_io.F90 | 3 - fms2_io/include/array_utils.inc | 5 +- fms2_io/include/array_utils_char.inc | 8 +- fms2_io/include/compressed_read.inc | 6 +- fms2_io/include/compressed_write.inc | 6 +- fms2_io/include/compute_global_checksum.inc | 6 +- fms2_io/include/domain_read.inc | 6 +- fms2_io/include/domain_write.inc | 6 +- fms2_io/include/gather_data_bc.inc | 6 +- fms2_io/include/get_data_type_string.inc | 9 +- fms2_io/include/get_global_attribute.inc | 7 +- fms2_io/include/get_variable_attribute.inc | 7 +- .../include/netcdf_add_restart_variable.inc | 7 +- fms2_io/include/netcdf_read_data.inc | 7 +- fms2_io/include/netcdf_write_data.inc | 6 +- .../register_domain_restart_variable.inc | 7 +- fms2_io/include/register_global_attribute.inc | 7 +- ...r_unstructured_domain_restart_variable.inc | 7 +- .../include/register_variable_attribute.inc | 7 +- fms2_io/include/scatter_data_bc.inc | 5 +- fms2_io/include/unstructured_domain_read.inc | 6 +- fms2_io/include/unstructured_domain_write.inc | 7 +- fms2_io/netcdf_io.F90 | 3 - horiz_interp/horiz_interp.F90 | 3 - horiz_interp/horiz_interp_bicubic.F90 | 3 - horiz_interp/horiz_interp_bilinear.F90 | 3 - horiz_interp/horiz_interp_conserve.F90 | 3 - horiz_interp/horiz_interp_spherical.F90 | 3 - horiz_interp/horiz_interp_type.F90 | 3 - interpolator/interpolator.F90 | 3 - memutils/memutils.F90 | 3 - monin_obukhov/monin_obukhov.F90 | 3 - monin_obukhov/monin_obukhov_inter.F90 | 3 - mosaic/gradient.F90 | 3 - mosaic/grid.F90 | 3 - mosaic/mosaic.F90 | 3 - mosaic2/grid2.F90 | 3 - mosaic2/mosaic2.F90 | 3 - mpp/include/mpp_alltoall_mpi.h | 46 +- mpp/include/mpp_alltoall_nocomm.h | 7 +- mpp/include/mpp_chksum.h | 22 +- mpp/include/mpp_chksum_int.h | 11 +- mpp/include/mpp_chksum_scalar.h | 18 +- mpp/include/mpp_comm.inc | 10 +- mpp/include/mpp_comm_mpi.inc | 67 +-- mpp/include/mpp_comm_nocomm.inc | 45 +- mpp/include/mpp_data_mpi.inc | 7 +- mpp/include/mpp_define_nest_domains.inc | 21 +- mpp/include/mpp_do_check.h | 9 +- mpp/include/mpp_do_checkV.h | 7 +- mpp/include/mpp_do_global_field.h | 7 +- mpp/include/mpp_do_global_field_ad.h | 7 +- mpp/include/mpp_do_redistribute.h | 3 + mpp/include/mpp_do_update.h | 5 +- mpp/include/mpp_do_updateV.h | 5 +- mpp/include/mpp_do_updateV_ad.h | 6 +- mpp/include/mpp_do_updateV_nonblock.h | 4 + mpp/include/mpp_do_update_ad.h | 5 +- mpp/include/mpp_do_update_nest.h | 4 +- mpp/include/mpp_do_update_nonblock.h | 3 + mpp/include/mpp_domains_comm.inc | 9 +- mpp/include/mpp_domains_define.inc | 202 ++++----- mpp/include/mpp_domains_misc.inc | 177 ++++---- mpp/include/mpp_domains_reduce.inc | 6 +- mpp/include/mpp_domains_util.inc | 118 ++---- mpp/include/mpp_gather.h | 5 + mpp/include/mpp_get_boundary.h | 7 +- mpp/include/mpp_get_boundary_ad.h | 8 +- mpp/include/mpp_global_field.h | 7 +- mpp/include/mpp_global_field_ad.h | 8 +- mpp/include/mpp_global_field_ug.h | 6 +- mpp/include/mpp_global_reduce.h | 3 + mpp/include/mpp_global_sum.h | 3 + mpp/include/mpp_global_sum_ad.h | 4 +- mpp/include/mpp_global_sum_tl.h | 3 + mpp/include/mpp_group_update.h | 3 + mpp/include/mpp_io_connect.inc | 5 +- mpp/include/mpp_io_misc.inc | 6 +- mpp/include/mpp_io_read.inc | 7 +- mpp/include/mpp_io_unstructured_read.inc | 12 +- mpp/include/mpp_io_unstructured_write.inc | 12 +- mpp/include/mpp_io_util.inc | 30 +- mpp/include/mpp_io_write.inc | 121 +----- mpp/include/mpp_read_distributed_ascii.inc | 6 +- mpp/include/mpp_reduce_mpi.h | 8 +- mpp/include/mpp_reduce_nocomm.h | 8 +- mpp/include/mpp_scatter.h | 42 +- mpp/include/mpp_sum.inc | 35 +- mpp/include/mpp_sum_ad.inc | 35 +- mpp/include/mpp_sum_mpi.h | 9 +- mpp/include/mpp_sum_mpi_ad.h | 11 +- mpp/include/mpp_sum_nocomm.h | 8 +- mpp/include/mpp_sum_nocomm_ad.h | 8 +- mpp/include/mpp_transmit.inc | 5 +- mpp/include/mpp_transmit_mpi.h | 37 +- mpp/include/mpp_transmit_nocomm.h | 30 +- mpp/include/mpp_type_mpi.h | 3 + mpp/include/mpp_unstruct_domain.inc | 15 +- mpp/include/mpp_unstruct_pass_data.h | 12 +- mpp/include/mpp_update_domains2D.h | 11 +- mpp/include/mpp_update_domains2D_ad.h | 11 +- mpp/include/mpp_update_domains2D_nonblock.h | 3 + mpp/include/mpp_update_nest_domains.h | 3 + mpp/include/mpp_util.inc | 399 +++++++----------- mpp/include/mpp_util_mpi.inc | 5 +- mpp/include/mpp_util_nocomm.inc | 17 +- mpp/include/system_clock.h | 11 +- mpp/mpp.F90 | 164 ++++--- mpp/mpp_data.F90 | 3 - mpp/mpp_domains.F90 | 98 ++++- mpp/mpp_efp.F90 | 3 - mpp/mpp_io.F90 | 99 ++++- mpp/mpp_memutils.F90 | 3 - mpp/mpp_parameter.F90 | 3 - mpp/mpp_pset.F90 | 15 +- mpp/mpp_utilities.F90 | 3 - platform/platform.F90 | 3 - random_numbers/mersennetwister.F90 | 3 - random_numbers/random_numbers.F90 | 3 - sat_vapor_pres/sat_vapor_pres.F90 | 3 - sat_vapor_pres/sat_vapor_pres_k.F90 | 3 - time_interp/time_interp.F90 | 3 - time_interp/time_interp_external.F90 | 3 - time_interp/time_interp_external2.F90 | 3 - time_manager/get_cal_time.F90 | 3 - time_manager/time_manager.F90 | 38 +- topography/gaussian_topog.F90 | 3 - topography/topography.F90 | 3 - tracer_manager/tracer_manager.F90 | 3 - tridiagonal/tridiagonal.F90 | 3 - 186 files changed, 1537 insertions(+), 1782 deletions(-) rename amip_interp/{amip_interp.rey_oi.txt => amip_interp.rey_oi.md} (97%) diff --git a/.github/workflows/update_docs.yml b/.github/workflows/update_docs.yml index 0327b8d2b7..aea7b04224 100644 --- a/.github/workflows/update_docs.yml +++ b/.github/workflows/update_docs.yml @@ -12,14 +12,14 @@ jobs: - name: Setup repo run: | # do autotool's job for substitutes since we don't need a full build environement mkdir gen_docs - sed 's/@abs_top_builddir@\/docs/gen_docs/' docs/Doxyfile.in > gen_docs/Doxyfile - sed -i 's/@abs_top_srcdir@/./' gen_docs/Doxyfile + sed 's/@abs_top_builddir@\/docs/gen_docs/g' docs/Doxyfile.in > gen_docs/Doxyfile + sed -i 's/@abs_top_srcdir@/./g' gen_docs/Doxyfile # grab version number from configure.ac export VER="`awk '/AC_INIT/{getline;print}' configure.ac | cut -d "[" -f2 | cut -d "]" -f1`" - sed -i "s/@PACKAGE_VERSION@/$VER/" gen_docs/Doxyfile + sed -i "s/@PACKAGE_VERSION@/$VER/g" gen_docs/Doxyfile - name: Install and run doxygen run: | - sudo apt -y install doxygen + sudo apt -y install doxygen graphviz doxygen gen_docs/Doxyfile - name: Deploy uses: peaceiris/actions-gh-pages@v3 diff --git a/affinity/affinity.c b/affinity/affinity.c index ebdda2cc35..fff6622fb1 100644 --- a/affinity/affinity.c +++ b/affinity/affinity.c @@ -40,12 +40,8 @@ // skips doc parsing for includes and license /** - * \file - * \brief Routines to set and get thread CPU affinity - * Get, set, and helper functions for thread CPU affinity to be interfaced - * in fortran via fms_affinity_mod - * \author @bensonr - * \ingroup affinity + * \addtogroup affinity + * \@{ */ /** @@ -146,3 +142,4 @@ int set_cpu_affinity(int cpu) #endif return 0; } +///@} diff --git a/affinity/fms_affinity.F90 b/affinity/fms_affinity.F90 index c1ded6ab45..c02fbc69cf 100644 --- a/affinity/fms_affinity.F90 +++ b/affinity/fms_affinity.F90 @@ -20,14 +20,11 @@ !> @defgroup fms_affinity_mod fms_affinity_mod !> @ingroup affinity !> @brief Fortran API interfaces to set the thread affinity. -!! API interfaces to allow setting and getting thread affinity. The thread affinity get and set -!! are managed in the C routines in affinity.c. +!! API interfaces to allow setting and getting thread affinity. The routines @ref get_cpuset +!! , @ref set_cpu_affinity , and @ref fms_affinity_get are defined via C routines in affinity.c. !! !! @author Rusty Benson -!> @file -!> File for @ref fms_affinity_mod - !> @addtogroup fms_affinity_mod !> @{ module fms_affinity_mod @@ -49,7 +46,6 @@ module fms_affinity_mod !> Interface to get affinity from the current component. !! !> Defined in @ref affinity.c. - !> @ingroup fms_affinity_mod integer(KIND=c_int) function fms_affinity_get() bind(c, name="get_cpu_affinity") import c_int end function fms_affinity_get diff --git a/amip_interp/amip_interp.F90 b/amip_interp/amip_interp.F90 index 6f77d951ab..931a16a745 100644 --- a/amip_interp/amip_interp.F90 +++ b/amip_interp/amip_interp.F90 @@ -26,10 +26,9 @@ !! !> When using these routines three possible data sets are available: !! -!! 1. AMIP @link http://www-pcmdi.llnl.gov/amip @endlink from Jan 1979 to Jan 1989 (2 deg x 2 deg) -!! 2. Reynolds OI @link amip_interp.rey_oi.txt @endlink from Nov 1981 to Jan 1999 (1 deg x 1 deg) -!! 3. Reynolds EOF @link ftp://podaac.jpl.nasa.gov/pub/sea_surface_temperature/reynolds/rsst/doc/rsst.html -!! @endlink from Jan 1950 to Dec 1998 (2 deg x 2 deg) +!! 1. AMIP http://www.pcmdi.github.io/mips/amip from Jan 1979 to Jan 1989 (2 deg x 2 deg) +!! 2. Reynolds OI @ref amip_interp.rey_oi.txt from Nov 1981 to Jan 1999 (1 deg x 1 deg) +!! 3. Reynolds EOF podaac.jpl.nasa.gov/ from Jan 1950 to Dec 1998 (2 deg x 2 deg) !! !! All original data are observed monthly means. This module !! interpolates linearly in time between pairs of monthly means. @@ -62,10 +61,55 @@ !! amip1 INPUT/amip1_sst.data !! reynolds_io INPUT/reyoi_sst.data !! reynolds_eof INPUT/reynolds_sst.data - - -!> @file -!> File for amip_interp_mod +!! +!> @var character(len=24) data_set +!! Name/type of SST data that will be used. +!! Possible values (case-insensitive) are: +!! 1) amip1 +!! 2) reynolds_eof +!! 3) reynolds_oi +!! See the @ref amip_interp_oi page for more information +!! @var character(len=16) date_out_of_range +!! Controls the use of climatological monthly mean data when +!! the requested date falls outside the range of the data set.
+!! Possible values are: +!! 
+!!   fail      - program will fail if requested date is prior
+!!               to or after the data set period.
+!!   initclimo - program uses climatological requested data is
+!!               prior to data set period and will fail if
+!!               requested date is after data set period.
+!!   climo     - program uses climatological data anytime.
+!!
+!! @var real tice_crit +!! Freezing point of sea water in degC or degK. Defaults to -1.80 +!! @var integer verbose +!! Controls printed output, 0 <= verbose <= 3, default=0 +!! additional parameters for controlling zonal prescribed sst ---- +!! these parameters only have an effect when use_zonal=.true. ---- +!! @var logical use_zonal +!! Flag to selected zonal sst or data set. Default=.false. +!! @var real teq +!! sst at the equator. Default=305 +!! @var real tdif +!! Equator to pole sst difference. Default=50 +!! @var real tann +!! Amplitude of annual cycle. Default=20 +!! @var real tlag +!! Offset for time of year (for annual cycle). Default=0.875 +!! @var integer amip_date +!! Single calendar date in integer "(year,month,day)" format +!! that is used only if set with year>0, month>0, day>0. +!! If used, model calendar date is replaced by this date, +!! but model time of day is still used to determine ice/sst. +!! Used for repeating-single-day (rsd) experiments. +!! Default=/-1,-1,-1/ +!! @var real sst_pert +!! Temperature perturbation in degrees Kelvin added onto the SST. +!! The perturbation is globally-uniform (even near sea-ice). +!! It is only used when abs(sst_pert) > 1.e-4. SST perturbation runs +!! may be useful in accessing model sensitivities. +!! Default=0. !> @addtogroup amip_interp_mod !> @{ @@ -299,56 +343,6 @@ module amip_interp_mod logical :: interp_oi_sst = .false. !< changed to false for regular runs logical :: use_mpp_io = .false. !< Set to .true. to use mpp_io, otherwise fms2io is used -!> @page amip_interp_nml @ref amip_interp_mod Namelist -!! -!> @var character(len=24) data_set -!! Name/type of SST data that will be used. -!! Possible values (case-insensitive) are: -!! 1) amip1 -!! 2) reynolds_eof -!! 3) reynolds_oi -!! See the @ref amip_interp_oi page for more information -!! @var character(len=16) date_out_of_range -!! Controls the use of climatological monthly mean data when -!! the requested date falls outside the range of the data set.
-!! Possible values are: -!! 
-!!   fail      - program will fail if requested date is prior
-!!               to or after the data set period.
-!!   initclimo - program uses climatological requested data is
-!!               prior to data set period and will fail if
-!!               requested date is after data set period.
-!!   climo     - program uses climatological data anytime.
-!!
-!! @var real tice_crit -!! Freezing point of sea water in degC or degK. Defaults to -1.80 -!! @var integer verbose -!! Controls printed output, 0 <= verbose <= 3, default=0 -!! additional parameters for controlling zonal prescribed sst ---- -!! these parameters only have an effect when use_zonal=.true. ---- -!! @var logical use_zonal -!! Flag to selected zonal sst or data set. Default=.false. -!! @var real teq -!! sst at the equator. Default=305 -!! @var real tdif -!! Equator to pole sst difference. Default=50 -!! @var real tann -!! Amplitude of annual cycle. Default=20 -!! @var real tlag -!! Offset for time of year (for annual cycle). Default=0.875 -!! @var integer amip_date -!! Single calendar date in integer "(year,month,day)" format -!! that is used only if set with year>0, month>0, day>0. -!! If used, model calendar date is replaced by this date, -!! but model time of day is still used to determine ice/sst. -!! Used for repeating-single-day (rsd) experiments. -!! Default=/-1,-1,-1/ -!! @var real sst_pert -!! Temperature perturbation in degrees Kelvin added onto the SST. -!! The perturbation is globally-uniform (even near sea-ice). -!! It is only used when abs(sst_pert) > 1.e-4. SST perturbation runs -!! may be useful in accessing model sensitivities. -!! Default=0. namelist /amip_interp_nml/ use_ncep_sst, no_anom_sst, use_ncep_ice, tice_crit, & interp_oi_sst, data_set, date_out_of_range, & use_zonal, teq, tdif, tann, tlag, amip_date, & diff --git a/amip_interp/amip_interp.rey_oi.txt b/amip_interp/amip_interp.rey_oi.md similarity index 97% rename from amip_interp/amip_interp.rey_oi.txt rename to amip_interp/amip_interp.rey_oi.md index 5f3240e529..fb6b57bc5f 100644 --- a/amip_interp/amip_interp.rey_oi.txt +++ b/amip_interp/amip_interp.rey_oi.md @@ -1,9 +1,8 @@ -\file -\ingroup amip_interp +@ingroup amip_interp -(This file was edited for the Flexible Modeling System on July 26, 1999) +## Information for the use of the monthly NMC SST analyzed fields -Information for the use of the monthly NMC SST analyzed fields +(This file was edited for the Flexible Modeling System on July 26, 1999) The monthly optimum interpolation (OI) fields are derived by a linear interpolation of the weekly OI fields to daily fields then averaging diff --git a/astronomy/astronomy.F90 b/astronomy/astronomy.F90 index 890b195425..192fc8f22a 100644 --- a/astronomy/astronomy.F90 +++ b/astronomy/astronomy.F90 @@ -24,10 +24,6 @@ !! radiation packages. !> @author Fei Liu - -!> @file -!> @brief File for @ref astronomy_mod - !> @addtogroup astronomy_mod !> @{ module astronomy_mod diff --git a/axis_utils/axis_utils.F90 b/axis_utils/axis_utils.F90 index 0353c5ae10..3947e370e3 100644 --- a/axis_utils/axis_utils.F90 +++ b/axis_utils/axis_utils.F90 @@ -19,11 +19,11 @@ !> @defgroup axis_utils_mod axis_utils_mod !> @ingroup axis_utils !> @brief A set of utilities for manipulating axes and extracting axis attributes, +!! A more recent version of this module using the updated fms2_io is available, @ref axis_utils2 +!! but this module should be used if still using @ref mpp_io +!! !> @author M.J. Harrison -!> @file -!> @brief File for @ref axis_utils_mod - !> @addtogroup axis_utils_mod !> @{ module axis_utils_mod diff --git a/axis_utils/axis_utils2.F90 b/axis_utils/axis_utils2.F90 index 806e59baa4..3086f3b867 100644 --- a/axis_utils/axis_utils2.F90 +++ b/axis_utils/axis_utils2.F90 @@ -19,13 +19,9 @@ !> @defgroup axis_utils2_mod axis_utils2_mod !> @ingroup axis_utils !> @brief A set of utilities for manipulating axes and extracting axis attributes. -!! -!> FMS2_IO equivalent version of @ref axis_utils_mod. +!! FMS2_IO equivalent version of @ref axis_utils_mod. !> @author M.J. Harrison -!> @file -!> @brief File for @ref axis_utils2_mod - !> @addtogroup axis_utils2_mod !> @{ module axis_utils2_mod diff --git a/block_control/block_control.F90 b/block_control/block_control.F90 index 444cb2f773..ee251087b5 100644 --- a/block_control/block_control.F90 +++ b/block_control/block_control.F90 @@ -21,9 +21,6 @@ !> @brief Routines for "blocks" used for OpenMP threading of column-based !! calculations -!> @file -!> @brief File for @ref block_control_mod - module block_control_mod use mpp_mod, only: mpp_error, NOTE, WARNING, FATAL diff --git a/column_diagnostics/column_diagnostics.F90 b/column_diagnostics/column_diagnostics.F90 index fd4ced5ade..2254f32b6a 100644 --- a/column_diagnostics/column_diagnostics.F90 +++ b/column_diagnostics/column_diagnostics.F90 @@ -20,9 +20,6 @@ !> @ingroup column_diagnostics !! @brief Module to locate and mark desired diagnostic columns -!> @file -!> @brief File for @ref column_diagnostics_mod - !> @addtogroup column_diagnostics_mod !> @{ module column_diagnostics_mod diff --git a/constants/constants.F90 b/constants/constants.F90 index 4332af986b..d3d8887a32 100644 --- a/constants/constants.F90 +++ b/constants/constants.F90 @@ -16,13 +16,35 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @file +!> @brief File for @ref constants_mod + !> @defgroup constants_mod constants_mod !> @ingroup constants !> @brief compatibility module as we transition to an FMSConstants module !! -!> @file -!> @brief File for @ref constants_mod +!> Constants have been declared as type REAL, PARAMETER. +!! +!! The value a constant can not be changed in a users program. +!! New constants can be defined in terms of values from the +!! constants module using a parameter statement.

+!! +!! The name given to a particular constant may be changed.

+!! +!! Constants can be used on the right side on an assignment statement +!! (their value can not be reassigned). +!! +!! Example: +!! +!! @verbatim +!! use constants_mod, only: TFREEZE, grav_new => GRAV +!! real, parameter :: grav_inv = 1.0 / grav_new +!! tempc(:,:,:) = tempk(:,:,:) - TFREEZE +!! geopotential(:,:) = height(:,:) * grav_new +!! @endverbatim +!> @addtogroup constants_mod +!> @{ module constants_mod !> rename to not conflict with any other version vars diff --git a/coupler/atmos_ocean_fluxes.F90 b/coupler/atmos_ocean_fluxes.F90 index e0a8147fd1..6e530abfaf 100644 --- a/coupler/atmos_ocean_fluxes.F90 +++ b/coupler/atmos_ocean_fluxes.F90 @@ -37,9 +37,6 @@ !! !! http://ocmip5.ipsl.fr/documentation/OCMIP/phase2/simulations/Biotic/HOWTO-Biotic.html -!> @file -!> @brief File for @ref atmos_ocean_fluxes_mod - !> @addtogroup atmos_ocean_fluxes_mod !> @{ module atmos_ocean_fluxes_mod diff --git a/coupler/coupler_types.F90 b/coupler/coupler_types.F90 index 1ab166601f..ab3f9ba3a4 100644 --- a/coupler/coupler_types.F90 +++ b/coupler/coupler_types.F90 @@ -21,9 +21,6 @@ !> @brief This module contains type declarations for the coupler. !> @author Richard Slater, John Dunne -!> @file -!> @brief File for @ref coupler_types_mod - !> @addtogroup coupler_types_mod !> @{ module coupler_types_mod diff --git a/coupler/ensemble_manager.F90 b/coupler/ensemble_manager.F90 index 5290a01f87..944e859455 100644 --- a/coupler/ensemble_manager.F90 +++ b/coupler/ensemble_manager.F90 @@ -20,9 +20,6 @@ !> @ingroup coupler !> @brief Routines for setting up and managing ensembles and ensemble pe lists. -!> @file -!> @brief File for @ref ensemble_manager_mod - !> @addtogroup ensemble_manager_mod !> @{ module ensemble_manager_mod diff --git a/data_override/data_override.F90 b/data_override/data_override.F90 index 0d1ace3845..61550b242f 100644 --- a/data_override/data_override.F90 +++ b/data_override/data_override.F90 @@ -36,9 +36,6 @@ !! A field can be overriden globally (by default) or users can specify one or two regions in which !! data_override will take place, field values outside the region will not be affected. -!> @file -!> @brief File for @ref data_override_mod - module data_override_mod use yaml_parser_mod use constants_mod, only: PI diff --git a/data_override/get_grid_version.F90 b/data_override/get_grid_version.F90 index 7a035a9bbd..a5b5f2370a 100644 --- a/data_override/get_grid_version.F90 +++ b/data_override/get_grid_version.F90 @@ -16,12 +16,9 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** -!> @defgroup get_grid_version_fms2_io_mod get_grid_version_fms2_io_mod +!> @defgroup get_grid_version_mod get_grid_version_mod !> @ingroup data_override -!> @brief fms2_io implementations of grid routines for @ref data_override_mod - -!> @file -!> @brief File for @ref get_grid_version_mod +!> @brief get_grid implementations and helper routines for @ref data_override_mod !> @addtogroup get_grid_version_mod !> @{ diff --git a/diag_integral/diag_integral.F90 b/diag_integral/diag_integral.F90 index b280e7880b..c47940d9d3 100644 --- a/diag_integral/diag_integral.F90 +++ b/diag_integral/diag_integral.F90 @@ -16,7 +16,6 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** - !> @defgroup diag_integral_mod diag_integral_mod !> @ingroup diag_integral !! @@ -24,42 +23,8 @@ !! !! @brief This module computes and outputs global and / or hemispheric physics !! integrals. -!! -!! Public Interfaces: -!! -!! - sum_diag_integral_field -!! -!! Public Subroutines: -!! -!! - diag_integral_init -!! - diag_integral_field_init -!! - diag_integral_output -!! - diag_integral_end -!! - sum_field_2d -!! - sum_field_3d -!! - sum_field_wght_3d -!! - sum_field_2d_hemi -!! -!! Private Functions: -!! -!! - set_axis_time -!! - get_field_index -!! - get_axis_time -!! - diag_integral_alarm -!! - vert_diag_integral -!! -!! Private Subroutines: -!! -!! - write_field_averages -!! - format_text_init -!! - format_data_init -!! - -!> @file -!! @brief File for @ref diag_integral_mod - - module diag_integral_mod +module diag_integral_mod !############################################################################### diff --git a/diag_manager/diag_axis.F90 b/diag_manager/diag_axis.F90 index fea049decf..4519f7f82c 100644 --- a/diag_manager/diag_axis.F90 +++ b/diag_manager/diag_axis.F90 @@ -26,9 +26,6 @@ !! Users first create axis ID by calling diag_axis_init, then use this axis ID in !! register_diag_field. -!> @file -!> @brief File for @ref diag_axis_mod - !> @addtogroup diag_axis_mod !> @{ MODULE diag_axis_mod diff --git a/diag_manager/diag_data.F90 b/diag_manager/diag_data.F90 index 21218070d5..486930940d 100644 --- a/diag_manager/diag_data.F90 +++ b/diag_manager/diag_data.F90 @@ -43,9 +43,6 @@ !! field with the input_field index, and to the output file with the output_file !! index. -!> @file -!> @brief File for @ref diag_data_mod - !> @addtogroup diag_data_mod !> @{ MODULE diag_data_mod diff --git a/diag_manager/diag_grid.F90 b/diag_manager/diag_grid.F90 index 887361eb71..39f9a8a0e9 100644 --- a/diag_manager/diag_grid.F90 +++ b/diag_manager/diag_grid.F90 @@ -16,7 +16,6 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** - !> @defgroup diag_grid_mod diag_grid_mod !> @ingroup diag_manager !> @brief diag_grid_mod is a set of procedures to work with the @@ -37,9 +36,6 @@ !! is to be called by the diag_manager_mod to discover the !! global indexes defining a subregion on the tile. -!> @file -!> @brief File for @ref diag_grid_mod - MODULE diag_grid_mod use platform_mod diff --git a/diag_manager/diag_manager.F90 b/diag_manager/diag_manager.F90 index f4a45fdfd0..4660e282f8 100644 --- a/diag_manager/diag_manager.F90 +++ b/diag_manager/diag_manager.F90 @@ -134,17 +134,17 @@ !!
  • When namelist variable debug_diag_manager = .true. array !! bounds are checked in @ref send_data.
    • !!
  • Coordinate attributes can be written in the output file if the -!! argument "aux" is given in @ref diag_axis_mod#diag_axis_init . The +!! argument "aux" is given in @ref diag_axis_mod#diag_axis_init . The !! corresponding fields (geolat/geolon) should also be written to the !! same file.
    • !! !> @file +!> @ingroup diag_manager_mod !> @brief File for @ref diag_manager_mod MODULE diag_manager_mod use platform_mod - ! ! ! diff --git a/diag_manager/diag_output.F90 b/diag_manager/diag_output.F90 index b9638f5d65..ff2042f599 100644 --- a/diag_manager/diag_output.F90 +++ b/diag_manager/diag_output.F90 @@ -23,9 +23,6 @@ !! field-meta-data and field data. !! @author Seth Underwood -!> @file -!> @brief File for @ref diag_output_mod - !> @addtogroup diag_output_mod !> @{ MODULE diag_output_mod diff --git a/diag_manager/diag_table.F90 b/diag_manager/diag_table.F90 index 3813488f97..7a23493657 100644 --- a/diag_manager/diag_table.F90 +++ b/diag_manager/diag_table.F90 @@ -247,9 +247,6 @@ !! !! -!> @file -!> @brief File for @ref diag_table_mod - MODULE diag_table_mod USE fms2_io_mod, ONLY: ascii_read diff --git a/diag_manager/diag_util.F90 b/diag_manager/diag_util.F90 index de34c14abb..ee08cdd5f5 100644 --- a/diag_manager/diag_util.F90 +++ b/diag_manager/diag_util.F90 @@ -21,9 +21,6 @@ !! @brief Functions and subroutines necessary for the diag_manager_mod. !! @author Seth Underwood -!> @file -!> @brief File for @ref diag_util_mod - MODULE diag_util_mod use platform_mod diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 63ac4a5084..df7e8596db 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -294,7 +294,7 @@ OPTIMIZE_OUTPUT_VHDL = NO # Note that for custom extensions you also need to set FILE_PATTERNS otherwise # the files are not read by doxygen. -EXTENSION_MAPPING = F90=FortranFree inc=FortranFree +EXTENSION_MAPPING = F90=FortranFree inc=FortranFree h=FortranFree # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments # according to the Markdown format, which allows for more readable @@ -390,7 +390,7 @@ SUBGROUPING = YES # SEPARATE_MEMBER_PAGES. # The default value is: NO. -INLINE_GROUPED_CLASSES = NO +INLINE_GROUPED_CLASSES = YES # When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions # with only public data fields or simple typedef fields will be shown inline in @@ -581,7 +581,7 @@ SORT_MEMBER_DOCS = YES # this will also influence the order of the classes in the class list. # The default value is: NO. -SORT_BRIEF_DOCS = NO +SORT_BRIEF_DOCS = YES # If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the # (brief and detailed) documentation of class members so that constructors and @@ -676,7 +676,7 @@ SHOW_USED_FILES = YES # (if specified). # The default value is: YES. -SHOW_FILES = YES +SHOW_FILES = NO # Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces # page. This will remove the Namespaces entry from the Quick Index and from the @@ -693,7 +693,8 @@ SHOW_NAMESPACES = NO # by doxygen. Whatever the program writes to standard output is used as the file # version. For an example see the documentation. -FILE_VERSION_FILTER = "/bin/sh doxygen_version_filter.sh" +# Version will be last commit hash for a file +FILE_VERSION_FILTER = "git log --format='%H' -1" # The LAYOUT_FILE tag can be used to specify a layout file which will be parsed # by doxygen. The layout file controls the global structure of the generated @@ -833,7 +834,7 @@ RECURSIVE = YES # run. # leave contributing info on github, keep build instructions and readme -EXCLUDE = CHANGELOG.md LICENSE.md CONTRIBUTING.md CODE_STYLE.md CODE_OF_CONDUCT.md +EXCLUDE = CHANGELOG.md LICENSE.md CONTRIBUTING.md CODE_STYLE.md CODE_OF_CONDUCT.md test_fms CI.md # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -2015,7 +2016,7 @@ SEARCH_INCLUDES = YES # preprocessor. # This tag requires that the tag SEARCH_INCLUDES is set to YES. -INCLUDE_PATH = ./fms2_io/include +INCLUDE_PATH = @abs_top_srcdir@/mpp/include @abs_top_srcdir@/fms2_io @abs_top_srcdir@/fms # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard # patterns (like *.h and *.hpp) to filter out the header-files in the @@ -2023,7 +2024,7 @@ INCLUDE_PATH = ./fms2_io/include # used. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -INCLUDE_FILE_PATTERNS = *.inc +INCLUDE_FILE_PATTERNS = *.h *.inc # The PREDEFINED tag can be used to specify one or more macro names that are # defined before the preprocessor is started (similar to the -D option of e.g. @@ -2111,7 +2112,7 @@ EXTERNAL_PAGES = YES # powerful graphs. # The default value is: YES. -CLASS_DIAGRAMS = NO +CLASS_DIAGRAMS = YES # You can include diagrams made with dia in doxygen documentation. Doxygen will # then run dia to produce the diagram and insert it in the documentation. The @@ -2133,7 +2134,7 @@ HIDE_UNDOC_RELATIONS = NO # set to NO # The default value is: NO. -HAVE_DOT = NO +HAVE_DOT = YES # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed # to run in parallel. When set to 0 doxygen will base this on the number of @@ -2191,7 +2192,7 @@ COLLABORATION_GRAPH = YES # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -GROUP_GRAPHS = YES +GROUP_GRAPHS = NO # If the UML_LOOK tag is set to YES, doxygen will generate inheritance and # collaboration diagrams in a style similar to the OMG's Unified Modeling diff --git a/docs/doxygenGuide.md b/docs/doxygenGuide.md index 76062fee07..2b5413ada3 100644 --- a/docs/doxygenGuide.md +++ b/docs/doxygenGuide.md @@ -1,6 +1,6 @@ -# Documentation Style Guide +# Documentation Style and Building Guide -Best practices for documenting FMS code with Doxygen. +Best practices for documenting FMS code with Doxygen, as well as instructions for generating the site. ### Basics @@ -36,8 +36,8 @@ Simple subroutine/function documentation: @code{.F90} !> description !! continued description -function foo() - integer :: bar !< variable description +function foo(bar) + integer, intent(inout) :: bar !< argument description ... @endcode @@ -119,3 +119,24 @@ end type typename !> @{ ... @endcode + + +### Generating the Doxygen Site + +The site can be generated from the source code either manually (must have doxygen installed), +or through a github action. + +To generate it manually from the repository: +``` +autoreconf -it +./configure --enable-docs +make -C docs +``` + +To have the site generated through a github action, you can go to the *Actions* tab +on your forked FMS repository. From there you can click on *Select Workflow* and select the +*Generate and deploy documentationon GH pages* action. This will show all previous runs, and will +display a button to run the doxygen workflow on whichever branch is desired. After completion, the page will be available at: +\.github.io/FMS + +If not available, settings for the site can be found in the forked repositories *Settings* tab, under *Pages*. diff --git a/docs/grouping.h b/docs/grouping.h index 2ab27141ca..2cefac675c 100644 --- a/docs/grouping.h +++ b/docs/grouping.h @@ -1,170 +1,146 @@ -/** - * GNU Lesser General Public License - * - * This file is part of the GFDL Flexible Modeling System (FMS). - * - * FMS is free software: you can redistribute it and!or modify it under - * the terms of the GNU Lesser General Public License as published by - * the Free Software Foundation, either version 3 of the License, or (at - * your option) any later version. - * - * FMS is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * for more details. - * - * You should have received a copy of the GNU Lesser General Public - * License along with FMS. If not, see . - ********************************************************************* - */ - -// This header file is used exclusively for doxygen documentation -// Defines groups for each subdirectory to add their modules into -// Additional doxygen pages can be added here as well - -/** @defgroup affinity Affinity - * - */ - -/** @defgroup astronomy Astronomy - * - */ - -/** @defgroup axis_utils Axis Utilities - * - */ - -/** @defgroup amip_interp AMIP Interpolator - * - */ - -/** @defgroup block_control Block Control - * - */ - -/** @defgroup column_diagnostics Column Diagnostics - * - */ - -/** @defgroup constants Constants - * - */ - -/** @defgroup coupler Coupler - * - */ - -/** @defgroup data_override Data Override - * - */ - -/** @defgroup diag_integral Diag Integral - * - */ - -/** @defgroup diag_manager Diag Manager - * - */ - -/** @defgroup drifters Drifters - * - */ - -/** @defgroup exchange Exchange - * - */ - -/** @defgroup field_manager Field Manager - * - */ - -/** @defgroup fms FMS - * - */ - -/** @defgroup fms2_io FMS2 IO - * - */ - -/** @defgroup horiz_interp Horizontal Interpolator - * - */ - -/** @defgroup interpolator Interpolator - * - */ - -/** @defgroup memutils Memory Utilities - * - */ - -/** @defgroup monin_obukhov Monin Obukhov - * - */ - -/** @defgroup mosaic Mosaic - * - */ - -/** @defgroup mosaic2 Mosaic2 - * - */ - -/** @defgroup mpp MPP - * - */ - -/** @defgroup parser Parser - * - */ - -/** @defgroup platform Platform - * - */ - -/** @defgroup random_numbers Random Numbers - * - */ - -/** @defgroup sat_vapor_pres Saturation Vapor Pressure - * - */ - -/** @defgroup string_utils String Utils - * - */ - -/** @defgroup time_interp Time Interpolator - * - */ - -/** @defgroup time_manager Time Manager - * - */ - -/** @defgroup topography Topography - * - */ - -/** @defgroup tracer_manager Tracer Manager - * - */ - -/** @defgroup tridiagonal Tridiagonal - * - */ - -/** @defgroup libfms FMS Global Module - * - */ - -/** @page build Building and Installation - * @brief Information about the build systems and how to build and install - * - * @subpage install - * - * @subpage autotools - * - * @subpage cmake - * - */ +!*********************************************************************** +!* GNU Lesser General Public License +!* +!* This file is part of the GFDL Flexible Modeling System (FMS). +!* +!* FMS is free software: you can redistribute it and/or modify it under +!* the terms of the GNU Lesser General Public License as published by +!* the Free Software Foundation, either version 3 of the License, or (at +!* your option) any later version. +!* +!* FMS is distributed in the hope that it will be useful, but WITHOUT +!* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +!* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +!* for more details. +!* +!* You should have received a copy of the GNU Lesser General Public +!* License along with FMS. If not, see . +!*********************************************************************** +!! This header file is used exclusively for doxygen documentation +!! Defines groups for each subdirectory to add their modules into +!! Additional doxygen pages can be added here as well + +!> @defgroup affinity Affinity +!> @brief Modules and associated files in the affinity directory + +!> @defgroup astronomy Astronomy +!> @brief Modules and associated files in the astronomy directory + +!> @defgroup axis_utils Axis Utilities +!> @brief Modules and associated files in the axis_utils directory + +!> @defgroup amip_interp AMIP Interpolator +!> @brief Modules and associated files in the amip_interp directory + +!> @defgroup block_control Block Control +!> @brief Modules and associated files in the block_control directory + +!> @defgroup column_diagnostics Column Diagnostics +!> @brief Modules and associated files in the column_diagnostics directory + +!> @defgroup constants Constants +!> @brief Modules and associated files in the constants directory + +!> @defgroup coupler Coupler +!> @brief Modules and associated files in the coupler directory + +!> @defgroup data_override Data Override +!> @brief Modules and associated files in the data_override directory + +!> @defgroup diag_integral Diag Integral +!> @brief Modules and associated files in the diag_integral directory + +!> @defgroup diag_manager Diag Manager +!> @brief Modules and associated files in the diag_manager directory. +!! See below for additional information on diag_tables. + +!> @defgroup drifters Drifters +!> @brief Modules and associated files in the drifters directory + +!> @defgroup exchange Exchange +!> @brief Modules and associated files in the exchange directory + +!> @defgroup field_manager Field Manager +!> @brief Modules and associated files in the field_manager directory + +!> @defgroup fms FMS +!> @brief Modules and associated files in the fms directory + +!> @defgroup fms2_io FMS2 IO +!> @brief Modules and associated files in the fms2_io directory +!! +!> Updated IO modules for parallel IO via netcdf files. Replaces the functionality of the IO +!! routines in mpp_io. fms2_io_mod is the main module for external usage and provides public +!! interfaces for routines defined throughout this directory, dependent on the +!! type of file. + +!> @defgroup horiz_interp Horizontal Interpolator +!> @brief Modules and associated files in the horiz_interp directory + +!> @defgroup interpolator Interpolator +!> @brief Modules and associated files in the interpolator directory + +!> @defgroup memutils Memory Utilities +!> @brief Modules and associated files in the memutils directory + +!> @defgroup monin_obukhov Monin Obukhov +!> @brief Modules and associated files in the monin_obukhov directory + +!> @defgroup mosaic Mosaic +!> @brief Modules and associated files in the mosaic directory + +!> @defgroup mosaic2 Mosaic2 +!> @brief Modules and associated files in the mosaic2 directory +!! +!> Provides a fms2_io equivalent to the mpp_io dependent routines in mosaic + +!> @defgroup mpp MPP +!> @brief Modules and associated files in the mpp directory +!! +!> Provides interfaces to facilitate common tasks for parallel computing and +!! modeling. Originally written to provide interfaces across different message-passing libraries, +!! it is now used mainly with the MPI standard, and provides wrappers to many MPI +!! routines. Documentation on serial implementations of routines (usually denoted by _nocommm in +!! the file name) will be excluded on these module pages, as they are currently unused but mo, but their documentation is still +!! available in the Files tab. + +!> @defgroup platform Platform +!> @brief Modules and associated files in the platform directory + +!> @defgroup random_numbers Random Numbers +!> @brief Modules and associated files in the random_numbers directory + +!> @defgroup sat_vapor_pres Saturation Vapor Pressure +!> @brief Modules and associated files in the sat_vapor_pres directory + +!> @defgroup time_interp Time Interpolator +!> @brief Modules and associated files in the time_interp directory + +!> @defgroup time_manager Time Manager +!> @brief Modules and associated files in the time_manager directory + +!> @defgroup topography Topography +!> @brief Modules and associated files in the topography directory + +!> @defgroup string_utils String Utils +!> @brief Modules and associated files in the string_utils directory + +!> @defgroup tracer_manager Tracer Manager +!> @brief Modules and associated files in the tracer_manager directory + +!> @defgroup tridiagonal Tridiagonal +!> @brief Modules and associated files in the tridiagonal directory + +!> @defgroup libfms FMS Global Module +!> @brief Modules and associated files in the libfms directory + +!> @defgroup parser Parser +!> @brief Modules and associated files for the yaml parser + +!> @page build Building and Installation +!> @brief Information about the build systems and how to build and install +!! @subpage install +!! +!! @subpage autotools +!! +!! @subpage cmake diff --git a/docs/landingPage.md b/docs/landingPage.md index 2f3da1d013..805506f129 100644 --- a/docs/landingPage.md +++ b/docs/landingPage.md @@ -2,13 +2,27 @@ This is the documentation homepage for the Flexible Modeling System(FMS), a software environment built for supporting atmospheric, oceanic, and climate system models on high-end computing architectures. + +### API Documentation +All interfaces, routines, derived type, and variable documentation for FMS can be found by parent +module in the 'Modules' section, or also linked [**here**](modules.html). + +Additionally, all interfaces and derived types are listed by name and module [**here**](annotated.html). + + +### Project Information For more general information on FMS, it's uses, scope, and licensing, please see the project's description page @ref rm "here". -For documentation on the FMS codebase, a top level view of all modules by subdirectory can be -found in the 'Modules' section in the sidebar, or linked [**here**](modules.html). + +### Building and Installation For installation and building instructions and information, see @ref build "Building and Installation" -To contribute, all project code and contributing information can be found at . -Additionaly, please see the documentation style guide [**here**](md_docs_doxygenGuide.html) for how to document FMS code for this site. + + +### Contribution +To contribute, all project code and contributing information can be found on our [**github project +page**](https://github.com/NOAA-GFDL/FMS). + +Please see the documentation style guide [**here**](md_docs_doxygenGuide.html) for how to document FMS code for this site. diff --git a/docs/layout.xml b/docs/layout.xml index 13d3a0c7c3..09b15a54a1 100644 --- a/docs/layout.xml +++ b/docs/layout.xml @@ -9,11 +9,11 @@ - - - - - + + + + + diff --git a/drifters/cloud_interpolator.F90 b/drifters/cloud_interpolator.F90 index ae194f24cd..f83f66274e 100644 --- a/drifters/cloud_interpolator.F90 +++ b/drifters/cloud_interpolator.F90 @@ -16,18 +16,12 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** -! nf95 -r8 -g -I ~/regression/ia64/23-Jun-2005/CM2.1U_Control-1990_E1.k32pe/include/ -D_TEST_CLOUD_INTERPOLATOR -! -D_F95 cloud_interpolator.F90 - #define _FLATTEN(A) reshape((A), (/size((A))/) ) !> @defgroup cloud_interpolator_mod cloud_interpolator_mod !> @ingroup drifters !! @brief Cloud interpolation routines for use in @ref drifters_mod -!> @file -!> @brief File for @ref cloud_interpolator_mod - !> @addtogroup cloud_interpolator_mod !> @{ MODULE cloud_interpolator_mod diff --git a/drifters/drifters.F90 b/drifters/drifters.F90 index c5d9e64776..ab1bcdc395 100644 --- a/drifters/drifters.F90 +++ b/drifters/drifters.F90 @@ -16,7 +16,6 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** -!FDOC_TAG_GFDL fdoc.pl generated xml skeleton #include "fms_switches.h" #define _FLATTEN(A) reshape((A), (/size((A))/) ) @@ -58,9 +57,6 @@ !! on a per PE domain basis. There is no support for locally nested or unstrucured !! meshes. Meshes need not be smooth and continuous across PE domains, however. -!> @file -!> @brief File for @ref drifters_mod - !> @addtogroup drifters_mod !> @{ module drifters_mod diff --git a/drifters/drifters_comm.F90 b/drifters/drifters_comm.F90 index 407be8a278..5319e19934 100644 --- a/drifters/drifters_comm.F90 +++ b/drifters/drifters_comm.F90 @@ -22,9 +22,6 @@ !> @ingroup drifters !> @brief Routines and types to update drifter positions across processor domains -!> @file -!> @brief File for @ref drifters_comm_mod - module drifters_comm_mod #ifdef _SERIAL diff --git a/drifters/drifters_core.F90 b/drifters/drifters_core.F90 index 541666027f..c25dd85e54 100644 --- a/drifters/drifters_core.F90 +++ b/drifters/drifters_core.F90 @@ -16,17 +16,10 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** -! -! nf95 -r8 -g -I ~/regression/ia64/23-Jun-2005/CM2.1U_Control-1990_E1.k32pe/include/ -D_TEST_DRIFTERS -! -D_F95 quicksort.F90 drifters_core.F90 - !> @defgroup drifters_core_mod drifters_core_mod !> @ingroup drifters !> @brief Handles the mechanics for adding and removing drifters -!> @file -!> @brief File for @ref drifters_core_mod - module drifters_core_mod use platform_mod implicit none @@ -34,9 +27,7 @@ module drifters_core_mod public :: drifters_core_type, drifters_core_new, drifters_core_del, drifters_core_set_ids public :: drifters_core_remove_and_add, drifters_core_set_positions, assignment(=) -!#ifdef _TEST_DRIFTERS_CORE public :: drifters_core_print, drifters_core_resize -!#endif ! Globals integer, parameter, private :: MAX_STR_LEN = 128 diff --git a/drifters/drifters_input.F90 b/drifters/drifters_input.F90 index 2e4f34461b..0327f67053 100644 --- a/drifters/drifters_input.F90 +++ b/drifters/drifters_input.F90 @@ -20,9 +20,6 @@ !> @ingroup drifters !> @brief Imports initial drifter positions from a netCDF file -!> @file -!> @brief File for @ref drifters_input_mod - !> @addtogroup drifters_input_mod !> @{ module drifters_input_mod diff --git a/drifters/drifters_io.F90 b/drifters/drifters_io.F90 index 6b2772bc8a..3592da9603 100644 --- a/drifters/drifters_io.F90 +++ b/drifters/drifters_io.F90 @@ -20,9 +20,6 @@ !> @ingroup drifters !> @brief Saves drifter data for postprocessing and restarts -!> @file -!> @brief File for @ref drifters_io_mod - !> @addtogroup drifters_io_mod !> @{ module drifters_io_mod diff --git a/drifters/quicksort.F90 b/drifters/quicksort.F90 index 4bf26b9b91..6f751858d1 100644 --- a/drifters/quicksort.F90 +++ b/drifters/quicksort.F90 @@ -21,9 +21,10 @@ #define _TYP integer !> @endcond -!> @file +!> @defgroup quicksort quicksort !> @ingroup drifters -!> @brief Fortran implementation of quicksort +!> @brief Fortran implementation of quicksort to be used in @ref drifters_core +!! !> @author Magnus Lie Hetland !> Create array partitions for quicksort diff --git a/exchange/stock_constants.F90 b/exchange/stock_constants.F90 index a3bbf22372..a2eb9dfc0d 100644 --- a/exchange/stock_constants.F90 +++ b/exchange/stock_constants.F90 @@ -20,9 +20,6 @@ !> @ingroup exchange !> @brief Parameters, routines, and types for computing stocks in @ref xgrid_mod -!> @file -!> @brief File for @ref stock_constants_mod - !> @addtogroup stock_constants_mod !> @{ module stock_constants_mod diff --git a/exchange/xgrid.F90 b/exchange/xgrid.F90 index 0874bfefad..54a32ec8e2 100644 --- a/exchange/xgrid.F90 +++ b/exchange/xgrid.F90 @@ -88,9 +88,6 @@ !! J_OCN_ATMxOCN, and AREA_ATMxOCN. These fields may be generated !! by the make_xgrids utility. -!> @file -!> @brief File for @ref xgrid_mod - !> @addtogroup xgrid_mod !> @{ module xgrid_mod diff --git a/field_manager/field_manager.F90 b/field_manager/field_manager.F90 index 1fe65abe0c..d2c5b82031 100644 --- a/field_manager/field_manager.F90 +++ b/field_manager/field_manager.F90 @@ -152,9 +152,6 @@ !! authors of code to allow modification of their routines. !! -!> @file -!> @brief File for @ref field_manager_mod - !> @addtogroup field_manager_mod !> @{ module field_manager_mod diff --git a/field_manager/fm_util.F90 b/field_manager/fm_util.F90 index d99eda2034..994b6cdbf0 100644 --- a/field_manager/fm_util.F90 +++ b/field_manager/fm_util.F90 @@ -24,9 +24,6 @@ !! termination while interfacing with the field manager. !> @author Richard D. Slater -!> @file -!> @brief File for @ref fm_util_mod - !> @addtogroup fm_util_mod !> @{ module fm_util_mod !{ diff --git a/fms/fms.F90 b/fms/fms.F90 index c606bab21a..e37139a056 100644 --- a/fms/fms.F90 +++ b/fms/fms.F90 @@ -39,9 +39,6 @@ !! the @ref mpp module. These are routines for getting processor !! numbers, commonly used I/O unit numbers, error handling, and timing sections of code. -!> @file -!> @brief File for @ref fms_mod - !> @addtogroup fms_mod !> @{ module fms_mod diff --git a/fms/fms_io.F90 b/fms/fms_io.F90 index 8dda1a1cc4..05e3597283 100644 --- a/fms/fms_io.F90 +++ b/fms/fms_io.F90 @@ -83,9 +83,6 @@ ! ! -!> @file -!> @brief File for @ref fms_io_mod - !> @addtogroup fms_io_mod !> @{ module fms_io_mod diff --git a/fms/fms_io_unstructured_field_exist.inc b/fms/fms_io_unstructured_field_exist.inc index 1cd3d13193..c06cb1a8d5 100644 --- a/fms/fms_io_unstructured_field_exist.inc +++ b/fms/fms_io_unstructured_field_exist.inc @@ -18,10 +18,10 @@ !*********************************************************************** !---------- !ug support -!> @file -!> @ingroup fms_io_mod +!> @addtogroup fms_io_mod +!> @{ -!>Return a flag indicating whether the inputted field exists in the inputted +!> Return a flag indicating whether the inputted field exists in the inputted !!file, where the file is associated with an unstructured mpp domain. function fms_io_unstructured_field_exist(file_name, & field_name, & @@ -107,5 +107,4 @@ function fms_io_unstructured_field_exist(file_name, & return end function fms_io_unstructured_field_exist - -!---------- +!> @} diff --git a/fms/fms_io_unstructured_file_unit.inc b/fms/fms_io_unstructured_file_unit.inc index d8be3178c1..1fe25ff073 100644 --- a/fms/fms_io_unstructured_file_unit.inc +++ b/fms/fms_io_unstructured_file_unit.inc @@ -18,8 +18,8 @@ !*********************************************************************** !---------- !ug support -!> @file -!> @ingroup fms_io_mod +!> @addtogroup fms_io_mod +!> @{ !>Find the file unit for an inputted file, searching for its variants. If the !!file is not found, then throw a fatal error. @@ -61,5 +61,4 @@ subroutine fms_io_unstructured_file_unit(filename, & return end subroutine fms_io_unstructured_file_unit - -!---------- +!> @} diff --git a/fms/fms_io_unstructured_get_field_size.inc b/fms/fms_io_unstructured_get_field_size.inc index 48eb0ea470..9d1f4769d0 100644 --- a/fms/fms_io_unstructured_get_field_size.inc +++ b/fms/fms_io_unstructured_get_field_size.inc @@ -18,8 +18,9 @@ !*********************************************************************** !---------- !ug support -!> @file -!> @ingroup fms_io_mod + +!> @addtogroup fms_io_mod +!> @{ !>Get the size of the dimensions of a field from a file associated with an !!unstructured mpp domain. @@ -195,3 +196,4 @@ subroutine fms_io_unstructured_get_field_size(filename, & return end subroutine fms_io_unstructured_get_field_size +!> @} diff --git a/fms/fms_io_unstructured_get_file_name.inc b/fms/fms_io_unstructured_get_file_name.inc index 28111fa306..b77461ccf6 100644 --- a/fms/fms_io_unstructured_get_file_name.inc +++ b/fms/fms_io_unstructured_get_file_name.inc @@ -18,8 +18,8 @@ !*********************************************************************** !---------- !ug support -!> @file -!> @ingroup fms_io_mod +!> @addtogroup fms_io_mod +!> @{ !>For an inputted file name, check if it or any of its variants exist. !!For a file named "foo", variants checked (in order) include: @@ -167,5 +167,4 @@ function fms_io_unstructured_get_file_name(orig_file, & return end function fms_io_unstructured_get_file_name - -!------------------------------------------------------------------------------ +!> @} diff --git a/fms/fms_io_unstructured_get_file_unit.inc b/fms/fms_io_unstructured_get_file_unit.inc index 771efd0394..9ca04d8877 100644 --- a/fms/fms_io_unstructured_get_file_unit.inc +++ b/fms/fms_io_unstructured_get_file_unit.inc @@ -18,8 +18,8 @@ !*********************************************************************** !---------- !ug support -!> @file -!> @ingroup fms_io_mod +!> @addtogroup fms_io_mod +!> @{ !>Return the file unit and index in the "files_read" module array for the !!inputted file. If the file does not currently exist in the "files_read" @@ -103,5 +103,4 @@ subroutine fms_io_unstructured_get_file_unit(filename, & return end subroutine fms_io_unstructured_get_file_unit - -!---------- +!> @} diff --git a/fms/fms_io_unstructured_read.inc b/fms/fms_io_unstructured_read.inc index 82aef3ee31..3a19409e8d 100644 --- a/fms/fms_io_unstructured_read.inc +++ b/fms/fms_io_unstructured_read.inc @@ -18,8 +18,8 @@ !*********************************************************************** !---------- !ug support -!> @file !> @ingroup fms_io_mod +!> @{ !------------------------------------------------------------------------------ !>Read in a scalar field from a file associated with an unstructured mpp @@ -473,7 +473,4 @@ subroutine fms_io_unstructured_read_i_2D(filename, & return end subroutine fms_io_unstructured_read_i_2D - -!------------------------------------------------------------------------------ - -!---------- +!> @} diff --git a/fms/fms_io_unstructured_register_restart_axis.inc b/fms/fms_io_unstructured_register_restart_axis.inc index ebdecc3373..08fcdae6db 100644 --- a/fms/fms_io_unstructured_register_restart_axis.inc +++ b/fms/fms_io_unstructured_register_restart_axis.inc @@ -18,8 +18,8 @@ !*********************************************************************** !---------- !ug support -!> @file -!> @ingroup fms_io_mod +!> @addtogroup +!> @{ !------------------------------------------------------------------------------ !>Store a real axis (x,y,z,...) in a restart object assoicated with an @@ -606,7 +606,4 @@ subroutine fms_io_unstructured_register_restart_axis_u(fileObj, & return end subroutine fms_io_unstructured_register_restart_axis_u - -!------------------------------------------------------------------------------ - -!---------- +!> @} diff --git a/fms/fms_io_unstructured_register_restart_field.inc b/fms/fms_io_unstructured_register_restart_field.inc index fc79c9fd73..783c16b04b 100644 --- a/fms/fms_io_unstructured_register_restart_field.inc +++ b/fms/fms_io_unstructured_register_restart_field.inc @@ -18,8 +18,8 @@ !*********************************************************************** !---------- !ug support -!> @file -!> @ingroup fms_io_mod +!> @addtogroup fms_io_mod +!> @{ !------------------------------------------------------------------------------ !>Add a real scalar field to a restart object (restart_file_type). Return @@ -1365,7 +1365,4 @@ function fms_io_unstructured_register_restart_field_i_2d(fileObj, & return end function fms_io_unstructured_register_restart_field_i_2d - -!------------------------------------------------------------------------------ - -!---------- +!> @} diff --git a/fms/fms_io_unstructured_save_restart.inc b/fms/fms_io_unstructured_save_restart.inc index f5d9ba194c..4dc9a037ef 100644 --- a/fms/fms_io_unstructured_save_restart.inc +++ b/fms/fms_io_unstructured_save_restart.inc @@ -18,8 +18,8 @@ !*********************************************************************** !---------- !ug support -!> @file -!> @ingroup fms_io_mod +!> @addtogroup fms_io_mod +!> @{ !>Write out metadata and data for axes and fields to a restart file !!associated with an unstructured mpp domain. @@ -695,5 +695,4 @@ subroutine fms_io_unstructured_save_restart(fileObj, & return end subroutine fms_io_unstructured_save_restart - -!---------- +!> @} diff --git a/fms/fms_io_unstructured_setup_one_field.inc b/fms/fms_io_unstructured_setup_one_field.inc index fac1f5e491..1bb07f1023 100644 --- a/fms/fms_io_unstructured_setup_one_field.inc +++ b/fms/fms_io_unstructured_setup_one_field.inc @@ -18,8 +18,8 @@ !*********************************************************************** !---------- !ug support -!> @file -!> @ingroup fms_io_mod +!> @addtogroup fms_io_mod +!> @{ !>Add a field to a restart object (restart_file_type). Return the index of the !!inputted field in the fileObj%var array. @@ -335,5 +335,4 @@ subroutine fms_io_unstructured_setup_one_field(fileObj, & return end subroutine fms_io_unstructured_setup_one_field - -!---------- +!> @} diff --git a/fms2_io/blackboxio.F90 b/fms2_io/blackboxio.F90 index 76c8740eca..e98eaf299f 100644 --- a/fms2_io/blackboxio.F90 +++ b/fms2_io/blackboxio.F90 @@ -20,9 +20,6 @@ !> @ingroup fms2_io !> @brief File utility functions for use within @ref fms2_io -!> @file -!> @brief File for @ref blackboxio - !> @addtogroup blackboxio !> @{ module blackboxio diff --git a/fms2_io/fms2_io.F90 b/fms2_io/fms2_io.F90 index 0d46a4498d..c8d06ad8db 100644 --- a/fms2_io/fms2_io.F90 +++ b/fms2_io/fms2_io.F90 @@ -20,13 +20,7 @@ !> @ingroup fms2_io !> @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. -!! -!> Provides public interfaces for routines within @ref fms2_io. -!! Interfaces and example usages are listed below, see individual routine -!! documentation for more specific argument information. - -!> @file -!> @brief File for @ref fms2_io_mod +!! A conversion guide for replacing mpp/fms_io code with this module is available below. !> @addtogroup fms2_io_mod !> @{ @@ -119,6 +113,10 @@ module fms2_io_mod !! !! Opens a domain netcdf file of type @ref fmsnetcdfdomainfile_t or !! @ref fmsnetcdfunstructureddomainfile_t at the given file path name and 2D or unstructured domain. +!! @note For individual documentation on the listed routines, please see the appropriate helper module. +!! For netcdf files with a structured domain: @ref fms_netcdf_domain_io_mod. +!! For netcdf files with an unstructured domain: @ref fms_netcdf_unstructured_domain_io_mod. +!! For generic netcdf: @ref netcdf_io_mod. !> @ingroup fms2_io_mod interface open_file module procedure netcdf_file_open_wrap @@ -140,8 +138,9 @@ module fms2_io_mod !! io_success = open_virtual_file(fileobj, domain, "filename") !! !! Opens a virtual domain file through @ref fmsnetcdfdomainfile_t or -!! - @ref fmsnetcdfunstructureddomainfile_t for a given 2D domain at an optional path
    +!! @ref fmsnetcdfunstructureddomainfile_t for a given 2D domain at an optional path
    !! +!! @note For individual documentation on the listed routines, please see the appropriate helper module: @ref blackboxio !> @ingroup fms2_io_mod interface open_virtual_file module procedure create_diskless_netcdf_file_wrap @@ -158,6 +157,10 @@ module fms2_io_mod !! !! Closes any given fileobj opened via @ref open_file or @ref open_virtual_file !! +!! @note For individual documentation on the listed routines, please see the appropriate helper module. +!! For netcdf files with a structured domain: @ref fms_netcdf_domain_io_mod. +!! For netcdf files with an unstructured domain: @ref fms_netcdf_unstructured_domain_io_mod. +!! For generic netcdf: @ref netcdf_io_mod. !> @ingroup fms2_io_mod interface close_file module procedure netcdf_file_close_wrap @@ -178,6 +181,10 @@ module fms2_io_mod !! !! Adds a dimension named "lon" with length n to a given netcdf file.
    !! +!! @note For individual documentation on the listed routines, please see the appropriate helper module. +!! For netcdf files with a structured domain: @ref fms_netcdf_domain_io_mod. +!! For netcdf files with an unstructured domain: @ref fms_netcdf_unstructured_domain_io_mod. +!! For generic netcdf: @ref netcdf_io_mod. !> @ingroup fms2_io_mod interface register_axis module procedure netcdf_add_dimension @@ -196,6 +203,10 @@ module fms2_io_mod !! The size of dimension name list provided is the amount of ranks for the created !! field, scalar if list not provided. !! +!! @note For individual documentation on the listed routines, please see the appropriate helper module. +!! For netcdf files with a structured domain: @ref fms_netcdf_domain_io_mod. +!! For netcdf files with an unstructured domain: @ref fms_netcdf_unstructured_domain_io_mod. +!! For generic netcdf: @ref netcdf_io_mod. !> @ingroup fms2_io_mod interface register_field module procedure netcdf_add_variable_wrap @@ -211,6 +222,10 @@ module fms2_io_mod !! Creates a restart variable and sets it to the values from data_ptr, corresponding to !! the list of dimension names. Rank of data_ptr must equal the amount of corresponding dimensions. !! +!! @note For individual documentation on the listed routines, please see the appropriate helper module. +!! For netcdf files with a structured domain: @ref fms_netcdf_domain_io_mod. +!! For netcdf files with an unstructured domain: @ref fms_netcdf_unstructured_domain_io_mod. +!! For generic netcdf: @ref netcdf_io_mod. !> @ingroup fms2_io_mod interface register_restart_field module procedure netcdf_add_restart_variable_0d_wrap @@ -301,6 +316,10 @@ module fms2_io_mod !! !! Writes previously registered restart fields to the given restart file !! +!! @note For individual documentation on the listed routines, please see the appropriate helper module. +!! For netcdf files with a structured domain: @ref fms_netcdf_domain_io_mod. +!! For netcdf files with an unstructured domain: @ref fms_netcdf_unstructured_domain_io_mod. +!! For generic netcdf: @ref netcdf_io_mod. !> @ingroup fms2_io_mod interface write_restart module procedure netcdf_save_restart_wrap @@ -316,6 +335,7 @@ module fms2_io_mod !! Creates a new restart file, with the provided timestamp and filename, out of the registered !! restart fields in the given restart file. !! +!! @note For individual documentation on the listed routines, please see the appropriate helper module: @ref blackboxio !> @ingroup fms2_io_mod interface write_new_restart module procedure netcdf_save_restart_wrap2 @@ -328,6 +348,9 @@ module fms2_io_mod !! call read_restart(fileobj) !! Reads registered restart variables from fileobj !! +!! @note For individual documentation on the listed routines, please see the appropriate helper module. +!! For netcdf files with a structured domain: @ref fms_netcdf_domain_io_mod. +!! For generic netcdf: @ref netcdf_io_mod. !> @ingroup fms2_io_mod interface read_restart module procedure netcdf_restore_state @@ -335,6 +358,12 @@ module fms2_io_mod end interface read_restart !> @brief Read registered restarts from a new file +!! Optionally takes directory to write to, model time and filename +!>
    Example usage: +!! call read_new_restart(fileobj, unlimted_dimension_level) +!! +!! call read_new_restart(fileobj, unlimited_dimension_level, directory, timestamp, filename) +!! @note For individual documentation on the listed routines, please see the appropriate helper module: @ref blackboxio !> @ingroup fms2_io_mod interface read_new_restart module procedure netcdf_restore_state_wrap diff --git a/fms2_io/fms_io_utils.F90 b/fms2_io/fms_io_utils.F90 index 92976564bb..cd72c0c8d5 100644 --- a/fms2_io/fms_io_utils.F90 +++ b/fms2_io/fms_io_utils.F90 @@ -20,9 +20,6 @@ !> @ingroup fms2_io !> @brief Misc. utility routines for use in @ref fms2_io -!> @file -!> @brief File for @ref fms_io_utils_mod - !> @addtogroup fms_io_utils_mod !> @{ module fms_io_utils_mod diff --git a/fms2_io/fms_netcdf_domain_io.F90 b/fms2_io/fms_netcdf_domain_io.F90 index 85d072c531..57e61800c5 100644 --- a/fms2_io/fms_netcdf_domain_io.F90 +++ b/fms2_io/fms_netcdf_domain_io.F90 @@ -20,9 +20,6 @@ !> @ingroup fms2_io !> @brief Domain-specific I/O wrappers. -!> @file -!> @brief File for @ref fms_netcdf_domain_io_mod - !> @addtogroup fms_netcdf_domain_io_mod !> @{ module fms_netcdf_domain_io_mod diff --git a/fms2_io/fms_netcdf_unstructured_domain_io.F90 b/fms2_io/fms_netcdf_unstructured_domain_io.F90 index fc6d766e81..ad6ef199b7 100644 --- a/fms2_io/fms_netcdf_unstructured_domain_io.F90 +++ b/fms2_io/fms_netcdf_unstructured_domain_io.F90 @@ -22,9 +22,6 @@ !! !> Mainly routines for use via interfaces in @ref fms2_io_mod -!> @file -!> @brief File for @ref fms_netcdf_unstructured_domain_io_mod - module fms_netcdf_unstructured_domain_io_mod use netcdf use mpp_domains_mod diff --git a/fms2_io/include/array_utils.inc b/fms2_io/include/array_utils.inc index d2528df0ee..6d67e62b03 100644 --- a/fms2_io/include/array_utils.inc +++ b/fms2_io/include/array_utils.inc @@ -17,7 +17,10 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup fms_io_utils_mod +!> @brief Array allocation routines for multiple types for @ref allocate_array interface + +!> @addtogroup fms_io_utils_mod +!> @{ !> @brief Allocate arrays using an input array of sizes. subroutine allocate_array_i4_kind_1d(buf, sizes) diff --git a/fms2_io/include/array_utils_char.inc b/fms2_io/include/array_utils_char.inc index 0c6387e019..884f1f3cda 100644 --- a/fms2_io/include/array_utils_char.inc +++ b/fms2_io/include/array_utils_char.inc @@ -16,11 +16,12 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** - !> @file -!> @ingroup fms_io_utils_mod !> @brief Character array routines used in @ref fms_io_utils_mod +!> @addtogroup fms_io_utils_mod +!> @{ + !> @brief Allocate character arrays using an input array of sizes. subroutine allocate_array_char_1d(buf, sizes) @@ -97,5 +98,4 @@ subroutine allocate_array_char_6d(buf, sizes) endif allocate(buf(sizes(1), sizes(2), sizes(3), sizes(4), sizes(5), sizes(6))) end subroutine allocate_array_char_6d - - +!> @} diff --git a/fms2_io/include/compressed_read.inc b/fms2_io/include/compressed_read.inc index 141a7121f0..9f0de7c794 100644 --- a/fms2_io/include/compressed_read.inc +++ b/fms2_io/include/compressed_read.inc @@ -17,7 +17,10 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup fms2_io +!> @brief Compressed read routines for @ref read_data interface + +!> @addtogroup fms2_io_mod +!> @{ !> @brief I/O domain reads in data from the netcdf file and broadcasts the !! data to the rest of the ranks. This routine may only be used with @@ -183,3 +186,4 @@ subroutine compressed_read_5d(fileobj, variable_name, cdata, unlim_dim_level, & ,edge_lengths=edge_lengths & ,broadcast=.true.) end subroutine compressed_read_5d +!> @} diff --git a/fms2_io/include/compressed_write.inc b/fms2_io/include/compressed_write.inc index 28a47ab47b..dffff9ea94 100644 --- a/fms2_io/include/compressed_write.inc +++ b/fms2_io/include/compressed_write.inc @@ -17,7 +17,10 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup fms2_io +!> @brief Compressed write routines for @ref write_data interface + +!> @addtogroup fms2_io_mod +!> @{ !> @brief For variables without a compressed dimension, this routine simply wraps !! netcdf_write data. If the variable does have a compressed axis, the I/O root @@ -742,3 +745,4 @@ subroutine compressed_write_5d_wrap(fileobj, variable_name, cdata, unlim_dim_lev call compressed_write(fileobj, variable_name, cdata, unlim_dim_level, corner, & edge_lengths=edge_lengths) end subroutine compressed_write_5d_wrap +!> @} diff --git a/fms2_io/include/compute_global_checksum.inc b/fms2_io/include/compute_global_checksum.inc index f4886fff6e..7a0df67671 100644 --- a/fms2_io/include/compute_global_checksum.inc +++ b/fms2_io/include/compute_global_checksum.inc @@ -17,7 +17,10 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup fms_netcdf_domain_io_mod +!> @brief Routines for calculating variable checksums across pes for the @ref compute_global_checksum interface + +!> @addtogroup fms_netcdf_domain_io_mod +!> @{ !> @briefs Calculates a variable's checksum across all ranks in the current pelist. !! @return A hex string containing the checksum. @@ -367,3 +370,4 @@ function compute_global_checksum_4d(fileobj, variable_name, variable_data, is_de chksum = "" write(chksum, "(Z16)") chksum_val end function compute_global_checksum_4d +!> @} diff --git a/fms2_io/include/domain_read.inc b/fms2_io/include/domain_read.inc index 50be8870d8..3a70c067b2 100644 --- a/fms2_io/include/domain_read.inc +++ b/fms2_io/include/domain_read.inc @@ -17,7 +17,10 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup fms_netcdf_domain_io_mod +!> @brief Reads domain decomposed variables and scatters data to pe's for the @ref read_data interface + +!> @addtogroup fms2_io_mod +!> @{ !> @brief I/O domain root reads in a domain decomposed variable at a !! specific unlimited dimension level and scatters the data to the @@ -960,3 +963,4 @@ subroutine domain_read_5d(fileobj, variable_name, vdata, unlim_dim_level, & end select endif end subroutine domain_read_5d +!> @} diff --git a/fms2_io/include/domain_write.inc b/fms2_io/include/domain_write.inc index db29f1f8b9..5ce4e5b6f0 100644 --- a/fms2_io/include/domain_write.inc +++ b/fms2_io/include/domain_write.inc @@ -17,7 +17,10 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup fms_netcdf_domain_io_mod +!> @brief Routines for writing domain decomposed variables for the @ref write_data interface + +!> @addtogroup fms2_io_mod +!> @{ !> @brief Gather "compute" domain data on the I/O root rank and then have !! the I/O root write out the data that spans the "global" domain. @@ -1255,3 +1258,4 @@ subroutine domain_write_5d(fileobj, variable_name, vdata, unlim_dim_level, & end select endif end subroutine domain_write_5d +!> @} diff --git a/fms2_io/include/gather_data_bc.inc b/fms2_io/include/gather_data_bc.inc index a15c01453f..4234e2861a 100644 --- a/fms2_io/include/gather_data_bc.inc +++ b/fms2_io/include/gather_data_bc.inc @@ -17,7 +17,10 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup fms2_io +!> @brief Routines for the @ref gather_data_bc interface + +!> @addtogroup netcdf_io_mod +!> @{ !> @brief gathers the 2d vdata from all of the relevant pes into the root_pe and saves it to a !! buffer. @@ -259,3 +262,4 @@ subroutine gather_data_bc_3d(fileobj, vdata, bc_info) endif end subroutine gather_data_bc_3d +!> @} diff --git a/fms2_io/include/get_data_type_string.inc b/fms2_io/include/get_data_type_string.inc index 880221a8df..71910ee867 100644 --- a/fms2_io/include/get_data_type_string.inc +++ b/fms2_io/include/get_data_type_string.inc @@ -17,7 +17,11 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup fms_io_utils_mod +!> @brief Routines to return a given arguments data type as a string. +!! Provides multiple dimensions for @ref get_data_type_string interface. + +!> @addtogroup fms_io_utils_mod +!> @{ !> @brief Return a string describing the input data's type. subroutine get_data_type_string_0d(sdata, type_string) @@ -160,5 +164,4 @@ subroutine get_data_type_string_5d(sdata, type_string) call error("unsupported type.") end select end subroutine get_data_type_string_5d - - +!> @} diff --git a/fms2_io/include/get_global_attribute.inc b/fms2_io/include/get_global_attribute.inc index 2ca9786174..0ed4880570 100644 --- a/fms2_io/include/get_global_attribute.inc +++ b/fms2_io/include/get_global_attribute.inc @@ -17,7 +17,11 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup fms2_io +!> @brief Routines for retrieving global attribute values from netcdf files with different +!! dimension sizes for the @ref get_global_attribute interface + +!> @addtogroup netcdf_io_mod +!> @{ !> @brief Get the value of a global attribute. subroutine get_global_attribute_0d(fileobj, & @@ -190,3 +194,4 @@ subroutine get_global_attribute_1d(fileobj, & &trim(attribute_name)//" for file: "//trim(fileobj%path)//"") end select end subroutine get_global_attribute_1d +!> @} diff --git a/fms2_io/include/get_variable_attribute.inc b/fms2_io/include/get_variable_attribute.inc index 923ad939c9..c1e9ec366b 100644 --- a/fms2_io/include/get_variable_attribute.inc +++ b/fms2_io/include/get_variable_attribute.inc @@ -17,7 +17,11 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup fms2_io +!> @brief Routines for retrieving variable attribute values from netcdf files with different +!! dimension sizes for the @ref get_variable_attribute interface + +!> @addtogroup netcdf_io_mod +!> @{ !> @brief Get the value of a variable's attribute. subroutine get_variable_attribute_0d(fileobj, variable_name, attribute_name, & @@ -169,3 +173,4 @@ subroutine get_variable_attribute_1d(fileobj, variable_name, attribute_name, & call error("unsupported attribute type: "//trim(append_error_msg)) end select end subroutine get_variable_attribute_1d +!> @} diff --git a/fms2_io/include/netcdf_add_restart_variable.inc b/fms2_io/include/netcdf_add_restart_variable.inc index 491a2a5b66..d76c62a1e3 100644 --- a/fms2_io/include/netcdf_add_restart_variable.inc +++ b/fms2_io/include/netcdf_add_restart_variable.inc @@ -17,7 +17,11 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup fms2_io +!> @brief Routines to add restart variables to a netcdf file with different dimension sizes +!! for the @ref netcdf_add_restart_variable interface + +!> @addtogroup netcdf_io_mod +!> @{ !> @brief Add a restart variable to a netcdf file. subroutine netcdf_add_restart_variable_0d(fileobj, variable_name, vdata, dimensions, & @@ -571,3 +575,4 @@ subroutine set_dimensions(fileobj, bc_dimensions, dimnames, global_size) endif endif end subroutine set_dimensions +!> @} diff --git a/fms2_io/include/netcdf_read_data.inc b/fms2_io/include/netcdf_read_data.inc index ece05d11c8..3a5e7e3733 100644 --- a/fms2_io/include/netcdf_read_data.inc +++ b/fms2_io/include/netcdf_read_data.inc @@ -17,7 +17,11 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup fms2_io +!> @brief Routines for retrieving variable values from netcdf files with different +!! dimension sizes for the @ref netcdf_read_data interface + +!> @addtogroup netcdf_io_mod +!> @{ !> @brief Read in data from a variable in a netcdf file. subroutine netcdf_read_data_0d(fileobj, variable_name, buf, unlim_dim_level, & @@ -621,3 +625,4 @@ subroutine netcdf_read_data_5d(fileobj, variable_name, buf, unlim_dim_level, & end select endif end subroutine netcdf_read_data_5d +!> @} diff --git a/fms2_io/include/netcdf_write_data.inc b/fms2_io/include/netcdf_write_data.inc index 865672b674..22e3d11b67 100644 --- a/fms2_io/include/netcdf_write_data.inc +++ b/fms2_io/include/netcdf_write_data.inc @@ -17,7 +17,11 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup fms2_io +!> @brief Routines for writing variable values to netcdf files with different +!! dimension sizes for the @ref netcdf_write_data interface + +!> @addtogroup netcdf_io_mod +!> @{ !> @brief Write data to a variable in a netcdf file. subroutine netcdf_write_data_0d(fileobj, variable_name, variable_data, unlim_dim_level, & diff --git a/fms2_io/include/register_domain_restart_variable.inc b/fms2_io/include/register_domain_restart_variable.inc index 9815147056..45c5bd9efd 100644 --- a/fms2_io/include/register_domain_restart_variable.inc +++ b/fms2_io/include/register_domain_restart_variable.inc @@ -17,7 +17,11 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup fms_netcdf_domain_io_mod +!> @brief Adds domain decomposed variable for restarts for the @ref register_restart_field +!! interface + +!> @addtogroup fms2_io_mod +!> @{ !> @brief Add a domain decomposed variable. subroutine register_domain_restart_variable_0d(fileobj, variable_name, vdata, & @@ -110,3 +114,4 @@ subroutine register_domain_restart_variable_5d(fileobj, variable_name, vdata, & call netcdf_add_restart_variable(fileobj, variable_name, vdata, dimensions,is_optional) end subroutine register_domain_restart_variable_5d +!> @} diff --git a/fms2_io/include/register_global_attribute.inc b/fms2_io/include/register_global_attribute.inc index b2f81abbf7..c3cf06e80b 100644 --- a/fms2_io/include/register_global_attribute.inc +++ b/fms2_io/include/register_global_attribute.inc @@ -17,7 +17,11 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup fms2_io +!> @brief Routines for different dimensions to add global attributes in netcdf files for the +!! @ref register_global_attribute interface + +!> @addtogroup netcdf_io_mod +!> @{ !> @brief Add a global attribute. subroutine register_global_attribute_0d(fileobj, & @@ -116,3 +120,4 @@ subroutine register_global_attribute_1d(fileobj, & & trim(attribute_name)) endif end subroutine register_global_attribute_1d +!> @} diff --git a/fms2_io/include/register_unstructured_domain_restart_variable.inc b/fms2_io/include/register_unstructured_domain_restart_variable.inc index 696e31cf37..6cc53baf0f 100644 --- a/fms2_io/include/register_unstructured_domain_restart_variable.inc +++ b/fms2_io/include/register_unstructured_domain_restart_variable.inc @@ -17,7 +17,11 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup fms_netcdf_unstructured_domain_io_mod +!> @brief Adds restart variable for unstructured domains for different dimension to be used in +!! the @ref register_restart_field interface + +!> @addtogroup fms2_io_mod +!> @{ !> @brief Add a domain decomposed variable. subroutine register_unstructured_domain_restart_variable_0d(fileobj, variable_name, vdata, & @@ -107,3 +111,4 @@ subroutine register_unstructured_domain_restart_variable_5d(fileobj, variable_na call netcdf_add_restart_variable(fileobj, variable_name, vdata, dimensions, is_optional) end subroutine register_unstructured_domain_restart_variable_5d +!> @} diff --git a/fms2_io/include/register_variable_attribute.inc b/fms2_io/include/register_variable_attribute.inc index 72bf9cd2e4..a473a72355 100644 --- a/fms2_io/include/register_variable_attribute.inc +++ b/fms2_io/include/register_variable_attribute.inc @@ -17,7 +17,11 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup fms2_io +!> @brief Routines to add variable attributes for different dimensions to be used in +!! the @ref register_variable_attribute interface + +!> @addtogroup fms2_io_mod +!> @{ !> @brief Add an attribute to a variable. subroutine register_variable_attribute_0d(fileobj, variable_name, attribute_name, & @@ -198,3 +202,4 @@ subroutine register_variable_attribute_1d(fileobj, variable_name, attribute_name endif endif end subroutine register_variable_attribute_1d +!> @} diff --git a/fms2_io/include/scatter_data_bc.inc b/fms2_io/include/scatter_data_bc.inc index 907984fdaa..63536f7d22 100644 --- a/fms2_io/include/scatter_data_bc.inc +++ b/fms2_io/include/scatter_data_bc.inc @@ -17,7 +17,10 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup fms2_io +!> @brief Routines for the @ref gather_data_bc interface + +!> @addtogroup netcdf_io_mod +!> @{ !< Root pe reads the data in the netcdf file and scatters it to the other pes subroutine scatter_data_bc_2d(fileobj, varname, vdata, bc_info, unlim_dim_level, ignore_checksum) diff --git a/fms2_io/include/unstructured_domain_read.inc b/fms2_io/include/unstructured_domain_read.inc index c23930e8e3..089496f5de 100644 --- a/fms2_io/include/unstructured_domain_read.inc +++ b/fms2_io/include/unstructured_domain_read.inc @@ -17,7 +17,10 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup fms_netcdf_unstructured_domain_io_mod +!> @brief Routines for reading unstructured domain data, used in @ref read_data interface + +!> @addtogroup fms2_io_mod +!> @{ !> @brief Wrapper to distinguish interfaces. subroutine unstructured_domain_read_0d(fileobj, & @@ -214,3 +217,4 @@ subroutine unstructured_domain_read_5d(fileobj, & edge_lengths, & broadcast) end subroutine unstructured_domain_read_5d +!> @} diff --git a/fms2_io/include/unstructured_domain_write.inc b/fms2_io/include/unstructured_domain_write.inc index 67f5a89f42..9dc36166c2 100644 --- a/fms2_io/include/unstructured_domain_write.inc +++ b/fms2_io/include/unstructured_domain_write.inc @@ -17,7 +17,11 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup fms_netcdf_unstructured_domain_io_mod +!> @brief Routines to write data from an unstructured domain decomposition. +!! Used in the @ref write_data interface + +!> @addtogroup fms2_io_mod +!> @{ !> @brief Wrapper to distinguish interfaces. subroutine unstructured_domain_write_0d(fileobj, variable_name, variable_data, & @@ -156,3 +160,4 @@ subroutine unstructured_domain_write_5d(fileobj, variable_name, variable_data, & call compressed_write(fileobj, variable_name, variable_data, unlim_dim_level, corner, & edge_lengths=edge_lengths) end subroutine unstructured_domain_write_5d +!> @} diff --git a/fms2_io/netcdf_io.F90 b/fms2_io/netcdf_io.F90 index c6984bb237..d6453ede52 100644 --- a/fms2_io/netcdf_io.F90 +++ b/fms2_io/netcdf_io.F90 @@ -22,9 +22,6 @@ !! !> Handles type definitions and interfaces for netcdf I/O. -!> @file -!> @brief File for @ref netcdf_io_mod - !> @addtogroup netcdf_io_mod !> @{ module netcdf_io_mod diff --git a/horiz_interp/horiz_interp.F90 b/horiz_interp/horiz_interp.F90 index fd9c440d4c..07e118f6af 100644 --- a/horiz_interp/horiz_interp.F90 +++ b/horiz_interp/horiz_interp.F90 @@ -35,9 +35,6 @@ !! missing input data. An optional output mask field may be used in conjunction with !! the input mask to show where output data exists. -!> @file -!> @brief File for @ref horiz_interp_mod - module horiz_interp_mod !----------------------------------------------------------------------- diff --git a/horiz_interp/horiz_interp_bicubic.F90 b/horiz_interp/horiz_interp_bicubic.F90 index 0de6652207..f640f2aa6b 100644 --- a/horiz_interp/horiz_interp_bicubic.F90 +++ b/horiz_interp/horiz_interp_bicubic.F90 @@ -44,9 +44,6 @@ !! Alle benotigten Felder werden extern von MOM verwaltet, da sie !! nicht fur alle interpolierten Daten die gleiche Dimension haben mussen. -!> @file -!> @brief File for @ref horiz_interp_bicubic_mod - module horiz_interp_bicubic_mod use mpp_mod, only: mpp_error, FATAL, stdout, mpp_pe, mpp_root_pe diff --git a/horiz_interp/horiz_interp_bilinear.F90 b/horiz_interp/horiz_interp_bilinear.F90 index 734dc84ed0..2fe244cab9 100644 --- a/horiz_interp/horiz_interp_bilinear.F90 +++ b/horiz_interp/horiz_interp_bilinear.F90 @@ -27,9 +27,6 @@ !! An optional output mask field may be used in conjunction with !! the input mask to show where output data exists. -!> @file -!> @brief File for @ref horiz_interp_bilinear_mod - module horiz_interp_bilinear_mod use mpp_mod, only: mpp_error, FATAL, stdout, mpp_pe, mpp_root_pe diff --git a/horiz_interp/horiz_interp_conserve.F90 b/horiz_interp/horiz_interp_conserve.F90 index ff1a718d3a..c09bc70e83 100644 --- a/horiz_interp/horiz_interp_conserve.F90 +++ b/horiz_interp/horiz_interp_conserve.F90 @@ -35,9 +35,6 @@ !! An optional output mask field may be used in conjunction with the input mask to show !! where output data exists. -!> @file -!> @brief File for @ref horiz_interp_conserve_mod - module horiz_interp_conserve_mod #include diff --git a/horiz_interp/horiz_interp_spherical.F90 b/horiz_interp/horiz_interp_spherical.F90 index 29fb519f1d..867e246503 100644 --- a/horiz_interp/horiz_interp_spherical.F90 +++ b/horiz_interp/horiz_interp_spherical.F90 @@ -25,9 +25,6 @@ !! An optional output mask field may be used in conjunction with !! the input mask to show where output data exists. -!> @file -!> @brief File for @ref horiz_interp_spherical_mod - !> @addtogroup horiz_interp_spherical_mod !> @{ module horiz_interp_spherical_mod diff --git a/horiz_interp/horiz_interp_type.F90 b/horiz_interp/horiz_interp_type.F90 index e2c4e4689e..ebcbdeecba 100644 --- a/horiz_interp/horiz_interp_type.F90 +++ b/horiz_interp/horiz_interp_type.F90 @@ -22,9 +22,6 @@ !! interpolations. !> @author Zhi Liang -!> @file -!> @brief File for @ref horiz_interp_type_mod - !> @addtogroup !> @{ module horiz_interp_type_mod diff --git a/interpolator/interpolator.F90 b/interpolator/interpolator.F90 index 613b1e1257..785ee68835 100644 --- a/interpolator/interpolator.F90 +++ b/interpolator/interpolator.F90 @@ -21,9 +21,6 @@ !> @brief A module to interpolate climatology data to model the grid. !> @author William Cooke -!> @file -!> File for @ref interpolator_mod - module interpolator_mod use mpp_mod, only : mpp_error, & diff --git a/memutils/memutils.F90 b/memutils/memutils.F90 index 31eddbc903..708027cb53 100644 --- a/memutils/memutils.F90 +++ b/memutils/memutils.F90 @@ -28,9 +28,6 @@ !! This module exposes the print_memuse_stat and memutils_init calls for !! use in external user code. -!> @file -!> @brief File for @ref memutils_mod - !> @addtogroup memutils_mod !> @{ module memutils_mod diff --git a/monin_obukhov/monin_obukhov.F90 b/monin_obukhov/monin_obukhov.F90 index f9475381f9..883e4cbe34 100644 --- a/monin_obukhov/monin_obukhov.F90 +++ b/monin_obukhov/monin_obukhov.F90 @@ -24,9 +24,6 @@ !! between the lowest model level and the ground !! using Monin-Obukhov scaling -!> @file -!> @brief File for @ref monin_obukhov_mod - module monin_obukhov_mod use constants_mod, only: grav, vonkarm diff --git a/monin_obukhov/monin_obukhov_inter.F90 b/monin_obukhov/monin_obukhov_inter.F90 index c170f0fb81..9aa43e8a0e 100644 --- a/monin_obukhov/monin_obukhov_inter.F90 +++ b/monin_obukhov/monin_obukhov_inter.F90 @@ -20,9 +20,6 @@ !> @ingroup monin_obukhov !> @brief Utility routines to be used in @ref monin_obukhov_mod -!> @file -!> @brief File for @ref monin_obukhov_inter - !> @addtogroup monin_obukhov_inter !> @{ module monin_obukhov_inter diff --git a/mosaic/gradient.F90 b/mosaic/gradient.F90 index 49df1a1221..6e1f72532d 100644 --- a/mosaic/gradient.F90 +++ b/mosaic/gradient.F90 @@ -24,9 +24,6 @@ !! Currently only gradient on cubic grid is implemented. Also a public interface !! is provided to calculate grid information needed to calculate gradient. -!> @file -!> @brief File for @ref gradient_mod - !> @addtogroup gradient_mod !> @{ module gradient_mod diff --git a/mosaic/grid.F90 b/mosaic/grid.F90 index 4253e6e132..6c94e1b733 100644 --- a/mosaic/grid.F90 +++ b/mosaic/grid.F90 @@ -20,9 +20,6 @@ !> @ingroup mosaic !> @brief Routines for grid calculations -!> @file -!> @brief File for @ref grid_mod - module grid_mod use mpp_mod, only : mpp_root_pe, uppercase, lowercase, FATAL, NOTE, mpp_error diff --git a/mosaic/mosaic.F90 b/mosaic/mosaic.F90 index 8ffd162fde..e8558fc8fa 100644 --- a/mosaic/mosaic.F90 +++ b/mosaic/mosaic.F90 @@ -25,9 +25,6 @@ !! mosaic grid resolution of each tile, mosaic contact information, mosaic exchange !! grid information. Each routine will call a C-version routine to get these information. -!> @file -!> @brief File for @ref mosaic_mod - !> @addtogroup mosaic_mod !> @{ module mosaic_mod diff --git a/mosaic2/grid2.F90 b/mosaic2/grid2.F90 index 3c52faa656..357e875ebf 100644 --- a/mosaic2/grid2.F90 +++ b/mosaic2/grid2.F90 @@ -20,9 +20,6 @@ !> @ingroup mosaic2 !> @brief Routines for grid calculations, using @ref fms2_io -!> @file -!> @brief File for @ref grid2_mod - module grid2_mod use mpp_mod, only : mpp_root_pe, mpp_error, uppercase, lowercase, FATAL, NOTE diff --git a/mosaic2/mosaic2.F90 b/mosaic2/mosaic2.F90 index a0c1421b14..ed225a07d2 100644 --- a/mosaic2/mosaic2.F90 +++ b/mosaic2/mosaic2.F90 @@ -27,9 +27,6 @@ !! mosaic grid resolution of each tile, mosaic contact information, mosaic exchange !! grid information. Each routine will call a C-version routine to get these information. -!> @file -!> @brief File for @ref mosaic2_mod - !> @addtogroup mosaic2_mod !> @{ module mosaic2_mod diff --git a/mpp/include/mpp_alltoall_mpi.h b/mpp/include/mpp_alltoall_mpi.h index 6a627aa914..9592e81685 100644 --- a/mpp/include/mpp_alltoall_mpi.h +++ b/mpp/include/mpp_alltoall_mpi.h @@ -1,3 +1,5 @@ +! -*-f90-*- + !*********************************************************************** !* GNU Lesser General Public License !* @@ -16,14 +18,19 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** + !> @file -!> @ingroup mpp !> @brief MPI implementation of @ref mpp_alltoall routines +!> @addtogroup mpp_mod +!> @{ + +!> Wrapper for mpi_alltoall routine, sends data from all to all processes subroutine MPP_ALLTOALL_(sbuf, scount, rbuf, rcount, pelist) - MPP_TYPE_, intent(in) :: sbuf(:) - MPP_TYPE_, intent(inout) :: rbuf(:) - integer, intent(in) :: scount, rcount + MPP_TYPE_, intent(in) :: sbuf(:) !< data to send + MPP_TYPE_, intent(inout) :: rbuf(:) !< received data + integer, intent(in) :: scount !< length of buffer data to send from each process + integer, intent(in) :: rcount !< length of buffer data to recieve from each proces integer, intent(in), optional :: pelist(0:) integer :: n @@ -46,14 +53,16 @@ subroutine MPP_ALLTOALL_(sbuf, scount, rbuf, rcount, pelist) end subroutine MPP_ALLTOALL_ - +!> Wrapper for mpi_alltoallv, sends data from all to all processes with vector displacement subroutine MPP_ALLTOALLV_(sbuf, ssize, sdispl, rbuf, rsize, rdispl, pelist) - MPP_TYPE_, intent(in) :: sbuf(:) - MPP_TYPE_, intent(inout) :: rbuf(:) + MPP_TYPE_, intent(in) :: sbuf(:) !< data to send + MPP_TYPE_, intent(inout) :: rbuf(:) !< received data ! TODO: Optionally set displacements to cumulative sums of ssize, rsize - integer, intent(in) :: ssize(:), rsize(:) - integer, intent(in) :: sdispl(:), rdispl(:) + integer, intent(in) :: ssize(:) !< array containing number of elements to send to each respective process + integer, intent(in) :: rsize(:) !< array containing number of elements to recieve from each respective process + integer, intent(in) :: sdispl(:)!< displacement of data sent to each respective process + integer, intent(in) :: rdispl(:)!< displacement of data received from each respective process integer, intent(in), optional :: pelist(0:) integer :: n @@ -76,15 +85,19 @@ subroutine MPP_ALLTOALLV_(sbuf, ssize, sdispl, rbuf, rsize, rdispl, pelist) end subroutine MPP_ALLTOALLV_ - +!> Wrapper for mpi_alltoallw, sends data from all to all processes with given data types, +!! displacements and block sizes subroutine MPP_ALLTOALLW_(sbuf, ssize, sdispl, stype, & rbuf, rsize, rdispl, rtype, pelist) - MPP_TYPE_, intent(in) :: sbuf(:) - MPP_TYPE_, intent(inout) :: rbuf(:) - - integer, intent(in) :: ssize(:), rsize(:) - integer, intent(in) :: sdispl(:), rdispl(:) - type(mpp_type), intent(in) :: stype(:), rtype(:) + MPP_TYPE_, intent(in) :: sbuf(:) !< data to send + MPP_TYPE_, intent(inout) :: rbuf(:) !< recieved data + + integer, intent(in) :: ssize(:) !< array containing number of elements to send to each respective process + integer, intent(in) :: rsize(:) !< array containing number of elements to recieve from each respective process + integer, intent(in) :: sdispl(:)!< displacement of data sent to each respective process + integer, intent(in) :: rdispl(:)!< displacement of data received from each respective process + type(mpp_type), intent(in) :: stype(:) !< mpp data types to send to each respective process + type(mpp_type), intent(in) :: rtype(:) !< mpp data types to recieve from each respective process integer, intent(in), optional :: pelist(0:) integer :: i, n @@ -118,3 +131,4 @@ subroutine MPP_ALLTOALLW_(sbuf, ssize, sdispl, stype, & call increment_current_clock(EVENT_ALLTOALL, MPP_TYPE_BYTELEN_) end subroutine MPP_ALLTOALLW_ +!> @} diff --git a/mpp/include/mpp_alltoall_nocomm.h b/mpp/include/mpp_alltoall_nocomm.h index 1c22749467..f8446a475b 100644 --- a/mpp/include/mpp_alltoall_nocomm.h +++ b/mpp/include/mpp_alltoall_nocomm.h @@ -1,3 +1,5 @@ +! -*-f90-*- + !*********************************************************************** !* GNU Lesser General Public License !* @@ -17,9 +19,9 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup mpp !> @brief @ref mpp_alltoall routine implementations without MPI +!> Sends data from all to all processes, non-mpi version subroutine MPP_ALLTOALL_(sbuf, scount, rbuf, rcount, pelist) MPP_TYPE_, dimension(:), intent(in) :: sbuf MPP_TYPE_, dimension(:), intent(inout) :: rbuf @@ -40,6 +42,7 @@ subroutine MPP_ALLTOALL_(sbuf, scount, rbuf, rcount, pelist) end subroutine MPP_ALLTOALL_ +!> Sends data from all to all processes with vector displacement, non-mpi version subroutine MPP_ALLTOALLV_(sbuf, ssize, sdispl, rbuf, rsize, rdispl, pelist) MPP_TYPE_, intent(in) :: sbuf(:) MPP_TYPE_, intent(inout) :: rbuf(:) @@ -62,6 +65,8 @@ subroutine MPP_ALLTOALLV_(sbuf, ssize, sdispl, rbuf, rsize, rdispl, pelist) end subroutine MPP_ALLTOALLV_ +!> Sends data from all to all processes with given data types, +!! displacements and block sizes. Non-mpi version subroutine MPP_ALLTOALLW_(sbuf, ssize, sdispl, stype, & rbuf, rsize, rdispl, rtype, pelist) MPP_TYPE_, intent(in) :: sbuf(:) diff --git a/mpp/include/mpp_chksum.h b/mpp/include/mpp_chksum.h index 9bf912058f..9efbfec73f 100644 --- a/mpp/include/mpp_chksum.h +++ b/mpp/include/mpp_chksum.h @@ -1,3 +1,5 @@ +! -*-f90-*- + !*********************************************************************** !* GNU Lesser General Public License !* @@ -16,20 +18,22 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** + !> @file -!> @ingroup mpp +!> @addtogroup mpp !> @brief Wrapper routine for @ref mpp_chksum interface +!> Wrapper routine for @ref mpp_chksum interface +!! +!> @returns i8_kind checksum of var, which will actually be int if no_8byte_integers is defined function MPP_CHKSUM_( var, pelist , mask_val) -!mold is a dummy array to be used by TRANSFER() -!must be same TYPE as result -!result is i8_kind, which will actually be int ifdef no_8byte_integers - !optional mask_val is masked away in checksum_int.h function via PACK() integer(i8_kind) :: MPP_CHKSUM_ - integer(MPP_TRANSFER_KIND_) :: mold(1) + integer(MPP_TRANSFER_KIND_) :: mold(1) !< Mold is a dummy array to be used by TRANSFER(), + !! must be same TYPE as result MPP_TYPE_, intent(in) :: var MPP_RANK_ integer, intent(in), optional :: pelist(:) - MPP_TYPE_, intent(in),optional :: mask_val + MPP_TYPE_, intent(in),optional :: mask_val !< optional mask_val is masked away in checksum_int.h + !! function via PACK() if ( PRESENT(mask_val) ) then MPP_CHKSUM_ = mpp_chksum( TRANSFER(var,mold), pelist, & @@ -38,5 +42,5 @@ function MPP_CHKSUM_( var, pelist , mask_val) MPP_CHKSUM_ = mpp_chksum( TRANSFER(var,mold), pelist ) end if - return - end function MPP_CHKSUM_ + return +end function MPP_CHKSUM_ diff --git a/mpp/include/mpp_chksum_int.h b/mpp/include/mpp_chksum_int.h index fe58fd38a6..1d511a2381 100644 --- a/mpp/include/mpp_chksum_int.h +++ b/mpp/include/mpp_chksum_int.h @@ -1,3 +1,5 @@ +! -*-f90-*- + !*********************************************************************** !* GNU Lesser General Public License !* @@ -17,9 +19,12 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup mpp !> @brief Routines for calculating global integer checksums for the @ref mpp_chksum interface. +!> @addtogroup mpp_mod +!> @{ + +!> Calculates integer checksum over pelist function MPP_CHKSUM_INT_( var, pelist, mask_val ) integer(i8_kind) :: MPP_CHKSUM_INT_ MPP_TYPE_, intent(in) :: var MPP_RANK_ @@ -41,8 +46,7 @@ function MPP_CHKSUM_INT_( var, pelist, mask_val ) end function MPP_CHKSUM_INT_ -!Handles real mask for easier implimentation -! until exists full integer vartypes... +!> Handles real mask for easier implementation function MPP_CHKSUM_INT_RMASK_( var, pelist, mask_val ) integer(KIND=i8_kind) :: MPP_CHKSUM_INT_RMASK_ MPP_TYPE_, intent(in) :: var MPP_RANK_ @@ -108,3 +112,4 @@ function MPP_CHKSUM_INT_RMASK_( var, pelist, mask_val ) return end function MPP_CHKSUM_INT_RMASK_ +!> @} diff --git a/mpp/include/mpp_chksum_scalar.h b/mpp/include/mpp_chksum_scalar.h index d4d26b947d..5335fe8915 100644 --- a/mpp/include/mpp_chksum_scalar.h +++ b/mpp/include/mpp_chksum_scalar.h @@ -1,3 +1,5 @@ +! -*-f90-*- + !*********************************************************************** !* GNU Lesser General Public License !* @@ -17,14 +19,17 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup mpp -!> @brief Wrapper routine for scalar checksums +!> @addtogroup mpp_mod +!> @{ + +!> @brief Wrapper routine for scalar checksums +!! +!> mold is a dummy array to be used by TRANSFER() +!! must be same TYPE as result +!! result is i8_kind, which will actually be int ifdef no_8byte_integers +!! mold and mask_val must be same numBytes, otherwise undefined behavior function MPP_CHKSUM_( var, pelist, mask_val ) -!mold is a dummy array to be used by TRANSFER() -!must be same TYPE as result -!result is i8_kind, which will actually be int ifdef no_8byte_integers - !mold and mask_val must be same numBytes, otherwise undefined behavior integer(i8_kind) :: MPP_CHKSUM_ MPP_TYPE_, intent(in) :: var integer, intent(in), optional :: pelist(:) @@ -41,3 +46,4 @@ function MPP_CHKSUM_( var, pelist, mask_val ) end if return end function MPP_CHKSUM_ +!> @} diff --git a/mpp/include/mpp_comm.inc b/mpp/include/mpp_comm.inc index 75d73ff8e1..22489fbb37 100644 --- a/mpp/include/mpp_comm.inc +++ b/mpp/include/mpp_comm.inc @@ -19,9 +19,11 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup mpp -!> @brief Imports checksum, gather, and scatter routines used for communications and calculations -!! between PE's in @ref mpp_mod +!> @brief Imports checksum, gather, and scatter routines from other include files used +!! for communications and calculations between PE's in @ref mpp_mod + +!> @addtogroup mpp_mod +!> @{ #if defined(use_libMPI) #include @@ -444,4 +446,4 @@ #define MPP_SCATTER_PELIST_2D_ mpp_scatter_pelist_real8_2d #define MPP_SCATTER_PELIST_3D_ mpp_scatter_pelist_real8_3d #include - +!> @} diff --git a/mpp/include/mpp_comm_mpi.inc b/mpp/include/mpp_comm_mpi.inc index ca0d8fb60b..ac6df35894 100644 --- a/mpp/include/mpp_comm_mpi.inc +++ b/mpp/include/mpp_comm_mpi.inc @@ -19,22 +19,23 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup mpp !> @brief Routines to initialize and finalize @ref mpp_mod with mpi enabled. +!> @addtogroup mpp_mod +!> @{ + !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ! ! ! ROUTINES TO INITIALIZE/FINALIZE MPP MODULE: mpp_init, mpp_exit ! ! ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - ! subroutine mpp_init( flags, in, out, err, log ) - ! integer, optional, intent(in) :: flags, in, out, err, log - !> @brief Initialize the @ref mpp_mod module + !> @brief Initialize the @ref mpp_mod module. Must be called before any usage. subroutine mpp_init( flags, localcomm, test_level, alt_input_nml_path ) - integer, optional, intent(in) :: flags - integer, optional, intent(in) :: localcomm - integer, optional, intent(in) :: test_level - character(len=*), optional, intent(in) :: alt_input_nml_path + integer, optional, intent(in) :: flags !< Flags for debug output, can be MPP_VERBOSE or MPP_DEBUG + integer, optional, intent(in) :: localcomm !< Id of MPI communicator used to initialize + integer, optional, intent(in) :: test_level !< Used to exit initialization at certain stages + !! before completion for testing purposes + character(len=*), optional, intent(in) :: alt_input_nml_path !< Input path for namelist integer :: i, iunit logical :: opened, existed integer :: io_status @@ -159,39 +160,6 @@ if (t_level == 7) return - !if optional argument logunit=stdout, write messages to stdout instead. - !if specifying non-defaults, you must specify units not yet in use. - ! if( PRESENT(in) )then - ! inquire( unit=in, opened=opened ) - ! if( opened )call mpp_error( FATAL, 'MPP_INIT: unable to open stdin.' ) - ! in_unit=in - ! end if - ! if( PRESENT(out) )then - ! inquire( unit=out, opened=opened ) - ! if( opened )call mpp_error( FATAL, 'MPP_INIT: unable to open stdout.' ) - ! out_unit=out - ! end if - ! if( PRESENT(err) )then - ! inquire( unit=err, opened=opened ) - ! if( opened )call mpp_error( FATAL, 'MPP_INIT: unable to open stderr.' ) - ! err_unit=err - ! end if - ! log_unit=get_unit() - ! if( PRESENT(log) )then - ! inquire( unit=log, opened=opened ) - ! if( opened .AND. log.NE.out_unit )call mpp_error( FATAL, 'MPP_INIT: unable to open stdlog.' ) - ! log_unit=log - ! end if - !!log_unit can be written to only from root_pe, all others write to stdout - ! if( log_unit.NE.out_unit )then - ! inquire( unit=log_unit, opened=opened ) - ! if( opened )call mpp_error( FATAL, 'MPP_INIT: specified unit for stdlog already in use.' ) - ! if( pe.EQ.root_pe )open( unit=log_unit, file=trim(configfile), status='REPLACE' ) - ! call mpp_sync() - ! if( pe.NE.root_pe )open( unit=log_unit, file=trim(configfile), status='OLD' ) - ! end if - - !messages iunit = stdlog() ! workaround for lf95. if( verbose )call mpp_error( NOTE, 'MPP_INIT: initializing MPP module...' ) @@ -215,7 +183,8 @@ end subroutine mpp_init !####################################################################### - !> To be called at the end of a run +!> Finalizes process termination. To be called at the end of a run. +!! Certain mpi implementations(openmpi) will fail if this is not called before program termination subroutine mpp_exit() integer :: i, j, n, nmax, out_unit, log_unit real :: t, tmin, tmax, tavg, tstd @@ -329,7 +298,7 @@ end subroutine mpp_exit !####################################################################### !> Set the mpp_stack variable to be at least n LONG words long subroutine mpp_set_stack_size(n) - integer, intent(in) :: n + integer, intent(in) :: n !< stack size to set character(len=8) :: text if( n.GT.mpp_stack_size .AND. allocated(mpp_stack) )deallocate(mpp_stack) @@ -349,10 +318,12 @@ end subroutine mpp_exit ! BASIC MESSAGE PASSING ROUTINE: mpp_transmit ! ! ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + !> Broadcasts a character string from the given pe to it's pelist subroutine mpp_broadcast_char(data, length, from_pe, pelist ) - character(len=*), intent(inout) :: data(:) - integer, intent(in) :: length, from_pe - integer, intent(in), optional :: pelist(:) + character(len=*), intent(inout) :: data(:) !< Character string to send + integer, intent(in) :: length !< length of given data to broadcast + integer, intent(in) :: from_pe !< pe to broadcast from + integer, intent(in), optional :: pelist(:) !< optional pelist to broadcast to integer :: n, i, from_rank character :: str1D(length*size(data(:))) pointer(lptr, str1D) @@ -1408,7 +1379,8 @@ end subroutine mpp_exit #undef MPP_TYPE_ #undef MPP_TYPE_CREATE_ -! NOTE: This should probably not take a pointer, but for now we do this. +!> Deallocates memory for mpp_type objects +!! @TODO This should probably not take a pointer, but for now we do this. subroutine mpp_type_free(dtype) type(mpp_type), pointer, intent(inout) :: dtype @@ -1445,3 +1417,4 @@ subroutine mpp_type_free(dtype) call increment_current_clock(EVENT_TYPE_FREE, MPP_TYPE_BYTELEN_) end subroutine mpp_type_free +!> @} diff --git a/mpp/include/mpp_comm_nocomm.inc b/mpp/include/mpp_comm_nocomm.inc index 9324e7f283..efe25205e3 100644 --- a/mpp/include/mpp_comm_nocomm.inc +++ b/mpp/include/mpp_comm_nocomm.inc @@ -18,9 +18,7 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** - !> @file -!> @ingroup mpp !> @brief Routines to initialize and finalize @ref mpp_mod without MPI. !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @@ -28,14 +26,13 @@ ! ROUTINES TO INITIALIZE/FINALIZE MPP MODULE: mpp_init, mpp_exit ! ! ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - ! subroutine mpp_init( flags, in, out, err, log ) - ! integer, optional, intent(in) :: flags, in, out, err, log !> @brief Initialize the @ref mpp_mod module subroutine mpp_init( flags, localcomm, test_level, alt_input_nml_path ) - integer, optional, intent(in) :: flags - integer, optional, intent(in) :: localcomm ! dummy here, used only in MPI - integer, optional, intent(in) :: test_level - character(len=*), optional, intent(in) :: alt_input_nml_path + integer, optional, intent(in) :: flags !< Flags for debug output, can be MPP_VERBOSE or MPP_DEBUG + integer, optional, intent(in) :: localcomm !< Id of MPI communicator used to initialize + integer, optional, intent(in) :: test_level !< Used to exit initialization at certain stages + !! before completion for testing purposes + character(len=*), optional, intent(in) :: alt_input_nml_path !< Input path for namelist integer :: my_pe, num_pes, len, i, logunit logical :: opened, existed integer :: io_status @@ -122,38 +119,6 @@ subroutine mpp_init( flags, localcomm, test_level, alt_input_nml_path ) else open( newunit=etc_unit, file=trim(etcfile) ) endif - !if optional argument logunit=stdout, write messages to stdout instead. - !if specifying non-defaults, you must specify units not yet in use. - ! if( PRESENT(in) )then - ! inquire( unit=in, opened=opened ) - ! if( opened )call mpp_error( FATAL, 'MPP_INIT: unable to open stdin.' ) - ! in_unit=in - ! end if - ! if( PRESENT(out) )then - ! inquire( unit=out, opened=opened ) - ! if( opened )call mpp_error( FATAL, 'MPP_INIT: unable to open stdout.' ) - ! out_unit=out - ! end if - ! if( PRESENT(err) )then - ! inquire( unit=err, opened=opened ) - ! if( opened )call mpp_error( FATAL, 'MPP_INIT: unable to open stderr.' ) - ! err_unit=err - ! end if - ! log_unit=get_unit() - ! if( PRESENT(log) )then - ! inquire( unit=log, opened=opened ) - ! if( opened .AND. log.NE.out_unit )call mpp_error( FATAL, 'MPP_INIT: unable to open stdlog.' ) - ! log_unit=log - ! end if - !!log_unit can be written to only from root_pe, all others write to stdout - ! if( log_unit.NE.out_unit )then - ! inquire( unit=log_unit, opened=opened ) - ! if( opened )call mpp_error( FATAL, 'MPP_INIT: specified unit for stdlog already in use.' ) - ! if( pe.EQ.root_pe )open( unit=log_unit, file=trim(configfile), status='REPLACE' ) - ! call mpp_sync() - ! if( pe.NE.root_pe )open( unit=log_unit, file=trim(configfile), status='OLD' ) - ! end if - !messages if( verbose )call mpp_error( NOTE, 'MPP_INIT: initializing MPP module...' ) diff --git a/mpp/include/mpp_data_mpi.inc b/mpp/include/mpp_data_mpi.inc index ea932142ef..03c247c869 100644 --- a/mpp/include/mpp_data_mpi.inc +++ b/mpp/include/mpp_data_mpi.inc @@ -18,7 +18,6 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** - !> @file !> @ingroup mpp_data_mod !> @brief Holds dummy constants and stack data for @ref mpp_mod and @ref mpp_domains_mod. @@ -28,7 +27,7 @@ ! The following data is used in mpp_mod and its components ! !----------------------------------------------------------------! integer :: stat(MPI_STATUS_SIZE) -real(r8_kind), allocatable :: mpp_stack(:) +real(r8_kind), allocatable :: mpp_stack(:) !< stack used for general mpp operations !--- some dummy variables with dummy values that will never be used integer, parameter :: ptr_stack = -999 @@ -40,8 +39,8 @@ integer, parameter :: mpp_from_pe = -999, ptr_from = -999 !-------------------------------------------------------------------! ! The following data is used in mpp_domains_mod and its components ! !-------------------------------------------------------------------! -real(r8_kind), allocatable :: mpp_domains_stack(:) -real(r8_kind), allocatable :: mpp_domains_stack_nonblock(:) +real(r8_kind), allocatable :: mpp_domains_stack(:) !< stack used to hold data for domain operations +real(r8_kind), allocatable :: mpp_domains_stack_nonblock(:) !< stack used for non-blocking domain operations !--- some dummy variables with dummy values that will never be used integer, parameter :: ptr_domains_stack = -999 integer, parameter :: ptr_domains_stack_nonblock = -999 diff --git a/mpp/include/mpp_define_nest_domains.inc b/mpp/include/mpp_define_nest_domains.inc index 4b7568f37d..cbcefd8927 100644 --- a/mpp/include/mpp_define_nest_domains.inc +++ b/mpp/include/mpp_define_nest_domains.inc @@ -21,10 +21,12 @@ !*********************************************************************** !> @file -!> @ingroup mpp_domains_mod !> @brief Routines for use in @ref mpp_domains_mod for routines utilizing !! domains with nested grids +!> @addtogroup mpp_domains_mod +!> @{ + !############################################################################# !> @brief Set up a domain to pass data between aligned coarse and fine grid of nested model. !! @@ -82,12 +84,14 @@ !! allocate(buffer (is_f:ie_f, js_f:je_f,nz)) !! call mpp_update_nest_coarse(x, nest_domain, buffer) ! -!! call mpp_define_nest_domains (nest_domain, domain, num_nest, nest_level, tile_fine, tile_coarse, & -!! istart_coarse, icount_coarse, jstart_coarse, jcount_coarse, & +!! call mpp_define_nest_domains (nest_domain, domain, num_nest, nest_level, tile_fine, tile_coarse, +!! istart_coarse, icount_coarse, jstart_coarse, jcount_coarse, !! npes_nest_tile, x_refine, y_refine, extra_halo, name) +!! !! @endcode !! !> @note Currently the contact will be limited to overlap contact. +!! subroutine mpp_define_nest_domains(nest_domain, domain, num_nest, nest_level, tile_fine, tile_coarse, & istart_coarse, icount_coarse, jstart_coarse, jcount_coarse, npes_nest_tile, & x_refine, y_refine, extra_halo, name) @@ -456,9 +460,9 @@ end subroutine mpp_shift_nest_domains subroutine define_nest_level_type(nest_domain, x_refine, y_refine, extra_halo) - type(nest_level_type), intent(inout) :: nest_domain - integer, intent(in ) :: extra_halo - integer, intent(in ) :: x_refine, y_refine + type(nest_level_type), intent(inout) :: nest_domain !< nest domain to be defined + integer, intent(in ) :: extra_halo !< halo value + integer, intent(in ) :: x_refine, y_refine !< x and y refinements integer :: n integer :: npes, npes_fine, npes_coarse @@ -1086,8 +1090,8 @@ subroutine compute_overlap_coarse_to_fine(nest_domain, overlap, extra_halo, posi end subroutine compute_overlap_coarse_to_fine !############################################################################### -!-- This routine will compute the send and recv information between overlapped nesting -!-- region. The data is assumed on T-cell center. +!> This routine will compute the send and recv information between overlapped nesting +!! region. The data is assumed on T-cell center. subroutine compute_overlap_fine_to_coarse(nest_domain, overlap, position, name) type(nest_level_type), intent(inout) :: nest_domain type(nestSpec), intent(inout) :: overlap @@ -2561,3 +2565,4 @@ function search_C2F_nest_overlap(nest_domain, nest_level, extra_halo, position) mpp_is_nest_coarse = nest_domain%nest(nest_level)%is_coarse_pe end function mpp_is_nest_coarse +!> @} diff --git a/mpp/include/mpp_do_check.h b/mpp/include/mpp_do_check.h index 6768542837..ef2e4a0753 100644 --- a/mpp/include/mpp_do_check.h +++ b/mpp/include/mpp_do_check.h @@ -18,15 +18,17 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup mpp !> @brief Updates data domain of 3D field whose computational domains have been computed +!> @addtogroup mpp_domains_mod +!> @{ + + !> Updates data domain of 3D field whose computational domains have been computed subroutine MPP_DO_CHECK_3D_( f_addrs, domain, check, d_type, ke, flags, name) -!updates data domain of 3D field whose computational domains have been computed integer(i8_kind), intent(in) :: f_addrs(:,:) type(domain2D), intent(in) :: domain type(overlapSpec), intent(in) :: check - MPP_TYPE_, intent(in) :: d_type ! creates unique interface + MPP_TYPE_, intent(in) :: d_type ! @} diff --git a/mpp/include/mpp_do_checkV.h b/mpp/include/mpp_do_checkV.h index b8ebe9f833..edd73e4382 100644 --- a/mpp/include/mpp_do_checkV.h +++ b/mpp/include/mpp_do_checkV.h @@ -18,12 +18,14 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup mpp !> @brief Updates data domain of 3D field whose computational domains have been computed +!> @addtogroup mpp_domains_mod +!> @{ + + !> Updates data domain of 3D field whose computational domains have been computed subroutine MPP_DO_CHECK_3D_V_(f_addrsx,f_addrsy, domain, check_x, check_y, & d_type, ke, flags, name) -!updates data domain of 3D field whose computational domains have been computed integer(i8_kind), intent(in) :: f_addrsx(:,:), f_addrsy(:,:) type(domain2d), intent(in) :: domain type(overlapSpec), intent(in) :: check_x, check_y @@ -531,3 +533,4 @@ return end subroutine MPP_DO_CHECK_3D_V_ +!> @} diff --git a/mpp/include/mpp_do_global_field.h b/mpp/include/mpp_do_global_field.h index ed1a9c0bc7..f38d4054e1 100644 --- a/mpp/include/mpp_do_global_field.h +++ b/mpp/include/mpp_do_global_field.h @@ -16,10 +16,12 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @addtogroup mpp_domains_mod +!> @{ + !> Gets a global field from a local field + !! local field may be on compute OR data domain subroutine MPP_DO_GLOBAL_FIELD_3D_( domain, local, global, tile, ishift, jshift, flags, default_data) -!get a global field from a local field -!local field may be on compute OR data domain type(domain2D), intent(in) :: domain MPP_TYPE_, intent(in) :: local(:,:,:) integer, intent(in) :: tile, ishift, jshift @@ -519,3 +521,4 @@ call mpp_sync_self() end subroutine MPP_DO_GLOBAL_FIELD_A2A_3D_ +!> @} diff --git a/mpp/include/mpp_do_global_field_ad.h b/mpp/include/mpp_do_global_field_ad.h index 88c15a715f..235ef1cf3b 100644 --- a/mpp/include/mpp_do_global_field_ad.h +++ b/mpp/include/mpp_do_global_field_ad.h @@ -19,10 +19,12 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @addtogroup mpp_domains_mod +!> @{ + !> Gets a global field from a local field + !! local field may be on compute OR data domain subroutine MPP_DO_GLOBAL_FIELD_3D_AD_( domain, local, global, tile, ishift, jshift, flags, default_data) -!get a global field from a local field -!local field may be on compute OR data domain type(domain2D), intent(in) :: domain MPP_TYPE_, intent(inout) :: local(:,:,:) integer, intent(in) :: tile, ishift, jshift @@ -278,3 +280,4 @@ return end subroutine MPP_DO_GLOBAL_FIELD_3D_AD_ +!> @} diff --git a/mpp/include/mpp_do_redistribute.h b/mpp/include/mpp_do_redistribute.h index d238828e2d..cf812b721c 100644 --- a/mpp/include/mpp_do_redistribute.h +++ b/mpp/include/mpp_do_redistribute.h @@ -16,6 +16,8 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @addtogroup mpp_domains_mod +!> @{ subroutine MPP_DO_REDISTRIBUTE_3D_( f_in, f_out, d_comm, d_type ) integer(i8_kind), intent(in) :: f_in(:), f_out(:) type(DomainCommunicator2D), intent(in) :: d_comm @@ -109,3 +111,4 @@ call mpp_sync_self() end subroutine MPP_DO_REDISTRIBUTE_3D_ +!> @} diff --git a/mpp/include/mpp_do_update.h b/mpp/include/mpp_do_update.h index 7bb5eefff3..c770d86483 100644 --- a/mpp/include/mpp_do_update.h +++ b/mpp/include/mpp_do_update.h @@ -17,8 +17,10 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @addtogroup mpp_domains_mod +!> @{ + !> Updates data domain of 3D field whose computational domains have been computed subroutine MPP_DO_UPDATE_3D_( f_addrs, domain, update, d_type, ke, flags) -!updates data domain of 3D field whose computational domains have been computed integer(i8_kind), intent(in) :: f_addrs(:,:) type(domain2D), intent(in) :: domain type(overlapSpec), intent(in) :: update @@ -299,3 +301,4 @@ call mpp_clock_end(wait_clock) return end subroutine MPP_DO_UPDATE_3D_ +!> @} diff --git a/mpp/include/mpp_do_updateV.h b/mpp/include/mpp_do_updateV.h index 1f8c9aa5ba..4009cd2b1b 100644 --- a/mpp/include/mpp_do_updateV.h +++ b/mpp/include/mpp_do_updateV.h @@ -17,9 +17,11 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @addtogroup mpp_domains_mod +!> @{ + !> Updates data domain of 3D field whose computational domains have been computed subroutine MPP_DO_UPDATE_3D_V_(f_addrsx,f_addrsy, domain, update_x, update_y, & d_type, ke, gridtype, flags) -!updates data domain of 3D field whose computational domains have been computed integer(i8_kind), intent(in) :: f_addrsx(:,:), f_addrsy(:,:) type(domain2d), intent(in) :: domain type(overlapSpec), intent(in) :: update_x, update_y @@ -1196,3 +1198,4 @@ return end subroutine MPP_DO_UPDATE_3D_V_ +!> @} diff --git a/mpp/include/mpp_do_updateV_ad.h b/mpp/include/mpp_do_updateV_ad.h index 65a803b6b8..d6cce14abf 100644 --- a/mpp/include/mpp_do_updateV_ad.h +++ b/mpp/include/mpp_do_updateV_ad.h @@ -19,10 +19,11 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** - +!> @addtogroup mpp_domains_mod +!> @{ + !> Updates data domain of 3D field whose computational domains have been computed subroutine MPP_DO_UPDATE_AD_3D_V_(f_addrsx,f_addrsy, domain, update_x, update_y, & d_type, ke, gridtype, flags) -!updates data domain of 3D field whose computational domains have been computed integer(i8_kind), intent(in) :: f_addrsx(:,:), f_addrsy(:,:) type(domain2d), intent(in) :: domain type(overlapSpec), intent(in) :: update_x, update_y @@ -1293,3 +1294,4 @@ return end subroutine MPP_DO_UPDATE_AD_3D_V_ +!> @} diff --git a/mpp/include/mpp_do_updateV_nonblock.h b/mpp/include/mpp_do_updateV_nonblock.h index 7be5fde3d1..aa4a83607d 100644 --- a/mpp/include/mpp_do_updateV_nonblock.h +++ b/mpp/include/mpp_do_updateV_nonblock.h @@ -17,6 +17,8 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @addtogroup mpp_domains_mod +!> @{ subroutine MPP_START_DO_UPDATE_3D_V_(id_update, f_addrsx, f_addrsy, domain, update_x, update_y, & d_type, ke_max, ke_list, gridtype, flags, reuse_id_update, name) integer, intent(in) :: id_update @@ -1114,3 +1116,5 @@ subroutine MPP_COMPLETE_DO_UPDATE_3D_V_(id_update, f_addrsx, f_addrsy, domain, u return end subroutine MPP_COMPLETE_DO_UPDATE_3D_V_ +!> @} +!> @{ diff --git a/mpp/include/mpp_do_update_ad.h b/mpp/include/mpp_do_update_ad.h index 07992faf15..7afbe8317d 100644 --- a/mpp/include/mpp_do_update_ad.h +++ b/mpp/include/mpp_do_update_ad.h @@ -19,9 +19,11 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @addtogroup mpp_domains_mod +!> @{ + !> Updates data domain of 3D field whose computational domains have been computed subroutine MPP_DO_UPDATE_AD_3D_( f_addrs, domain, update, d_type, ke, flags) -!updates data domain of 3D field whose computational domains have been computed integer(i8_kind), intent(in) :: f_addrs(:,:) type(domain2D), intent(in) :: domain type(overlapSpec), intent(in) :: update @@ -271,3 +273,4 @@ return end subroutine MPP_DO_UPDATE_AD_3D_ +!> @} diff --git a/mpp/include/mpp_do_update_nest.h b/mpp/include/mpp_do_update_nest.h index bb844f48b5..4122516da2 100644 --- a/mpp/include/mpp_do_update_nest.h +++ b/mpp/include/mpp_do_update_nest.h @@ -17,6 +17,8 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @addtogroup mpp_domains_mod +!> @{ subroutine MPP_DO_UPDATE_NEST_FINE_3D_(f_addrs, nest_domain, update, d_type, ke, wb_addrs, eb_addrs, & sb_addrs, nb_addrs, flags, xbegin, xend, ybegin, yend) integer(i8_kind), intent(in) :: f_addrs(:) @@ -1156,5 +1158,5 @@ subroutine MPP_DO_UPDATE_NEST_COARSE_3D_V_(f_addrsx_in, f_addrsy_in, f_addrsx_ou return end subroutine MPP_DO_UPDATE_NEST_COARSE_3D_V_ - +!> @} #endif diff --git a/mpp/include/mpp_do_update_nonblock.h b/mpp/include/mpp_do_update_nonblock.h index 10fc2bdd71..7d1e90f92d 100644 --- a/mpp/include/mpp_do_update_nonblock.h +++ b/mpp/include/mpp_do_update_nonblock.h @@ -17,6 +17,8 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @addtogroup mpp_domains_mod +!> @{ subroutine MPP_START_DO_UPDATE_3D_(id_update, f_addrs, domain, update, d_type, ke_max, ke_list, flags, & & reuse_id_update, name) integer, intent(in) :: id_update @@ -374,3 +376,4 @@ subroutine MPP_COMPLETE_DO_UPDATE_3D_(id_update, f_addrs, domain, update, d_type return end subroutine MPP_COMPLETE_DO_UPDATE_3D_ +!> @} diff --git a/mpp/include/mpp_domains_comm.inc b/mpp/include/mpp_domains_comm.inc index e35dbdd6dc..a092aaf41c 100644 --- a/mpp/include/mpp_domains_comm.inc +++ b/mpp/include/mpp_domains_comm.inc @@ -21,9 +21,10 @@ !*********************************************************************** !> @file -!> @ingroup mpp_domains_mod !> @brief Routines for domain communications via @ref domaincommunicator2d +!> @addtogroup mpp_domains_mod +!> @{ function mpp_redistribute_init_comm(domain_in,l_addrs_in, domain_out,l_addrs_out, & isize_in,jsize_in,ksize_in,isize_out,jsize_out,ksize_out) RESULT(d_comm) type(DomainCommunicator2D), pointer :: d_comm @@ -205,7 +206,7 @@ end function mpp_redistribute_init_comm - + !> initializes a @ref DomainCommunicator2D type for use in @ref mpp_global_field function mpp_global_field_init_comm(domain,l_addr,isize_g,jsize_g,isize_l, & jsize_l, ksize,l_addr2,flags, position) RESULT(d_comm) type(DomainCommunicator2D), pointer :: d_comm @@ -749,6 +750,4 @@ endif end if end function set_domain_id - - -!####################################################################### +!> @} diff --git a/mpp/include/mpp_domains_define.inc b/mpp/include/mpp_domains_define.inc index bcb2bcbad4..f3d6eff63a 100644 --- a/mpp/include/mpp_domains_define.inc +++ b/mpp/include/mpp_domains_define.inc @@ -1,6 +1,4 @@ ! -*-f90-*- - - !*********************************************************************** !* GNU Lesser General Public License !* @@ -21,14 +19,10 @@ !*********************************************************************** !> @file -!> @ingroup mpp_domains_mod !> @brief Various routines handling domains in @ref mpp_domains_mod - ! - ! - ! - ! - ! +!> @addtogroup mpp_domains_mod +!> @{ !> @brief Instantiates a layout with the given indices and divisions subroutine mpp_define_layout2D( global_indices, ndivs, layout ) integer, intent(in) :: global_indices(:) !< (/ isg, ieg, jsg, jeg /); Defines the global domain. @@ -60,13 +54,11 @@ end subroutine mpp_define_layout2D !############################################################################ - ! - ! - ! - ! - ! NOTE: The following routine may need to revised to improve the capability. - ! It is very hard to make it balance for all the situation. - ! Hopefully some smart idea will come up someday. + + !> Defines a pelist for use with mosaic tiles + !! @note The following routine may need to revised to improve the capability. + !! It is very hard to make it balance for all the situation. + !! Hopefully some smart idea will come up someday. subroutine mpp_define_mosaic_pelist( sizes, pe_start, pe_end, pelist, costpertile) integer, dimension(:), intent(in) :: sizes integer, dimension(:), intent(inout) :: pe_start, pe_end @@ -162,8 +154,10 @@ end subroutine mpp_define_mosaic_pelist - !-- The following implementation is different from mpp_compute_extents - !-- The last block might have most points + !> Computes the extents of a grid block + !! + !> Tis implementation is different from mpp_compute_extents + !! The last block might have most points subroutine mpp_compute_block_extent(isg,ieg,ndivs,ibegin,iend) integer, intent(in) :: isg, ieg, ndivs integer, dimension(:), intent(out) :: ibegin, iend @@ -189,6 +183,7 @@ !##################################################################### + !> Computes extents for a grid decomposition with the given indices and divisions subroutine mpp_compute_extent(isg,ieg,ndivs,ibegin,iend, extent ) integer, intent(in) :: isg, ieg, ndivs integer, dimension(0:), intent(out) :: ibegin, iend @@ -281,15 +276,8 @@ !##################################################################### -!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - ! ! - !>@brief MPP_DEFINE_DOMAINS: define layout and decomposition ! - ! ! -!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - !> @brief MPP_DEFINE_DOMAINS: define layout and decomposition ! - !! - !> Routine to divide global array indices among domains, and assign domains to PEs + !> Define data and computational domains on a 1D set of data (isg:ieg) and assign them to PEs subroutine mpp_define_domains1D( global_indices, ndivs, domain, pelist, flags, halo, extent, maskmap, & memory_size, begin_halo, end_halo ) integer, intent(in) :: global_indices(:) !< (/ isg, ieg /) gives the extent of global domain @@ -465,10 +453,10 @@ end subroutine mpp_define_domains1D !################################################################################ - !> define the IO domain. + !> Define the layout for IO pe's for the given domain subroutine mpp_define_io_domain(domain, io_layout) - type(domain2D), intent(inout) :: domain - integer, intent(in ) :: io_layout(2) + type(domain2D), intent(inout) :: domain !< Input 2D domain + integer, intent(in ) :: io_layout(2) !< 2 value io pe layout to define integer :: layout(2) integer :: npes_in_group type(domain2D), pointer :: io_domain=>NULL() @@ -610,27 +598,17 @@ end subroutine mpp_define_io_domain - ! - ! - ! - ! - ! - ! - ! - ! - ! - ! - ! + !> Define 2D data and computational domain on global rectilinear cartesian domain + !! (isg:ieg,jsg:jeg) and assign them to PEs subroutine mpp_define_domains2D( global_indices, layout, domain, pelist, xflags, yflags, & xhalo, yhalo, xextent, yextent, maskmap, name, symmetry, memory_size, & whalo, ehalo, shalo, nhalo, is_mosaic, tile_count, tile_id, complete, x_cyclic_offset, y_cyclic_offset ) - !define 2D data and computational domain on global rectilinear cartesian domain (isg:ieg,jsg:jeg) - !and assign them to PEs integer, intent(in) :: global_indices(:) !<(/ isg, ieg, jsg, jeg /) - integer, intent(in) :: layout(:) - type(domain2D), intent(inout) :: domain - integer, intent(in), optional :: pelist(0:) - integer, intent(in), optional :: xflags, yflags, xhalo, yhalo + integer, intent(in) :: layout(:) !< pe layout + type(domain2D), intent(inout) :: domain !< 2D domain decomposition to define + integer, intent(in), optional :: pelist(0:) !< current pelist to run on + integer, intent(in), optional :: xflags, yflags !< directional flag + integer, intent(in), optional :: xhalo, yhalo !< halo sizes for x and y indices integer, intent(in), optional :: xextent(0:), yextent(0:) logical, intent(in), optional :: maskmap(0:,0:) character(len=*), intent(in), optional :: name @@ -1198,26 +1176,28 @@ end subroutine check_message_size !??? how to specify pelist, we may use two dimensional variable pelist to represent. !z1l: We assume the tilelist are in always limited to 1, 2, ... num_tile. If we want ! to remove this limitation, we need to add one more argument tilelist. + + !> Defines a domain for mosaic tile grids subroutine mpp_define_mosaic( global_indices, layout, domain, num_tile, num_contact, tile1, tile2, & istart1, iend1, jstart1, jend1, istart2, iend2, jstart2, jend2, pe_start, & pe_end, pelist, whalo, ehalo, shalo, nhalo, xextent, yextent, & maskmap, name, memory_size, symmetry, xflags, yflags, tile_id ) - integer, intent(in) :: global_indices(:,:) ! The size of first indice is 4, + integer, intent(in) :: global_indices(:,:) !>The size of first indice is 4, !! (/ isg, ieg, jsg, jeg /) - ! The size of second indice - ! is number of tiles in mosaic. + !!The size of second indice + !!is number of tiles in mosaic. integer, intent(in) :: layout(:,:) type(domain2D), intent(inout) :: domain - integer, intent(in) :: num_tile ! number of tiles in the mosaic - integer, intent(in) :: num_contact ! number of contact region between tiles. - integer, intent(in) :: tile1(:), tile2(:) ! tile number - integer, intent(in) :: istart1(:), iend1(:) ! i-index in tile_1 of contact region - integer, intent(in) :: jstart1(:), jend1(:) ! j-index in tile_1 of contact region - integer, intent(in) :: istart2(:), iend2(:) ! i-index in tile_2 of contact region - integer, intent(in) :: jstart2(:), jend2(:) ! j-index in tile_2 of contact region - integer, intent(in) :: pe_start(:) ! start pe of the pelist used in each tile - integer, intent(in) :: pe_end(:) ! end pe of the pelist used in each tile - integer, intent(in), optional :: pelist(:) ! list of processors used in mosaic + integer, intent(in) :: num_tile !< number of tiles in the mosaic + integer, intent(in) :: num_contact !< number of contact region between tiles. + integer, intent(in) :: tile1(:), tile2(:) !< tile number + integer, intent(in) :: istart1(:), iend1(:) !< i-index in tile_1 of contact region + integer, intent(in) :: jstart1(:), jend1(:) !< j-index in tile_1 of contact region + integer, intent(in) :: istart2(:), iend2(:) !< i-index in tile_2 of contact region + integer, intent(in) :: jstart2(:), jend2(:) !< j-index in tile_2 of contact region + integer, intent(in) :: pe_start(:) !< start pe of the pelist used in each tile + integer, intent(in) :: pe_end(:) !< end pe of the pelist used in each tile + integer, intent(in), optional :: pelist(:) !< list of processors used in mosaic integer, intent(in), optional :: whalo, ehalo, shalo, nhalo integer, intent(in), optional :: xextent(:,:), yextent(:,:) logical, intent(in), optional :: maskmap(:,:,:) @@ -1225,7 +1205,7 @@ end subroutine check_message_size integer, intent(in), optional :: memory_size(2) logical, intent(in), optional :: symmetry integer, intent(in), optional :: xflags, yflags - integer, intent(in), optional :: tile_id(:) ! tile_id of each tile in the mosaic + integer, intent(in), optional :: tile_id(:) !< tile_id of each tile in the mosaic integer :: n, m, ndivx, ndivy, nc, nlist, nt, pos, n1, n2 integer :: whalosz, ehalosz, shalosz, nhalosz, xhalosz, yhalosz, t1, t2, tile @@ -1568,17 +1548,18 @@ end subroutine check_message_size end subroutine mpp_define_mosaic !##################################################################### + !> Accessor function for value of mosaic_defined logical function mpp_mosaic_defined() - ! Accessor function for value of mosaic_defined mpp_mosaic_defined = mosaic_defined end function mpp_mosaic_defined !##################################################################### + !> @brief Computes remote domain overlaps + !! + !> Assumes only one in each direction + !! will calculate the overlapping for T,E,C,N-cell seperately. subroutine compute_overlaps( domain, position, update, check, ishift, jshift, x_cyclic_offset, y_cyclic_offset, & whalo, ehalo, shalo, nhalo ) - !computes remote domain overlaps - !assumes only one in each direction - !will calculate the overlapping for T,E,C,N-cell seperately. type(domain2D), intent(inout) :: domain type(overlapSpec), intent(inout), pointer :: update type(overlapSpec), intent(inout), pointer :: check @@ -2987,10 +2968,10 @@ end subroutine check_message_size end subroutine fill_overlap !#################################################################################### + !> Computes remote domain overlaps + !! assumes only one in each direction + !! will calculate the overlapping for T,E,C,N-cell seperately. subroutine compute_overlaps_fold_south( domain, position, ishift, jshift) - !computes remote domain overlaps - !assumes only one in each direction - !will calculate the overlapping for T,E,C,N-cell seperately. type(domain2D), intent(inout) :: domain integer, intent(in) :: position, ishift, jshift @@ -3628,10 +3609,10 @@ end subroutine check_message_size end subroutine compute_overlaps_fold_south !#################################################################################### + !> Computes remote domain overlaps + !! assumes only one in each direction + !! will calculate the overlapping for T,E,C,N-cell seperately. subroutine compute_overlaps_fold_west( domain, position, ishift, jshift) - !computes remote domain overlaps - !assumes only one in each direction - !will calculate the overlapping for T,E,C,N-cell seperately. type(domain2D), intent(inout) :: domain integer, intent(in) :: position, ishift, jshift @@ -4247,11 +4228,11 @@ end subroutine check_message_size end subroutine compute_overlaps_fold_west !############################################################################### + !> computes remote domain overlaps + !! assumes only one in each direction + !! will calculate the overlapping for T,E,C,N-cell seperately. + !! here assume fold-east and y-cyclic boundary condition subroutine compute_overlaps_fold_east( domain, position, ishift, jshift ) - !computes remote domain overlaps - !assumes only one in each direction - !will calculate the overlapping for T,E,C,N-cell seperately. - !here assume fold-east and y-cyclic boundary condition type(domain2D), intent(inout) :: domain integer, intent(in) :: position, ishift, jshift @@ -4939,7 +4920,7 @@ end subroutine check_message_size !##################################################################################### - ! add offset to the index + !> add offset to the index subroutine apply_cyclic_offset(lstart, lend, offset, gstart, gend, gsize) integer, intent(inout) :: lstart, lend integer, intent(in ) :: offset, gstart, gend, gsize @@ -4956,12 +4937,12 @@ end subroutine check_message_size end subroutine apply_cyclic_offset !################################################################################### - ! this routine setup the overlapping for mpp_update_domains for arbitrary halo update. - ! should be the halo size defined in mpp_define_domains. - ! xhalo_out, yhalo_out should not be exactly the same as xhalo_in, yhalo_in - ! currently we didn't consider about tripolar grid situation, because in the folded north - ! region, the overlapping is specified through list of points, not through rectangular. - ! But will return back to solve this problem in the future. + !> this routine sets up the overlapping for mpp_update_domains for arbitrary halo update. + !! should be the halo size defined in mpp_define_domains. + !! xhalo_out, yhalo_out should not be exactly the same as xhalo_in, yhalo_in + !! currently we didn't consider about tripolar grid situation, because in the folded north + !! region, the overlapping is specified through list of points, not through rectangular. + !! But will return back to solve this problem in the future. subroutine set_overlaps(domain, overlap_in, overlap_out, whalo_out, ehalo_out, shalo_out, nhalo_out) type(domain2d), intent(in) :: domain type(overlapSpec), intent(in) :: overlap_in @@ -5255,22 +5236,22 @@ end subroutine check_message_size end subroutine set_single_overlap !################################################################################### - !--- compute the overlapping between tiles for the T-cell. + !> compute the overlapping between tiles for the T-cell. subroutine define_contact_point( domain, position, num_contact, tile1, tile2, align1, align2, & refine1, refine2, istart1, iend1, jstart1, jend1, istart2, iend2, jstart2, jend2, & isgList, iegList, jsgList, jegList ) type(domain2D), intent(inout) :: domain integer, intent(in) :: position - integer, intent(in) :: num_contact ! number of contact regions - integer, dimension(:), intent(in) :: tile1, tile2 ! tile number - integer, dimension(:), intent(in) :: align1, align2 ! align direction of contact region - real, dimension(:), intent(in) :: refine1, refine2 ! refinement between tiles - integer, dimension(:), intent(in) :: istart1, iend1 ! i-index in tile_1 of contact region - integer, dimension(:), intent(in) :: jstart1, jend1 ! j-index in tile_1 of contact region - integer, dimension(:), intent(in) :: istart2, iend2 ! i-index in tile_2 of contact region - integer, dimension(:), intent(in) :: jstart2, jend2 ! j-index in tile_2 of contact region - integer, dimension(:), intent(in) :: isgList, iegList ! i-global domain of each tile - integer, dimension(:), intent(in) :: jsgList, jegList ! j-global domain of each tile + integer, intent(in) :: num_contact !< number of contact regions + integer, dimension(:), intent(in) :: tile1, tile2 !< tile number + integer, dimension(:), intent(in) :: align1, align2 !< align direction of contact region + real, dimension(:), intent(in) :: refine1, refine2 !< refinement between tiles + integer, dimension(:), intent(in) :: istart1, iend1 !< i-index in tile_1 of contact region + integer, dimension(:), intent(in) :: jstart1, jend1 !< j-index in tile_1 of contact region + integer, dimension(:), intent(in) :: istart2, iend2 !< i-index in tile_2 of contact region + integer, dimension(:), intent(in) :: jstart2, jend2 !< j-index in tile_2 of contact region + integer, dimension(:), intent(in) :: isgList, iegList !< i-global domain of each tile + integer, dimension(:), intent(in) :: jsgList, jegList !< j-global domain of each tile integer :: isc, iec, jsc, jec, isd, ied, jsd, jed integer :: isc1, iec1, jsc1, jec1, isc2, iec2, jsc2, jec2 @@ -5887,7 +5868,7 @@ end subroutine check_message_size end subroutine define_contact_point !############################################################################## -!--- always fill the contact according to index order. +!> always fill the contact according to index order. subroutine fill_contact(Contact, tile, is1, ie1, js1, je1, is2, ie2, js2, je2, align1, align2, refine1, refine2 ) type(contact_type), intent(inout) :: Contact integer, intent(in) :: tile @@ -5930,7 +5911,7 @@ subroutine fill_contact(Contact, tile, is1, ie1, js1, je1, is2, ie2, js2, je2, a end subroutine fill_contact !############################################################################ -! this routine sets the overlapping between tiles for E,C,N-cell based on T-cell overlapping +!> this routine sets the overlapping between tiles for E,C,N-cell based on T-cell overlapping subroutine set_contact_point(domain, position) type(domain2d), intent(inout) :: domain integer, intent(in) :: position @@ -6174,9 +6155,9 @@ subroutine set_contact_point(domain, position) end subroutine set_contact_point -!--- set up the overlapping for boundary check if the domain is symmetry. The check will be -!--- done on current pe for east boundary for E-cell, north boundary for N-cell, -!--- East and North boundary for C-cell +!> set up the overlapping for boundary check if the domain is symmetry. The check will be +!! done on current pe for east boundary for E-cell, north boundary for N-cell, +!! East and North boundary for C-cell subroutine set_check_overlap( domain, position ) type(domain2d), intent(in) :: domain integer, intent(in) :: position @@ -6338,7 +6319,7 @@ if(nrecv>0) call deallocate_overlap_type(overlap) end subroutine set_check_overlap !############################################################################# -!--- set up the overlapping for boundary if the domain is symmetry. +!> set up the overlapping for boundary if the domain is symmetry. subroutine set_bound_overlap( domain, position ) type(domain2d), intent(inout) :: domain integer, intent(in) :: position @@ -7472,14 +7453,8 @@ end subroutine check_alignment ! MPP_MODIFY_DOMAIN: modify extent of domain ! ! ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -! -! -! -! -! -! - -! + +!> @brief Modifies the exents of a domain subroutine mpp_modify_domain1D(domain_in,domain_out,cbegin,cend,gbegin,gend, hbegin, hend) ! type(domain1D), intent(in) :: domain_in !< The source domain. @@ -7513,21 +7488,9 @@ if(present(gend)) domain_out%global%end = gend domain_out%global%size = domain_out%global%end - domain_out%global%begin + 1 end subroutine mpp_modify_domain1D -! !####################################################################### -!---------------------------------------------------------------------------------- -! -! -! -! -! -! -! -! -! - -! + subroutine mpp_modify_domain2D(domain_in, domain_out, isc, iec, jsc, jec, isg, ieg, jsg, jeg, whalo, ehalo, & & shalo, nhalo) ! @@ -7763,7 +7726,7 @@ subroutine insert_check_overlap(overlap, pe, tileMe, dir, rotation, is, ie, js, end subroutine insert_check_overlap !####################################################################### -!--- this routine add the overlap_in into overlap_out +!> this routine adds the overlap_in into overlap_out subroutine add_check_overlap( overlap_out, overlap_in) type(overlap_type), intent(inout) :: overlap_out type(overlap_type), intent(in ) :: overlap_in @@ -8201,3 +8164,4 @@ subroutine set_domain_comm_inf(update) end subroutine set_domain_comm_inf +!> @} diff --git a/mpp/include/mpp_domains_misc.inc b/mpp/include/mpp_domains_misc.inc index 8623057e41..a6b833e3c5 100644 --- a/mpp/include/mpp_domains_misc.inc +++ b/mpp/include/mpp_domains_misc.inc @@ -19,37 +19,28 @@ !*********************************************************************** !> @file -!> @ingroup mpp_domains_mod !> @brief Initialization and finalization routines for @ref mpp_domains_mod as well !! as other utility routines. +!> @ingroup mpp_domains_mod +!> @{ !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ! ! ! MPP_DOMAINS: initialization and termination ! ! ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -! -! -! Initialize domain decomp package. -! -! -! Called to initialize the mpp_domains_mod package. -! -! flags can be set to MPP_VERBOSE to have -! mpp_domains_mod keep you informed of what it's up -! to. MPP_DEBUG returns even more information for debugging. -! -! mpp_domains_init will call mpp_init, to make sure -! mpp_mod is initialized. (Repeated -! calls to mpp_init do no harm, so don't worry if you already -! called it). -! -! -! -! + !> @brief Initialize domain decomp package. + !! + !> Called to initialize the mpp_domains_mod package. + !! flags can be set to MPP_VERBOSE to have + !! mpp_domains_mod keep you informed of what it's up + !! to. MPP_DEBUG returns even more information for debugging. + !! + !! mpp_domains_init will call mpp_init, to make sure + !! @ref mpp_mod is initialized. (Repeated + !! calls to @ref mpp_init do no harm, so don't worry if you already + !! called it). subroutine mpp_domains_init(flags) integer, intent(in), optional :: flags integer :: n @@ -168,18 +159,10 @@ subroutine init_nonblock_type( nonblock_obj ) end subroutine init_nonblock_type !##################################################################### -! -! -! Exit mpp_domains_mod. -! -! -! Serves no particular purpose, but is provided should you require to -! re-initialize mpp_domains_mod, for some odd reason. -! -! -! + + !> @brief Exit mpp_domains_mod. + !! Serves no particular purpose, but is provided should you require to + !! re-initialize mpp_domains_mod, for some odd reason. subroutine mpp_domains_exit() integer :: unit if( .NOT.module_is_initialized )return @@ -195,32 +178,24 @@ end subroutine init_nonblock_type ! MPP_CHECK_FIELD: Check parallel ! ! ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -! -! -! -! -! -! -! -! + !> This routine is used to do parallel checking for 3d data between n and m pe. The comparison is + !! is done on pelist2. When size of pelist2 is 1, we can check the halo; otherwise, + !! halo can not be checked. subroutine mpp_check_field_3D(field_in, pelist1, pelist2, domain, mesg, & w_halo, s_halo, e_halo, n_halo, force_abort, position ) -! This routine is used to do parallel checking for 3d data between n and m pe. The comparison is -! is done on pelist2. When size of pelist2 is 1, we can check the halo; otherwise, -! halo can not be checked. - - real, dimension(:,:,:), intent(in) :: field_in ! field to be checked - integer, dimension(:), intent(in) :: pelist1, pelist2 ! pe list for the two groups - type(domain2d), intent(in) :: domain ! domain for each pe - character(len=*), intent(in) :: mesg ! message to be printed out - ! if differences found + + real, dimension(:,:,:), intent(in) :: field_in !< field to be checked + integer, dimension(:), intent(in) :: pelist1, pelist2 !< pe list for the two groups + type(domain2d), intent(in) :: domain !< domain for each pe + character(len=*), intent(in) :: mesg !< message to be printed out + !! if differences found integer, intent(in), optional :: w_halo, s_halo, e_halo, n_halo - ! halo size for west, south, east and north - logical, intent(in), optional :: force_abort ! when true, call mpp_error if any difference - ! found. default value is false. - integer, intent(in), optional :: position ! when domain is symmetry, only value = CENTER is - ! implemented. + !< halo size for west, south, east and north + logical, intent(in), optional :: force_abort !< when true, call mpp_error if any difference + !! found. default value is false. + integer, intent(in), optional :: position !< when domain is symmetry, only value = CENTER is + !! implemented. integer :: k character(len=256) :: temp_mesg @@ -236,26 +211,23 @@ end subroutine init_nonblock_type !##################################################################################### -! -! -! + + !> This routine is used to do parallel checking for 2d data between n and m pe. The comparison is + !! is done on pelist2. When size of pelist2 is 1, we can check the halo; otherwise, + !! halo can not be checked. subroutine mpp_check_field_2d(field_in, pelist1, pelist2, domain, mesg, & w_halo, s_halo, e_halo, n_halo,force_abort, position ) -! This routine is used to do parallel checking for 2d data between n and m pe. The comparison is -! is done on pelist2. When size of pelist2 is 1, we can check the halo; otherwise, -! halo can not be checked. - - real, dimension(:,:), intent(in) :: field_in ! field to be checked - integer, dimension(:), intent(in) :: pelist1, pelist2 ! pe list for the two groups - type(domain2d), intent(in) :: domain ! domain for each pe - character(len=*), intent(in) :: mesg ! message to be printed out - ! if differences found - integer, intent(in), optional :: w_halo, s_halo, e_halo, n_halo - ! halo size for west, south, east and north - logical, intent(in), optional :: force_abort ! when, call mpp_error if any difference - ! found. default value is false. - integer, intent(in), optional :: position ! when domain is symmetry, only value = CENTER is - ! implemented. + + real, dimension(:,:), intent(in) :: field_in !< field to be checked + integer, dimension(:), intent(in) :: pelist1, pelist2 !< pe list for the two groups + type(domain2d), intent(in) :: domain !< domain for each pe + character(len=*), intent(in) :: mesg !< message to be printed out + !! if differences found + integer, intent(in), optional :: w_halo, s_halo, e_halo, n_halo !< halo size for west, south, east and north + logical, intent(in), optional :: force_abort !< when true, call mpp_error if any difference + !! found. default value is false. + integer, intent(in), optional :: position !< when domain is symmetry, only value = CENTER is + !! implemented. if(present(position)) then if(position .NE. CENTER .AND. domain%symmetry) call mpp_error(FATAL, & @@ -279,21 +251,20 @@ end subroutine init_nonblock_type !#################################################################################### + !> This routine is used to check field between running on 1 pe (pelist2) and + !! n pe(pelist1). The need_to_be_checked data is sent to the pelist2 and All the + !! comparison is done on pelist2. subroutine mpp_check_field_2d_type1(field_in, pelist1, pelist2, domain, mesg, & w_halo, s_halo, e_halo, n_halo,force_abort ) -! This routine is used to check field between running on 1 pe (pelist2) and -! n pe(pelist1). The need_to_be_checked data is sent to the pelist2 and All the -! comparison is done on pelist2. - - real, dimension(:,:), intent(in) :: field_in ! field to be checked - integer, dimension(:), intent(in) :: pelist1, pelist2 ! pe list for the two groups - type(domain2d), intent(in) :: domain ! domain for each pe - character(len=*), intent(in) :: mesg ! message to be printed out - ! if differences found - integer, intent(in), optional :: w_halo, s_halo, e_halo, n_halo - ! halo size for west, south, east and north - logical, intent(in), optional :: force_abort ! when, call mpp_error if any difference - ! found. default value is false. + + real, dimension(:,:), intent(in) :: field_in !< field to be checked + integer, dimension(:), intent(in) :: pelist1, pelist2 !< pe list for the two groups + type(domain2d), intent(in) :: domain !< domain for each pe + character(len=*), intent(in) :: mesg !< message to be printed out + !! if differences found + integer, intent(in), optional :: w_halo, s_halo, e_halo, n_halo !< halo size for west, south, east and north + logical, intent(in), optional :: force_abort !< when, call mpp_error if any difference + !! found. default value is false. ! some local data integer :: pe,npes, p @@ -412,17 +383,17 @@ end subroutine init_nonblock_type !#################################################################### + !> This routine is used to check field between running on m pe (root pe) and + !! n pe. This routine can not check halo. subroutine mpp_check_field_2d_type2(field_in, pelist1, pelist2, domain, mesg,force_abort) -! This routine is used to check field between running on m pe (root pe) and -! n pe. This routine can not check halo. real, dimension(:,:), intent(in) :: field_in type(domain2d), intent(in) :: domain integer, dimension(:), intent(in) :: pelist1 integer, dimension(:), intent(in) :: pelist2 character(len=*), intent(in) :: mesg - logical, intent(in), optional :: force_abort ! when, call mpp_error if any difference - ! found. default value is false. + logical, intent(in), optional :: force_abort !< when, call mpp_error if any difference + !! found. default value is false. ! some local variables logical :: check_success, error_exit real, dimension(:,:), allocatable :: field1, field2 @@ -485,14 +456,14 @@ end subroutine init_nonblock_type ! ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + !> broadcast domain (useful only outside the context of its own pelist) subroutine mpp_broadcast_domain_1( domain ) -!broadcast domain (useful only outside the context of its own pelist) type(domain2D), intent(inout) :: domain integer, allocatable :: pes(:) - logical :: native !true if I'm on the pelist of this domain + logical :: native !> true if I'm on the pelist of this domain integer :: listsize, listpos integer :: n - integer, dimension(12) :: msg, info !pe and compute domain of each item in list + integer, dimension(12) :: msg, info !> pe and compute domain of each item in list integer :: errunit errunit = stderr() @@ -609,14 +580,14 @@ end subroutine init_nonblock_type !############################################################################## + !> Broadcast domain (useful only outside the context of its own pelist) subroutine mpp_broadcast_domain_2( domain_in, domain_out ) -!broadcast domain (useful only outside the context of its own pelist) type(domain2D), intent(in) :: domain_in type(domain2D), intent(inout) :: domain_out integer, allocatable :: pes(:) integer :: listpos integer :: n - integer, dimension(12) :: msg, info !pe and compute domain of each item in list + integer, dimension(12) :: msg, info !< pe and compute domain of each item in list integer :: errunit, npes_in, npes_out, pstart, pend errunit = stderr() @@ -738,15 +709,15 @@ end subroutine init_nonblock_type end subroutine mpp_broadcast_domain_2 + !> Broadcast fine nested domain (useful only outside the context of its own pelist) subroutine mpp_broadcast_domain_nest_fine( domain, tile_nest ) -!broadcast domain (useful only outside the context of its own pelist) type(domain2D), intent(inout) :: domain integer, intent(in) :: tile_nest(:) integer, allocatable :: pes(:) - logical :: native !true if I'm on the pelist of this domain + logical :: native !< true if I'm on the pelist of this domain integer :: listsize, listpos, nestsize(size(tile_nest(:))) integer :: n, tile, ind, num_nest - integer, dimension(15) :: msg, info !pe and compute domain of each item in list + integer, dimension(15) :: msg, info !< pe and compute domain of each item in list integer :: errunit errunit = stderr() @@ -857,16 +828,16 @@ end subroutine init_nonblock_type end subroutine mpp_broadcast_domain_nest_fine + !> Broadcast nested domain (useful only outside the context of its own pelist) subroutine mpp_broadcast_domain_nest_coarse( domain, tile_coarse ) -!broadcast domain (useful only outside the context of its own pelist) type(domain2D), intent(inout) :: domain integer, intent(in) :: tile_coarse integer, allocatable :: pes(:) - logical :: native !true if I'm on the pelist of this domain + logical :: native !< true if I'm on the pelist of this domain integer :: listsize, listpos integer, allocatable :: tile_pesize(:) integer :: n, maxtile - integer, dimension(17) :: msg, info !pe and compute domain of each item in list + integer, dimension(17) :: msg, info !< pe and compute domain of each item in list integer :: errunit errunit = stderr() @@ -984,7 +955,7 @@ end subroutine init_nonblock_type end do end subroutine mpp_broadcast_domain_nest_coarse - +!> @} !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ! ! diff --git a/mpp/include/mpp_domains_reduce.inc b/mpp/include/mpp_domains_reduce.inc index 46d3bc935a..c0ef09d0e1 100644 --- a/mpp/include/mpp_domains_reduce.inc +++ b/mpp/include/mpp_domains_reduce.inc @@ -18,11 +18,12 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** - !> @file -!> @ingroup mpp_domains_mod !> @brief Routines for calculating data from distributed arrays +!> @addtogroup mpp_domains_mod +!> @{ + !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ! ! ! MPP_GLOBAL_REDUCE: get global max/min of field ! @@ -1145,3 +1146,4 @@ #define MPP_TYPE_ logical(l4_kind) #include #undef LOGICAL_VARIABLE +!> @} diff --git a/mpp/include/mpp_domains_util.inc b/mpp/include/mpp_domains_util.inc index 6f886b07b5..74b195b809 100644 --- a/mpp/include/mpp_domains_util.inc +++ b/mpp/include/mpp_domains_util.inc @@ -20,26 +20,10 @@ !*********************************************************************** !> @file -!> @ingroup mpp_domains_mod !> @brief Utility routines for getting and setting values in @ref mpp_domains_mod - ! - ! - ! Set user stack size. - ! - ! - ! This sets the size of an array that is used for internal storage by - ! mpp_domains. This array is used, for instance, to buffer the - ! data sent and received in halo updates. - ! - ! This call has implied global synchronization. It should be - ! placed somewhere where all PEs can call it. - ! - ! - ! - ! +!> @ingroup mpp_domains_mod +!> @{ !> @brief Set user stack size. !! @@ -428,20 +412,14 @@ end subroutine mpp_set_global_domain2D !##################################################################### - ! - ! - ! Retrieve 1D components of 2D decomposition. - ! - ! - ! It is sometime necessary to have direct recourse to the domain1D types - ! that compose a domain2D object. This call retrieves them. - ! - ! - ! - ! - ! + + !> @brief Retrieve 1D components of 2D decomposition. + !! + !! It is sometime necessary to have direct recourse to the domain1D types + !! that compose a domain2D object. This call retrieves them. + !! @code{.F90} + !! call mpp_get_domain_components( domain, x, y ) + !! @endcode subroutine mpp_get_domain_components( domain, x, y, tile_count ) type(domain2D), intent(in) :: domain type(domain1D), intent(inout), optional :: x, y @@ -651,7 +629,7 @@ subroutine mpp_get_domain_extents1D(domain, xextent, yextent) end subroutine mpp_get_domain_extents1D !##################################################################### -! This will return xextent and yextent for each tile +!> This will return xextent and yextent for each tile subroutine mpp_get_domain_extents2D(domain, xextent, yextent) type(domain2d), intent(in) :: domain integer, dimension(:,:), intent(inout) :: xextent, yextent @@ -794,32 +772,19 @@ subroutine mpp_get_layout2D( domain, layout ) end subroutine mpp_get_layout2D !##################################################################### - ! - ! - ! Returns the shift value in x and y-direction according to domain position.. - ! - ! - ! When domain is symmetry, one extra point maybe needed in - ! x- and/or y-direction. This routine will return the shift value based - ! on the position - ! - ! - ! - ! predefined data contains 2-d domain decomposition. - ! - ! - ! return value will be 0 or 1. - ! - ! - ! position of data. Its value can be CENTER, EAST, NORTH or CORNER. - ! - ! + + !> @brief Returns the shift value in x and y-direction according to domain position.. + !! + !> When domain is symmetry, one extra point maybe needed in + !! x- and/or y-direction. This routine will return the shift value based + !! on the position + !! @code{.F90} + !! call mpp_get_domain_shift( domain, ishift, jshift, position ) + !! @endcode subroutine mpp_get_domain_shift(domain, ishift, jshift, position) - type(domain2D), intent(in) :: domain - integer, intent(out) :: ishift, jshift - integer, optional, intent(in) :: position + type(domain2D), intent(in) :: domain!> predefined data contains 2-d domain decomposition. + integer, intent(out) :: ishift, jshift!< return value will be 0 or 1. + integer, optional, intent(in) :: position!< position of data. Its value can be CENTER, EAST, NORTH or CORNER. integer :: pos ishift = 0 ; jshift = 0 @@ -841,10 +806,8 @@ end subroutine mpp_get_domain_shift !##################################################################### + !> Return PE to the righ/left of this PE-domain. subroutine mpp_get_neighbor_pe_1d(domain, direction, pe) - - ! Return PE to the righ/left of this PE-domain. - type(domain1D), intent(inout) :: domain integer, intent(in) :: direction integer, intent(out) :: pe @@ -890,11 +853,9 @@ end subroutine mpp_get_domain_shift end subroutine mpp_get_neighbor_pe_1d !##################################################################### + !> Return PE North/South/East/West of this PE-domain. + !! direction must be NORTH, SOUTH, EAST or WEST. subroutine mpp_get_neighbor_pe_2d(domain, direction, pe) - - ! Return PE North/South/East/West of this PE-domain. - ! direction must be NORTH, SOUTH, EAST or WEST. - type(domain2D), intent(inout) :: domain integer, intent(in) :: direction integer, intent(out) :: pe @@ -1036,8 +997,8 @@ end subroutine mpp_get_domain_shift end function domain_update_is_needed !####################################################################### - ! this routine found the domain has the same halo size with the input - ! whalo, ehalo, + !> this routine found the domain has the same halo size with the input + !! whalo, ehalo, function search_update_overlap(domain, whalo, ehalo, shalo, nhalo, position) type(domain2d), intent(inout) :: domain integer, intent(in) :: whalo, ehalo, shalo, nhalo @@ -1094,7 +1055,7 @@ end subroutine mpp_get_domain_shift end function search_update_overlap !####################################################################### - ! this routine found the check at certain position + !> this routine finds the check at certain position function search_check_overlap(domain, position) type(domain2d), intent(in) :: domain integer, intent(in) :: position @@ -1116,7 +1077,7 @@ end subroutine mpp_get_domain_shift end function search_check_overlap !####################################################################### - ! this routine found the bound at certain position + !> This routine finds the bound at certain position function search_bound_overlap(domain, position) type(domain2d), intent(in) :: domain integer, intent(in) :: position @@ -1138,7 +1099,7 @@ end subroutine mpp_get_domain_shift end function search_bound_overlap !######################################################################## - ! return the tile_id on current pe + !> Returns the tile_id on current pe function mpp_get_tile_id(domain) type(domain2d), intent(in) :: domain integer, dimension(size(domain%tile_id(:))) :: mpp_get_tile_id @@ -1149,7 +1110,7 @@ end subroutine mpp_get_domain_shift end function mpp_get_tile_id !####################################################################### - ! return the tile_id on current pelist. one-tile-per-pe is assumed. + !> Return the tile_id on current pelist. one-tile-per-pe is assumed. subroutine mpp_get_tile_list(domain, tiles) type(domain2d), intent(in) :: domain integer, intent(inout) :: tiles(:) @@ -1166,7 +1127,7 @@ end subroutine mpp_get_domain_shift end subroutine mpp_get_tile_list !######################################################################## - ! return number of tiles in mosaic + !> Returns number of tiles in mosaic function mpp_get_ntile_count(domain) type(domain2d), intent(in) :: domain integer :: mpp_get_ntile_count @@ -1177,7 +1138,7 @@ end subroutine mpp_get_domain_shift end function mpp_get_ntile_count !######################################################################## - ! return number of tile on current pe + !> Returns number of tile on current pe function mpp_get_current_ntile(domain) type(domain2d), intent(in) :: domain integer :: mpp_get_current_ntile @@ -1188,9 +1149,9 @@ end subroutine mpp_get_domain_shift end function mpp_get_current_ntile !####################################################################### - ! return if current pe is the root pe of the tile, if number of tiles on current pe - ! is greater than 1, will return true, if isc==isg and jsc==jsg also will return true, - ! otherwise false will be returned. + !> Returns if current pe is the root pe of the tile, if number of tiles on current pe + !! is greater than 1, will return true, if isc==isg and jsc==jsg also will return true, + !! otherwise false will be returned. function mpp_domain_is_tile_root_pe(domain) type(domain2d), intent(in) :: domain logical :: mpp_domain_is_tile_root_pe @@ -1200,7 +1161,7 @@ end subroutine mpp_get_domain_shift end function mpp_domain_is_tile_root_pe !######################################################################### - ! return number of processors used on current tile. + !> Returns number of processors used on current tile. function mpp_get_tile_npes(domain) type(domain2d), intent(in) :: domain integer :: mpp_get_tile_npes @@ -1221,7 +1182,7 @@ end subroutine mpp_get_domain_shift end function mpp_get_tile_npes !######################################################################## - ! get the processors list used on current tile. + !> Get the processors list used on current tile. subroutine mpp_get_tile_pelist(domain, pelist) type(domain2d), intent(in) :: domain integer, intent(inout) :: pelist(:) @@ -2409,3 +2370,4 @@ end subroutine set_group_update mpp_group_update_is_set = (group%nscalar > 0 .OR. group%nvector > 0) end function mpp_group_update_is_set +!> @} diff --git a/mpp/include/mpp_gather.h b/mpp/include/mpp_gather.h index 28c5dad7e9..17b09c0312 100644 --- a/mpp/include/mpp_gather.h +++ b/mpp/include/mpp_gather.h @@ -16,6 +16,10 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @file + +!> @addtogroup mpp_mod +!> @{ subroutine MPP_GATHER_1D_(sbuf, rbuf,pelist) ! JWD: Did not create mpp_gather_2d because have no requirement for it ! JWD: See mpp_gather_2dv below @@ -242,3 +246,4 @@ subroutine MPP_GATHER_PELIST_3D_(is, ie, js, je, nk, pelist, array_seg, data, is return end subroutine MPP_GATHER_PELIST_3D_ +!> @} diff --git a/mpp/include/mpp_get_boundary.h b/mpp/include/mpp_get_boundary.h index 686551372b..2103aea05d 100644 --- a/mpp/include/mpp_get_boundary.h +++ b/mpp/include/mpp_get_boundary.h @@ -17,8 +17,10 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** -! this routine is used to retrieve scalar boundary data for symmetric domain. +!> @addtogroup mpp_domains_mod +!> @{ +!> This routine is used to retrieve scalar boundary data for symmetric domain. subroutine MPP_GET_BOUNDARY_2D_(field, domain, ebuffer, sbuffer, wbuffer, nbuffer, flags, & position, complete, tile_count) type(domain2D), intent(in) :: domain @@ -301,7 +303,7 @@ end subroutine MPP_GET_BOUNDARY_3D_ !#################################################################### -! vector update +!> vector update subroutine MPP_GET_BOUNDARY_2D_V_(fieldx, fieldy, domain, ebufferx, sbufferx, wbufferx, nbufferx, & ebuffery, sbuffery, wbuffery, nbuffery, flags, gridtype, & complete, tile_count) @@ -741,3 +743,4 @@ subroutine MPP_GET_BOUNDARY_3D_V_(fieldx, fieldy, domain, ebufferx, sbufferx, wb end if end subroutine MPP_GET_BOUNDARY_3D_V_ +!> @} diff --git a/mpp/include/mpp_get_boundary_ad.h b/mpp/include/mpp_get_boundary_ad.h index 6c3e395573..56a18120e6 100644 --- a/mpp/include/mpp_get_boundary_ad.h +++ b/mpp/include/mpp_get_boundary_ad.h @@ -18,9 +18,10 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @addtogroup mpp_domains_mod +!> @{ -! this routine is used to retrieve scalar boundary data for symmetric domain. - +!> This routine is used to retrieve scalar boundary data for symmetric domain. subroutine MPP_GET_BOUNDARY_AD_2D_(field, domain, ebuffer, sbuffer, wbuffer, nbuffer, flags, & position, complete, tile_count) type(domain2D), intent(in) :: domain @@ -303,7 +304,7 @@ end subroutine MPP_GET_BOUNDARY_AD_3D_ !#################################################################### -! vector update +!> vector update version of @ref mpp_get_boundary_ad_2d subroutine MPP_GET_BOUNDARY_AD_2D_V_(fieldx, fieldy, domain, ebufferx, sbufferx, wbufferx, nbufferx, & ebuffery, sbuffery, wbuffery, nbuffery, flags, gridtype, & complete, tile_count) @@ -743,3 +744,4 @@ subroutine MPP_GET_BOUNDARY_AD_3D_V_(fieldx, fieldy, domain, ebufferx, sbufferx, end if end subroutine MPP_GET_BOUNDARY_AD_3D_V_ +!> @} diff --git a/mpp/include/mpp_global_field.h b/mpp/include/mpp_global_field.h index f11ad15517..3e5ff0d9db 100644 --- a/mpp/include/mpp_global_field.h +++ b/mpp/include/mpp_global_field.h @@ -16,6 +16,10 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @addtogroup mpp_domains_mod +!> @{ + !> get a global field from a local field + !! local field may be on compute OR data domain subroutine MPP_GLOBAL_FIELD_2D_( domain, local, global, flags, position,tile_count, default_data) type(domain2D), intent(in) :: domain MPP_TYPE_, intent(in) :: local(:,:) @@ -38,8 +42,6 @@ end subroutine MPP_GLOBAL_FIELD_2D_ subroutine MPP_GLOBAL_FIELD_3D_( domain, local, global, flags, position, tile_count, default_data) -!get a global field from a local field -!local field may be on compute OR data domain type(domain2D), intent(in) :: domain MPP_TYPE_, intent(in) :: local(:,:,:) MPP_TYPE_, intent(out) :: global(:,:,:) @@ -114,3 +116,4 @@ gptr = LOC(global) call mpp_global_field( domain, local3D, global3D, flags, position,tile_count, default_data ) end subroutine MPP_GLOBAL_FIELD_5D_ +!> @} diff --git a/mpp/include/mpp_global_field_ad.h b/mpp/include/mpp_global_field_ad.h index b967e72fe8..7d948f9366 100644 --- a/mpp/include/mpp_global_field_ad.h +++ b/mpp/include/mpp_global_field_ad.h @@ -19,7 +19,10 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** - +!> @addtogroup mpp_domains_mod +!> @{ + !> Get a global field from a local field + !! local field may be on compute OR data domain subroutine MPP_GLOBAL_FIELD_2D_AD_( domain, local, global, flags, position,tile_count, default_data) type(domain2D), intent(in) :: domain MPP_TYPE_, intent(out) :: local(:,:) @@ -41,8 +44,6 @@ end subroutine MPP_GLOBAL_FIELD_2D_AD_ subroutine MPP_GLOBAL_FIELD_3D_AD_( domain, local, global, flags, position, tile_count, default_data) -!get a global field from a local field -!local field may be on compute OR data domain type(domain2D), intent(in) :: domain MPP_TYPE_, intent(out) :: local(:,:,:) MPP_TYPE_, intent(in) :: global(:,:,:) @@ -98,3 +99,4 @@ gptr = LOC(global) call mpp_global_field_ad( domain, local3D, global3D, flags, position,tile_count, default_data ) end subroutine MPP_GLOBAL_FIELD_5D_AD_ +!> @} diff --git a/mpp/include/mpp_global_field_ug.h b/mpp/include/mpp_global_field_ug.h index 4e7f65ad86..e21a7bffa8 100644 --- a/mpp/include/mpp_global_field_ug.h +++ b/mpp/include/mpp_global_field_ug.h @@ -16,6 +16,8 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @addtogroup mpp_domains_mod +!> @{ subroutine MPP_GLOBAL_FIELD_UG_2D_( domain, local, global, flags, default_data) type(domainUG), intent(in) :: domain MPP_TYPE_, intent(in) :: local(:) @@ -200,6 +202,4 @@ gptr = LOC(global) call mpp_global_field_UG( domain, local3D, global3D, flags, default_data ) end subroutine MPP_GLOBAL_FIELD_UG_5D_ - - - +!> @} diff --git a/mpp/include/mpp_global_reduce.h b/mpp/include/mpp_global_reduce.h index b0756f34bf..060a052868 100644 --- a/mpp/include/mpp_global_reduce.h +++ b/mpp/include/mpp_global_reduce.h @@ -16,6 +16,8 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @addtogroup mpp_domains_mod +!> @{ function MPP_GLOBAL_REDUCE_2D_( domain, field, locus, position ) MPP_TYPE_ :: MPP_GLOBAL_REDUCE_2D_ type(domain2D), intent(in) :: domain @@ -142,3 +144,4 @@ end if return end function MPP_GLOBAL_REDUCE_5D_ +!> @} diff --git a/mpp/include/mpp_global_sum.h b/mpp/include/mpp_global_sum.h index c59e350fe8..a230191952 100644 --- a/mpp/include/mpp_global_sum.h +++ b/mpp/include/mpp_global_sum.h @@ -16,6 +16,8 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @addtogroup mpp_domains_mod +!> @{ function MPP_GLOBAL_SUM_( domain, field, flags, position, tile_count, overflow_check) MPP_TYPE_ :: MPP_GLOBAL_SUM_ type(domain2D), intent(in) :: domain @@ -155,3 +157,4 @@ return end function MPP_GLOBAL_SUM_ +!> @} diff --git a/mpp/include/mpp_global_sum_ad.h b/mpp/include/mpp_global_sum_ad.h index 88baad07c3..627b208f17 100644 --- a/mpp/include/mpp_global_sum_ad.h +++ b/mpp/include/mpp_global_sum_ad.h @@ -19,7 +19,8 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** - +!> @addtogroup mpp_domains_mod +!> @{ subroutine MPP_GLOBAL_SUM_AD_( domain, field, gsum_, flags, position, tile_count, overflow_check) MPP_TYPE_ :: MPP_GLOBAL_SUM_ type(domain2D), intent(in) :: domain @@ -156,3 +157,4 @@ subroutine MPP_GLOBAL_SUM_AD_( domain, field, gsum_, flags, position, tile_count return end subroutine MPP_GLOBAL_SUM_AD_ +!> @} diff --git a/mpp/include/mpp_global_sum_tl.h b/mpp/include/mpp_global_sum_tl.h index b2e0e7e8c0..817d7a89fd 100644 --- a/mpp/include/mpp_global_sum_tl.h +++ b/mpp/include/mpp_global_sum_tl.h @@ -16,6 +16,8 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @addtogroup mpp_domains_mod +!> @{ subroutine MPP_GLOBAL_SUM_TL_( domain, field, field_tl, gsum, gsum_tl, flags, position, tile_count ) type(domain2D), intent(in) :: domain MPP_TYPE_, intent(inout) :: field(:,: MPP_EXTRA_INDICES_ ) @@ -31,3 +33,4 @@ return end subroutine MPP_GLOBAL_SUM_TL_ +!> @} diff --git a/mpp/include/mpp_group_update.h b/mpp/include/mpp_group_update.h index 924a2c7911..0f04c06c3b 100644 --- a/mpp/include/mpp_group_update.h +++ b/mpp/include/mpp_group_update.h @@ -17,6 +17,8 @@ !* License along with FMS. If not, see . !*********************************************************************** ! -*-f90-*- +!> @addtogroup mpp_domains_mod +!> @{ subroutine MPP_CREATE_GROUP_UPDATE_2D_(group, field, domain, flags, position, & whalo, ehalo, shalo, nhalo) type(mpp_group_update_type), intent(inout) :: group @@ -1022,3 +1024,4 @@ subroutine MPP_RESET_GROUP_UPDATE_FIELD_4D_V_(group, fieldx, fieldy) group%addrs_y(group%reset_index_v) = LOC(fieldy) end subroutine MPP_RESET_GROUP_UPDATE_FIELD_4D_V_ +!> @} diff --git a/mpp/include/mpp_io_connect.inc b/mpp/include/mpp_io_connect.inc index 5d484e702f..1da34ba761 100644 --- a/mpp/include/mpp_io_connect.inc +++ b/mpp/include/mpp_io_connect.inc @@ -19,9 +19,11 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup mpp_io_mod !> @brief Handles opening and closing files in @ref mpp_io_mod +!> @addtogroup mpp_io_mod +!> @{ + ! ! @@ -995,3 +997,4 @@ return end subroutine file_size +!> @} diff --git a/mpp/include/mpp_io_misc.inc b/mpp/include/mpp_io_misc.inc index 9d9365025f..0f2168a92d 100644 --- a/mpp/include/mpp_io_misc.inc +++ b/mpp/include/mpp_io_misc.inc @@ -19,9 +19,11 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup mpp_io_mod !> @brief Misc. routines including initialization and finalization of @ref mpp_io_mod +!> @addtogroup mpp_io_mod +!> @{ + !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ! ! ! mpp_io_init: initialize parallel I/O ! @@ -302,4 +304,4 @@ logical function do_cf_compliance() do_cf_compliance = cf_compliance end function do_cf_compliance - +!> @} diff --git a/mpp/include/mpp_io_read.inc b/mpp/include/mpp_io_read.inc index dbf5a6e278..8645805098 100644 --- a/mpp/include/mpp_io_read.inc +++ b/mpp/include/mpp_io_read.inc @@ -19,9 +19,11 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup mpp_io_mod !> @brief Parallel file read routines for structured grids for use in @ref mpp_io_mod +!> @addtogroup mpp_io_mod +!> @{ + !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ! ! ! MPP_READ ! @@ -1315,5 +1317,4 @@ end if return end subroutine mpp_get_tavg_info - -!####################################################################### +!> @} diff --git a/mpp/include/mpp_io_unstructured_read.inc b/mpp/include/mpp_io_unstructured_read.inc index 31d0cc3cb8..7fc113c3aa 100644 --- a/mpp/include/mpp_io_unstructured_read.inc +++ b/mpp/include/mpp_io_unstructured_read.inc @@ -18,12 +18,11 @@ !*********************************************************************** !> @file -!> @ingroup mpp_io_mod !> @brief Parallel file reads for unstructured grids, used in @ref mpp_io_mod -!---------- -!ug support -!------------------------------------------------------------------------------ +!> @addtogroup mpp_io_mod +!> @{ + !>Read in one-dimensional data for a field associated with an unstructured !!mpp domain. subroutine mpp_io_unstructured_read_r8_1D(funit, & @@ -1118,7 +1117,4 @@ subroutine mpp_io_unstructured_read_r4_3D(funit, & return end subroutine mpp_io_unstructured_read_r4_3D - -!------------------------------------------------------------------------------ - -!---------- +!> @} diff --git a/mpp/include/mpp_io_unstructured_write.inc b/mpp/include/mpp_io_unstructured_write.inc index d5b832e636..efc9f50e1b 100644 --- a/mpp/include/mpp_io_unstructured_write.inc +++ b/mpp/include/mpp_io_unstructured_write.inc @@ -18,12 +18,11 @@ !*********************************************************************** !> @file -!> @ingroup mpp_io_mod !> @brief Parallel file writes for unstructured grids, used in @ref mpp_io_mod -!---------- -!ug support -!------------------------------------------------------------------------------ +!> @addtogroup mpp_io_mod +!> @{ + !>Write data for a 1D field associated with an unstructured mpp domain to a !!restart file. subroutine mpp_io_unstructured_write_r8_1D(funit, & @@ -1410,7 +1409,4 @@ subroutine mpp_io_unstructured_write_r4_4D(funit, & return end subroutine mpp_io_unstructured_write_r4_4D - -!------------------------------------------------------------------------------ - -!---------- +!> @} diff --git a/mpp/include/mpp_io_util.inc b/mpp/include/mpp_io_util.inc index f5720671ea..03cb4a1def 100644 --- a/mpp/include/mpp_io_util.inc +++ b/mpp/include/mpp_io_util.inc @@ -1,6 +1,4 @@ ! -*-f90-*- - - !*********************************************************************** !* GNU Lesser General Public License !* @@ -19,28 +17,11 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** - !> @file -!> @ingroup mpp_io_mod !> @brief Routines to retrieve data used in @ref mpp_io_mod - !##################################################################### -! -! -! Get some general information about a file. -! -! -! Get some general information about a file. -! -! -! -! -! -! -! -! +!> @addtogroup mpp_io_mod +!> @{ !> @brief Get some general information about a file. !! @@ -67,12 +48,6 @@ end subroutine mpp_get_info - !##################################################################### -! -! -! -! -! !> @brief Copy global file attributes for use by user subroutine mpp_get_global_atts( unit, global_atts ) @@ -923,3 +898,4 @@ logical function mpp_is_dist_ioroot(ssize,ioroot,lsize) if(PRESENT(ioroot)) ioroot = d_ioroot if(PRESENT(lsize)) lsize = d_lsize end function mpp_is_dist_ioroot +!> @} diff --git a/mpp/include/mpp_io_write.inc b/mpp/include/mpp_io_write.inc index d23c452b95..ed08c14398 100644 --- a/mpp/include/mpp_io_write.inc +++ b/mpp/include/mpp_io_write.inc @@ -19,124 +19,13 @@ !* License along with FMS. If not, see . !*********************************************************************** -!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -! ! -! MPP_WRITE_META ! -! ! !> @file -!> @ingroup mpp_io_mod !> @brief This series of routines is used to describe the contents of the file !! being written on . -!! -!> Each file can contain any number of fields, -!! which can be functions of 0-3 spatial axes and 0-1 time axes. Axis -!! descriptors are stored in the structure and field -!! descriptors in the structure. -!! -!! The metadata contained in the type is always written for each axis and -!! field. Any other metadata one wishes to attach to an axis or field -!! can subsequently be passed to mpp_write_meta using the ID, as shown below. -!! -!! mpp_write_meta can take several forms: -!! -!! mpp_write_meta( unit, name, rval=rval, pack=pack ) -!! mpp_write_meta( unit, name, ival=ival ) -!! mpp_write_meta( unit, name, cval=cval ) -!! integer, intent(in) :: unit -!! character(len=*), intent(in) :: name -!! real, intent(in), optional :: rval(:) -!! integer, intent(in), optional :: ival(:) -!! character(len=*), intent(in), optional :: cval -!! -!! This form defines global metadata associated with the file as a -!! whole. The attribute is named and can take on a real, integer -!! or character value. and can be scalar or 1D arrays. -!! -!! mpp_write_meta( unit, id, name, rval=rval, pack=pack ) -!! mpp_write_meta( unit, id, name, ival=ival ) -!! mpp_write_meta( unit, id, name, cval=cval ) -!! integer, intent(in) :: unit, id -!! character(len=*), intent(in) :: name -!! real, intent(in), optional :: rval(:) -!! integer, intent(in), optional :: ival(:) -!! character(len=*), intent(in), optional :: cval -!! -!! This form defines metadata associated with a previously defined -!! axis or field, identified to mpp_write_meta by its unique ID . -!! The attribute is named and can take on a real, integer -!! or character value. and can be scalar or 1D arrays. -!! This need not be called for attributes already contained in -!! the type. -!! -!! PACK can take values 1,2,4,8. This only has meaning when writing -!! floating point numbers. The value of PACK defines the number of words -!! written into 8 bytes. For pack=4 and pack=8, an integer value is -!! written: rval is assumed to have been scaled to the appropriate dynamic -!! range. -!! PACK currently only works for netCDF files, and is ignored otherwise. -!! -!! subroutine mpp_write_meta_axis( unit, axis, name, units, longname, & -!! cartesian, sense, domain, data ) -!! integer, intent(in) :: unit -!! type(axistype), intent(inout) :: axis -!! character(len=*), intent(in) :: name, units, longname -!! character(len=*), intent(in), optional :: cartesian -!! integer, intent(in), optional :: sense -!! type(domain1D), intent(in), optional :: domain -!! real, intent(in), optional :: data(:) -!! -!! This form defines a time or space axis. Metadata corresponding to the -!! type above are written to the file on . A unique ID for subsequent -!! references to this axis is returned in axis%id. If the -!! element is present, this is recognized as a distributed data axis -!! and domain decomposition information is also written if required (the -!! domain decomposition info is required for multi-fileset multi-threaded -!! I/O). If the element is allocated, it is considered to be a -!! space axis, otherwise it is a time axis with an unlimited dimension. -!! Only one time axis is allowed per file. -!! @code{.F90} -!! subroutine mpp_write_meta_field( unit, field, axes, name, units, longname -!! standard_name, min, max, missing, fill, scale, add, pack) -!! integer, intent(in) :: unit -!! type(fieldtype), intent(out) :: field -!! type(axistype), intent(in) :: axes(:) -!! character(len=*), intent(in) :: name, units, longname, standard_name -!! real, intent(in), optional :: min, max, missing, fill, scale, add -!! integer, intent(in), optional :: pack -!! @endcode -!! This form defines a field. Metadata corresponding to the type -!! above are written to the file on . A unique ID for subsequent -!! references to this field is returned in field%id. At least one axis -!! must be associated, 0D variables are not considered. mpp_write_meta -!! must previously have been called on all axes associated with this -!! field. -!! -!! The mpp_write_meta package also includes subroutines write_attribute and -!! write_attribute_netcdf, that are private to this module. -! ! -! ! -! type, public :: axistype ! -! sequence ! -! character(len=128) :: name ! -! character(len=128) :: units ! -! character(len=256) :: longname ! -! integer :: sense !+/-1, depth or height? ! -! type(domain1D) :: domain ! -! real, pointer :: data(:) !axis values (not used if time axis) ! -! integer :: id ! -! end type axistype ! -! ! -! type, public :: fieldtype ! -! sequence ! -! character(len=128) :: name ! -! character(len=128) :: units ! -! character(len=256) :: longname ! -! character(len=256) :: standard_name !CF standard name ! -! real :: min, max, missing, fill, scale, add ! -! type(axistype), pointer :: axis(:) ! -! integer :: id ! -! end type fieldtype ! -!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +!> @addtogroup mpp_io_mod +!> @{ + !> Writes a global metadata attribute to unit !! attribute can be an real, integer or character !! one and only one of rval, ival, and cval should be present @@ -1740,4 +1629,4 @@ return end subroutine fillin_fieldtype - +!> @} diff --git a/mpp/include/mpp_read_distributed_ascii.inc b/mpp/include/mpp_read_distributed_ascii.inc index 58ec3f2227..577c024f18 100644 --- a/mpp/include/mpp_read_distributed_ascii.inc +++ b/mpp/include/mpp_read_distributed_ascii.inc @@ -18,8 +18,11 @@ !*********************************************************************** !> @file -!> @ingroup mpp !> @brief Routines for reading distributed ascii files for @ref mpp_io_mod + +!> @addtogroup mpp_io_mod +!> @{ + #undef MPP_READ_DISTRIBUTED_ASCII_1D_ #define MPP_READ_DISTRIBUTED_ASCII_1D_ mpp_read_distributed_ascii_r1D #undef MPP_TYPE_ @@ -62,3 +65,4 @@ subroutine mpp_read_distributed_ascii_a1D(unit,fmt,ssize,data,iostat) call mpp_broadcast(data,len(data(1)),pelist(1),pelist) deallocate(pelist) ! Don't forget to deallocate pelist end subroutine mpp_read_distributed_ascii_a1D +!> @} diff --git a/mpp/include/mpp_reduce_mpi.h b/mpp/include/mpp_reduce_mpi.h index 9ffcc8d17d..3064ae36d6 100644 --- a/mpp/include/mpp_reduce_mpi.h +++ b/mpp/include/mpp_reduce_mpi.h @@ -16,9 +16,9 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** + !> Find the max of scalar a the PEs in pelist (all PEs if this argument is omitted) + !! result is also automatically broadcast to all PEs subroutine MPP_REDUCE_0D_( a, pelist ) -!find the max of scalar a the PEs in pelist (all PEs if this argument is omitted) -!result is also automatically broadcast to all PEs MPP_TYPE_, intent(inout) :: a integer, intent(in), optional :: pelist(0:) integer :: n @@ -35,9 +35,9 @@ return end subroutine MPP_REDUCE_0D_ + !> Find the max of scalar a the PEs in pelist (all PEs if this argument is omitted) + !! result is also automatically broadcast to all PEs subroutine MPP_REDUCE_1D_( a, length, pelist ) -!find the max of scalar a the PEs in pelist (all PEs if this argument is omitted) -!result is also automatically broadcast to all PEs MPP_TYPE_, intent(inout) :: a(:) integer, intent(in) :: length integer, intent(in), optional :: pelist(0:) diff --git a/mpp/include/mpp_reduce_nocomm.h b/mpp/include/mpp_reduce_nocomm.h index 614f4c37e9..fa681dcf60 100644 --- a/mpp/include/mpp_reduce_nocomm.h +++ b/mpp/include/mpp_reduce_nocomm.h @@ -16,9 +16,9 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** + !> Find the max of scalar a the PEs in pelist (all PEs if this argument is omitted) + !! result is also automatically broadcast to all PEs. Nocomm version subroutine MPP_REDUCE_0D_( a, pelist ) -!find the max of scalar a the PEs in pelist (all PEs if this argument is omitted) -!result is also automatically broadcast to all PEs MPP_TYPE_, intent(inout) :: a integer, intent(in), optional :: pelist(0:) integer :: n @@ -26,9 +26,9 @@ return end subroutine MPP_REDUCE_0D_ + !> Find the max of scalar a the PEs in pelist (all PEs if this argument is omitted) + !! result is also automatically broadcast to all PEs. Nocomm version subroutine MPP_REDUCE_1D_( a, length, pelist ) -!find the max of scalar a the PEs in pelist (all PEs if this argument is omitted) -!result is also automatically broadcast to all PEs MPP_TYPE_, intent(inout) :: a(:) integer, intent(in) :: length integer, intent(in), optional :: pelist(0:) diff --git a/mpp/include/mpp_scatter.h b/mpp/include/mpp_scatter.h index ae96ae24df..998723e9e7 100644 --- a/mpp/include/mpp_scatter.h +++ b/mpp/include/mpp_scatter.h @@ -16,35 +16,22 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** - ! - ! - ! Scatter data from one pe to the specified pes. - ! - ! - ! - ! Scatter (ie - is) * (je - js) contiguous elements of array data from the designated root pe - ! into contigous members of array segment in each pe that is included in the pelist argument. - ! - ! Start and end index of the first dimension of the segment array - ! Start and end index of the second dimension of the segment array - ! The PE list of of target pes, Needs to be in monotonic increasing order. - ! The root pe is allowed to be included (see input is_root_pe). If a pe is absent in this list then - ! its segment array is not updated. - ! The 2D array that the data is to be copied into - ! The source array. - ! True if the calee is root pe, false otherwise. - ! Offsets specifying the first element in data array. + +!> addtogroup mpp_mod +!> @{ + +!> @brief Scatter data from one pe to the specified pes. +!! +!> Scatter (ie - is) * (je - js) contiguous elements of array data from the designated root pe +!! into contigous members of array segment in each pe that is included in the pelist argument. subroutine MPP_SCATTER_PELIST_2D_(is, ie, js, je, pelist, array_seg, data, is_root_pe, & ishift, jshift) - integer, intent(in) :: is, ie, js, je - integer, dimension(:), intent(in) :: pelist - MPP_TYPE_, dimension(is:ie,js:je), intent(inout) :: array_seg - MPP_TYPE_, dimension(:,:), intent(in) :: data - logical, intent(in) :: is_root_pe - integer, optional, intent(in) :: ishift, jshift + integer, intent(in) :: is, ie, js, je !< indices of segment array + integer, dimension(:), intent(in) :: pelist! @} diff --git a/mpp/include/mpp_sum.inc b/mpp/include/mpp_sum.inc index 062144f4d2..cbb1e12923 100644 --- a/mpp/include/mpp_sum.inc +++ b/mpp/include/mpp_sum.inc @@ -20,12 +20,14 @@ !*********************************************************************** !> @file -!> @ingroup mpp !> @brief Summation routines for @ref mpp_mod + +!> @addtogroup mpp_mod +!> @{ !####################################################################### + !> Sums array a when only first element is passed: this routine just converts to a call to MPP_SUM_ subroutine MPP_SUM_SCALAR_( a, pelist ) -!sums array a when only first element is passed: this routine just converts to a call to MPP_SUM_ MPP_TYPE_, intent(inout) :: a integer, intent(in), optional :: pelist(:) MPP_TYPE_ :: b(1) @@ -38,10 +40,11 @@ end subroutine MPP_SUM_SCALAR_ !####################################################################### + !> Sums 2d array across pes subroutine MPP_SUM_2D_( a, length, pelist ) - MPP_TYPE_, intent(inout) :: a(:,:) - integer, intent(in) :: length - integer, intent(in), optional :: pelist(:) + MPP_TYPE_, intent(inout) :: a(:,:) !< 2d array to sum + integer, intent(in) :: length !< amount of indices in given 2d array + integer, intent(in), optional :: pelist(:) !< pelist to calculate sum across MPP_TYPE_ :: a1D(length) pointer( ptr, a1D ) @@ -52,10 +55,11 @@ end subroutine MPP_SUM_2D_ !####################################################################### + !> Sums 3d array across pes subroutine MPP_SUM_3D_( a, length, pelist ) - MPP_TYPE_, intent(inout) :: a(:,:,:) - integer, intent(in) :: length - integer, intent(in), optional :: pelist(:) + MPP_TYPE_, intent(inout) :: a(:,:,:) !< 3d array to sum + integer, intent(in) :: length !< amount of indices in given 3d array + integer, intent(in), optional :: pelist(:) !< pelist to calculate sum across MPP_TYPE_ :: a1D(length) pointer( ptr, a1D ) @@ -66,10 +70,11 @@ end subroutine MPP_SUM_3D_ !####################################################################### + !> Sums 4d array across pes subroutine MPP_SUM_4D_( a, length, pelist ) - MPP_TYPE_, intent(inout) :: a(:,:,:,:) - integer, intent(in) :: length - integer, intent(in), optional :: pelist(:) + MPP_TYPE_, intent(inout) :: a(:,:,:,:) !< 4d array to sum + integer, intent(in) :: length !< amount of indices in given 4d array + integer, intent(in), optional :: pelist(:) !< pelist to calculate sum across MPP_TYPE_ :: a1D(length) pointer( ptr, a1D ) @@ -80,10 +85,11 @@ end subroutine MPP_SUM_4D_ !####################################################################### + !> Sums 5d array across pes subroutine MPP_SUM_5D_( a, length, pelist ) - MPP_TYPE_, intent(inout) :: a(:,:,:,:,:) - integer, intent(in) :: length - integer, intent(in), optional :: pelist(:) + MPP_TYPE_, intent(inout) :: a(:,:,:,:,:) !< 5d array to sum + integer, intent(in) :: length !< amount of indices in given 5d array + integer, intent(in), optional :: pelist(:) !< pelist to calculate sum across MPP_TYPE_ :: a1D(length) pointer( ptr, a1D ) @@ -92,3 +98,4 @@ return end subroutine MPP_SUM_5D_ +!> @} diff --git a/mpp/include/mpp_sum_ad.inc b/mpp/include/mpp_sum_ad.inc index e77fedfb4d..19cdea822a 100644 --- a/mpp/include/mpp_sum_ad.inc +++ b/mpp/include/mpp_sum_ad.inc @@ -19,14 +19,17 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup mpp !> @brief Adjoint summation routines for @ref mpp_mod + +!> @addtogroup mpp_mod +!> @{ + !####################################################################### !> Sums array a. !! when only first element is passed: this routine just converts to a call to MPP_SUM_ subroutine MPP_SUM_SCALAR_AD_( a, pelist ) - MPP_TYPE_, intent(inout) :: a + MPP_TYPE_, intent(inout) :: a !< scalar value to sum over pelist integer, intent(in), optional :: pelist(:) MPP_TYPE_ :: b(1) @@ -38,10 +41,11 @@ end subroutine MPP_SUM_SCALAR_AD_ !####################################################################### + !> Sums 2d array across pes subroutine MPP_SUM_2D_AD_( a, length, pelist ) - MPP_TYPE_, intent(inout) :: a(:,:) - integer, intent(in) :: length - integer, intent(in), optional :: pelist(:) + MPP_TYPE_, intent(inout) :: a(:,:) !< 2d array to sum + integer, intent(in) :: length !< amount of indices in given 2d array + integer, intent(in), optional :: pelist(:) !< pelist to calculate sum across MPP_TYPE_ :: a1D(length) pointer( ptr, a1D ) @@ -52,10 +56,11 @@ end subroutine MPP_SUM_2D_AD_ !####################################################################### + !> Sums 3d array across pes subroutine MPP_SUM_3D_AD_( a, length, pelist ) - MPP_TYPE_, intent(inout) :: a(:,:,:) - integer, intent(in) :: length - integer, intent(in), optional :: pelist(:) + MPP_TYPE_, intent(inout) :: a(:,:,:) !< 3d array to sum + integer, intent(in) :: length !< amount of indices in given 3d array + integer, intent(in), optional :: pelist(:) !< pelist to calculate sum across MPP_TYPE_ :: a1D(length) pointer( ptr, a1D ) @@ -66,10 +71,11 @@ end subroutine MPP_SUM_3D_AD_ !####################################################################### + !> Sums 4d array across pes subroutine MPP_SUM_4D_AD_( a, length, pelist ) - MPP_TYPE_, intent(inout) :: a(:,:,:,:) - integer, intent(in) :: length - integer, intent(in), optional :: pelist(:) + MPP_TYPE_, intent(inout) :: a(:,:,:,:) !< 4d array to sum + integer, intent(in) :: length !< amount of indices in given 4d array + integer, intent(in), optional :: pelist(:) !< pelist to calculate sum across MPP_TYPE_ :: a1D(length) pointer( ptr, a1D ) @@ -80,10 +86,11 @@ end subroutine MPP_SUM_4D_AD_ !####################################################################### + !> Sums 5d array across pes subroutine MPP_SUM_5D_AD_( a, length, pelist ) - MPP_TYPE_, intent(inout) :: a(:,:,:,:,:) - integer, intent(in) :: length - integer, intent(in), optional :: pelist(:) + MPP_TYPE_, intent(inout) :: a(:,:,:,:,:) !< 5d array to sum + integer, intent(in) :: length !< amount of indices in given 5d array + integer, intent(in), optional :: pelist(:) !< pelist to calculate sum across MPP_TYPE_ :: a1D(length) pointer( ptr, a1D ) diff --git a/mpp/include/mpp_sum_mpi.h b/mpp/include/mpp_sum_mpi.h index 9f9da7f842..5a5cd4858f 100644 --- a/mpp/include/mpp_sum_mpi.h +++ b/mpp/include/mpp_sum_mpi.h @@ -16,11 +16,12 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** + !> Sums array a over the PEs in pelist (all PEs if this argument is omitted) + !! result is also automatically broadcast: all PEs have the sum in a at the end + !! we are using f77-style call: array passed by address and not descriptor; further, + !! the f90 conformance check is avoided. + !> @ingroup mpp_mod subroutine MPP_SUM_( a, length, pelist ) -!sums array a over the PEs in pelist (all PEs if this argument is omitted) -!result is also automatically broadcast: all PEs have the sum in a at the end - !we are using f77-style call: array passed by address and not descriptor; further, - !the f90 conformance check is avoided. integer, intent(in) :: length integer, intent(in), optional :: pelist(:) MPP_TYPE_, intent(inout) :: a(*) diff --git a/mpp/include/mpp_sum_mpi_ad.h b/mpp/include/mpp_sum_mpi_ad.h index 4ed32cf8b8..9b61b9457b 100644 --- a/mpp/include/mpp_sum_mpi_ad.h +++ b/mpp/include/mpp_sum_mpi_ad.h @@ -19,12 +19,12 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** - + !> Sums array a over the PEs in pelist (all PEs if this argument is omitted) + !! result is also automatically broadcast: all PEs have the sum in a at the end + !! we are using f77-style call: array passed by address and not descriptor; further, + !! the f90 conformance check is avoided. + !> @ingroup mpp_mod subroutine MPP_SUM_AD_( a, length, pelist ) -!sums array a over the PEs in pelist (all PEs if this argument is omitted) -!result is also automatically broadcast: all PEs have the sum in a at the end - !we are using f77-style call: array passed by address and not descriptor; further, - !the f90 conformance check is avoided. integer, intent(in) :: length integer, intent(in), optional :: pelist(:) MPP_TYPE_, intent(inout) :: a(*) @@ -43,6 +43,5 @@ if( debug .and. (current_clock.NE.0) )call increment_current_clock( EVENT_ALLREDUCE, length*MPP_TYPE_BYTELEN_ ) return end subroutine MPP_SUM_AD_ - !####################################################################### #include diff --git a/mpp/include/mpp_sum_nocomm.h b/mpp/include/mpp_sum_nocomm.h index caa9c66b00..3ae6ad4138 100644 --- a/mpp/include/mpp_sum_nocomm.h +++ b/mpp/include/mpp_sum_nocomm.h @@ -16,11 +16,11 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** + !> Sums array a over the PEs in pelist (all PEs if this argument is omitted) + !! result is also automatically broadcast: all PEs have the sum in a at the end + !! we are using f77-style call: array passed by address and not descriptor; further, + !! the f90 conformance check is avoided. subroutine MPP_SUM_( a, length, pelist ) -!sums array a over the PEs in pelist (all PEs if this argument is omitted) -!result is also automatically broadcast: all PEs have the sum in a at the end -!we are using f77-style call: array passed by address and not descriptor; further, the f90 -!conformance check is avoided. integer, intent(in) :: length integer, intent(in), optional :: pelist(:) MPP_TYPE_, intent(inout) :: a(*) diff --git a/mpp/include/mpp_sum_nocomm_ad.h b/mpp/include/mpp_sum_nocomm_ad.h index f532c4da4c..9a427aa9d0 100644 --- a/mpp/include/mpp_sum_nocomm_ad.h +++ b/mpp/include/mpp_sum_nocomm_ad.h @@ -20,11 +20,11 @@ !* License along with FMS. If not, see . !*********************************************************************** + !> Sums array a over the PEs in pelist (all PEs if this argument is omitted) + !! result is also automatically broadcast: all PEs have the sum in a at the end + !! we are using f77-style call: array passed by address and not descriptor; further, + !! the f90 conformance check is avoided. subroutine MPP_SUM_AD_( a, length, pelist ) -!sums array a over the PEs in pelist (all PEs if this argument is omitted) -!result is also automatically broadcast: all PEs have the sum in a at the end - !we are using f77-style call: array passed by address and not descriptor; further, - !the f90 conformance check is avoided. integer, intent(in) :: length integer, intent(in), optional :: pelist(:) MPP_TYPE_, intent(inout) :: a(*) diff --git a/mpp/include/mpp_transmit.inc b/mpp/include/mpp_transmit.inc index 100fc334ee..24d0cc437f 100644 --- a/mpp/include/mpp_transmit.inc +++ b/mpp/include/mpp_transmit.inc @@ -19,9 +19,11 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup mpp !> @brief Routines for data transmission between PE's +!> @addtogroup mpp_mod +!> @{ + !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ! ! ! MPP_TRANSMIT ! @@ -380,3 +382,4 @@ return end subroutine MPP_BROADCAST_5D_ +!> @} diff --git a/mpp/include/mpp_transmit_mpi.h b/mpp/include/mpp_transmit_mpi.h index 7f886bf9cb..16c7006ba2 100644 --- a/mpp/include/mpp_transmit_mpi.h +++ b/mpp/include/mpp_transmit_mpi.h @@ -21,27 +21,22 @@ ! MPP_TRANSMIT ! ! ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - +!> @addtogroup mpp_mod +!> @{ +!> A message-passing routine intended to be reminiscent equally of both MPI and SHMEM +!! put_data and get_data are contiguous MPP_TYPE_ arrays +!!at each call, your put_data array is put to to_pe's get_data +!! your get_data array is got from from_pe's put_data +!!i.e we assume that typically (e.g updating halo regions) each PE performs a put _and_ a get +!!special PE designations: +!! NULL_PE: to disable a put or a get (e.g at boundaries) +!! ANY_PE: if remote PE for the put or get is to be unspecific +!! ALL_PES: broadcast and collect operations (collect not yet implemented) +!!ideally we would not pass length, but this f77-style call performs better (arrays passed by address, not descriptor) +!!further, this permits contiguous words from an array of any rank to be passed (avoiding f90 rank conformance check) +!!caller is responsible for completion checks (mpp_sync_self) before and after subroutine MPP_TRANSMIT_( put_data, put_len, to_pe, get_data, get_len, from_pe, block, tag, recv_request, & & send_request ) -!a message-passing routine intended to be reminiscent equally of both MPI and SHMEM - -!put_data and get_data are contiguous MPP_TYPE_ arrays - -!at each call, your put_data array is put to to_pe's get_data -! your get_data array is got from from_pe's put_data -!i.e we assume that typically (e.g updating halo regions) each PE performs a put _and_ a get - -!special PE designations: -! NULL_PE: to disable a put or a get (e.g at boundaries) -! ANY_PE: if remote PE for the put or get is to be unspecific -! ALL_PES: broadcast and collect operations (collect not yet implemented) - -!ideally we would not pass length, but this f77-style call performs better (arrays passed by address, not descriptor) -!further, this permits contiguous words from an array of any rank to be passed (avoiding -!f90 rank conformance check) - -!caller is responsible for completion checks (mpp_sync_self) before and after integer, intent(in) :: put_len, to_pe, get_len, from_pe MPP_TYPE_, intent(in) :: put_data(*) @@ -164,7 +159,7 @@ ! MPP_BROADCAST ! ! ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - + !> Broadcasts data to a pelist subroutine MPP_BROADCAST_( data, length, from_pe, pelist ) !this call was originally bundled in with mpp_transmit, but that doesn't allow !broadcast to a subset of PEs. This version will, and mpp_transmit will remain @@ -198,6 +193,6 @@ if( debug .and. (current_clock.NE.0) )call increment_current_clock( EVENT_BROADCAST, length*MPP_TYPE_BYTELEN_ ) return end subroutine MPP_BROADCAST_ - +!> @} !#################################################################################### #include diff --git a/mpp/include/mpp_transmit_nocomm.h b/mpp/include/mpp_transmit_nocomm.h index 8b7ddf2b45..3074971d8f 100644 --- a/mpp/include/mpp_transmit_nocomm.h +++ b/mpp/include/mpp_transmit_nocomm.h @@ -22,26 +22,20 @@ ! ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +!> A message-passing routine intended to be reminiscent equally of both MPI and SHMEM +!! put_data and get_data are contiguous MPP_TYPE_ arrays +!!at each call, your put_data array is put to to_pe's get_data +!! your get_data array is got from from_pe's put_data +!!i.e we assume that typically (e.g updating halo regions) each PE performs a put _and_ a get +!!special PE designations: +!! NULL_PE: to disable a put or a get (e.g at boundaries) +!! ANY_PE: if remote PE for the put or get is to be unspecific +!! ALL_PES: broadcast and collect operations (collect not yet implemented) +!!ideally we would not pass length, but this f77-style call performs better (arrays passed by address, not descriptor) +!!further, this permits contiguous words from an array of any rank to be passed (avoiding f90 rank conformance check) +!!caller is responsible for completion checks (mpp_sync_self) before and after subroutine MPP_TRANSMIT_( put_data, put_len, to_pe, get_data, get_len, from_pe, block, tag, recv_request, & & send_request ) -!a message-passing routine intended to be reminiscent equally of both MPI and SHMEM - -!put_data and get_data are contiguous MPP_TYPE_ arrays - -!at each call, your put_data array is put to to_pe's get_data -! your get_data array is got from from_pe's put_data -!i.e we assume that typically (e.g updating halo regions) each PE performs a put _and_ a get - -!special PE designations: -! NULL_PE: to disable a put or a get (e.g at boundaries) -! ANY_PE: if remote PE for the put or get is to be unspecific -! ALL_PES: broadcast and collect operations (collect not yet implemented) - -!ideally we would not pass length, but this f77-style call performs better (arrays passed by address, not descriptor) -!further, this permits contiguous words from an array of any rank to be passed (avoiding -!f90 rank conformance check) - -!caller is responsible for completion checks (mpp_sync_self) before and after integer, intent(in) :: put_len, to_pe, get_len, from_pe MPP_TYPE_, intent(in) :: put_data(*) diff --git a/mpp/include/mpp_type_mpi.h b/mpp/include/mpp_type_mpi.h index 6341876f86..c1fa4e15c5 100644 --- a/mpp/include/mpp_type_mpi.h +++ b/mpp/include/mpp_type_mpi.h @@ -16,6 +16,8 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @addtogroup mpp_mod +!> @{ subroutine MPP_TYPE_CREATE_(field, array_of_subsizes, array_of_starts, & dtype_out) @@ -99,3 +101,4 @@ subroutine MPP_TYPE_CREATE_(field, array_of_subsizes, array_of_starts, & call increment_current_clock(EVENT_TYPE_CREATE, MPP_TYPE_BYTELEN_) end subroutine MPP_TYPE_CREATE_ +!> @} diff --git a/mpp/include/mpp_unstruct_domain.inc b/mpp/include/mpp_unstruct_domain.inc index 168581ff3b..7444b82068 100644 --- a/mpp/include/mpp_unstruct_domain.inc +++ b/mpp/include/mpp_unstruct_domain.inc @@ -16,22 +16,22 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** - !> @file -!> @ingroup mpp_domains_mod !> @brief Routines for defining and managing unstructured grids +!> @addtogroup mpp_domains_mod +!> @{ !##################################################################### subroutine mpp_define_unstruct_domain(UG_domain, SG_domain, npts_tile, grid_nlev, ndivs, npes_io_group, & & grid_index, name) type(domainUG), intent(inout) :: UG_domain type(domain2d), target, intent(in) :: SG_domain - integer, intent(in) :: npts_tile(:) ! number of unstructured points on each tile - integer, intent(in) :: grid_nlev(:) ! number of levels in each unstructured grid. + integer, intent(in) :: npts_tile(:) !< number of unstructured points on each tile + integer, intent(in) :: grid_nlev(:) !< number of levels in each unstructured grid. integer, intent(in) :: ndivs - integer, intent(in) :: npes_io_group ! number of processors in a io group. Only - !! pe with same tile_id - ! in the same group + integer, intent(in) :: npes_io_group!< number of processors in a io group. + !! Only pe with same tile_id + !! in the same group integer, intent(in) :: grid_index(:) character(len=*), optional, intent(in) :: name integer, dimension(size(npts_tile(:))) :: ndivs_tile, pe_start, pe_end @@ -900,3 +900,4 @@ end subroutine mpp_deallocate_domainUG #undef MPP_TYPE_ #define MPP_TYPE_ integer(i4_kind) #include +!> @} diff --git a/mpp/include/mpp_unstruct_pass_data.h b/mpp/include/mpp_unstruct_pass_data.h index a6f0b6d76c..656a7789d3 100644 --- a/mpp/include/mpp_unstruct_pass_data.h +++ b/mpp/include/mpp_unstruct_pass_data.h @@ -16,8 +16,11 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** -! This subroutine pass data from unstructured domain2d to domain. -! First only implement for data at grid cell center. +!> @addtogroup mpp_domains_mod +!> @{ + +!> This subroutine pass data from unstructured domain2d to domain. +!! First only implement for data at grid cell center. SUBROUTINE mpp_pass_SG_to_UG_2D_(UG_domain, field_SG, field_UG) type(domainUG), intent(in) :: UG_domain MPP_TYPE_, intent(inout) :: field_UG(:) @@ -119,8 +122,8 @@ SUBROUTINE mpp_pass_SG_to_UG_3D_(UG_domain, field_SG, field_UG) end SUBROUTINE mpp_pass_SG_to_UG_3D_ -! This subroutine pass data from unstructured domain2d to domain. -! First only implement for data at grid cell center. +!> This subroutine pass data from unstructured domain2d to domain. +!! First only implement for data at grid cell center. SUBROUTINE mpp_pass_UG_to_SG_2D_(UG_domain, field_UG, field_SG) type(domainUG), intent(in) :: UG_domain MPP_TYPE_, intent(in) :: field_UG(:) @@ -221,3 +224,4 @@ SUBROUTINE mpp_pass_UG_to_SG_3D_(UG_domain, field_UG, field_SG) call mpp_sync_self( ) end SUBROUTINE mpp_pass_UG_to_SG_3D_ +!> @} diff --git a/mpp/include/mpp_update_domains2D.h b/mpp/include/mpp_update_domains2D.h index f605ba5ed0..8f13cd235a 100644 --- a/mpp/include/mpp_update_domains2D.h +++ b/mpp/include/mpp_update_domains2D.h @@ -17,9 +17,11 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @addtogroup mpp_domains_mod +!> @{ + !> Updates data domain of 2D field whose computational domains have been computed subroutine MPP_UPDATE_DOMAINS_2D_( field, domain, flags, complete, position, & whalo, ehalo, shalo, nhalo, name, tile_count) -!updates data domain of 2D field whose computational domains have been computed MPP_TYPE_, intent(inout) :: field(:,:) type(domain2D), intent(inout) :: domain integer, intent(in), optional :: flags @@ -37,9 +39,9 @@ return end subroutine MPP_UPDATE_DOMAINS_2D_ + !> Updates data domain of 3D field whose computational domains have been computed subroutine MPP_UPDATE_DOMAINS_3D_( field, domain, flags, complete, position, & whalo, ehalo, shalo, nhalo, name, tile_count) -!updates data domain of 3D field whose computational domains have been computed MPP_TYPE_, intent(inout) :: field(:,:,:) type(domain2D), intent(inout) :: domain integer, intent(in), optional :: flags @@ -174,9 +176,9 @@ end subroutine MPP_UPDATE_DOMAINS_3D_ + !> Updates data domain of 4D field whose computational domains have been computed subroutine MPP_UPDATE_DOMAINS_4D_( field, domain, flags, complete, position, & whalo, ehalo, shalo, nhalo, name, tile_count ) -!updates data domain of 4D field whose computational domains have been computed MPP_TYPE_, intent(inout) :: field(:,:,:,:) type(domain2D), intent(inout) :: domain integer, intent(in), optional :: flags @@ -194,9 +196,9 @@ return end subroutine MPP_UPDATE_DOMAINS_4D_ + !> Updates data domain of 5D field whose computational domains have been computed subroutine MPP_UPDATE_DOMAINS_5D_( field, domain, flags, complete, position, & whalo, ehalo, shalo, nhalo, name, tile_count ) -!updates data domain of 5D field whose computational domains have been computed MPP_TYPE_, intent(inout) :: field(:,:,:,:,:) type(domain2D), intent(inout) :: domain integer, intent(in), optional :: flags @@ -637,3 +639,4 @@ return end subroutine MPP_UPDATE_DOMAINS_5D_V_ #endif /* VECTOR_FIELD_ */ +!> @} diff --git a/mpp/include/mpp_update_domains2D_ad.h b/mpp/include/mpp_update_domains2D_ad.h index e692a40d60..e5fc6e7af3 100644 --- a/mpp/include/mpp_update_domains2D_ad.h +++ b/mpp/include/mpp_update_domains2D_ad.h @@ -17,9 +17,11 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @addtogroup mpp_domains_mod +!> @{ + !> Updates data domain of 2D field whose computational domains have been computed subroutine MPP_UPDATE_DOMAINS_AD_2D_( field, domain, flags, complete, position, & whalo, ehalo, shalo, nhalo, name, tile_count) -!updates data domain of 2D field whose computational domains have been computed MPP_TYPE_, intent(inout) :: field(:,:) type(domain2D), intent(inout) :: domain integer, intent(in), optional :: flags @@ -37,9 +39,9 @@ return end subroutine MPP_UPDATE_DOMAINS_AD_2D_ + !> Updates data domain of 3D field whose computational domains have been computed subroutine MPP_UPDATE_DOMAINS_AD_3D_( field, domain, flags, complete, position, & whalo, ehalo, shalo, nhalo, name, tile_count) -!updates data domain of 3D field whose computational domains have been computed MPP_TYPE_, intent(inout) :: field(:,:,:) type(domain2D), intent(inout) :: domain integer, intent(in), optional :: flags @@ -174,9 +176,9 @@ end subroutine MPP_UPDATE_DOMAINS_AD_3D_ + !> Updates data domain of 4D field whose computational domains have been computed subroutine MPP_UPDATE_DOMAINS_AD_4D_( field, domain, flags, complete, position, & whalo, ehalo, shalo, nhalo, name, tile_count ) -!updates data domain of 4D field whose computational domains have been computed MPP_TYPE_, intent(inout) :: field(:,:,:,:) type(domain2D), intent(inout) :: domain integer, intent(in), optional :: flags @@ -194,9 +196,9 @@ return end subroutine MPP_UPDATE_DOMAINS_AD_4D_ + !> Updates data domain of 5D field whose computational domains have been computed subroutine MPP_UPDATE_DOMAINS_AD_5D_( field, domain, flags, complete, position, & whalo, ehalo, shalo, nhalo, name, tile_count ) -!updates data domain of 5D field whose computational domains have been computed MPP_TYPE_, intent(inout) :: field(:,:,:,:,:) type(domain2D), intent(inout) :: domain integer, intent(in), optional :: flags @@ -464,3 +466,4 @@ return end subroutine MPP_UPDATE_DOMAINS_AD_5D_V_ #endif /* VECTOR_FIELD_ */ +!> @} diff --git a/mpp/include/mpp_update_domains2D_nonblock.h b/mpp/include/mpp_update_domains2D_nonblock.h index 48d523e822..fc8c9df306 100644 --- a/mpp/include/mpp_update_domains2D_nonblock.h +++ b/mpp/include/mpp_update_domains2D_nonblock.h @@ -16,6 +16,8 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @addtogroup mpp_domains_mod +!> @{ function MPP_START_UPDATE_DOMAINS_2D_( field, domain, flags, position, & whalo, ehalo, shalo, nhalo, name, tile_count, update_id, complete) type(domain2D), intent(inout) :: domain @@ -1096,3 +1098,4 @@ subroutine MPP_COMPLETE_UPDATE_DOMAINS_5D_V_( id_update, fieldx, fieldy, domain, end subroutine MPP_COMPLETE_UPDATE_DOMAINS_5D_V_ #endif +!> @} diff --git a/mpp/include/mpp_update_nest_domains.h b/mpp/include/mpp_update_nest_domains.h index 2fbb0af36c..054bc4ba2b 100644 --- a/mpp/include/mpp_update_nest_domains.h +++ b/mpp/include/mpp_update_nest_domains.h @@ -17,6 +17,8 @@ !* You should have received a copy of the GNU Lesser General Public !* License along with FMS. If not, see . !*********************************************************************** +!> @addtogroup mpp_domains_mod +!> @{ subroutine MPP_UPDATE_NEST_FINE_2D_(field, nest_domain, wbuffer, ebuffer, sbuffer, nbuffer, & nest_level, flags, complete, position, extra_halo, name, tile_count) MPP_TYPE_, intent(in) :: field(:,:) !< field on the model grid @@ -1060,3 +1062,4 @@ end subroutine MPP_UPDATE_NEST_COARSE_4D_V_ #endif +!> @} diff --git a/mpp/include/mpp_util.inc b/mpp/include/mpp_util.inc index 465c0345ac..19f911d50e 100644 --- a/mpp/include/mpp_util.inc +++ b/mpp/include/mpp_util.inc @@ -20,27 +20,17 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup mpp_mod !> @brief General utility functions for use in @ref mpp_mod +!> @addtogroup mpp_mod +!> @{ + #if defined(use_libMPI) #include #else #include #endif - !##################################################################### - ! - ! - ! Standard fortran unit numbers. - ! - ! - ! This function returns the current standard fortran unit numbers for input. - ! - ! - ! !> @brief This function returns the current standard fortran unit numbers for input. function stdin() integer :: stdin @@ -48,18 +38,6 @@ return end function stdin - !##################################################################### - ! - ! - ! Standard fortran unit numbers. - ! - ! - ! This function returns the current standard fortran unit numbers for output. - ! - ! - ! !> @brief This function returns the current standard fortran unit numbers for output. function stdout() integer :: stdout @@ -68,18 +46,6 @@ return end function stdout - !##################################################################### - ! - ! - ! Standard fortran unit numbers. - ! - ! - ! This function returns the current standard fortran unit numbers for error messages. - ! - ! - ! !> @brief This function returns the current standard fortran unit numbers for error messages. function stderr() integer :: stderr @@ -87,19 +53,6 @@ return end function stderr - !##################################################################### - ! - ! - ! Standard fortran unit numbers. - ! - ! - ! This function returns the current standard fortran unit numbers for log messages. - ! Log messages, by convention, are written to the file logfile.out. - ! - ! - ! !> @brief This function returns the current standard fortran unit numbers for log messages. !! Log messages, by convention, are written to the file logfile.out. function stdlog() @@ -415,23 +368,8 @@ integer :: i, len_tmp, len_string end function rarray_to_char - !##################################################################### - ! - ! - ! Returns processor ID. - ! - ! - ! This returns the unique ID associated with a PE. This number runs - ! between 0 and npes-1, where npes is the total - ! processor count, returned by mpp_npes. For a uniprocessor - ! application this will always return 0. - ! - ! - ! - !> @brief Returns processor ID. + !! !> This returns the unique ID associated with a PE. This number runs !! between 0 and npes-1, where npes is the total !! processor count, returned by mpp_npes. For a uniprocessor @@ -445,18 +383,7 @@ end function rarray_to_char end function mpp_pe !##################################################################### - ! - ! - ! Returns processor count for current pelist. - ! - ! - ! This returns the number of PEs in the current pelist. For a - ! uniprocessor application, this will always return 1. - ! - ! - ! + !> @brief Returns processor count for current pelist !! !> This returns the number of PEs in the current pelist. For a uniprocessor application, @@ -489,29 +416,18 @@ end function rarray_to_char return end subroutine mpp_set_root_pe - !##################################################################### - ! - ! - ! Declare a pelist. - ! - ! - ! This call is written specifically to accommodate a MPI restriction - ! that requires a parent communicator to create a child communicator, In - ! other words: a pelist cannot go off and declare a communicator, but - ! every PE in the parent, including those not in pelist(:), must get - ! together for the MPI_COMM_CREATE call. The parent is - ! typically MPI_COMM_WORLD, though it could also be a subset - ! that includes all PEs in pelist. - ! - ! This call implies synchronization across the PEs in the current - ! pelist, of which pelist is a subset. - ! - ! - ! - ! - + !> @brief Declare a pelist. + !! + !> This call is written specifically to accommodate a MPI restriction + !! that requires a parent communicator to create a child communicator, In + !! other words: a pelist cannot go off and declare a communicator, but + !! every PE in the parent, including those not in pelist(:), must get + !! together for the MPI_COMM_CREATE call. The parent is + !! typically MPI_COMM_WORLD, though it could also be a subset + !! that includes all PEs in pelist. + !! + !! This call implies synchronization across the PEs in the current + !! pelist, of which pelist is a subset. subroutine mpp_declare_pelist( pelist, name ) integer, intent(in) :: pelist(:) character(len=*), intent(in), optional :: name @@ -525,29 +441,19 @@ end function rarray_to_char end subroutine mpp_declare_pelist !##################################################################### - ! - ! - ! Set context pelist. - ! - ! - ! This call sets the value of the current pelist, which is the - ! context for all subsequent "global" calls where the optional - ! pelist argument is omitted. All the PEs that are to be in the - ! current pelist must call it. - ! - ! In MPI, this call may hang unless pelist has been previous - ! declared using mpp_declare_pelist. - ! - ! If the argument pelist is absent, the current pelist is - ! set to the "world" pelist, of all PEs in the job. - ! - ! - ! - ! + !> @brief Set context pelist + !! + !! This call sets the value of the current pelist, which is the + !! context for all subsequent "global" calls where the optional + !! pelist argument is omitted. All the PEs that are to be in the + !! current pelist must call it. + !! + !! In MPI, this call may hang unless pelist has been previous + !! declared using @ref mpp_declare_pelist + !! + !! If the argument pelist is absent, the current pelist is + !! set to the "world" pelist, of all PEs in the job. subroutine mpp_set_current_pelist( pelist, no_sync ) !Once we branch off into a PE subset, we want subsequent "global" calls to !sync only across this subset. This is declared as the current pelist (peset(current_peset_num)%list) @@ -604,110 +510,101 @@ end function rarray_to_char ! PERFORMANCE PROFILING CALLS ! ! ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - ! - ! - ! Set the level of granularity of timing measurements. - ! - ! - ! This routine and three other routines, mpp_clock_id, mpp_clock_begin(id), - ! and mpp_clock_end(id) may be used to time parallel code sections, and - ! extract parallel statistics. Clocks are identified by names, which - ! should be unique in the first 32 characters. The mpp_clock_id - ! call initializes a clock of a given name and returns an integer - ! id. This id can be used by subsequent - ! mpp_clock_begin and mpp_clock_end calls set around a - ! code section to be timed. Example: - ! 
    -  !    integer :: id
-  !    id = mpp_clock_id( 'Atmosphere' )
-  !    call mpp_clock_begin(id)
-  !    call atmos_model()
-  !    call mpp_clock_end()
-  !
    - ! Two flags may be used to alter the behaviour of - ! mpp_clock. If the flag MPP_CLOCK_SYNC is turned on - ! by mpp_clock_id, the clock calls mpp_sync across all - ! the PEs in the current pelist at the top of the timed code section, - ! but allows each PE to complete the code section (and reach - ! mpp_clock_end) at different times. This allows us to measure - ! load imbalance for a given code section. Statistics are written to - ! stdout by mpp_exit. - ! - ! The flag MPP_CLOCK_DETAILED may be turned on by - ! mpp_clock_id to get detailed communication - ! profiles. Communication events of the types SEND, RECV, BROADCAST, - ! REDUCE and WAIT are separately measured for data volume - ! and time. Statistics are written to stdout by - ! mpp_exit, and individual PE info is also written to the file - ! mpp_clock.out.#### where #### is the PE id given by - ! mpp_pe. - ! - ! The flags MPP_CLOCK_SYNC and MPP_CLOCK_DETAILED are - ! integer parameters available by use association, and may be summed to - ! turn them both on. - ! - ! While the nesting of clocks is allowed, please note that turning on - ! the non-optional flags on inner clocks has certain subtle issues. - ! Turning on MPP_CLOCK_SYNC on an inner - ! clock may distort outer clock measurements of load imbalance. Turning - ! on MPP_CLOCK_DETAILED will stop detailed measurements on its - ! outer clock, since only one detailed clock may be active at one time. - ! Also, detailed clocks only time a certain number of events per clock - ! (currently 40000) to conserve memory. If this array overflows, a - ! warning message is printed, and subsequent events for this clock are - ! not timed. - ! - ! Timings are done using the f90 standard - ! SYSTEM_CLOCK intrinsic. - ! - ! The resolution of SYSTEM_CLOCK is often too coarse for use except - ! across large swaths of code. On SGI systems this is transparently - ! overloaded with a higher resolution clock made available in a - ! non-portable fortran interface made available by - ! nsclock.c. This approach will eventually be extended to other - ! platforms. - ! - ! New behaviour added at the Havana release allows the user to embed - ! profiling calls at varying levels of granularity all over the code, - ! and for any particular run, set a threshold of granularity so that - ! finer-grained clocks become dormant. - ! - ! The threshold granularity is held in the private module variable - ! clock_grain. This value may be modified by the call - ! mpp_clock_set_grain, and affect clocks initiated by - ! subsequent calls to mpp_clock_id. The value of - ! clock_grain is set to an arbitrarily large number initially. - ! - ! Clocks initialized by mpp_clock_id can set a new optional - ! argument grain setting their granularity level. Clocks check - ! this level against the current value of clock_grain, and are - ! only triggered if they are at or below ("coarser than") the - ! threshold. Finer-grained clocks are dormant for that run. - ! - !The following grain levels are pre-defined: - ! - !
    -  !!predefined clock granularities, but you can use any integer
-  !!using CLOCK_LOOP and above may distort coarser-grain measurements
-  !  integer, parameter, public :: CLOCK_COMPONENT=1 !component level, e.g model, exchange
-  !  integer, parameter, public :: CLOCK_SUBCOMPONENT=11 !top level within a model component, e.g dynamics, physics
-  !  integer, parameter, public :: CLOCK_MODULE=21 !module level, e.g main subroutine of a physics module
-  !  integer, parameter, public :: CLOCK_ROUTINE=31 !level of individual subroutine or function
-  !  integer, parameter, public :: CLOCK_LOOP=41 !loops or blocks within a routine
-  !  integer, parameter, public :: CLOCK_INFRA=51 !infrastructure level, e.g halo update
-  !
    - ! - ! Note that subsequent changes to clock_grain do not - ! change the status of already initiated clocks, and that if the - ! optional grain argument is absent, the clock is always - ! triggered. This guarantees backward compatibility. - !     - ! - ! - !     + !> @brief Set the level of granularity of timing measurements. + !! + !> This routine and three other routines, mpp_clock_id, mpp_clock_begin(id), + !! and mpp_clock_end(id) may be used to time parallel code sections, and + !! extract parallel statistics. Clocks are identified by names, which + !! should be unique in the first 32 characters. The mpp_clock_id + !! call initializes a clock of a given name and returns an integer + !! id. This id can be used by subsequent + !! mpp_clock_begin and mpp_clock_end calls set around a + !! code section to be timed. Example: + !! 
    +  !!    integer :: id
+  !!    id = mpp_clock_id( 'Atmosphere' )
+  !!    call mpp_clock_begin(id)
+  !!    call atmos_model()
+  !!    call mpp_clock_end()
+  !!
    + !! Two flags may be used to alter the behaviour of + !! mpp_clock. If the flag MPP_CLOCK_SYNC is turned on + !! by mpp_clock_id, the clock calls mpp_sync across all + !! the PEs in the current pelist at the top of the timed code section, + !! but allows each PE to complete the code section (and reach + !! mpp_clock_end) at different times. This allows us to measure + !! load imbalance for a given code section. Statistics are written to + !! stdout by mpp_exit. + !! + !! The flag MPP_CLOCK_DETAILED may be turned on by + !! mpp_clock_id to get detailed communication + !! profiles. Communication events of the types SEND, RECV, BROADCAST, + !! REDUCE and WAIT are separately measured for data volume + !! and time. Statistics are written to stdout by + !! mpp_exit, and individual PE info is also written to the file + !! mpp_clock.out.#### where #### is the PE id given by + !! mpp_pe. + !! + !! The flags MPP_CLOCK_SYNC and MPP_CLOCK_DETAILED are + !! integer parameters available by use association, and may be summed to + !! turn them both on. + !! + !! While the nesting of clocks is allowed, please note that turning on + !! the non-optional flags on inner clocks has certain subtle issues. + !! Turning on MPP_CLOCK_SYNC on an inner + !! clock may distort outer clock measurements of load imbalance. Turning + !! on MPP_CLOCK_DETAILED will stop detailed measurements on its + !! outer clock, since only one detailed clock may be active at one time. + !! Also, detailed clocks only time a certain number of events per clock + !! (currently 40000) to conserve memory. If this array overflows, a + !! warning message is printed, and subsequent events for this clock are + !! not timed. + !! + !! Timings are done using the f90 standard + !! SYSTEM_CLOCK intrinsic. + !! + !! The resolution of SYSTEM_CLOCK is often too coarse for use except + !! across large swaths of code. On SGI systems this is transparently + !! overloaded with a higher resolution clock made available in a + !! non-portable fortran interface made available by + !! nsclock.c. This approach will eventually be extended to other + !! platforms. + !! + !! New behaviour added at the Havana release allows the user to embed + !! profiling calls at varying levels of granularity all over the code, + !! and for any particular run, set a threshold of granularity so that + !! finer-grained clocks become dormant. + !! + !! The threshold granularity is held in the private module variable + !! clock_grain. This value may be modified by the call + !! mpp_clock_set_grain, and affect clocks initiated by + !! subsequent calls to mpp_clock_id. The value of + !! clock_grain is set to an arbitrarily large number initially. + !! + !! Clocks initialized by mpp_clock_id can set a new optional + !! argument grain setting their granularity level. Clocks check + !! this level against the current value of clock_grain, and are + !! only triggered if they are at or below ("coarser than") the + !! threshold. Finer-grained clocks are dormant for that run. + !! + !!The following grain levels are pre-defined: + !! + !!
    +  !!!predefined clock granularities, but you can use any integer
+  !!!using CLOCK_LOOP and above may distort coarser-grain measurements
+  !!  integer, parameter, public :: CLOCK_COMPONENT=1 !component level, e.g model, exchange
+  !!  integer, parameter, public :: CLOCK_SUBCOMPONENT=11 !top level within a model component, e.g dynamics, physics
+  !!  integer, parameter, public :: CLOCK_MODULE=21 !module level, e.g main subroutine of a physics module
+  !!  integer, parameter, public :: CLOCK_ROUTINE=31 !level of individual subroutine or function
+  !!  integer, parameter, public :: CLOCK_LOOP=41 !loops or blocks within a routine
+  !!  integer, parameter, public :: CLOCK_INFRA=51 !infrastructure level, e.g halo update
+  !!
    + !! + !! Note that subsequent changes to clock_grain do not + !! change the status of already initiated clocks, and that if the + !! optional grain argument is absent, the clock is always + !! triggered. This guarantees backward compatibility. subroutine mpp_clock_set_grain( grain ) integer, intent(in) :: grain !set the granularity of times: only clocks whose grain is lower than @@ -771,7 +668,7 @@ end function rarray_to_char end subroutine clock_init !##################################################################### - !return an ID for a new or existing clock + !> Return an ID for a new or existing clock function mpp_clock_id( name, flags, grain ) integer :: mpp_clock_id character(len=*), intent(in) :: name @@ -1165,8 +1062,8 @@ end function rarray_to_char end subroutine sum_clock_data !##################################################################### - ! This routine will double the size of peset and copy the original peset data - ! into the expanded one. The maximum allowed to expand is PESET_MAX. + !> This routine will double the size of peset and copy the original peset data + !! into the expanded one. The maximum allowed to expand is PESET_MAX. subroutine expand_peset() integer :: old_peset_max,n type(communicator), allocatable :: peset_old(:) @@ -1278,16 +1175,14 @@ end function rarray_to_char ! !----------------------------------------------------------------------- -! subroutine READ_INPUT_NML -! -! -! Reads an existing input nml file into a character array and broadcasts -! it to the non-root mpi-tasks. This allows the use of reads from an -! internal file for namelist settings (requires 2003 compliant compiler) -! -! read(input_nml_file, nml=, iostat=status) -! -! + +!> Reads an existing input nml file into a character array and broadcasts +!! it to the non-root mpi-tasks. This allows the use of reads from an +!! internal file for namelist settings (requires 2003 compliant compiler) +!! +!! read(input_nml_file, nml=, iostat=status) +!! +!! subroutine read_input_nml(pelist_name_in, alt_input_nml_path) ! Include variable "version" to be written to log file. @@ -1495,19 +1390,18 @@ end function rarray_to_char ! subroutine READ_ASCII_FILE ! ! - ! Reads any ascii file into a character array and broadcasts - ! it to the non-root mpi-tasks. Based off READ_INPUT_NML. - ! - ! Passed in 'Content' array, must be of the form: - ! character(len=LENGTH), dimension(:), allocatable :: array_name - ! - ! Reads from this array must be done in a do loop over the number of - ! lines, i.e.: - ! - ! do i=1, num_lines - ! read (UNIT=array_name(i), FMT=*) var1, var2, ... - ! end do - ! + !> Reads any ascii file into a character array and broadcasts + !! it to the non-root mpi-tasks. Based off READ_INPUT_NML. + !! + !! Passed in 'Content' array, must be of the form: + !! character(len=LENGTH), dimension(:), allocatable :: array_name + !! + !! Reads from this array must be done in a do loop over the number of + !! lines, i.e.: + !! + !! do i=1, num_lines + !! read (UNIT=array_name(i), FMT=*) var1, var2, ... + !! end do subroutine read_ascii_file(FILENAME, LENGTH, Content, PELIST) character(len=*), intent(in) :: FILENAME integer, intent(in) :: LENGTH @@ -1605,3 +1499,4 @@ end function rarray_to_char call mpp_broadcast(Content, LENGTH, from_pe, PELIST=PELIST) end subroutine read_ascii_file +!> @} diff --git a/mpp/include/mpp_util_mpi.inc b/mpp/include/mpp_util_mpi.inc index a22a4f74ff..ef9443783a 100644 --- a/mpp/include/mpp_util_mpi.inc +++ b/mpp/include/mpp_util_mpi.inc @@ -19,9 +19,11 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup mpp !> @brief Utility routines for parallelization with MPI +!> @addtogroup mpp_mod +!> @{ + !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ! ! ! MISCELLANEOUS UTILITIES: mpp_error ! @@ -232,3 +234,4 @@ subroutine mpp_sync_self( pelist, check, request, msg_size, msg_type) if( debug .and. (current_clock.NE.0) )call increment_current_clock(EVENT_WAIT) return end subroutine mpp_sync_self +!> @} diff --git a/mpp/include/mpp_util_nocomm.inc b/mpp/include/mpp_util_nocomm.inc index 59025e69d2..3fcdf6446e 100644 --- a/mpp/include/mpp_util_nocomm.inc +++ b/mpp/include/mpp_util_nocomm.inc @@ -19,7 +19,6 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup mpp !> @brief Utility routines for parallelization, non-mpi version !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @@ -73,10 +72,10 @@ subroutine mpp_error_basic( errortype, errormsg ) end subroutine mpp_error_basic !##################################################################### -!--- makes a PE set out of a PE list. A PE list is an ordered list of PEs -!--- a PE set is a triad (start,log2stride,size) for SHMEM, an a communicator for MPI -!--- if stride is non-uniform or not a power of 2, -!--- will return error (not required for MPI but enforced for uniformity) +!> Makes a PE set out of a PE list. A PE list is an ordered list of PEs +!! a PE set is a triad (start,log2stride,size) for SHMEM, an a communicator for MPI +!! if stride is non-uniform or not a power of 2, +!! will return error (not required for MPI but enforced for uniformity) function get_peset(pelist) integer :: get_peset integer, intent(in), optional :: pelist(:) @@ -92,7 +91,7 @@ function get_peset(pelist) end function get_peset !####################################################################### - !synchronize PEs in list +!> synchronize PEs in list subroutine mpp_sync( pelist, check ) integer, intent(in), optional :: pelist(:) integer, intent(in), optional :: check @@ -101,9 +100,9 @@ subroutine mpp_sync( pelist, check ) end subroutine mpp_sync !####################################################################### - !this is to check if current PE's outstanding puts are complete - !but we can't use shmem_fence because we are actually waiting for - !a remote PE to complete its get +!> This is to check if current PE's outstanding puts are complete +!! but we can't use shmem_fence because we are actually waiting for +!! a remote PE to complete its get subroutine mpp_sync_self( pelist, check, request, msg_size, msg_type ) integer, intent(in), optional :: pelist(:) integer, intent(in), optional :: check diff --git a/mpp/include/system_clock.h b/mpp/include/system_clock.h index 766d0e6911..1ba8fda2ef 100644 --- a/mpp/include/system_clock.h +++ b/mpp/include/system_clock.h @@ -17,16 +17,18 @@ !* License along with FMS. If not, see . !*********************************************************************** !> @file -!> @ingroup mpp_mod + +!> @addtogroup mpp_mod +!> @{ #if defined(use_libMPI) #define SYSTEM_CLOCK system_clock_mpi !####################################################################### +!> There can be one ONE baseline count0 and this routine is +!! included in multiple places. +!! mimics F90 SYSTEM_CLOCK intrinsic subroutine system_clock_mpi( count, count_rate, count_max ) -! There can be one ONE baseline count0 and this routine is -! included in multiple places. -!mimics F90 SYSTEM_CLOCK intrinsic integer(i8_kind), intent(out), optional :: count, count_rate, count_max !count must return a number between 0 and count_max integer(i8_kind), parameter :: maxtick=HUGE(count_max) @@ -61,3 +63,4 @@ subroutine system_clock_default( count, count_rate, count_max ) return end subroutine system_clock_default #endif +!> @} diff --git a/mpp/mpp.F90 b/mpp/mpp.F90 index a516e31097..30cfc7b5cc 100644 --- a/mpp/mpp.F90 +++ b/mpp/mpp.F90 @@ -27,6 +27,9 @@ !> @defgroup mpp_mod mpp_mod !> @ingroup mpp !> @brief This module defines interfaces for common operations using message-passing libraries. +!! Any type-less arguments in the documentation are MPP_TYPE_ which is defined by the pre-processor +!! to create multiple subroutines out of one implementation for use in an interface. See the note +!! below for more information !! !> @author V. Balaji <"V.Balaji@noaa.gov"> !! @@ -76,9 +79,8 @@ !!
  • Performance to be not significantly lower than any native API.
    • !! !! -!! This module is used to develop higher-level calls for domain decomposition and parallel I/O. +!! This module is used to develop higher-level calls for +!! domain decomposition (@ref mpp_domains) and parallel I/O (@ref fms2_io) !!
    !! Parallel computing is initially daunting, but it soon becomes !! second nature, much the way many of us can now write vector code @@ -90,7 +92,7 @@ !! function calls are particularly subtle, since it is not always obvious !! from looking at a call what synchronization between execution streams !! it implies. An example of erroneous code would be a global barrier -!! call (see mpp_sync below) placed +!! call (see @ref mpp_sync below) placed !! within a code block that not all PEs will execute, e.g: !! !! 
    @@ -136,7 +138,7 @@
 !! 
 !! 
    
 !!
-!!  F90 is a strictly-typed language, and the syntax pass of the
+!!  @note F90 is a strictly-typed language, and the syntax pass of the
 !!  compiler requires matching of type, kind and rank (TKR). Most calls
 !!  listed here use a generic type, shown here as MPP_TYPE_. This
 !!  is resolved in the pre-processor stage to any of a variety of
@@ -146,9 +148,6 @@
 !!  generic interface. Any of the variables below shown as
 !!  MPP_TYPE_ is treated in this way.
 
-!> @file
-!> @brief File for @ref mpp_mod
-
 module mpp_mod
 
 ! Define rank(X) for PGI compiler
@@ -406,6 +405,8 @@ module mpp_mod
      module procedure mpp_error_rs_rs
   end interface
   !> Takes a given integer or real array and returns it as a string
+  !> @param[in] array An array of integers or reals
+  !> @returns string equivalent of given array
   !> @ingroup mpp_mod
   interface array_to_char
      module procedure iarray_to_char
@@ -424,38 +425,38 @@ module mpp_mod
   !                                                                             !
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
-  !> @fn subroutine mpp_init( flags, localcomm, test_level)
-  !> @brief Initialize @ref mpp_mod
-  !!
-  !> Called to initialize the mpp_mod package. It is recommended
-  !! that this call be the first executed line in your program. It sets the
-  !! number of PEs assigned to this run (acquired from the command line, or
-  !! through the environment variable NPES), and associates an ID
-  !! number to each PE. These can be accessed by calling @ref mpp_npes and
-  !! @ref mpp_pe.
-  !! 
     Example usage:
-  !!
-  !!            call mpp_init( flags )
-  !!
-  !! @param flags
-  !!   flags can be set to MPP_VERBOSE to
-  !!   have mpp_mod keep you informed of what it's up to.
-  !! @param test_level
-  !!   Debugging flag to set amount of initialization tasks performed
-  !> @ingroup mpp_mod
-
-  !> @fn subroutine mpp_exit()
-  !> @brief Exit @ref mpp_mod.
-  !!
-  !> Called at the end of the run, or to re-initialize mpp_mod,
-  !! should you require that for some odd reason.
-  !!
-  !! This call implies synchronization across all PEs.
-  !!
-  !! 
    Example usage:
-  !!
-  !!            call mpp_exit()
-  !> @ingroup mpp_mod
+!> @fn mpp_mod::mpp_init::mpp_init( flags, localcomm, test_level)
+!> @ingroup mpp_mod
+!> @brief Initialize @ref mpp_mod
+!!
+!> Called to initialize the mpp_mod package. It is recommended
+!! that this call be the first executed line in your program. It sets the
+!! number of PEs assigned to this run (acquired from the command line, or
+!! through the environment variable NPES), and associates an ID
+!! number to each PE. These can be accessed by calling @ref mpp_npes and
+!! @ref mpp_pe.
+!! 
     Example usage:
+!!
+!!            call mpp_init( flags )
+!!
+!! @param flags
+!!   flags can be set to MPP_VERBOSE to
+!!   have mpp_mod keep you informed of what it's up to.
+!! @param test_level
+!!   Debugging flag to set amount of initialization tasks performed
+
+!> @fn mpp_mod::mpp_exit()
+!> @brief Exit @ref mpp_mod.
+!!
+!> Called at the end of the run, or to re-initialize mpp_mod,
+!! should you require that for some odd reason.
+!!
+!! This call implies synchronization across all PEs.
+!!
+!! 
    Example usage:
+!!
+!!            call mpp_exit()
+!> @ingroup mpp_mod
 
   !#####################################################################
 
@@ -524,7 +525,7 @@ module mpp_mod
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
   !> @brief Reduction operations.
-  !>    Find the max of scalar a the PEs in pelist
+  !>    Find the max of scalar a from the PEs in pelist
   !!    result is also automatically broadcast to all PEs
   !!    @code{.F90}
   !!            call  mpp_max( a, pelist )
@@ -545,8 +546,16 @@ module mpp_mod
      module procedure mpp_max_int4_1d
   end interface
 
-  !> @brief Get minimum value out of the PEs in pelist
-  !> Result is also broadcast to all PEs
+  !> @brief Reduction operations.
+  !>    Find the min of scalar a from the PEs in pelist
+  !!    result is also automatically broadcast to all PEs
+  !!    @code{.F90}
+  !!            call  mpp_min( a, pelist )
+  !!    @endcode
+  !> @param a real or integer, of 4-byte of 8-byte kind.
+  !> @param pelist If pelist is omitted, the context is assumed to be the
+  !!    current pelist. This call implies synchronization across the PEs in
+  !!    pelist, or the current pelist if pelist is absent.
   !> @ingroup mpp_mod
   interface mpp_min
      module procedure mpp_min_real8_0d
@@ -571,8 +580,8 @@ module mpp_mod
   !! bit-reproducible. In any case, changing the processor count changes
   !! the data layout, and thus very likely the order of operations. For
   !! bit-reproducible sums of distributed arrays, consider using the
-  !! mpp_global_sum routine provided by the mpp_domains module.
+  !! mpp_global_sum routine provided by the
+  !! @ref mpp_domains module.
   !!
   !! The bit_reproducible flag provided in earlier versions of
   !! this routine has been removed.
@@ -673,8 +682,19 @@ module mpp_mod
 #endif
   end interface
 
-  !> @brief Gather information onto root pe
+  !> @brief Gather data sent from pelist onto the root pe
+  !! Wrapper for MPI_gather, can be used with and without indices
   !> @ingroup mpp_mod
+  !!
+  !> @param sbuf MPP_TYPE_ data buffer to send
+  !> @param rbuf MPP_TYPE_ data buffer to receive
+  !> @param pelist integer(:) optional pelist to gather from, defaults to current
+  !>
+  !> 
     Example usage:
+  !!
+  !!                    call mpp_gather(send_buffer,recv_buffer, pelist)
+  !!                    call mpp_gather(is, ie, js, je, pelist, array_seg, data, is_root_pe)
+  !!
   interface mpp_gather
      module procedure mpp_gather_logical_1d
      module procedure mpp_gather_int4_1d
@@ -694,8 +714,23 @@ module mpp_mod
      module procedure mpp_gather_pelist_real8_3d
   end interface
 
-  !> @brief Scatter information to the given pelist
+  !> @brief Scatter (ie - is) * (je - js) contiguous elements of array data from the designated root pe
+  !! into contigous members of array segment in each pe that is included in the pelist argument.
   !> @ingroup mpp_mod
+  !!
+  !> @param is, ie integer start and end index of the first dimension of the segment array
+  !> @param je, js integer start and end index of the second dimension of the segment array
+  !> @param pelist integer(:) the PE list of target pes, needs to be monotonically increasing
+  !> @param array_seg MPP_TYPE_ 2D array that the data is to be copied into
+  !> @param data MPP_TYPE_ the source array
+  !> @param is_root_pe logical true if calling from root pe
+  !> @param ishift integer offsets specifying the first elelement in the data array
+  !> @param nk integer size of third dimension for 3D calls
+  !!
+  !> 
     Example usage:
+  !!
+  !!                    call mpp_scatter(is, ie, js, je, pelist, segment, data, .true.)
+  !!
   interface mpp_scatter
      module procedure mpp_scatter_pelist_int4_2d
      module procedure mpp_scatter_pelist_int4_3d
@@ -709,6 +744,14 @@ module mpp_mod
   !> @brief Scatter a vector across all PEs
   !!
   !> Transpose the vector and PE index
+  !! Wrapper for the MPI_alltoall function, includes more generic _V and _W
+  !! versions if given displacements/data types
+  !!
+  !! Generic MPP_TYPE_ implentations:
+  !! 
  •  @ref mpp_alltoall_ 
    • 
+  !! 
  •  @ref mpp_alltoallv_ 
    • 
+  !! 
  •  @ref mpp_alltoallw_ 
    • 
+  !!
   !> @ingroup mpp_mod
   interface mpp_alltoall
      module procedure mpp_alltoall_int4
@@ -777,8 +820,8 @@ module mpp_mod
   !!    portability is a concern, it is best avoided).
    
   !!    ALL_PES: is used for broadcast operations.
   !!
-  !!    It is recommended that mpp_broadcast be used for
+  !!    It is recommended that
+  !!    @ref mpp_broadcast be used for
   !!    broadcasts.
   !!
   !!    The following example illustrates the use of
@@ -876,7 +919,7 @@ module mpp_mod
      module procedure mpp_transmit_logical4_4d
      module procedure mpp_transmit_logical4_5d
   end interface
-  !> @brief Recieve data to another PE
+  !> @brief Recieve data from another PE
   !!
   !> @param[out] get_data scalar or array to get written with received data
   !> @param get_len size of array to recv from get_data
@@ -1021,8 +1064,8 @@ module mpp_mod
   !! contiguous block from a multi-dimensional array may be passed by its
   !! starting address and its length, as in f77.
   !!
-  !! Global broadcasts through the ALL_PES argument to mpp_transmit are still provided for
+  !! Global broadcasts through the ALL_PES argument to
+  !! @ref mpp_transmit are still provided for
   !! backward-compatibility.
   !!
   !! If pelist is omitted, the context is assumed to be the
@@ -1103,20 +1146,17 @@ module mpp_mod
   !!
   !> \e mpp_chksum is a parallel checksum routine that returns an
   !! identical answer for the same array irrespective of how it has been
-  !! partitioned across processors. \eint_kind is the KIND
+  !! partitioned across processors. \e int_kind is the KIND
   !! parameter corresponding to long integers (see discussion on
   !! OS-dependent preprocessor directives) defined in
-  !! the file platform.F90. \eMPP_TYPE_ corresponds to any
-  !! 4-byte and 8-byte variant of \einteger, \ereal, \ecomplex, \elogical
+  !! the file platform.F90. \e MPP_TYPE_ corresponds to any
+  !! 4-byte and 8-byte variant of \e integer, \e real, \e complex, \e logical
   !! variables, of rank 0 to 5.
   !!
   !! Integer checksums on FP data use the F90 TRANSFER()
   !! intrinsic.
   !!
-  !! The serial
-  !! checksum module is superseded
-  !! by this function, and is no longer being actively maintained. This
-  !! provides identical results on a single-processor job, and to perform
+  !! This provides identical results on a single-processor job, and to perform
   !! serial checksums on a single processor of a parallel job, you only
   !! need to use the optional pelist argument.
   !! 
    @@ -1144,6 +1184,12 @@ module mpp_mod
   !! @param pelist Optional list of PE's to include in checksum calculation if not using
   !! current pelist
   !! @return Parallel checksum of var across given or implicit pelist
+  !!
+  !! Generic MPP_TYPE_ implentations:
+  !! 
  •  @ref mpp_chksum_
    • 
+  !! 
  •  @ref mpp_chksum_int_
    • 
+  !! 
  •  @ref mpp_chksum_int_rmask_
    • 
+  !!
   !> @ingroup mpp_mod
   interface mpp_chksum
      module procedure mpp_chksum_i8_1d
diff --git a/mpp/mpp_data.F90 b/mpp/mpp_data.F90
index 6b9b91931e..639417fb07 100644
--- a/mpp/mpp_data.F90
+++ b/mpp/mpp_data.F90
@@ -24,9 +24,6 @@
 !! mpp_data_nocomm.inc for use in @ref mpp modules. This module is mainly
 !! for internal use within @ref mpp_mod and @ref mpp_domains_mod .
 
-!> @file
-!> @brief File for @ref mpp_data_mod
-
 !> @addtogroup mpp_data_mod
 !> @{
 module mpp_data_mod
diff --git a/mpp/mpp_domains.F90 b/mpp/mpp_domains.F90
index 91a429fb58..b2ccf3540f 100644
--- a/mpp/mpp_domains.F90
+++ b/mpp/mpp_domains.F90
@@ -86,9 +86,6 @@
 !!      type(domain1D), public :: NULL_DOMAIN1D
 !!      type(domain2D), public :: NULL_DOMAIN2D
 
-!> @file
-!> @brief File for @ref mpp_domains_mod
-
 !> @addtogroup mpp_domains_mod
 !> @{
 
@@ -295,19 +292,7 @@ module mpp_domains_mod
      logical :: is_global !< .true. if domain axis extent covers global domain
   end type domain_axis_spec
 
-  !> One dimensional domain used to manage shared data access between pes
-  !> @ingroup mpp_domains_mod
-  type :: domain1D
-     private
-     type(domain_axis_spec) :: compute, data, global, memory !> index limits for different domains
-     logical :: cyclic
-     type(domain1D), pointer :: list(:) =>NULL() !> list of each pe's domains
-     integer :: pe ! Private type used to specify index limits for a domain decomposition
+  !> A private type used to specify index limits for a domain decomposition
   !> @ingroup mpp_domains_mod
   type :: domain1D_spec
      private
@@ -638,6 +623,22 @@ module mpp_domains_mod
      integer            :: type_recv(MAX_REQUEST)
   end type mpp_group_update_type
 
+  !> One dimensional domain used to manage shared data access between pes
+  !> @ingroup mpp_domains_mod
+  type :: domain1D
+     private
+     type(domain_axis_spec) :: compute !< index limits for compute domain
+     type(domain_axis_spec) :: data    !< index limits for data domain
+     type(domain_axis_spec) :: global  !< index limits for global domain
+     type(domain_axis_spec) :: memory  !< index limits for memory domain
+     logical :: cyclic !< true if domain is cyclic
+     type(domain1D), pointer :: list(:) =>NULL() !< list of each pe's domains
+     integer :: pe ! @addtogroup mpp_domains_mod
@@ -910,6 +911,7 @@ module mpp_domains_mod
      module procedure mpp_copy_domain2D
   end interface mpp_copy_domain
   !> Deallocate given 1D or 2D domain
+  !> @param domain an allocated @ref domain1D or @ref domain2D
   !> @ingroup mpp_domains_mod
   interface mpp_deallocate_domain
      module procedure mpp_deallocate_domain1D
@@ -1301,7 +1303,10 @@ module mpp_domains_mod
      module procedure mpp_complete_do_update_i4_3d
   end interface
 
-
+  !> Constructor for the @ref mpp_group_update_type which is
+  !! then used with @ref mpp_start_group_update
+  !!
+  !> @param
   !> @ingroup mpp_domains_mod
   interface mpp_create_group_update
      module procedure mpp_create_group_update_r4_2d
@@ -1324,12 +1329,24 @@ module mpp_domains_mod
      module procedure mpp_do_group_update_r8
   end interface mpp_do_group_update
 
+  !> Starts non-blocking group update
+  !! Must be followed up with a call to @ref mpp_complete_group_update
+  !! @ref mpp_group_update_type can be created with @ref mpp_create_group_update
+  !!
+  !> @param[inout] type(mpp_group_update_type) group type created for group update
+  !> @param[inout] type(domain2D) domain to update
   !> @ingroup mpp_domains_mod
   interface mpp_start_group_update
      module procedure mpp_start_group_update_r4
      module procedure mpp_start_group_update_r8
   end interface mpp_start_group_update
 
+  !> Completes a pending non-blocking group update
+  !! Must follow a call to @ref mpp_start_group_update
+  !!
+  !> @param[inout] type(mpp_group_update_type) group
+  !> @param[inout] type(domain2D) domain
+  !> @param[in] d_type data type
   !> @ingroup mpp_domains_mod
   interface mpp_complete_group_update
      module procedure mpp_complete_group_update_r4
@@ -1353,7 +1370,7 @@ module mpp_domains_mod
   end interface mpp_reset_group_update_field
 
   !> Pass the data from coarse grid to fill the buffer to be ready to be interpolated
-  !! nto fine grid.
+  !! onto fine grid.
   !! 
    Example usage:
   !!
   !!                call mpp_update_nest_fine(field, nest_domain, wbuffer, ebuffer, sbuffer,
@@ -1445,6 +1462,8 @@ module mpp_domains_mod
      module procedure mpp_update_nest_coarse_i4_4d
   end interface
 
+  !> @brief Used by @ref mpp_update_nest_coarse to perform domain updates
+  !!
   !> @ingroup mpp_domains_mod
   interface mpp_do_update_nest_coarse
      module procedure mpp_do_update_nest_coarse_r8_3d
@@ -1472,7 +1491,13 @@ module mpp_domains_mod
     module procedure mpp_get_F2C_index_coarse
   end interface
 
-  !> Send domain to every pe
+  !> Broadcasts domain to every pe. Only useful outside the context of it's own pelist
+  !!
+  !> 
    Example usage:
+  !!                    call mpp_broadcast_domain(domain)
+  !!                    call mpp_broadcast_domain(domain_in, domain_out)
+  !!                    call mpp_broadcast_domain(domain, tile_coarse) ! nested domains
+  !!
   !> @ingroup mpp_domains_mod
   interface mpp_broadcast_domain
     module procedure mpp_broadcast_domain_1
@@ -1522,7 +1547,7 @@ module mpp_domains_mod
 #endif
      module procedure mpp_do_update_i4_3d
   end interface
-
+  !> Private interface to updates data domain of 3D field whose computational domains have been computed
   !> @ingroup mpp_domains_mod
   interface mpp_do_check
      module procedure mpp_do_check_r8_3d
@@ -1555,6 +1580,10 @@ module mpp_domains_mod
      module procedure mpp_pass_SG_to_UG_l4_3d
   end interface
 
+  !> Passes a data field from a structured grid to an unstructured grid
+  !! 
    Example usage:
+  !!
+  !!            call mpp_pass_SG_to_UG(SG_domain, field_SG, field_UG)
   !> @ingroup mpp_domains_mod
   interface mpp_pass_UG_to_SG
      module procedure mpp_pass_UG_to_SG_r8_2d
@@ -1567,6 +1596,11 @@ module mpp_domains_mod
      module procedure mpp_pass_UG_to_SG_l4_3d
   end interface
 
+  !> Passes a data field from a unstructured grid to an structured grid
+  !! 
    Example usage:
+  !!
+  !!            call mpp_pass_UG_to_SG(UG_domain, field_UG, field_SG)
+  !!
   !> @ingroup mpp_domains_mod
   interface mpp_do_update_ad
      module procedure mpp_do_update_ad_r8_3d
@@ -1574,9 +1608,9 @@ module mpp_domains_mod
      module procedure mpp_do_update_ad_r4_3d
      module procedure mpp_do_update_ad_r4_3dv
   end interface
-!
+
 !> Get the boundary data for symmetric domain when the data is at C, E, or N-cell center.
    
-!! \e mpp_get_boundary is used to get the boundary data for symmetric domain
+!! @ref mpp_get_boundary is used to get the boundary data for symmetric domain
 !! when the data is at C, E, or N-cell center. For cubic grid, the data should always
 !! at C-cell center.
 !! 
    Example usage:
@@ -1823,6 +1857,7 @@ module mpp_domains_mod
      module procedure mpp_global_field2D_l4_5d_ad
   end interface
 
+!> Private helper interface used by @ref mpp_global_field
 !> @ingroup mpp_domains_mod
   interface mpp_do_global_field
      module procedure mpp_do_global_field2D_r8_3d
@@ -1854,6 +1889,7 @@ module mpp_domains_mod
      module procedure mpp_do_global_field2D_a2a_l4_3d
   end interface
 
+!> Same functionality as @ref mpp_global_field but for unstructured domains
 !> @ingroup mpp_domains_mod
   interface mpp_global_field_ug
      module procedure mpp_global_field2D_ug_r8_2d
@@ -1890,7 +1926,7 @@ module mpp_domains_mod
      module procedure mpp_do_global_field2D_l4_3d_ad
   end interface
 
-!> Global max/min of domain-decomposed arrays.
    
+!> Global max of domain-decomposed arrays.
    
 !! \e mpp_global_max is used to get the maximum value of a
 !! domain-decomposed array on each PE. \e MPP_TYPE_can be of type
 !! \e integer or \e real; of 4-byte or 8-byte kind; of rank
@@ -1926,6 +1962,22 @@ module mpp_domains_mod
      module procedure mpp_global_max_i4_5d
   end interface
 
+!> Global min of domain-decomposed arrays.
    
+!! \e mpp_global_min is used to get the minimum value of a
+!! domain-decomposed array on each PE. \e MPP_TYPE_can be of type
+!! \e integer or \e real; of 4-byte or 8-byte kind; of rank
+!! up to 5. The dimension of \e locus must equal the rank of \e field.
    
+!!
    
+!! All PEs in a domain decomposition must call \e mpp_global_min,
+!! and each will have the result upon exit.
+!! The function \e mpp_global_max, with an identical syntax. is also available.
+!!
+!! @param domain 2D domain
+!! @param field field data dimensioned on either the compute or data domains of 'domain'
+!! @param locus If present, van be used to retrieve the location of the minimum
+!!
+!! 
    Example usage:
+!!              mpp_global_min( domain, field, locus )
 !> @ingroup mpp_domains_mod
   interface mpp_global_min
      module procedure mpp_global_min_r8_2d
diff --git a/mpp/mpp_efp.F90 b/mpp/mpp_efp.F90
index 892340f67e..cdfc7728bd 100644
--- a/mpp/mpp_efp.F90
+++ b/mpp/mpp_efp.F90
@@ -24,9 +24,6 @@
 !> Mainly includes interfaces and type definitions for reproducing operations with extended
 !! fixed point data.
 
-!> @file
-!> @brief file for @ref mpp_efp_mod
-
 !> @addtogroup mpp_efp_mod
 !> @{
 module mpp_efp_mod
diff --git a/mpp/mpp_io.F90 b/mpp/mpp_io.F90
index feb18f7d51..af52ac1e10 100644
--- a/mpp/mpp_io.F90
+++ b/mpp/mpp_io.F90
@@ -305,11 +305,9 @@
 !! 
 !! @endhtmlonly
 
-!> @file
-!> @brief File for @ref mpp_io_mod
-
 !> @addtogroup mpp_io_mod
 !> @{
+ 
 module mpp_io_mod
 
 #define _MAX_FILE_UNITS 1024
@@ -798,15 +796,92 @@ module mpp_io_mod
 !  
 !  
 !  
-! 
-!    Note that mpp_write_meta is expecting axis data on the
-!    global domain even if it is a domain-decomposed axis.
-!
-!    You cannot interleave calls to mpp_write and
-!    mpp_write_meta: the first call to
-!    mpp_write implies that metadata specification is complete.
-! 
-! 
+
+!> Each file can contain any number of fields,
+!! which can be functions of 0-3 spatial axes and 0-1 time axes. Axis
+!! descriptors are stored in the  structure and field
+!! descriptors in the  structure.
+!!
+!! The metadata contained in the type is always written for each axis and
+!! field. Any other metadata one wishes to attach to an axis or field
+!! can subsequently be passed to mpp_write_meta using the ID, as shown below.
+!!
+!! mpp_write_meta can take several forms:
+!!
+!!  mpp_write_meta( unit, name, rval=rval, pack=pack )
+!!  mpp_write_meta( unit, name, ival=ival )
+!!  mpp_write_meta( unit, name, cval=cval )
+!!      integer, intent(in) :: unit
+!!      character(len=*), intent(in) :: name
+!!      real, intent(in), optional :: rval(:)
+!!      integer, intent(in), optional :: ival(:)
+!!      character(len=*), intent(in), optional :: cval
+!!
+!! This form defines global metadata associated with the file as a
+!! whole. The attribute is named  and can take on a real, integer
+!! or character value.  and  can be scalar or 1D arrays.
+!!
+!!  mpp_write_meta( unit, id, name, rval=rval, pack=pack )
+!!  mpp_write_meta( unit, id, name, ival=ival )
+!!  mpp_write_meta( unit, id, name, cval=cval )
+!!      integer, intent(in) :: unit, id
+!!      character(len=*), intent(in) :: name
+!!      real, intent(in), optional :: rval(:)
+!!      integer, intent(in), optional :: ival(:)
+!!      character(len=*), intent(in), optional :: cval
+!!
+!! This form defines metadata associated with a previously defined
+!! axis or field, identified to mpp_write_meta by its unique ID .
+!! The attribute is named  and can take on a real, integer
+!! or character value.  and  can be scalar or 1D arrays.
+!! This need not be called for attributes already contained in
+!! the type.
+!!
+!! PACK can take values 1,2,4,8. This only has meaning when writing
+!! floating point numbers. The value of PACK defines the number of words
+!! written into 8 bytes. For pack=4 and pack=8, an integer value is
+!! written: rval is assumed to have been scaled to the appropriate dynamic
+!! range.
+!! PACK currently only works for netCDF files, and is ignored otherwise.
+!!
+!!  subroutine mpp_write_meta_axis( unit, axis, name, units, longname, &
+!!        cartesian, sense, domain, data )
+!!     integer, intent(in) :: unit
+!!     type(axistype), intent(inout) :: axis
+!!     character(len=*), intent(in) :: name, units, longname
+!!     character(len=*), intent(in), optional :: cartesian
+!!     integer, intent(in), optional :: sense
+!!     type(domain1D), intent(in), optional :: domain
+!!     real, intent(in), optional :: data(:)
+!!
+!! This form defines a time or space axis. Metadata corresponding to the
+!! type above are written to the file on . A unique ID for subsequent
+!! references to this axis is returned in axis%id. If the 
+!! element is present, this is recognized as a distributed data axis
+!! and domain decomposition information is also written if required (the
+!! domain decomposition info is required for multi-fileset multi-threaded
+!! I/O). If the  element is allocated, it is considered to be a
+!! space axis, otherwise it is a time axis with an unlimited dimension.
+!! Only one time axis is allowed per file.
+!! @code{.F90}
+!!  subroutine mpp_write_meta_field( unit, field, axes, name, units, longname
+!!                                   standard_name, min, max, missing, fill, scale, add, pack)
+!!     integer, intent(in) :: unit
+!!     type(fieldtype), intent(out) :: field
+!!     type(axistype), intent(in) :: axes(:)
+!!     character(len=*), intent(in) :: name, units, longname, standard_name
+!!     real, intent(in), optional :: min, max, missing, fill, scale, add
+!!     integer, intent(in), optional :: pack
+!! @endcode
+!! This form defines a field. Metadata corresponding to the type
+!! above are written to the file on . A unique ID for subsequent
+!! references to this field is returned in field%id. At least one axis
+!! must be associated, 0D variables are not considered. mpp_write_meta
+!! must previously have been called on all axes associated with this
+!! field.
+!!
+!! The mpp_write_meta package also includes subroutines write_attribute and
+!! write_attribute_netcdf, that are private to this module.
   interface mpp_write_meta
      module procedure mpp_write_meta_var
      module procedure mpp_write_meta_scalar_r
diff --git a/mpp/mpp_memutils.F90 b/mpp/mpp_memutils.F90
index 265611b068..79a5f00467 100644
--- a/mpp/mpp_memutils.F90
+++ b/mpp/mpp_memutils.F90
@@ -20,9 +20,6 @@
 !> @ingroup mpp
 !> @brief Routines to initialize and report on memory usage during the model run.
 
-!> @file
-!> @brief File for mpp_memutils_mod
-
 !> @addtogroup mpp_memutils_mod
 !> @{
 module mpp_memutils_mod
diff --git a/mpp/mpp_parameter.F90 b/mpp/mpp_parameter.F90
index c5a2000531..182e3f2a7d 100644
--- a/mpp/mpp_parameter.F90
+++ b/mpp/mpp_parameter.F90
@@ -21,9 +21,6 @@
 !> @brief Parameters values for use in various @ref mpp modules
 !> If needed, these values should be imported from their corresponding mpp module
 
-!> @file
-!> @brief File for @ref mpp_parameter_mod
-
 !> @addtogroup mpp_parameter_mod
 !> @{
 module mpp_parameter_mod
diff --git a/mpp/mpp_pset.F90 b/mpp/mpp_pset.F90
index 3bab87ef98..918e1021d4 100644
--- a/mpp/mpp_pset.F90
+++ b/mpp/mpp_pset.F90
@@ -16,16 +16,20 @@
 !* You should have received a copy of the GNU Lesser General Public
 !* License along with FMS.  If not, see .
 !***********************************************************************
-! module within MPP for handling PSETs:
-! PSET: Persistent Shared-memory Execution Thread
-!
-! AUTHOR: V. Balaji (v.balaji@noaa.gov)
-! DATE: 2006-01-15
 #ifdef test_mpp_pset
 !PSET_DEBUG is always turned on in the test program
 #define PSET_DEBUG
 #endif
 
+!> @defgroup mpp_pset_mod mpp_pset_mod
+!> @ingroup mpp
+!> @brief Handles PSETs(Persistent Shared-memory Execution Threads) for mpp modules
+!!
+!! @author V. Balaji (v.balaji@noaa.gov)
+!! @date 2006-01-15
+
+!> @addtogroup mpp_pset_mod mpp_pset_mod
+!> @{
 module mpp_pset_mod
 #include 
   use mpp_mod, only: mpp_pe, mpp_npes, mpp_root_pe, mpp_send, mpp_recv, &
@@ -579,3 +583,4 @@ subroutine mpp_pset_get_root_pelist(pset,pelist,commID)
   end subroutine mpp_pset_get_root_pelist
 
 end module mpp_pset_mod
+!> @}
diff --git a/mpp/mpp_utilities.F90 b/mpp/mpp_utilities.F90
index de9f23326f..1e7bf78fb5 100644
--- a/mpp/mpp_utilities.F90
+++ b/mpp/mpp_utilities.F90
@@ -22,9 +22,6 @@
 !!
 !> Currently only holds one routine for finding global min and max
 
-!> @file
-!> @brief File for @ref mpp_utilities_mod
-
 !> @addtogroup mpp_utilities_mod
 !> @{
 module mpp_utilities_mod
diff --git a/platform/platform.F90 b/platform/platform.F90
index 32396839f5..f6dde8d1f4 100644
--- a/platform/platform.F90
+++ b/platform/platform.F90
@@ -21,9 +21,6 @@
 !> @brief Uses @ref fms_platform.h to define byte sizes for variable kinds
 !! to be used in fms.
 
-!> @file
-!> @brief File for @ref platform_mod
-
 !> @addtogroup platform_mod
 !> @{
 module platform_mod
diff --git a/random_numbers/mersennetwister.F90 b/random_numbers/mersennetwister.F90
index 9bbfa54586..61ef197cc0 100644
--- a/random_numbers/mersennetwister.F90
+++ b/random_numbers/mersennetwister.F90
@@ -88,9 +88,6 @@
 !!    http://www.math.keio.ac.jp/matumoto/emt.html
 !!    email: matumoto@math.keio.ac.jp
 
-!> @file
-!> @brief File for @ref MersenneTwister_mod
-
 !> @addtogroup mersennetwister_mod
 !> @{
 module MersenneTwister_mod
diff --git a/random_numbers/random_numbers.F90 b/random_numbers/random_numbers.F90
index f545e88320..4d2e1727cc 100644
--- a/random_numbers/random_numbers.F90
+++ b/random_numbers/random_numbers.F90
@@ -25,9 +25,6 @@
 !!  in the range 0 to 1.
 !!  This version uses the Mersenne Twister to generate random numbers on [0, 1].
 
-!> @file
-!> @brief File for @ref random_numbers_mod
-
 module random_numbers_mod
 
   use MersenneTwister_mod, only: randomNumberSequence, & ! The random number engine.
diff --git a/sat_vapor_pres/sat_vapor_pres.F90 b/sat_vapor_pres/sat_vapor_pres.F90
index 16ea75c72e..e2e193cae8 100644
--- a/sat_vapor_pres/sat_vapor_pres.F90
+++ b/sat_vapor_pres/sat_vapor_pres.F90
@@ -97,9 +97,6 @@
 !!              call compute_mrs (temp, press, mrs, mr, hc, dmrsdT, esat,
 !!                                err_msg, es_over_liq)
 
-!> @file
-!> @brief File for @ref sat_vapor_pres_mod
-
 module sat_vapor_pres_mod
 
 !-----------------------------------------------------------------------
diff --git a/sat_vapor_pres/sat_vapor_pres_k.F90 b/sat_vapor_pres/sat_vapor_pres_k.F90
index a9662a7d3b..034bf0f7ed 100644
--- a/sat_vapor_pres/sat_vapor_pres_k.F90
+++ b/sat_vapor_pres/sat_vapor_pres_k.F90
@@ -21,9 +21,6 @@
 !> @brief Kernel module to be used by @ref sat_vapor_pres_mod for
 !! table lookups and calculations
 
-!> @file
-!> @brief File for @ref sat_vapor_pres_k_mod
-
  module sat_vapor_pres_k_mod
 
 ! This module is what I (pjp) think a kernel should be.
diff --git a/time_interp/time_interp.F90 b/time_interp/time_interp.F90
index 654f50f6b2..a6a31c0425 100644
--- a/time_interp/time_interp.F90
+++ b/time_interp/time_interp.F90
@@ -27,9 +27,6 @@
 !! The dates may be expressed as years, months, or days or
 !! as indices in an array.
 
-!> @file
-!> @brief File for @ref time_interp_mod
-
 module time_interp_mod
 
 use time_manager_mod, only: time_type, get_date, set_date, set_time, &
diff --git a/time_interp/time_interp_external.F90 b/time_interp/time_interp_external.F90
index 5ac524660f..c25f694dea 100644
--- a/time_interp/time_interp_external.F90
+++ b/time_interp/time_interp_external.F90
@@ -29,9 +29,6 @@
 !! data are defined over data domain for domain2d data
 !! (halo values are NOT updated by this module)
 
-!> @file
-!> @brief File for @ref time_interp_external_mod
-
 !> @addtogroup time_interp_external_mod
 !> @{
 module time_interp_external_mod
diff --git a/time_interp/time_interp_external2.F90 b/time_interp/time_interp_external2.F90
index 21eed80f05..fbe2f9e6f1 100644
--- a/time_interp/time_interp_external2.F90
+++ b/time_interp/time_interp_external2.F90
@@ -31,9 +31,6 @@
 !! data are defined over data domain for domain2d data
 !! (halo values are NOT updated by this module)
 
-!> @file
-!> @brief File for @ref time_interp_external2_mod
-
 !> @addtogroup time_interp_external2_mod
 !> @{
 module time_interp_external2_mod
diff --git a/time_manager/get_cal_time.F90 b/time_manager/get_cal_time.F90
index af4a488949..74dade7f33 100644
--- a/time_manager/get_cal_time.F90
+++ b/time_manager/get_cal_time.F90
@@ -21,9 +21,6 @@
 !> @brief Given a time increment as a real number, and base time and calendar
 !!  as a character strings, returns time as a time_type variable.
 
-!> @file
-!> @brief File for @ref get_cal_time_mod
-
 !> @addtogroup get_cal_time_mod
 !> @{
 module get_cal_time_mod
diff --git a/time_manager/time_manager.F90 b/time_manager/time_manager.F90
index 4effa75515..6346ff9a23 100644
--- a/time_manager/time_manager.F90
+++ b/time_manager/time_manager.F90
@@ -21,31 +21,15 @@
 !> @link http://www.gfdl.noaa.gov/fms-cgi-bin/cvsweb.cgi/FMS/
 !> @brief A software package that provides a set of simple interfaces for
 !!   modelers to perform computations related to time and dates.
-!> The changes between the lima revision and this revision are more
-!! extensive that all those between antwerp and lima.
-!! A brief description of these changes follows.
 !!
-!! 
  •  Added option to set the smallest time increment to something less than one second.
-!!    This is controlled by calling the pubic subroutine set_ticks_per_second. 
    • 
+!! Optional error flag can be used in calling arguments of public routines.
+!! This allows the using routine to terminate the program. It is likely that more
+!! diagnostic information is available from the user than from time_manager alone.
+!! If the error flag is present then it is the responsibility of the using
+!! routine to test it and add additional information to the error message.
 !!
-!! 
  • Gregorian calendar fixed.
    • 
-!!
-!! 
  • Optional error flag added to calling arguments of public routines.
-!!    This allows the using routine to terminate the program. It is likely that more
-!!    diagnostic information is available from the user than from time_manager alone.
-!!    If the error flag is present then it is the responsibility of the using
-!!    routine to test it and add additional information to the error message.
    • 
-!!
-!! 
  • Removed the restriction that time increments be positive in routines that increment or decrement
-!!    time and date. The option to prohibit negative increments can be turned on via optional argument.
    • 
-!!
-!! 
  • subroutine set_date_c modified to handle strings that include only hours or only hours and minutes.
-!!    This complies with CF convensions.
    • 
-!!
-!! 
  • Made calendar specific routines private.
-!!    They are not used, and should not be used, by any using code.
    • 
-!!
-!! 
  • Error messages made more informative.
    • 
+!! Calendar specific routines are private.
+!! They are not used, and should not be used, by any using code.
 !!
 !! The module defines a type that can be used to represent discrete
 !! times (accurate to one second) and to map these times into dates
@@ -74,14 +58,6 @@
 !! The number of ticks per second is set via pubic subroutine set_ticks_per_second.
 !! For example, ticks_per_second = 1000  will set the tick to one millisecond.
 
-!! 
-!!    Derived-type data variable used to store time and date quantities. It
-!!    contains three PRIVATE variables: days, seconds and ticks.
-!! 
-
-!> @file
-!> @brief File for @ref time_manager_mod
-
 !> @addtogroup time_manager_mod
 !> @{
 module time_manager_mod
diff --git a/topography/gaussian_topog.F90 b/topography/gaussian_topog.F90
index 84b0443e04..65d9c66dba 100644
--- a/topography/gaussian_topog.F90
+++ b/topography/gaussian_topog.F90
@@ -27,9 +27,6 @@
 !! The mountain shapes are controlled by the height, half-width,
 !! and ridge-width parameters.
 
-!> @file
-!> @brief File for @ref gaussian_topog_mod
-
 !> @addtogroup gaussian_topog_mod
 !> @{
 module gaussian_topog_mod
diff --git a/topography/topography.F90 b/topography/topography.F90
index e97d14e9f9..1cfe0ec7fb 100644
--- a/topography/topography.F90
+++ b/topography/topography.F90
@@ -35,9 +35,6 @@
 !! The interfaces get_gaussian_topog and gaussian_topog_init are documented
 !! in @ref gaussian_topog_mod
 
-!> @file
-!> @brief File for @ref topography_mod
-
 module topography_mod
 
 use gaussian_topog_mod, only: gaussian_topog_init, get_gaussian_topog
diff --git a/tracer_manager/tracer_manager.F90 b/tracer_manager/tracer_manager.F90
index 14d28f1fcc..5c2321fce4 100644
--- a/tracer_manager/tracer_manager.F90
+++ b/tracer_manager/tracer_manager.F90
@@ -39,9 +39,6 @@
 !! the Nth tracer within the component model. Therefore a call with MODEL_ATMOS and 5
 !! is different from a call with MODEL_OCEAN and 5.
 
-!> @file
-!> @brief File for @ref tracer_manager_mod
-
 module tracer_manager_mod
 
 !----------------------------------------------------------------------
diff --git a/tridiagonal/tridiagonal.F90 b/tridiagonal/tridiagonal.F90
index 266696764a..3aaddf070c 100644
--- a/tridiagonal/tridiagonal.F90
+++ b/tridiagonal/tridiagonal.F90
@@ -55,9 +55,6 @@
 !! Arguments A, B, and C are optional, and are saved as module variables
 !! if one recalls tri_invert without changing (A,B,C)
 
-!> @file
-!> @brief File for @ref tridiagonal_mod
-
 !> @addtogroup tridiagonal_mod
 !> @{
 module tridiagonal_mod