Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation updates for UGWP Version 0 #217

Merged
merged 3 commits into from
Aug 27, 2019
Merged

Documentation updates for UGWP Version 0 #217

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8d54a4c
doc/CCPPtechnical/source/ConstructingSuite.rst: update name of scheme…
climbfuji Aug 22, 2019
f0a5199
Merge branch 'gmtb/develop' of https://github.com/NCAR/ccpp-framework…
climbfuji Aug 22, 2019
27f5add
src/ccpp_fields_idx.h: increase default size for CCPP dynamic variabl…
climbfuji Aug 23, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 35 additions & 35 deletions doc/CCPPtechnical/source/ConstructingSuite.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,14 @@ Constructing Suites
Suite Definition File
==============================

The :term:`SDF` is a file in XML format used to specify the name of the suite, the physics schemes to run, groups of physics that run together, the order in which to run the physics, and whether subcycling will be used to run any of the parameterizations with shorter timesteps. The :term:`SDF` files are located in ``ccpp/suites/suite_*.xml``.
The :term:`SDF` is a file in XML format used to specify the name of the suite, the physics schemes to run, groups of physics that run together, the order in which to run the physics, and whether subcycling will be used to run any of the parameterizations with shorter timesteps. The :term:`SDF` files are located in ``ccpp/suites/suite_*.xml``.

In addition to the primary parameterization categories (such as radiation, boundary layer, deep convection, resolved moist physics, etc.), the :term:`SDF` can have an arbitrary number of interstitial schemes in between the parameterizations to preprocess or postprocess data. In many models, this interstitial code is not obvious to the model user but, with the :term:`SDF`, both the primary parameterizations and the interstitial schemes are listed explicitly.

The name of the suite is listed at the top of the :term:`SDF` and must be consistent with the name of the :term:`SDF`: file ``suite_ABC.xml`` contains ``suite name=’ABC’``, as in the example below. The suite name is followed by the ``time_vary`` step, which is run only once when the model is first initialized.

.. code-block:: xml

<suite name="ABC" lib="ccppphys" ver="3.0.0">
<!-- <init></init> -->
<group name="time_vary">
Expand All @@ -34,12 +34,12 @@ Groups
The concept of grouping physics in the :term:`SDF` (reflected in the ``<group name="XYZ">`` elements) enables “groups” of parameterizations to be called with other computation (such as related to the dycore, I/O, etc.) in between. One can edit the groups to suit the needs of the host application. For example, if a subset of physics schemes needs to be more tightly connected with the dynamics and called more frequently, one could create a group consisting of that subset and place a ``ccpp_run`` call in the appropriate place in the host application. The remainder of the parameterization groups could be called using ``ccpp_run`` calls in a different part of the host application code.

-----------------
Subcycling
Subcycling
-----------------
The :term:`SDF` allows subcycling of schemes, or calling a subset of schemes at a smaller time step than others. The ``<subcycle loop = n>`` element in the :term:`SDF` controls this function. All schemes within such an element are called n times during one ccpp_run call. An example of this is found in the ``FV3_GFS_v15.xml`` :term:`SDF`, where the surface schemes are executed twice for each timestep (implementing a predictor/corrector paradigm):

.. code-block:: xml

<!-- Surface iteration loop -->
<subcycle loop="2">
<scheme>sfc_diff</scheme>
Expand All @@ -58,7 +58,7 @@ Note that currently no time step information is included in the :term:`SDF` and
Order of Schemes
----------------------

Schemes may be interdependent and the order in which the schemes are run may make a difference in the model output. For the static build, reading the :term:`SDF`\(s) and defining the order of schemes for each suite happens at compile time. For the dynamic build, no :term:`SDF` is used at compile time (:numref:`Figure %s <ccpp_sdf_dynamic_static>`). Instead, at runtime the :term:`SDF` is read and the order of schemes is determined.
Schemes may be interdependent and the order in which the schemes are run may make a difference in the model output. For the static build, reading the :term:`SDF`\(s) and defining the order of schemes for each suite happens at compile time. For the dynamic build, no :term:`SDF` is used at compile time (:numref:`Figure %s <ccpp_sdf_dynamic_static>`). Instead, at runtime the :term:`SDF` is read and the order of schemes is determined.

Some schemes require additional interstitial code that must be run before or after the scheme and cannot be part of the scheme itself. This can be due to dependencies on other schemes and/or the order of the schemes as determined in the :term:`SDF`.

Expand All @@ -67,7 +67,7 @@ Some schemes require additional interstitial code that must be run before or aft
.. figure:: _static/ccpp_sdf_dynamic_static.png
:scale: 30 %
:alt: map to buried treasure
:align: center
:align: center

*Schematic of the use of the SDF in dynamic and static builds. Note that, for the static build, more than one SDF can be supplied at compile time, but only one can be used at runtime*.

Expand All @@ -87,7 +87,7 @@ Simplest Case: Single Group and no Subcycling
Consider the simplest case, in which all physics schemes are to be called together in a single group with no subcycling (i.e. ``subcycle loop=”1”``). The subcycle loop must be set in each group. The :term:`SDF` ``suite_Suite_A.xml`` could contain the following:

.. code-block:: console

<?xml version="1.0" encoding="UTF-8"?>
<suite name="Suite_A" lib="ccppphys" ver="3.0.0">
...
Expand All @@ -107,8 +107,8 @@ Consider the simplest case, in which all physics schemes are to be called togeth
</subcycle>
</group>
</suite>


Note the syntax of the :term:`SDF` file. The root (the first element to appear in the xml file) is the ``suite`` with the ``name`` of the suite given as an attribute. In this example, the suite name is ``Suite_A``. Within each suite are groups, which specify a physics group to call (i.e. ``physics, fast_physics, time_vary, radiation, stochastics``). Each group has an option to subcycle. The value given for loop determines the number of times all of the schemes within the ``subcycle`` element are called. Finally, the ``scheme`` elements are children of the ``subcycle`` elements and are listed in the order they will be executed. In this example, ``scheme_1_pre`` and ``scheme_1_post`` are scheme-specific preprocessing and postprocessing interstitial schemes, respectively. The suite-level preprocessing and postprocessing interstitial ``schemes scheme_2_generic_pre`` and ``scheme_2_generic_post`` are also called in this example. ``Suite_A_interstitial_2`` is a scheme for ``suite_A`` and connects various schemes within this suite.

-------------------------------
Expand All @@ -118,7 +118,7 @@ Case with Multiple Groups
Some models require that the physics be called in groups, with non-physics computations in-between the groups.

.. code-block:: xml

<?xml version="1.0" encoding="UTF-8"?>
<suite name="Suite_B" lib="ccppphys" ver="3.0.0">
<group name="g1">
Expand All @@ -137,14 +137,14 @@ Some models require that the physics be called in groups, with non-physics compu
</group>
</suite>

----------------------------
----------------------------
Case with Subcycling
----------------------------

Consider the case where a model requires that some subset of physics be called on a smaller time step than the rest of the physics, e.g. for computational stability. In this case, one would make use of the subcycle element as follows:
Consider the case where a model requires that some subset of physics be called on a smaller time step than the rest of the physics, e.g. for computational stability. In this case, one would make use of the subcycle element as follows:

.. code-block:: xml

<?xml version="1.0" encoding="UTF-8"?>
<suite name="Suite_C" lib="ccppphys" ver="3.0.0">
<group name="g1">
Expand All @@ -160,16 +160,16 @@ Consider the case where a model requires that some subset of physics be called o
</group>
</suite>

-------------------------------
-------------------------------
Operational GFS v15 Suite
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am still not sure why the GFS suite is documented in the CCPP Framework which is supposed to be infrastructure for all models. Are all suites going to be documented here?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We briefly touched on this issue of having documentation that changes more frequently under ccpp-framework. The problem I think is that the "big document" aka techdoc combines technical aspects of the ccpp-framework and scientific aspects such as the suites.

We agreed that it would be better to move this contents into a ccpp-doc (ccpp-documentation) repository on the NCAR GitHub to avoid changing ccpp-framework everytime a small change is made to the documentation. Since the techdoc is NOAA-NCAR/DTC centric, this would be something NCAR/CGD NCAR/MMM don't really have to worry about. We also agreed that your feedback is valuable and that it still would be good to invite you for looking at the PRs. What do you think? Details could be fleshed out next Thursday?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I agree on all these fronts. The CCPP Framework documentation should describe some simple suite or suites that demonstrate the features of suites.
The ccpp-doc would be a more complete technical document for GMTB / NOAA.
Ideally, we could configure the CCPP Framework technical document to make it easy to incorporate into model-specific docs (e.g., UFS, CESM). I would also like to see some way to have a technical document for a suite that is part of the suite when we finally stand up a CCPP Physics repository.
I am happy to review other documents (when I'm not too busy :).

-------------------------------

Here is the :term:`SDF` for the physics suite equivalent to the operational GFS v15 in the :term:`UFS` Atmosphere, which employs various groups and subcycling:

.. code-block:: xml

<?xml version="1.0" encoding="UTF-8"?>

<suite name="FV3_GFS_v15" lib="ccppphys" ver="3.0.0">
<!-- <init></init> -->
<group name="fast_physics">
Expand Down Expand Up @@ -232,7 +232,7 @@ Here is the :term:`SDF` for the physics suite equivalent to the operational GFS
<scheme>GFS_PBL_generic_pre</scheme>
<scheme>hedmf</scheme>
<scheme>GFS_PBL_generic_post</scheme>
<scheme>gwdps_pre</scheme>
<scheme>GFS_GWD_generic_pre</scheme>
<scheme>gwdps</scheme>
<scheme>gwdps_post</scheme>
<scheme>rayleigh_damp</scheme>
Expand Down Expand Up @@ -266,19 +266,19 @@ Here is the :term:`SDF` for the physics suite equivalent to the operational GFS
</group>
<!-- <finalize></finalize> -->
</suite>

The suite name is ``FV3_GFS_v15``. Five groups (``fast_physics, time_vary, radiation, physics, and stochastics``) are used, because the physics needs to be called in different parts of the host model. The detailed explanation of each primary physics scheme can be found in scientific documentation. A short explanation of each scheme is below.

* ``fv_sat_adj``: Saturation adjustment (for the UFS Atmosphere only)
* ``fv_sat_adj``: Saturation adjustment (for the UFS Atmosphere only)
* ``GFS_time_vary_pre``: GFS physics suite time setup
* ``GFS_rrtmg_setup``: Rapid Radiative Transfer Model for Global Circulation Models (RRTMG) setup
* ``GFS_rad_time_vary``: GFS radiation time setup
* ``GFS_phys_time_vary``: GFS physics suite time setup
* ``stochastic_physics``: Stochastic physics
* ``stochastic_physics_sfc``: Surface part of stochastic physics
* ``GFS_suite_interstitial_rad_reset``: GFS suite interstitial radiation reset
* ``GFS_rrtmg_pre``: Preprocessor for the GFS radiation schemes
* ``rrtmg_sw_pre``: Preprocessor for the RRTMG shortwave radiation
* ``GFS_rrtmg_pre``: Preprocessor for the GFS radiation schemes
* ``rrtmg_sw_pre``: Preprocessor for the RRTMG shortwave radiation
* ``rrtmg_sw``: RRTMG for shortwave radiation
* ``rrtmg_sw_post``: Postprocessor for the RRTMG shortwave radiation
* ``rrtmg_lw_pre``: Preprocessor for the RRTMG longwave radiation
Expand All @@ -295,8 +295,8 @@ The suite name is ``FV3_GFS_v15``. Five groups (``fast_physics, time_vary, radia
* ``GFS_suite_interstitial_2``: GFS suite interstitial 2
* ``sfc_diff``: Calculation of the exchange coefficients in the GFS surface layer
* ``GFS_surface_loop_control_part1``: GFS surface loop control part 1
* ``sfc_nst_pre``: Preprocessor for the near-surface sea temperature
* ``sfc_nst``: GFS Near-surface sea temperature
* ``sfc_nst_pre``: Preprocessor for the near-surface sea temperature
* ``sfc_nst``: GFS Near-surface sea temperature
* ``sfc_nst_post``: Postprocessor for the near-surface temperature
* ``lsm_noah``: Noah land surface scheme driver
* ``sfc_sice``: Simple sea ice scheme
Expand All @@ -307,30 +307,30 @@ The suite name is ``FV3_GFS_v15``. Five groups (``fast_physics, time_vary, radia
* ``sfc_diag_post``: Postprocessor for the land surface diagnostic calculation
* ``GFS_surface_generic_post``: Postprocessor for the GFS surface process
* ``GFS_PBL_generic_pre``: Preprocessor for all Planetary Boundary Layer (PBL) schemes (except MYNN)
* ``hedmf``: Hybrid eddy-diffusivity mass-flux PBL
* ``GFS_PBL_generic_post``: Postprocessor for all PBL schemes (except MYNN)
* ``gwdps_pre``: Preprocessor for the orographic gravity wave drag
* ``gwdps``: Orographic gravity wave drag
* ``Gwdps_post``: Postprocessor for the orographic gravity wave drag
* ``rayleigh_damp``: Rayleigh damping
* ``hedmf``: Hybrid eddy-diffusivity mass-flux PBL
* ``GFS_PBL_generic_post``: Postprocessor for all PBL schemes (except MYNN)
* ``GFS_GWD_generic_pre``: Preprocessor for the orographic gravity wave drag
* ``gwdps``: Orographic gravity wave drag
* ``Gwdps_post``: Postprocessor for the orographic gravity wave drag
* ``rayleigh_damp``: Rayleigh damping
* ``GFS_suite_stateout_update``: GFS suite stateout update
* ``ozphys``: Ozone photochemistry
* ``GFS_DCNV_generic_pre``: Preprocessor for the GFS deep convective schemes
* ``get_phi_fv3``: Hydrostatic adjustment to the height in a way consistent with FV3 discretization
* ``GFS_suite_interstitial_3``: GFS suite interstitial 3
* ``samfdeepcnv``: Simplified Arakawa Schubert (SAS) Mass Flux deep convection
* ``samfdeepcnv``: Simplified Arakawa Schubert (SAS) Mass Flux deep convection
* ``GFS_DCNV_generic_post``: Postprocessor for all deep convective schemes
* ``gwdc_pre``:Preprocessor for the convective gravity wave drag
* ``gwdc``: Convective gravity wave drag
* ``gwdc_pre``:Preprocessor for the convective gravity wave drag
* ``gwdc``: Convective gravity wave drag
* ``gwdc_post``: Postprocessor for the convective gravity wave drag
* ``GFS_SCNV_generic_pre``: Preprocessor for the GFS shallow convective schemes
* ``samfshalcnv``: SAS mass flux shallow convection
* ``samfshalcnv``: SAS mass flux shallow convection
* ``samfshalcnv_post``: Postprocessor for the SAS Mass Flux shallow convection
* ``GFS_SCNV_generic_post``: Postprocessor for the GFS shallow convective scheme
* ``GFS_suite_interstitial_4``: GFS suite interstitial 4
* ``cnvc90``: Convective cloud cover
* ``cnvc90``: Convective cloud cover
* ``GFS_MP_generic_pre``: Preprocessor for all GFS microphysics
* ``gfdl_cloud_microphys``: GFDL cloud microphysics
* ``GFS_MP_generic_post``: Postprocessor for GFS microphysics
* ``Maximum_hourly_diagnostics``: Computation of the maximum of the selected diagnostics
* ``GFS_stochastics``: GFS stochastics scheme: Stochastic Kinetic Energy Backscatter (SKEB), Perturbed boundary layer specific humidity (SHUM), or Stochastically Perturbed Physics Tendencies (SPPT)
* ``GFS_stochastics``: GFS stochastics scheme: Stochastic Kinetic Energy Backscatter (SKEB), Perturbed boundary layer specific humidity (SHUM), or Stochastically Perturbed Physics Tendencies (SPPT)
2 changes: 1 addition & 1 deletion src/ccpp_fields_idx.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ extern "C"
#endif


#define CCPP_FIELD_IDX_MAX 1000
#define CCPP_FIELD_IDX_MAX 1500
#define CCPP_FIELD_IDX_GROW 2


Expand Down