It is expected that many users still have the need for putting d*3dt output into history files, and it is suggested that instructions on the method for doing this be available online.

The documentation has fallen out-of-date in some places, this issue will track the sections and topics that need updating and/or corrections:

• Use of optional variables in physics
• Needs documentation of standard names
  • Introduce the concept and say that each hash of ccpp-physics has a compliant version of the standard names dictionary (information kept in top-level README.md of NCAR ccpp-physics main)
• Compilation with stub physics capability (https://github.com/NCAR/ccpp-framework/pull/436/files)
• New debugging feature in auto-generated caps (new/changed arguments to ccpp_prebuild.py)
• ccpp_error_flag -> ccpp_error_code update
• --debug flag for ccpp_prebuild.py renamed to --verbose (NCAR/ccpp-framework#404)
• Chapter 2: when describing the phases, explain how they relate to blocking of data
• CCPP Overview: Change from Earth System Prediction Capability to Interagency Council for Advancing Meteorological Services (ICAMS; previously Earth System Prediction Capability)
• CCPP Overview: Update the table of supported suites/schemes to match CCPP v6 public release
• Chapter on host side coding is seriously out of date, it still refers to the dynamic CCPP implementation, doesn't know about the new timestep_init and timestep_finalize phases, ...
• Replace CCPP-Framework and CCPP-Physics with CCPP Framework and CCPP Physics
• Review the document to standardize the use of regular font, italics, and this font
• Replace examples based on the unsupported GFSv15 suite with GFSv16.
• Update "Code Management" section
• Update links to the CCPP SciDoc and SCM User's Guide to v6, once it is published
• Remove references to MRW, update description for v17_p8

Please edit this issue to add topics as you see fit.

The CCPP TechDoc Overview needs to be updated to correctly reflect the suites that will be part of the CCPP v5.0 release.

• Reference to the _no_nsst suites should be removed.
• Suite RRFS_v1beta may change per the SRW App leads with one or more of the following
  -- Suite name change to RRFS_v1alpha
  -- Sfc layer: change from MYNN to GFS
  --LSM: change from NoahMP to Noah

In addition, documentation should list the target resolution for teh suites (RRFS - CAM scales, others MRW-S2S scales).

Need to hear back from SRW App leads before proceeding.

Mandatory items

• Update all references to release number
• Update supported suites
• Update wording around associated UFS Applications
• Note that MPI (specifically, mpi_f08) is now required (see NCAR/ccpp-framework#523)
• Note that pointer variables are no longer allowed (see NCAR/ccpp-framework#541)
• Note that all optional arguments should be at the end of the argument list (see NCAR/ccpp-framework#544)
• Updates to optional arguments (ufs-community/ccpp-physics#189)

Wanted items

• Items covered in #70

Nice-to-have items

Anyone should fill in additional items as they see fit

This issue will track the sections and topics that need updating when time and resources allow:

• Review the document to standardize the use of regular font, italics, and this font
• Expand glossary, standardize how glossary items are linked
  • Only link a term once per chapter, at that term's first mention in the chapter
  • If a term already appears in another linked/defined term (e.g. "CCPP" as a part of "CCPP Physics", do not link in that chapter
    • Exceptions can be made for sections that are likely to be linked directly, such as Troubleshooting in CCPPPreBuild.rst
  • If a term appears in the glossary but there is a chapter or section describing it in detail, provide a brief description in the glossary with a link to the relevant chapter/section for more information
• Section 6.3 in the technical documentation describes CCPP Variables in the SCM and UFS Atmosphere Host Models (https://ccpp-techdoc.readthedocs.io/en/latest/HostSideCoding.html). There was a set of PRs for the ufs-weather-model that modified where these data structures are stored and how they are named (see ufs-community/ufs-weather-model#1130 for the top-level ufs-weather-model PR). This requires updates to section 6.3.
• Update README file to remove "GMTB"
• Consider adding information about tests available
• Chapter 7, CCPP code management. Should we say something about UFS Fork?
• Remove mentions of forum, add mentions of GitHub discussions
• Remove unused acronyms from the list of acronyms, such as NEMSfv3gfs

Please edit this issue to add topics as you see fit.

Description

Update documentation to reflect removal of support for optional arguments from CCPP framework/metadata.

Solution

See above.

Alternatives (optional)

None.

Please edit/add as needed

• Information on the various (and preferred) ways to add connect a scheme to CCPP, including pros/cons of using a wrapper versus pre- and post- interstitials
• Best practices and guidelines wrt ways to allocate memory so schemes can be stateless (recommended but not required) (@dustinswales pls add as needed)
• • Suggest not using the term stateless because audience may not know what it is
• • Schemes should not use dynamic memory allocation on the HEAP
• • Schemes should not contain data that clashes when multiple non-interacting instances of the scheme are being used in one executable"
• • No allocations in module memory
• More detailed code contribution instructions
• Add note about problem fixed in ufs-community/ccpp-physics#106
• "Single Column Model" --> "Single-Column Model"

A new documentation wiki has been stood up for the UFS weather model at https://github.com/ufs-community/ufs-weather-model/wiki. This duplicates part of the content of Chapters 7 and 9 of the CCPP Tech Doc, which should be updated to refer to this new source of information.

The CCPP team would like to rename the "master" branch to "main" to be sensitive to anti-racism practices.
Here is an article about this topic: https://www.zdnet.com/article/github-to-replace-master-with-alternative-term-to-avoid-slavery-references/.
Here is the GitHub page with steps for the renaming: https://github.com/github/renaming.

We need to check that we use a consistent description of CCPP metadata hooks in Fortran code between the CCPP technical documentation, the scientific documentation (and ideally also in the Fortran code, although the latter doesn't matter because there are no errors).

Previously, we used

!> \section arg_table_foo_type Argument Table
!! \htmlinclude foo_type.html
!!
   type foo_type

but the CCPP framework doesn't care about Argument Table (and there is really no need or reason for it). The following works and should be used consistently across the board, most importantly in the CCPP v6 release of the scidoc and techdoc (because it will be in the CCPP paper this way):

!> \section arg_table_foo_type
!! \htmlinclude foo_type.html
!!
   type foo_type

It doesn't matter whether the Fortran code has the trailing Argument Table or not, it will simply be ignored. I just tested this again, and it works. This applies to both ccpp_prebuild.py and capgen.py, so we are good here.

The capability of the CCPP Framework to auto-convert units of variables is not currently documented.

We learned yesterday that the UFS MRW App v2 public release will not take place in June 2022 as originally planned. This makes the draft Scientific Documentation for CCPP v6.0.0 release incorrect, since it lists the capability to use this upcoming CCPP release with MRW v2. The DTC team, and @mkavulich in particular, are assessing how to fix this.

As described in detail in ufs-community/ufs-weather-model#135, the call to ccpp_prebuild.py has been moved from the top-level ufs-weather-model repository to subdirectory FV3.

We initially wanted to push back on this change and revert it. However, given that we "taught" the new way to run ccpp_prebuild.py manually at the UFS MRW tutorial, we should instead change the documentation and keep it as is.

A few items did not make it in in time for the previous release, and there are some new documentation items that need updating:

• Details about available unit conversions per (Some available here, but needs updating: https://github.com/NCAR/ccpp-framework/blob/main/scripts/conversion_tools/unit_conversion.py)
• More detailed information about contributing code
• Add more details to scientific doc rules, especially on how to make block comments and examples of how they appear in the final documentation
  • Example: samfshalcnv.f --> https://dtcenter.ucar.edu/GMTB/UFS_SRW_App_v2.2.0/sci_doc/group___s_a_m_f__shal_ga7c9c5f5be5cf7b4f28738a89a9103939.html
• Add details on the required python environment for the CCPP framework

This issue will track the updates needed for the UFS SRW v2.1 minor release update

• Update links to Scientific Documentation
• Introduction: Update/remove wording that refers to SCM, CCPP releases. In particular, for the SRW v2.1 release, restrict the information to the suites/schemes supported for SRW.

Please edit this issue to add topics as you see fit.

Section 6.3 in the technical documentation describes CCPP Variables in the SCM and UFS Atmosphere Host Models (https://ccpp-techdoc.readthedocs.io/en/latest/HostSideCoding.html).

There is a set of PRs for the ufs-weather-model that modifies where these data structures are stored and how they are named (see ufs-community/ufs-weather-model#1130 for the top-level ufs-weather-model PR). When these PR get merged, section 6.3 needs to be updated.