Skip to content

Commit fa48ea1

Browse files
andrewdnolanandrewdnolan
committed
Add documentation
1 parent 1c68bdd commit fa48ea1

6 files changed

Lines changed: 401 additions & 1 deletion

File tree

‎compass/landice/tests/ismip6_GrIS_forcing/forcing_gen/forcing_gen.cfg‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,4 +23,4 @@ archive_fp = /global/cfs/cdirs/fanssie/standard_datasets/ISMIP6-Forcing-Ghub/GrI
2323

2424
# list of experiments to generate forcing for.
2525
# See `experiments.yml` for a list of supported experiments
26-
experiments = ctrl, Exp05
26+
experiments = ctrl, hist, Exp05, Exp06, Exp07, Exp08

‎docs/developers_guide/landice/api.rst‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -355,6 +355,45 @@ ismip6_forcing
355355
shelf_collapse.process_shelf_collapse.ProcessShelfCollapse.remap_ismip6_shelf_mask_to_mali_vars
356356
shelf_collapse.process_shelf_collapse.ProcessShelfCollapse.rename_ismip6_shelf_mask_to_mali_vars
357357

358+
ismip6_GrIS_forcing
359+
~~~~~~~~~~~~~~~~~~~
360+
361+
.. currentmodule:: compass.landice.tests.ismip6_GrIS_forcing
362+
363+
.. autosummary::
364+
:toctree: generated/
365+
366+
Ismip6GrISForcing
367+
368+
forcing_gen.ForcingGen
369+
forcing_gen.ForcingGen.configure
370+
forcing_gen.ForcingGen.find_forcing_files
371+
372+
create_mapping_files.CreateMappingFiles
373+
create_mapping_files.CreateMappingFiles.setup
374+
create_mapping_files.CreateMappingFiles.run
375+
create_mapping_files.CreateMappingFiles.make_scrip_and_weights_files
376+
377+
ref_smb_climatology.SMBRefClimatology
378+
ref_smb_climatology.SMBRefClimatology.setup
379+
ref_smb_climatology.SMBRefClimatology.run
380+
381+
process_forcing.ProcessForcing
382+
process_forcing.ProcessForcing.run
383+
process_forcing.ProcessForcing.process_variables
384+
process_forcing.ProcessForcing.process_variable
385+
386+
file_finders.ISMIP6FileFinder
387+
file_finders.ISMIP6FileFinder.get_filename
388+
file_finders.ISMIP6FileFinder.check_file_exists
389+
file_finders.oceanFileFinder
390+
file_finders.oceanFileFinder.get_filename
391+
file_finders.atmosphereFileFinder
392+
file_finders.atmosphereFileFinder.get_filename
393+
394+
utilities.add_xtime
395+
utilities.remap_variables
396+
358397
ismip6_run
359398
~~~~~~~~~~
360399

‎docs/developers_guide/landice/test_groups/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Test groups
1919
humboldt
2020
hydro_radial
2121
ismip6_forcing
22+
ismip6_GrIS_forcing
2223
ismip6_run
2324
isunnguata_sermia
2425
kangerlussuaq

‎docs/developers_guide/landice/test_groups/ismip6_GrIS_forcing.rst‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
.. _dev_landice_ismip6_GrIS_forcing:
2+
3+
ismip6_GrIS_forcing
4+
===================
5+
6+
The ``ismip6_GrIS_forcing`` test group
7+
(:py:class:`compass.landice.tests.ismip6_GrIS_forcing.Ismip6GrISForcing`)
8+
processes (i.e., remaps and renames) atmospheric and ocean forcing data for
9+
ISMIP6 Greenland Ice Sheet (GrIS) projection simulations with MALI. The test
10+
group includes a single test case, ``forcing_gen``
11+
(:py:class:`compass.landice.tests.ismip6_GrIS_forcing.forcing_gen.ForcingGen`),
12+
which consists of three steps.
13+
14+
Upon initialization, the test group reads and validates the ``experiments.yml``
15+
file bundled with the package. This YAML file defines the supported experiments
16+
(``ctrl``, ``hist``, ``Exp05``–``Exp08``) and stores them as the
17+
``experiments`` dictionary attribute on the test group. The subset of
18+
experiments to process is determined at configure time from the
19+
``ISMIP6_GrIS_Forcing`` config section.
20+
21+
The shared config options are described in
22+
:ref:`landice_ismip6_GrIS_forcing` in the User's Guide.
23+
24+
.. _dev_landice_ismip6_GrIS_forcing_framework:
25+
26+
framework
27+
---------
28+
29+
file_finders
30+
~~~~~~~~~~~~
31+
32+
The :py:mod:`compass.landice.tests.ismip6_GrIS_forcing.file_finders` module
33+
provides classes for locating ISMIP6 GrIS forcing files within the archive
34+
directory structure. The base class
35+
:py:class:`compass.landice.tests.ismip6_GrIS_forcing.file_finders.ISMIP6FileFinder`
36+
provides shared file-existence checking via the ``check_file_exists`` method.
37+
Two subclasses are provided:
38+
39+
- :py:class:`compass.landice.tests.ismip6_GrIS_forcing.file_finders.oceanFileFinder`
40+
navigates ``Ocean_Forcing/Melt_Implementation/{version}/`` to locate ocean
41+
thermal forcing (``thermal_forcing``) and basin runoff (``basin_runoff``)
42+
files. Ocean forcing files span the full period and are stored as a single
43+
file per variable, GCM, and scenario.
44+
45+
- :py:class:`compass.landice.tests.ismip6_GrIS_forcing.file_finders.atmosphereFileFinder`
46+
navigates ``Atmosphere_Forcing/aSMB_observed/{version}/`` to locate yearly
47+
atmospheric forcing files, which are then concatenated along the time
48+
dimension into a single file spanning the requested period.
49+
50+
utilities
51+
~~~~~~~~~
52+
53+
The :py:mod:`compass.landice.tests.ismip6_GrIS_forcing.utilities` module
54+
provides two helper functions used across multiple steps:
55+
56+
- :py:func:`compass.landice.tests.ismip6_GrIS_forcing.utilities.add_xtime`
57+
converts a dataset's cftime/datetime ``time`` coordinate to the 64-byte MPAS
58+
``xtime`` string format required by MALI.
59+
60+
- :py:func:`compass.landice.tests.ismip6_GrIS_forcing.utilities.remap_variables`
61+
calls ``ncremap`` with a pre-computed weights file to remap variables from
62+
the source grid to the MALI mesh.
63+
64+
.. _dev_landice_ismip6_GrIS_forcing_test_case:
65+
66+
Test case
67+
---------
68+
69+
.. _dev_landice_ismip6_GrIS_forcing_gen:
70+
71+
forcing_gen
72+
~~~~~~~~~~~
73+
74+
The :py:class:`compass.landice.tests.ismip6_GrIS_forcing.forcing_gen.ForcingGen`
75+
test case stores the filenames for SCRIP grid descriptor files
76+
(``mali_mesh_scrip``, ``racmo_gis_scrip``, ``ismip6_gis_scrip``) and mapping
77+
weight files (``racmo_2_mali_weights``, ``ismip6_2_mali_weights``) as
78+
attributes. It also stores the path to the SMB reference climatology
79+
(``smb_ref_climatology``) so it is accessible to all steps. These attributes
80+
are initialized as bare filenames and are updated to full paths during the
81+
``setup`` method of ``CreateMappingFiles``.
82+
83+
In ``configure``, the test case reads the requested experiment names from the
84+
``ISMIP6_GrIS_Forcing`` config section, builds the ``experiments`` subset
85+
dictionary from the full ``experiments.yml`` dictionary, and initializes the
86+
:py:class:`~compass.landice.tests.ismip6_GrIS_forcing.file_finders.oceanFileFinder`
87+
and
88+
:py:class:`~compass.landice.tests.ismip6_GrIS_forcing.file_finders.atmosphereFileFinder`
89+
instances based on the ``archive_fp`` config option.
90+
91+
The ``find_forcing_files`` method on the test case dispatches file-location
92+
requests to the appropriate file finder based on the variable name.
93+
94+
.. _dev_landice_ismip6_GrIS_forcing_create_mapping_files:
95+
96+
create_mapping_files
97+
^^^^^^^^^^^^^^^^^^^^
98+
99+
The
100+
:py:class:`compass.landice.tests.ismip6_GrIS_forcing.create_mapping_files.CreateMappingFiles`
101+
step parses the config file during ``setup`` to validate input file paths and
102+
registers the SCRIP and weight files as output files. During ``run``, it:
103+
104+
1. Calls :py:func:`mpas_tools.scrip.from_mpas.scrip_from_mpas` to produce a
105+
SCRIP file describing the MALI mesh.
106+
2. Uses :py:class:`pyremap.descriptor.ProjectionGridDescriptor` to build SCRIP
107+
files for the RACMO and ISMIP6 GrIS source grids, both of which are on the
108+
EPSG:3413 (WGS84 / NSIDC Sea Ice Polar Stereographic North) projection.
109+
3. Calls ``ESMF_RegridWeightGen`` (via ``srun``) with the ``bilinear`` method
110+
to generate weight files for RACMO to MALI and ISMIP6 GrIS to MALI.
111+
112+
The helper method ``make_scrip_and_weights_files`` encapsulates steps 2–3 for
113+
each source grid. Log files generated by ``ESMF_RegridWeightGen`` are
114+
organized into dedicated subdirectories to keep the work directory tidy.
115+
116+
To locate an ISMIP6 forcing file needed to describe the source grid, the
117+
private ``_find_ismip6_forcing_files`` method selects the first projection
118+
experiment from the YAML-defined experiments and calls ``find_forcing_files``
119+
on the test case.
120+
121+
.. _dev_landice_ismip6_GrIS_forcing_smb_ref_climatology:
122+
123+
smb_ref_climatology
124+
^^^^^^^^^^^^^^^^^^^
125+
126+
The
127+
:py:class:`compass.landice.tests.ismip6_GrIS_forcing.ref_smb_climatology.SMBRefClimatology`
128+
step reads the RACMO SMB file path from config during ``setup``, registers it
129+
as an input file, and registers the output climatology file path on the test
130+
case as ``smb_ref_climatology``.
131+
132+
During ``run``, it calls
133+
:py:func:`~compass.landice.tests.ismip6_GrIS_forcing.utilities.remap_variables`
134+
to remap the RACMO monthly ``SMB_rec`` field onto the MALI mesh, then computes
135+
the time mean over the requested climatology period. The result is:
136+
137+
- converted from the RACMO units to MALI units
138+
(kg m\ :sup:`-2` s\ :sup:`-1`),
139+
- renamed (``SMB_rec`` to ``sfcMassBal``, ``ncol`` to ``nCells``), and
140+
- written to ``racmo_climatology_{start}--{end}.nc`` via
141+
:py:func:`mpas_tools.io.write_netcdf`.
142+
143+
.. _dev_landice_ismip6_GrIS_forcing_process_forcing:
144+
145+
process_forcing
146+
^^^^^^^^^^^^^^^
147+
148+
The
149+
:py:class:`compass.landice.tests.ismip6_GrIS_forcing.process_forcing.ProcessForcing`
150+
step iterates over the experiments dictionary. For each experiment, it calls
151+
``process_variables`` separately for the atmosphere variables (``aSMB``,
152+
``dSMBdz``, ``aST``, ``dSTdz``) and ocean variables (``thermal_forcing``,
153+
``basin_runoff``), then writes each group to a single merged output file via
154+
:py:func:`mpas_tools.io.write_netcdf`.
155+
156+
The ``process_variable`` method performs the following for each variable:
157+
158+
1. Locates the source file via ``find_forcing_files`` on the test case.
159+
2. Calls :py:func:`~compass.landice.tests.ismip6_GrIS_forcing.utilities.remap_variables`
160+
to remap the variable to the MALI grid.
161+
3. Subsets the remapped dataset to the requested time range (including one year
162+
prior to ``start``, since forcing data is provided in July).
163+
4. Adds the ``xtime`` coordinate via
164+
:py:func:`~compass.landice.tests.ismip6_GrIS_forcing.utilities.add_xtime`,
165+
and renames dimensions and variables to MALI/MPAS conventions
166+
(``ncol`` to ``nCells``, ``time`` to ``Time``, plus the variable name
167+
per ``renaming_dict``).
168+
5. For ``sfcMassBal``: adds the RACMO reference climatology
169+
(``smb_ref_climatology``) to the ISMIP6 anomaly.
170+
6. For ``surfaceAirTemperature``: adds the MALI mesh surface air temperature
171+
baseline (read from the MALI mesh file) to the ISMIP6 anomaly.
172+
7. For ocean variables (``ismip6_2dThermalForcing``, ``ismip6Runoff``): fills
173+
NaN values with zero.
174+
8. For the ``ctrl`` experiment: time-averages the result over the reference
175+
climatology period.
176+
177+
The module-level ``renaming_dict`` maps ISMIP6 variable names to the
178+
corresponding MALI variable names:
179+
180+
.. code-block:: python
181+
182+
renaming_dict = {
183+
"thermal_forcing": "ismip6_2dThermalForcing",
184+
"basin_runoff": "ismip6Runoff",
185+
"aSMB": "sfcMassBal",
186+
"dSMBdz": "sfcMassBal_lapseRate",
187+
"aST": "surfaceAirTemperature",
188+
"dSTdz": "surfaceAirTemperature_lapseRate",
189+
}

‎docs/users_guide/landice/test_groups/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ physics but that are not run routinely.
2424
humboldt
2525
hydro_radial
2626
ismip6_forcing
27+
ismip6_GrIS_forcing
2728
ismip6_run
2829
isunnguata_sermia
2930
kangerlussuaq

0 commit comments

Comments
 (0)