Merge pull request #589 from hertneky/548_doc_updates

Add documenation for DEPHY converter and NSST behavior

Author: hertneky

scm/doc/TechGuide/acknow.rst

@@ -7,6 +7,6 @@ acknowledge the Developmental Testbed Center team.
 For referencing this document please use:
 
       Firl, G., D. Swales, L. Carson, L. Bernardet, D. Heinzeller, M. Harrold, T. Hertneky, and
-      M. Kavulich, 2024. Common Community Physics Package Single Column Model v7.0.0 User and
-      Technical Guide. Available at https://ccpp-scm.readthedocs.io/en/v7.0.0/.
+      M. Kavulich, 2024. Common Community Physics Package Single Column Model v7.0.1 User and
+      Technical Guide. Available at https://ccpp-scm.readthedocs.io/en/v7.0.1/.
 

scm/doc/TechGuide/chap_cases.rst

@@ -129,6 +129,35 @@ format requirements can be found at `DEPHY <https://github.com/GdR-DEPHY/DEPHY-S
     :name: lst_case_input_netcdf_header_dephy
     :caption: example NetCDF file (DEPHY format) header for case initialization and forcing data
 
+As of the CCPP v7.0.0 release, all SCM case files are expected to use the DEPHY format.
+To assist with this transition, a conversion script is provided in the repository to reformat
+legacy SCM case files into the new DEPHY-compliant format.
+
+The conversion script is located at:
+
+.. code:: bash
+
+   ccpp-scm/scm/etc/scripts/dephy_converter.py
+
+To convert a case, run the script with the -n option followed by the name of the case
+(excluding the .nc extension):
+
+.. code:: bash
+
+   python dephy_converter.py -n name_of_case
+
+This script performs the following actions:
+- Reads the legacy case file from ccpp-scm/scm/data/processed_case_data/name_of_case.nc
+- Reads the corresponding configuration namelist from ccpp-scm/scm/etc/case_config/name_of_case.nml
+- Outputs a new DEPHY-formatted file named name_of_case_SCM_driver.nc to the same data directory
+- Updates the configuration namelist accordingly
+
+.. Note::
+    Before running the script, back up both the original ``.nc`` file and its corresponding ``.nml``
+    configuration file. After conversion, you can test the new DEPHY-formatted case by running it
+    and comparing its output with the original. Although results may not be bit-for-bit identical,
+    they should be visually very similar when plotted.
+
 Included Cases
 --------------
 
@@ -182,6 +211,58 @@ In addition, cases can be generated from UFS initial conditions See
 files for other locations and dates, given appropriate UFS Atmosphere
 initial conditions and output.
 
+Maritime Cases with Active Surface Fluxes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When modeling cases over ocean surfaces without prescribed surface fluxes, instead
+of relying on physics to calculate them, GFS-based physics suites rely on the
+Near-Surface Sea Temperature (NSST) scheme.
+
+**Cold-Starting the NSST Scheme**
+
+To initialize NSST in a cold start configuration:
+
+1. Provide a sea surface temperature (SST) time series via the ``ts_forc`` time
+   series in the case data file.
+2. Set the following in the case data file:
+
+   - ``surface_forcing_temp = "ts"``
+   - ``surface_type = "ocean"``
+
+3. In the physics namelist, ensure the second digit of the nstf_name variable
+   is set to 1 (i.e., nstf_name = [*,1,*,*,*]).
+
+   - This value indicates NSST spin-up and is the default in physics namelists
+     distributed with the CCPP-SCM.
+
+Resulting behavior in CCPP-SCM:
+
+- The NSST scheme is initialized using the SST from ``ts_forc``.
+- The default ocean mixed layer depth ``xz`` is 20 meters.
+- The NSST reference temperature remains fixed at the initial SST value throughout
+  the simulation (in contrast to a 3D ocean model where it would ideally vary slowly).
+
+**Using UFS Output to Initialize NSST**
+
+When working with case data generated from UFS model output, NSST can be initialized
+directly from the history files. In this case:
+
+- Set the second digit of the ``nstf_name`` variable to 0 to bypass spin-up and use
+  supplied NSST state variables directly.
+
+**Default SST behavior in CCPP SCM**
+
+The SST is forced using the ``ts_forc`` time series in the case data file. This means:
+
+- The SST seen by the physics is linearly interpolated in time from the time series.
+  The SST is set during every timestep from that data.
+
+To instead allow the SST to evolve according to model physics:
+
+- Set the case configuration namelist variable ``do_sst_initialize_only = .true.``
+  This causes the SST to be initialized from the first value in ``ts_forc``, after
+  which the physics controls its evolution.
+
 How to set up new cases
 -----------------------
 

scm/doc/TechGuide/chap_intro.rst

@@ -35,6 +35,27 @@ through the CCPP infrastructure.
 Version Notes
 -------------
 
+The CCPP SCM v7.0.1 contains the following minor changes since v7.0.0.
+
+-  Enhanced UFS case generation tools: Reinstated functionality to support specifying
+   i, j grid indices (from the FV3 native grid) along with a tile number in
+   UFS_case_gen.py to generate single-column cases. Also added the ability to accept
+   a list of i, j indices for batch generation of multiple cases.
+
+-  Use of standardized missing values: Replaced hard coded missing values, -9999.0
+   and -9999, with the _FillValue or missing value attributes defined in the NetCDF
+   variables.
+
+-  Fix area logic in the SCM: Corrected assignment of the column area from the DEPHY
+   forcing file by removing the dependency on surface forcing LSM. Also allow the
+   column_area in the configuration namelist to override the DEPHY assignment.
+
+-  Enhanced documentation for 1) using the DEPHY converter script, which converts
+   forcing files from the legacy format to the DEPHY v1.0 format, and 2) including
+   expected behavior of the Near-Surface Sea Temperature (NSST) scheme within the SCM.
+
+-  Added support for NOAA’s Ursa platform using spack-stack v1.9.1.
+
 The CCPP SCM v7.0.0 contains the following major and minor changes since v6.0.
 
 Major

scm/doc/TechGuide/chap_quick.rst

@@ -25,7 +25,7 @@ Clone the source using
 
 .. code:: bash
 
-   git clone --recursive -b v7.0.0 https://github.com/NCAR/ccpp-scm
+   git clone --recursive -b v7.0.1 https://github.com/NCAR/ccpp-scm
 
 The ``--recursive`` option is required to retrieve the ccpp-physics and ccpp-framework code,
 which are stored in separate repositories and linked to the SCM repository as submodules.
@@ -452,7 +452,7 @@ execute the following scripts:
 If the download step fails, make sure that your system’s firewall does
 not block access to GitHub. If it does, download the files ``comparison_data.tar.gz``,
 ``physics_input_data.tar.gz``, ``processed_case_input.tar.gz``, and ``raw_case_input.tar.gz``
-from the `SCM release page <https://github.com/NCAR/ccpp-scm/releases/tag/v7.0.0>`__ using your browser and manually extract its
+from the `SCM release page <https://github.com/NCAR/ccpp-scm/releases/tag/v7.0.1>`__ using your browser and manually extract its
 contents in the directory ``scm/data``. Similarly, do the same for
 ``thompson_tables.tar.gz`` and ``MG_INCCN_data.tar.gz`` and extract
 to ``scm/data/physics_input_data/``.
@@ -769,7 +769,7 @@ internet search.
 Building the Docker image
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The Dockerfile builds CCPP SCM v7.0.0 from source using the GNU
+The Dockerfile builds CCPP SCM v7.0.1 from source using the GNU
 compiler.
 
 The CCPP SCM has a number of system requirements and necessary libraries
@@ -833,7 +833,7 @@ following from the terminal where Docker is run:
 
 .. code:: bash
 
-   docker pull dtcenter/ccpp-scm:v7.0.0
+   docker pull dtcenter/ccpp-scm:v7.0.1
 
 To verify that it exists afterward, run
 
@@ -921,7 +921,7 @@ Running the Docker image
    .. note::
      If you are using a prebuilt image from Dockerhub, substitute
      the name of the image that was pulled from Dockerhub in the commands
-     above; i.e. instead of ``ccpp-scm`` above, one would have ``dtcenter/ccpp-scm:v7.0.0``.
+     above; i.e. instead of ``ccpp-scm`` above, one would have ``dtcenter/ccpp-scm:v7.0.1``.
 
 #. To use the SCM interactively, run non-default configurations, create
    plots, or even develop code, issue the following command:

scm/doc/TechGuide/conf.py

@@ -27,7 +27,7 @@
 # The short X.Y version
 version = '7.0'
 # The full version, including alpha/beta/rc tags
-release = '7.0.0'
+release = '7.0.1'
 
 numfig = True
 

scm/doc/TechGuide/index.rst

@@ -1,4 +1,4 @@
-CCPP Single Column Model (SCM) User and Technical Guide v7.0.0
+CCPP Single Column Model (SCM) User and Technical Guide v7.0.1
 ============================
 
 .. toctree::