.. _dev_landice_mismipplus:

mismipplus
==========

The ``mismipplus`` test group (:py:class:`compass.landice.tests.mismipplus.MISMIPplus`)
performs a limited number of the MISMIP+ experiments
(see :ref:`landice_mismipplus`).  Here, we describe the shared framework for
this test group and the two test cases.

.. _dev_landice_mismipplus_framework:

Framework
---------

The shared config options for the ``mismipplus`` test group
are described in :ref:`landice_mismipplus` in the User's Guide.

Test cases within the ``mismipplus`` group should only be run with the 
FO velocity solver, or with a data velocity field. Running with the FO solver 
requires building MALI with the Albany library.

The test group has a shared ``namelist.landice`` file with
a few common namelist options related to model numerics,
and a shared ``streams.landice`` file that defines ``input``, ``restart``, and
``output``, and ``globalStatsOutPut`` streams. There also is an 
``albany_input.yaml`` file that is needed for running the FO solver.


setup_mesh
~~~~~~~~~~
The class :py:class:`compass.landice.tests.mismipplus.setup_mesh.SetupMesh` 
defines a step for creating the mesh/initial conditions for a MISMIP+ spinup 
simulation. This step is only used by the ``spin_up`` test case. An odd number 
of rows are culled along the North/South boundaries such that the ragged 
layout of mesh rows is symmetric in the y direction. 

The ``resolution`` parameter from the ``[mesh]`` section of the configuration
file is the nominal resolution, where the actual resolution is iteratively 
calculated so that the cell center to cell center distance along the y-axis 
of the mesh is exactly equal to the vertical domain length (80 km). 
 
run_model
~~~~~~~~~

The class :py:class:`compass.landice.tests.mismipplus.run_model.RunModel`
defines a step for setting up the input files (i.e. streams, namelist, 
``albany_input.yaml``) needed to run MALI. The initial condition can either 
be downloaded from the shared data server (for the 
:ref:`landice_mismipplus_smoke_test` testcase) or generated by the 
:py:class:`compass.landice.tests.mismipplus.setup_mesh.SetupMesh` step 
(for the :ref:`landice_mismipplus_spin_up` testcase).


.. _dev_landice_mismipplus_tasks:

tasks
~~~~~

The function :py:func:`compass.landice.tests.mismipplus.tasks.get_ntasks_from_cell_count()`
can be used to compute a good number of MPI tasks (both the target and the
minimum) for MALI to use based on the ``goal_cells_per_core`` and
``max_cells_per_core`` config options as well as the number of cells in a mesh.
The idea is that we want to run MALI with about 300 cells per core
(the default value of ``goal_cells_per_core``) but that we would be okay
with as many as 5000 cells per core (the default ``max_cells_per_core``).

A complication of using this function is that the number of cells in a mesh
is not known until the :py:class:`compass.landice.tests.mismipplus.setup_mesh.SetupMesh`
step has been run (i.e. at ``compass run``) for a given ``resolution``, but we 
need to know how many cores and nodes we will use at setup 
(i.e. at ``compass setup ...``) since that is when the job script is created. 
That's why there is both ``exact_cell_count()`` and ``approx_cell_count()`` 
within the ``tasks`` module. :py:func:`compass.landice.tests.mismipplus.tasks.approx_cell_count()` 
is called at ``compass setup`` when the exact number of gridcells is
unknown, but can be approximated by scaling a heuristic by the requested 
resolution. Whereas, at ``compass run`` the number of gridcells is precisely 
known and can be queried using :py:func:`compass.landice.tests.mismipplus.tasks.exact_cell_count()`, 
which is then used to determine ``ntasks`` for MALI runs at various resolutions.  

.. _dev_landice_mismipplus_testcases:

Test cases
----------

.. _dev_landice_mismipplus_spin_up:

spin_up
~~~~~~~

The :py:class:`compass.landice.tests.mismipplus.spin_up.SpinUp` case will 
generate a new MISMIP+ mesh at the requested ``resolution`` 
(from the ``[mesh]`` section of the config file) and setup the files to run 
a 20,000 year spinup run. 

.. _dev_landice_mismipplus_smoke_test:
   
smoke_test
~~~~~~~~~~

The :py:class:`compass.landice.tests.mismipplus.smoke_test.SmokeTest`
performs a 5 year version of the `Ice0` experiment. There is a validation step 
that compares the output file against itself.  This is to allow the test to be 
compared against a baseline if desired.