Update the docs

Author: xylar

docs/source/parameters.rst

@@ -12,8 +12,8 @@ be overridden by parameters set in a ``[[subsection]``.
    Note that some parameters will be overriden by defaults if you define them too high up in the inheritance hierarchy.
 
 See `this release's parameter defaults <https://github.com/E3SM-Project/zppy/blob/bfbba5f9c3794cd7e399e35f8153866b1c8f6910/zppy/defaults/default.ini>`_
-on GitHub for a complete list of parameters and their default values. 
-You can also view the most up-to-date, 
+on GitHub for a complete list of parameters and their default values.
+You can also view the most up-to-date,
 `unreleased parameter defaults <https://github.com/E3SM-Project/zppy/blob/main/zppy/templates/default.ini>`_.
 
 Deprecated parameters
@@ -61,6 +61,33 @@ For the ``e3sm_diags`` task:
 * If ``reference_data_path`` (the path to the reference data) is undefined, assume it is the ``diagnostics_base_path`` from Mache plus ``/observations/Atm/climatology/``. (So, it is important to change this for model-vs-model runs).
 
 
+For the ``mpas_analysis`` task:
+
+* ``reference_data_path`` and ``test_data_path`` are optional and are only used for model-vs-model comparisons.
+  If provided, ``zppy`` uses them to locate the MPAS-Analysis config files from a *previous* MPAS-Analysis run and passes those through to MPAS-Analysis as ``controlRunConfigFile`` (reference) and ``mainRunConfigFile`` (test).
+
+  .. note::
+     These parameter names are intentionally consistent with the terminology used by ``e3sm_diags`` for model-vs-model runs: in both cases, ``reference_data_path`` identifies the *reference simulation's zppy-generated outputs*.
+
+     The practical difference is what each downstream tool consumes:
+     ``e3sm_diags`` needs ``reference_data_path`` to be the specific directory containing the reference climatology files (typically under the reference run's ``post/.../clim`` tree), whereas ``mpas_analysis`` needs to find the reference MPAS-Analysis config file.
+     For MPAS-Analysis, ``zppy`` can resolve that config file when ``reference_data_path`` points to the prior run's zppy output directory (the one containing ``post/``), the ``post/`` directory itself, or directly to an ``mpas_analysis_*.cfg`` file.
+
+  ``reference_data_path`` is intended to point to the prior run's zppy output directory (the one containing ``post/``) but zppy will also find the MPAS-Analysis config file if ``reference_data_path`` points to the ``post/`` directory itself, the MPAS-Analysis directory (``analysis/mpas_analysis``), the ``cfg/`` directory, or directly to an ``mpas_analysis_*.cfg`` file.
+
+
+**MPAS-Analysis model-vs-model year ranges**
+
+MPAS-Analysis comparisons are configured by year ranges, similar to other ``zppy`` tasks.
+For model-vs-model comparisons, ``zppy`` supports separate year ranges for the test and reference runs:
+
+* ``ts_years``, ``climo_years``, ``enso_years`` define the test run year ranges.
+* ``ref_ts_years``, ``ref_climo_years``, ``ref_enso_years`` optionally override the reference run year ranges.
+
+If a ``ref_*_years`` parameter is not provided, it defaults to the corresponding test year ranges.
+If a ``ref_*_years`` parameter contains a single range and multiple test ranges are requested, the single reference range is used for each test range.
+
+
 For the ``ilamb`` task:
 
 * If ``ilamb_obs`` (the path to observation data for ``ilamb``) is undefined, assume it is the ``diagnostics_base_path`` from Mache plus ``/ilamb_data``.
@@ -76,7 +103,7 @@ There are many parameter-handling functions.
 
 In ``utils.py``:
 
-* ``get_value_from_parameter``: check if parameter is in the configuration dictionary. If not, if inference is turned on (the default), then just use the value of ``second_choice_parameter``. If inferenceis turned off, raise a ``ParameterNotProvidedError``. Use this function if the backup option 
+* ``get_value_from_parameter``: check if parameter is in the configuration dictionary. If not, if inference is turned on (the default), then just use the value of ``second_choice_parameter``. If inferenceis turned off, raise a ``ParameterNotProvidedError``. Use this function if the backup option
 * ``set_value_of_parameter_if_undefined``: check if parameter is in the configuration dictionary. If not, if inferenceis turned on (the default), then just set the parameter's value to the ``backup_option``. If inferenceis turned off, raise a ``ParameterNotProvidedError``.
 
 In ``e3sm_diags.py``:
@@ -85,6 +112,6 @@ In ``e3sm_diags.py``:
 * ``check_set_specific_parameter``: if any requested ``e3sm_diags`` sets require this parameter, make sure it is present. If not, raise a ``ParameterNotProvidedError``.
 * ``check_parameters_for_bash``: use ``check_set_specific_parameter`` to check the existence of parameters that aren't used until the bash script.
 * ``check_mvm_only_parameters_for_bash``: similar, but these are specifically parameters used for model-vs-model runs. Uses ``check_parameter_defined`` in addition to ``check_set_specific_parameter``.
-* ``check_and_define_parameters``: make sure all parameters are defined, using ``utils.py get_value_from_parameter``, ``utils.py set_value_of_parameter_if_undefined``,  and ``check_mvm_only_parameters_for_bash``. 
+* ``check_and_define_parameters``: make sure all parameters are defined, using ``utils.py get_value_from_parameter``, ``utils.py set_value_of_parameter_if_undefined``,  and ``check_mvm_only_parameters_for_bash``.
 
 ``check_parameters_for_bash`` can be run immediately for each subtask because it has very few conditions. Other checks are included in ``check_and_define_parameters`` later on in the code.

docs/source/post.mpas_analysis_model_vs_model.cfg

@@ -0,0 +1,38 @@
+[default]
+input = <test simulation input>
+# Where the `post/` directory will be written
+output = <test simulation output>
+case = <test case name>
+www = <www>
+partition = <partition>
+
+# MPAS-Analysis: model vs. model ("test" vs. "reference")
+[mpas_analysis]
+active = True
+walltime = "4:00:00"
+parallelTaskCount = 6
+mesh = "EC30to60E2r2"
+shortTermArchive = True
+
+# Test run year ranges (these determine the identifier used for the generated
+# MPAS-Analysis cfg: mpas_analysis_ts_<ts>_climo_<climo>.cfg)
+ts_years = "1850-2014",
+climo_years = "1985-2014",
+enso_years = "1850-2014",
+
+# Point at a *previous zppy run output directory* for the reference simulation.
+# zppy will locate the matching MPAS-Analysis cfg file under (typical):
+#   <reference_data_path>/post/analysis/mpas_analysis/cfg/
+# You may also point at the `post/` directory, `analysis/mpas_analysis`, the `cfg/`
+# directory, or directly at an mpas_analysis_*.cfg file.
+reference_data_path = <reference zppy output directory>
+
+# Optional: point at a previous zppy output directory for the test simulation,
+# if you want MPAS-Analysis to reuse a completed test run as well.
+# test_data_path = <test zppy output directory>
+
+# Optional: override the reference year ranges (defaults to the test ranges).
+# If you provide a single range, it will be reused for each test range.
+# ref_ts_years = "451-500",
+# ref_climo_years = "451-500",
+# ref_enso_years = "451-500",

docs/source/tutorial.rst

@@ -58,6 +58,27 @@ This is another example of a configuration file, this time using a RRM simulatio
    :language: cfg
    :linenos:
 
+
+Example 3
+=========
+
+MPAS-Analysis model vs. model
+-----------------------------
+
+MPAS-Analysis supports "main vs. control" (model-vs-model) comparisons.
+In ``zppy``, this is configured in the ``[mpas_analysis]`` section using
+``reference_data_path`` (and optionally ``test_data_path``), consistent with the
+terminology used for ``e3sm_diags`` model-vs-model runs.
+
+Unlike ``e3sm_diags`` (where ``run_type = "model_vs_model"`` and ``reference_data_path``
+points directly at reference climatology output), MPAS-Analysis comparisons are driven
+by MPAS-Analysis config files. For model-vs-model mode, ``zppy`` locates the matching
+config file(s) from prior MPAS-Analysis output and passes them to MPAS-Analysis.
+
+.. literalinclude:: post.mpas_analysis_model_vs_model.cfg
+   :language: cfg
+   :linenos:
+
 Debugging failures
 ==================