Move MPAS Framework section, fix level-3 subsection headers

components/mpas-seaice/docs/dev-guide/index.md

@@ -11,6 +11,25 @@ Development of the MPAS-seaice component should follow the general procedures ou
 
 MPAS-seaice is controlled using namelist options.  Namelist files for E3SM runs are found in ``E3SM/components/mpas-seaice/bld/namelist_files/``.  However, the values in these files are drawn from the Registry, following the convention of all MPAS components. Registry files are used directly for stand-alone MPAS-seaice runs, and E3SM scripts pass information from them into E3SM's namelist files when a PR is merged.  E3SM's namelist files need to be changed for development purposes.  It's easiest to change all of them when needed, to keep them consistent, taking care not to unintentionally change standalone MPAS-seaice configurations.
 
+**MPAS Framework**
+------------------
+
+MPAS-seaice is built on the MPAS Framework.
+
+The MPAS Framework provides the foundation for a generalized geophysical fluid dynamics model on unstructured spherical and planar meshes. On top of the framework, implementations specific to the modeling of a particular physical system (e.g., sea ice, ocean) are created as MPAS cores. The MPAS design philosophy is to leverage the efforts of developers from the various MPAS cores to provide common framework functionality with minimal effort, allowing MPAS core developers to focus on development of the physics and features relevant to their application.
+
+The framework code includes shared modules for fundamental model operation. Significant capabilities include:
+
+- **Description of model data types.** MPAS uses a handful of fundamental Fortran derived types for basic model functionality. Core-specific model variables are handled through custom groupings of model fields called pools, for which custom access routines exist. Core-specific variables are defined in XML syntax in a Registry, and the framework parses the Registry, defines variables, and allocates memory as needed.
+- **Mesh specification.** MPAS requires 36 fields to fully describe the mesh used in a simulation. These include the position, area, orientation, and connectivity of all cells, edges, and vertices in the mesh. The mesh specification can flexibly describe both spherical and planar meshes. For more information about the meshes, see the [Users Guide](../user-guide/index.md).
+- **Distributed memory parallelization and domain decomposition.** The MPAS Framework provides needed routines for exchanging information between processors in a parallel environment using Message Passing Interface (MPI). This includes halo updates, global reductions, and global broadcasts. MPAS also supports decomposing multiple domain blocks on each processor to optimize model performance by minimizing transfer of data from disk to memory. Shared memory parallelization through OpenMP is also supported, but the implementation is left up to each core.
+- **Parallel input and output capabilities.** MPAS performs parallel input and output of data from and to disk through the commonly used libraries of NetCDF, Parallel NetCDF (pnetcdf), and Parallel Input/Output (PIO). The Registry definitions control which fields can be input and/or output, and a framework "streams" functionality provides run-time configuration of what fields are to be written to what file name and at what frequency through an XML streams file. The MPAS framework includes additional functionality specific to providing a flexible model restart capability.
+- **Advanced timekeeping.** MPAS uses a customized version of the timekeeping functionality of the Earth System Modeling Framework (ESMF), which includes a robust set of time and calendar tools used by many Earth System Models (ESMs). This allows explicit definition of model epochs in terms of years, months, days, hours, minutes, seconds, and fractional seconds and can be set to three different calendar types: Gregorian, Gregorian no leap, and 360 day. This flexibility helps enable multi-scale physics and simplifies coupling to ESMs. To manage the complex date/time types that ensue, MPAS framework provides routines for arithmetic of time intervals and the definition of alarm objects for handling events (e.g., when to write output, when the simulation should end).
+- **Run-time configurable control of model options.** Model options are configured through namelist files that use standard Fortran namelist file format, and input/output are configured through streams files that use XML format. Both are completely adjustable at run time.
+- **Online, run-time analysis framework.** A system for defining analysis of model states during run time, reducing the need for post-processing and model output.
+
+Additionally, a number of shared operators exist to perform common operations on model data. These include geometric operations (e.g., length, area, and angle operations on the sphere or the plane), interpolation (linear, barycentric, Wachspress, radial basis functions, spline), vector and tensor operations (e.g., cross products, divergence), and vector reconstruction (e.g., interpolating from cell edges to cell centers). Most operators work on both spherical and planar meshes.
+
 **Icepack**
 -----------
 
@@ -25,7 +44,7 @@ Basic Icepack development can be done in standalone mode using Icepack's testing
 
 To accelerate early development stages, a script is available for configuring and testing MPAS-seaice (including the Icepack submodule) in D compsets, which have the sea ice component active and data models for the other components.
 
-**View helpful information, including default values for duration, configuration, etc.**
+### View helpful information, including default values for duration, configuration, etc.
 
 ```text
 git clone [email protected]:E3SM-Project/SimulationScripts.git
@@ -37,7 +56,7 @@ For debugging E3SM, search the script for 'debug' and follow the instructions.
 
 The following examples describe how to use the script for development in Icepack.  Similar procedures could be used for any MPAS-SI physics development.
 
-**Set up and run baselines.**
+### Set up and run baselines
 
 Create a file containing modified namelist options. The file ``nset01.nlk`` in this example creates baselines for two types of column physics and turns off the ``snicar_ad`` radiation scheme.
 
@@ -77,7 +96,7 @@ Examine the diagnostic output (compares the icepack run with the column_package
 ./E3SM-Polar-Developer.sh -s baselines01 -k nset01.nlk -e -a -v
 ```
 
-**Set up a sandbox for model development, to be compared with the baselines.**
+### Set up a sandbox for model development, to be compared with the baselines
 
 Fetch E3SM (choose any name for the directory newdev01):
 
@@ -124,7 +143,7 @@ Compare with the baselines case directory (use your D3 baselines directory):
 ./E3SM-Polar-Developer.sh -s newdev01 -k nset01.nlk -a D3.nset01.baselines01.master.E3SM-Project.anvil -v
 ```
 
-**Make changes in Icepack and PR to the Consortium.**
+### Make changes in Icepack and PR to the Consortium
 
 We recommend PR’ing Icepack changes first to the Consortium then to E3SM’s icepack fork, in order to keep the repositories in sync and to ensure the changes are robust outside of E3SM.  Some changes to Icepack require extensive changes to the driver code (e.g. MPAS-seaice or CICE), making this process challenging.  Contact the [CICE Consortium](https://github.com/CICE-Consortium/About-Us/wiki/Contributing) to discuss and identify a collaborative path forward.
 
@@ -162,7 +181,7 @@ More extensive documentation of this workflow tool used for the Icepack merge pr
 
 Example to run a CICE-QC comparison between two E3SM simulations with changes to the sea ice component.
 
-**Set up and run simulations to be compared.**
+### Set up and run simulations to be compared
 
 ```text
 cd ~/SimulationScripts/archive/PolarGroup/
@@ -253,7 +272,7 @@ cd ~/SimulationScripts/archive/PolarGroup/
 ./E3SM-Polar-Developer.sh -s newdev01 -k qcbase.nlk -e -d60 -q
 ```
 
-**Run QC comparison.**
+### Run QC comparison
 
 ```text
 cd ~/E3SM-Polar/code/newdev01/components/mpas-seaice/testing/cice-qc
@@ -287,7 +306,7 @@ Quadratic Skill Test Passed for Northern Hemisphere
 Quadratic Skill Test Passed for Southern Hemisphere
 ```
 
-**Generate statistics from the CICE-QC runs.**
+### Generate statistics from the CICE-QC runs
 
 This only works if the .nlk filename is the same for both cases.  If comparing only namelist changes within MPAS-seaice, use the ``./E3SM-Polar-Developer.sh`` script with a single .nlk file that includes each option.
 
@@ -296,7 +315,7 @@ cd ~/SimulationScripts/archive/PolarGroup/
 $ ./E3SM-Polar-Developer.sh -s qcbaseline -k qcbase.nlk -e -d60 -a D12.qcbase.emc.newdev01.branch.E3SM-Project.anvil -v
 ```
 
-**Create comparison plots.**
+### Create comparison plots
 
 To generate MPAS-Analysis plots from the CICE-QC runs and compare:
 

components/mpas-seaice/docs/tech-guide/index.md

@@ -70,25 +70,25 @@ Icepack includes sophisticated vertical physics and biogeochemical schemes, whic
 
 Full documentation for E3SM's version of Icepack can be found in [E3SM's Icepack readthedocs](https://e3sm-icepack.readthedocs.io/en/latest).  The most up-to-date documentation from the CICE Consortium's main Icepack repository is [here](https://cice-consortium-icepack.readthedocs.io/en/main).
 
-**Thermodynamics.**
+### Thermodynamics
 
 In its default configuration, MPAS-Seaice uses the “mushy layer” vertical thermodynamics scheme of Turner et al. (2013) and Turner and Hunke (2015).  The mushy layer formulation describes the sea ice as a two-phase system of crystalline, fresh ice and liquid brine. Enthalpy depends on temperature and salinity, all of which are prognostic variables.  The mushy layer equations are derived from conservation of energy, conservation of salt, an ice-brine liquidus relation that determines the temperature- and salinity-dependent phase, and Darcy flow through a porous medium to describe the vertical movement of brine within the ice.  When or where the ice is cold, brine pockets are isolated from each other, but warmer temperatures cause the brine pockets to expand and connect into vertical channels in which meltwater, seawater, biology and nutrients may move through the ice.
 
-**Melt Ponds.**
+### Melt Ponds
 
 MPAS-seaice uses the level-ice melt pond scheme of Hunke et al. (2013). The ponds are carried as tracers on the level (undeformed) ice area of each thickness category, thus limiting their spatial extent based on the simulated sea ice topography. This limiting is meant to approximate the horizontal drainage of melt water into depressions in ice floes. The ponds evolve according to physically based process descriptions, assuming a thickness-area ratio for changes in pond volume. Melt pond processes include addition of liquid water from rain, melting snow and melting surface ice, drainage of pond water when its weight pushes the ice surface below sea level or when the ice interior becomes permeable, and refreezing of the pond water. If snow falls after a layer of ice has formed on the ponds, the snow may block sunlight from reaching the ponds below. When melt water forms with snow still on the ice, the water is assumed to infiltrate the snow. If there is enough water to fill the air spaces within the snowpack, then the pond becomes visible above the snow, thus decreasing the albedo and ultimately causing the snow to melt faster. The albedo also decreases as snow depth decreases, and thus a thin layer of snow remaining above a pond-saturated layer of snow will have a lower albedo than if the melt water were not present. Level-ice melt ponds are “virtual” in the sense that rain and meltwater is sent to the ocean immediately, and the tracers are only used thereafter to adjust the radiative calculations as if the ponds were present.  The delta-Eddington radiative transfer scheme must be active for this purpose.
 
-**Radiation.**
+### Radiation
 
 The Delta-Eddington radiation scheme of Briegleb & Light (2007) has been updated to the Dang et al. (2019) SNICAR-AD model, to ensure radiative consistency across all snow surfaces in E3SM, including on land, ice sheets and sea ice. The SNICAR-AD radiative transfer code includes five-band snow single-scattering properties, two-stream Delta-Eddington approximation with the adding–doubling technique, and parameterization for correcting the near-infrared (NIR) snow albedo biases when solar zenith angle exceeds 75 degrees (Dang et al., 2019).
 
-**Snow.**
+### Snow
 
 A new snow-on-sea-ice morphology has been added to E3SMv2 that includes the effects of wind redistribution: losses to leads and meltponds, and the piling of snow against ridges. Snow grain radius, now a prognosed tracer field on sea ice, evolves according to temperature gradient and wet snow metamorphism and feeds back to the SNICAR-AD radiative model up to a dry maximum of 2800 μm. Fresh snow falls at a grain radius of 54.5 μm, and five vertical snow layers replace the previous single snow layer atop each of the five sea ice thickness categories retained from E3SMv1.
 
 A paper describing the advanced snow physics is in preparation.
 
-**Biogeochemistry.**
+### Biogeochemistry
 
 This section is under construction, pending the full merge of BGC codes in Icepack and the older column physics package.
 
@@ -101,6 +101,6 @@ v1: Coupling of the sea ice component to the ocean takes advantage of z star oce
 
 v2: The most significant improvement to the sea ice climate since E3SMv1 was achieved with coupling changes associated with mushy-layer thermodynamics. Whereas the basal temperature of the ice was held fixed at -1.8◦C in E3SMv1, the new version of the model assumes the mushy liquidus basal temperature from the sea ice as described by Turner & Hunke (2015). Conversion of frazil ice from MPAS-Ocean with a fixed reference salinity of 4 PSU to the mushy layer now conserves to computational accuracy over a 500-year control integration. This was achieved by exchanging additional mass between the upper ocean and sea ice model to accommodate an assumed 25% mushy liquid content  assumed from heat and mass transferred adiabatically from the MPAS-Ocean frazil scheme active from a depth of 100 m. In addition to achieving perfect heat and mass conserva tion between sea ice and ocean models, this improvement greatly reduces a negative sea  ice thickness bias in the summer Arctic reported by Golaz et al. (2019) for E3SMv1; it only minimally impacts Southern Ocean sea ice mass that was better simulated as compared to northern hemisphere sea ice in E3SMv1. Note that E3SM does not use virtual ice-ocean fluxes, but instead full mass and heat flux exchange consistent with a Boussinesq ocean model as described by Campin et al. (2008). 
Radiative coupling with the atmosphere still integrates across just two bands (visible and NIR) separated at 700nm, which does not fully exploit the five-band capability available in the delta-Eddington scheme.
 
-**Prescribed Ice Mode.**
+### Prescribed Ice Mode
 
 E3SM also includes a prescribed-extent ice mode for MPAS-SeaIce based the CESM implementation. This mode is needed for Atmospheric Model Intercomparison Project (AMIP) style simulations where a full prognostic sea ice model is not desired but sea ice surface fluxes, albedos, snow depth, and surface temperature are needed by the atmosphere model. These fields are calculated by the vertical thermodynamics module of the sea ice component. The prescribed-ice mode is intended for atmosphere sensitivity experiments and does not conserve energy or mass. In this mode, sea ice thermodynamics is active but sea ice dynamics are disabled, and at each time step ice area and thickness are reset to specified values. Ice area is interpolated in time and space from an input data set, while ice thickness in grid cells containing sea ice is set to 2 m in the Northern hemisphere and 1 m in the Southern hemisphere. During each area and thickness adjustment, snow volume preserves the snow thickness prognosed in the previous time step. Snow temperatures are reset to the surface temperature, as prognosed in the previous time step, while ice temperatures are set so that the ice temperature gradient is linear, with the ice temperature at the top equal to the prognosed surface temperature, and equal to the sea freezing temperature at the base of the ice. The vertical ice salinity profile is reset to the profile from Bitz & Lipscomb (1999). The prescribed-ice mode implemented in MPAS-SeaIce can now replace that in CICE in such configurations, but CICE continues to be used for those requiring exceptional computational efficiency.