Add mpas analysis model vs model

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,41 @@ 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`` resolves the config file when ``reference_data_path`` points to the prior run's zppy output directory (the one containing ``post/``).
+
+   ``reference_data_path`` is intended to point to the prior run's zppy output directory (the one containing ``post/``). ``zppy`` will then use:
+   ``<reference_data_path>/post/analysis/mpas_analysis/cfg/mpas_analysis_<identifier>.cfg`` (or ``mpas_analysis_mvm`` if the referenced run was MVM).
+
+   When ``reference_data_path`` is set to a non-subsection path, ``reference_case`` is required so the MVM output directory can include the reference case name. If ``reference_data_path`` is set to ``[[subsection]]``, ``reference_case`` is inferred to be the same as the current ``case``.
+
+
+**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.
+   If ``test_data_path`` references a prior ``[mpas_analysis]`` subsection using
+   ``[[subsection]]``, and these values are not provided, zppy uses that
+   subsection's year ranges instead.
+* ``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 ``reference_data_path`` references a prior ``[mpas_analysis]`` subsection using ``[[subsection]]``,
+the defaults come from that subsection's year ranges instead.
+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 +111,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 +120,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,44 @@
+[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:
+#   <reference_data_path>/post/analysis/mpas_analysis/cfg/
+reference_data_path = <reference zppy output directory>
+
+# Required when reference_data_path is not a [[subsection]].
+# Used to build the MVM output directory name.
+reference_case = <reference case name>
+
+# 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.
+# If set to [[subsection]], zppy will use that subsection's year ranges
+# when ts_years/climo_years/enso_years are not provided.
+# test_data_path = <test zppy output directory>
+
+# Optional: override the reference year ranges (defaults to the test ranges).
+# If reference_data_path points to a prior [mpas_analysis] subsection using
+# the form [[subsection]], these default to that subsection's year 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
 ==================
 

tests/integration/template_weekly_comprehensive_v3.cfg

@@ -201,17 +201,28 @@ tc_obs = "#expand diagnostics_base_path#/observations/Atm/tc-analysis/"
 [mpas_analysis]
 active = #expand active_mpas_analysis#
 anomalyRefYear = 1985
-climo_years = "1985-1989", "1990-1995",
-enso_years = "1985-1989", "1990-1995",
 environment_commands = "#expand mpas_analysis_environment_commands#"
 mesh = "IcoswISC30E3r5"
 parallelTaskCount = 6
 partition = "#expand partition_long#"
 qos = "#expand qos_long#"
 shortTermArchive = True
-ts_years = "1985-1989", "1985-1995",
 walltime = "#expand mpas_analysis_walltime#"
 
+  [[ reference ]]
+  ts_years = "1985-1989",
+  climo_years = "1985-1989",
+  enso_years = "1985-1989",
+
+  [[ test ]]
+  ts_years = "1985-1995",
+  climo_years = "1990-1995",
+  enso_years = "1990-1995",
+
+  [[ mvm ]]
+  reference_data_path = [[ reference ]]
+  test_data_path = [[ test ]]
+
 [global_time_series]
 active = #expand active_global_time_series#
 climo_years = "1985-1989", "1990-1995",

zppy/defaults/default.ini

@@ -314,6 +314,33 @@ ts_daily_subsection = string(default="")
 [mpas_analysis]
 anomalyRefYear = integer(default=1)
 cache = boolean(default=True)
+# Year ranges for the MPAS-Analysis sub-runs. These are used to form identifiers like:
+#   ts_1850-2014_climo_1985-2014
+ts_years = string_list(default=list(""))
+climo_years = string_list(default=list(""))
+enso_years = string_list(default=list(""))
+# Optional: enable MPAS-Analysis test-vs-reference ("main vs. control") mode.
+# Set these to the output directory of a prior zppy run (the one containing post/),
+# or to [[ subsection ]] to refer to a previous mpas_analysis subsection in this workflow.
+# zppy will use:
+#   <output>/post/analysis/mpas_analysis/cfg/mpas_analysis_<identifier>.cfg
+#   (or <output>/post/analysis/mpas_analysis_mvm/cfg/ if the referenced run was MVM)
+# where <identifier> matches each MPAS-Analysis sub-run (e.g. ts_1850-2014_climo_1985-2014).
+reference_data_path = string(default="")
+test_data_path = string(default="")
+# Required when reference_data_path is set to a non-subsection path.
+# If reference_data_path is set to [[subsection]], reference_case is inferred
+# to be the same as the current case.
+reference_case = string(default="")
+# Optional: allow reference run years to differ from test run years.
+# If these are left empty, zppy uses the test run's corresponding year sets.
+# If reference_data_path points to [[ subsection ]], zppy uses that subsection's
+# year sets when these are left empty.
+# If a single range is provided, it will be replicated for all test year sets.
+ref_ts_years = string_list(default=list(""))
+ref_climo_years = string_list(default=list(""))
+ref_enso_years = string_list(default=list(""))
+
 # Note that environment_commands needs to be the same for all related runs of [mpas_analysis].
 # For example, if years 1-50 are run using one environment and years 51-100 are run using another, MPAS-Analysis may fail.
 generate = string_list(default=list('all', 'no_landIceCavities', 'no_BGC', 'no_icebergs', 'no_min', 'no_max', 'no_sose', 'no_waves', 'no_eke', 'no_climatologyMapAntarcticMelt', 'no_regionalTSDiagrams', 'no_timeSeriesAntarcticMelt', 'no_timeSeriesOceanRegions', 'no_climatologyMapSose', 'no_woceTransects', 'no_soseTransects', 'no_geojsonTransects', 'no_oceanRegionalProfiles', 'no_hovmollerOceanRegions', 'no_oceanConservation'))
@@ -331,6 +358,32 @@ stream_ocn = string(default="streams.ocean")
 # NOTE: always overrides value in [default]
 walltime = string(default="06:00:00")
 
+  [[__many__]]
+  anomalyRefYear = integer(default=None)
+  cache = boolean(default=None)
+  ts_years = string_list(default=None)
+  climo_years = string_list(default=None)
+  enso_years = string_list(default=None)
+  reference_data_path = string(default=None)
+  test_data_path = string(default=None)
+  reference_case = string(default=None)
+  ref_ts_years = string_list(default=None)
+  ref_climo_years = string_list(default=None)
+  ref_enso_years = string_list(default=None)
+  generate = string_list(default=None)
+  mapMpiTasks = integer(default=None)
+  mpaso_nml = string(default=None)
+  mpassi_nml = string(default=None)
+  ncclimoThreads = integer(default=None)
+  ncclimoParallelMode = string(default=None)
+  parallelTaskCount = integer(default=None)
+  PostMOC = boolean(default=None)
+  purge = boolean(default=None)
+  shortTermArchive = boolean(default=None)
+  stream_ice = string(default=None)
+  stream_ocn = string(default=None)
+  walltime = string(default=None)
+
 [global_time_series]
 climo_years = string_list(default=list(""))
 # The color to be used for the graphs.