From b1b9683e933e78057423a3eeb4b407ea68619b74 Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Wed, 11 Mar 2026 21:58:47 -0600 Subject: [PATCH 1/3] Adding more information on Standard Names for dimensions in metadata files --- .../source/CompliantPhysicsParams.rst | 50 +++++++++++++++---- CCPPtechnical/source/HostSideCoding.rst | 2 +- 2 files changed, 40 insertions(+), 12 deletions(-) diff --git a/CCPPtechnical/source/CompliantPhysicsParams.rst b/CCPPtechnical/source/CompliantPhysicsParams.rst index 1954063..1d6a984 100644 --- a/CCPPtechnical/source/CompliantPhysicsParams.rst +++ b/CCPPtechnical/source/CompliantPhysicsParams.rst @@ -338,14 +338,7 @@ After the ``ccpp-arg-table``, there should be a metadata entry for every input a .. note:: The ``intent`` argument is only valid in ``scheme`` metadata tables, as it is not applicable to the other ``types``. -* ``dimensions`` indicates the dimensionality of the variable. The dimensions attribute should be empty parentheses for scalars, or indicate the start and end of each dimension of an array with an appropriate standard name; see the `ESM Standard Names documentation `__. ``ccpp_constant_one`` is the assumed start for any dimension which only has a single value. Some examples are listed here: - -.. code-block:: fortran - - dimensions = () - dimensions = (ccpp_constant_one:horizontal_loop_extent, vertical_level_dimension) - dimensions = (horizontal_dimension,vertical_dimension) - dimensions = (horizontal_dimension,vertical_dimension_of_ozone_forcing_data,number_of_coefficients_in_ozone_forcing_data) +* ``dimensions`` indicates the dimensionality of the variable. See :numref:`Section %s ` for details. * ``type`` indicates the variable type. Can be ``character``, ``integer``, ``real``, ``complex``, ``logical``, ``ddt``, or a custom type defined by the host. Custom types must be listed under ``TYPEDEFS_NEW_METADATA`` in the prebuild configuration file. @@ -374,12 +367,47 @@ After the ``ccpp-arg-table``, there should be a metadata entry for every input a .. warning:: The ``pointer`` and ``rank`` attributes are deprecated and no longer allowed in CCPP -.. _HorizontalDimensionOptionsSchemes: +.. _SchemeDimensionOptions: -``horizontal_dimension`` vs. ``horizontal_loop_extent`` +Horizontal, vertical, and other dimensions ------------------------------------------------------- +The dimensions attribute in metadata should indicate both the dimensionality of the data, as well as the breakdown of data among parallel processes. It should be empty parentheses for scalars, or indicate the start and end of each dimension of an array with an appropriate standard name as listed in the `ESM Standard Names documentation `__. ``ccpp_constant_one`` is the assumed start for any dimension which only has a single value. Some examples are listed here: + +.. code-block:: fortran + + dimensions = () + dimensions = (ccpp_constant_one:horizontal_loop_extent, vertical_level_dimension) + dimensions = (horizontal_dimension,vertical_dimension) + dimensions = (horizontal_dimension,vertical_dimension_of_ozone_forcing_data,number_of_coefficients_in_ozone_forcing_data) + +The standard names used for dimensions may come in sets of six related standard names for each dimension: + +.. code-block:: fortran + + [dim_name]_dimension -- The full dimension size + [dim_name]_loop_extent -- Size of dim for current call + [dim_name]_begin - Start index for dimension + [dim_name]_end - End index for dimension + [dim_name]_index - Single index for dimension + [dim_name]_selection - Array of selected indices for + dimension + +Note that the cap generator may substitute among standard names in this category in order to +properly call suite parts and individual schemes. In the substitutions below, the name on +the left is the standard_name in the dimensions field of the caller while the name(s) on the right +is (are) the standard name(s) of the callee (in the form used in the subroutine call). + +.. code-block:: fortran + [dim_name]_dimension ==> 1:[dim_name]_loop_extent + [dim_name]_loop_extent ==> 1:[dim_name]_loop_extent + [dim_name]_begin:[dim_name]_end ==> 1:[dim_name]_loop_extent + [dim_name]_begin:[dim_name]_end ==> 1:[dim_name]_dimension + +Also note that horizontal_dimension should be used in ``xxx_[timestep_]init`` and ``xxx_[timestep_]final`` routines, +but not in xxx_run routines. Currently, the only dimension which supports all +six dimension types is horizontal_dimension. -It is important to understand the difference between these metadata dimension names. +**It is important to understand the difference between ``horizontal_dimension`` vs. ``horizontal_loop_extent``.** * ``horizontal_dimension`` refers to all (horizontal) grid columns that an MPI process owns/is responsible for, and that are passed to the physics in the *init*, *timestep_init*, *timestep_finalize*, and *finalize* phases. diff --git a/CCPPtechnical/source/HostSideCoding.rst b/CCPPtechnical/source/HostSideCoding.rst index 2331360..eca470d 100644 --- a/CCPPtechnical/source/HostSideCoding.rst +++ b/CCPPtechnical/source/HostSideCoding.rst @@ -187,7 +187,7 @@ and :ref:`Listing 6.2 ` for examples of host model metadat ``horizontal_dimension`` vs. ``horizontal_loop_extent`` ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, -Please refer to section :numref:`Section %s ` for a description of the differences between ``horizontal_dimension`` and ``horizontal_loop_extent``. The host model must define both variables to represent the horizontal dimensions in use by the physics in the metadata. +Please refer to section :numref:`Section %s ` for a description of the differences between ``horizontal_dimension`` and ``horizontal_loop_extent``. The host model must define both variables to represent the horizontal dimensions in use by the physics in the metadata. For the examples in listing :ref:`Listing 6.2 `, the host model stores all horizontal grid columns of each variable in one contiguous block, and the variables ``horizontal_dimension`` and ``horizontal_loop_extent`` are identical. Alternatively, a host model could store (non-contiguous) blocks of data in an array of DDTs with a length of the total number of blocks, as shown in listing :ref:`Listing 6.3 `. :numref:`Figure %s ` depicts the differences in variable allocation for these two cases. From ac52226e79ae1bd83c56c054e1d373968b4cf39d Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Wed, 11 Mar 2026 22:09:19 -0600 Subject: [PATCH 2/3] Better formatting --- CCPPtechnical/source/CompliantPhysicsParams.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CCPPtechnical/source/CompliantPhysicsParams.rst b/CCPPtechnical/source/CompliantPhysicsParams.rst index 1d6a984..b8d7560 100644 --- a/CCPPtechnical/source/CompliantPhysicsParams.rst +++ b/CCPPtechnical/source/CompliantPhysicsParams.rst @@ -382,7 +382,7 @@ The dimensions attribute in metadata should indicate both the dimensionality of The standard names used for dimensions may come in sets of six related standard names for each dimension: -.. code-block:: fortran +:: [dim_name]_dimension -- The full dimension size [dim_name]_loop_extent -- Size of dim for current call @@ -397,7 +397,8 @@ properly call suite parts and individual schemes. In the substitutions below, th the left is the standard_name in the dimensions field of the caller while the name(s) on the right is (are) the standard name(s) of the callee (in the form used in the subroutine call). -.. code-block:: fortran +:: + [dim_name]_dimension ==> 1:[dim_name]_loop_extent [dim_name]_loop_extent ==> 1:[dim_name]_loop_extent [dim_name]_begin:[dim_name]_end ==> 1:[dim_name]_loop_extent From 3890f0f09fc668009e9cad7aee7b4ec560c7ebd8 Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Tue, 17 Mar 2026 08:19:36 -0600 Subject: [PATCH 3/3] Attempt to re-word new section more clearly --- .../source/CompliantPhysicsParams.rst | 36 +++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/CCPPtechnical/source/CompliantPhysicsParams.rst b/CCPPtechnical/source/CompliantPhysicsParams.rst index b8d7560..d551624 100644 --- a/CCPPtechnical/source/CompliantPhysicsParams.rst +++ b/CCPPtechnical/source/CompliantPhysicsParams.rst @@ -370,7 +370,7 @@ After the ``ccpp-arg-table``, there should be a metadata entry for every input a .. _SchemeDimensionOptions: Horizontal, vertical, and other dimensions -------------------------------------------------------- +------------------------------------------ The dimensions attribute in metadata should indicate both the dimensionality of the data, as well as the breakdown of data among parallel processes. It should be empty parentheses for scalars, or indicate the start and end of each dimension of an array with an appropriate standard name as listed in the `ESM Standard Names documentation `__. ``ccpp_constant_one`` is the assumed start for any dimension which only has a single value. Some examples are listed here: .. code-block:: fortran @@ -392,31 +392,31 @@ The standard names used for dimensions may come in sets of six related standard [dim_name]_selection - Array of selected indices for dimension -Note that the cap generator may substitute among standard names in this category in order to -properly call suite parts and individual schemes. In the substitutions below, the name on -the left is the standard_name in the dimensions field of the caller while the name(s) on the right -is (are) the standard name(s) of the callee (in the form used in the subroutine call). +Dimension differences in different CCPP phases +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +The CCPP cap generator will use different standard names for the CCPP *_run* `:term:`phases ` vs other phases. +This is because the *_run* phase supports OpenMP parallel threading, so dimension variables in the CCPP *_run* phase for a given scheme +must refer to the ``loop_extent`` rather than the ``dimension`` for a variable's dimensional extent. As an example, the below dimensions +on the left in the *init*, *timestep_init*, *timestep_finalize*, and *finalize* phases (as well as the host model) will be substituted +with the dimensions on the right in the *_run* phase: - [dim_name]_dimension ==> 1:[dim_name]_loop_extent - [dim_name]_loop_extent ==> 1:[dim_name]_loop_extent - [dim_name]_begin:[dim_name]_end ==> 1:[dim_name]_loop_extent - [dim_name]_begin:[dim_name]_end ==> 1:[dim_name]_dimension +:: -Also note that horizontal_dimension should be used in ``xxx_[timestep_]init`` and ``xxx_[timestep_]final`` routines, -but not in xxx_run routines. Currently, the only dimension which supports all -six dimension types is horizontal_dimension. + [dim_name]_dimension ==> ccpp_constant_one:[dim_name]_loop_extent + [dim_name]_loop_extent ==> ccpp_constant_one:[dim_name]_loop_extent + [dim_name]_begin:[dim_name]_end ==> ccpp_constant_one:[dim_name]_loop_extent + [dim_name]_begin:[dim_name]_end ==> ccpp_constant_one:[dim_name]_dimension -**It is important to understand the difference between ``horizontal_dimension`` vs. ``horizontal_loop_extent``.** +To use the horizontal dimension as a specific example: * ``horizontal_dimension`` refers to all (horizontal) grid columns that an MPI process owns/is responsible for, and that are passed to the physics in the *init*, *timestep_init*, *timestep_finalize*, and *finalize* phases. -* ``horizontal_loop_extent`` or, equivalent, ``ccpp_constant_one:horizontal_loop_extent`` stands for a subset of grid columns that are passed to the physics during the time integration, i.e. in the *run* phase. - -* Note that ``horizontal_loop_extent`` is identical to ``horizontal_dimension`` for host models that pass all columns to the physics during the time integration. +* ``horizontal_loop_extent``, or equivalently ``ccpp_constant_one:horizontal_loop_extent`` stands for a subset of grid columns that are passed to the physics during the time integration, i.e. in the *run* phase. -Since physics developers cannot know whether a host model is passing all columns to the physics during the time integration or just a subset of it, the following rules apply to all schemes: +Note that ``horizontal_loop_extent`` is identical to ``horizontal_dimension`` for host models that pass all columns to the physics during the time integration. +Since physics developers cannot know whether a host model is passing all columns to the physics during the time integration or just a subset of it, +the following rules apply to all schemes: * Variables that depend on the horizontal decomposition must use