diff --git a/components/mpas-seaice/docs/dev-guide/index.md b/components/mpas-seaice/docs/dev-guide/index.md index 7f17f5fb62d6..24fabfa73acc 100644 --- a/components/mpas-seaice/docs/dev-guide/index.md +++ b/components/mpas-seaice/docs/dev-guide/index.md @@ -1,18 +1,15 @@ -Developer's Guide -================= +# Developer's Guide Development of the MPAS-seaice component should follow the general procedures outlined by the E3SM project. [Development Guide for E3SM Code](https://acme-climate.atlassian.net/wiki/spaces/DOC/pages/1868455/Development+Getting+Started+Guide) [Development Guide for E3SM Documentation](https://acme-climate.atlassian.net/wiki/spaces/DOC/pages/3924787306/Developing+Documentation) -**Configuration Controls** --------------------------- +## Configuration Controls 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 Framework MPAS-seaice is built on the MPAS Framework. @@ -30,8 +27,7 @@ The framework code includes shared modules for fundamental model operation. Sign 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** ------------ +## Icepack For changes to Icepack, please consult the [CICE Consortium's recommendations for code contributions](https://github.com/CICE-Consortium/About-Us/wiki/Contributing). @@ -39,12 +35,11 @@ To access the column physics in Icepack, MPAS-seaice uses methods defined in ``i Basic Icepack development can be done in standalone mode using Icepack's testing scripts, directly in the submodule branch in MPAS-seaice. **We recommend that Icepack developments be thoroughly tested within E3SM's coupled framework throughout the development process, including fully coupled simulations.** -**E3SM-Polar-Developer Script** -------------------------------- +## E3SM-Polar-Developer Script 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 git@github.com:E3SM-Project/SimulationScripts.git @@ -176,8 +171,7 @@ Once the PR has been tested and merged into the main Icepack codebase, a new PR More extensive documentation of this workflow tool used for the Icepack merge project is available [here](https://acme-climate.atlassian.net/wiki/spaces/ICE/pages/3450339435/Project+Workflow). -**CICE-QC Quality Control Testing** ------------------------------------ +## CICE-QC Quality Control Testing Example to run a CICE-QC comparison between two E3SM simulations with changes to the sea ice component. diff --git a/components/mpas-seaice/docs/tech-guide/index.md b/components/mpas-seaice/docs/tech-guide/index.md index ec7e06fff23f..7f0a2e4c9400 100644 --- a/components/mpas-seaice/docs/tech-guide/index.md +++ b/components/mpas-seaice/docs/tech-guide/index.md @@ -1,8 +1,6 @@ -Technical Guide -=============== +# Technical Guide -**Primary documentation for MPAS-seaice** ------------------------------------------ +## Primary documentation for MPAS-seaice See complete citations in [References](../references.md). @@ -16,8 +14,7 @@ See complete citations in [References](../references.md). A comprehensive paper describing MPAS-seaice is in preparation. -**Meshes** ----------- +## Meshes MPAS-Seaice is the sea ice component of E3SMv1. MPAS-Seaice and MPAS-Ocean share identical meshes, but MPAS-Seaice uses B-grid discretizations (Arakawa & Lamb, 1977) with sea ice concentration, volume, and tracers defined at cell centers and velocity defined at cell vertices. @@ -25,8 +22,7 @@ The MPAS mesh system requires the definition of seven elements. These seven ele ![mesh](../figures/mesh.png) Figure: Sample from an MPAS mesh showing the primal mesh (solid lines), the dual mesh (dashed), and velocity components aligned with a locally Cartesian coordinate system (east/north). -**Velocity and Stresses** -------------------------- +## Velocity and Stresses Velocity components at cell vertices are not aligned with the mesh, as in sea ice models with structured meshes and quadrilateral cells. Instead, the velocity components are aligned with a spherical coordinate system that is locally Cartesian, eastwards (u) and northwards (v), irrespective of the orientation of edges joining that vertex. Such a definition, however, would result in a convergence of v components at the geographic North Pole and strong metric terms in the velocity solution. Consequently, in addition, these definitions of u and v are rotated so that their pole lies on the geographical equator at 0 deg longitude. @@ -40,8 +36,7 @@ Velocities are determined by solving the sea ice momentum equation (Hibler, 1979 Two schemes to calculate the strain rate tensor and the divergence of internal stress on MPAS meshes are implemented in MPAS-Seaice, a variational scheme based on that used in CICE (Hunke and Dukowicz, 2002), and a weak scheme that uses the line integral forms of the symmetric gradient and divergence operators. The variational scheme is based on the fact that over the entire domain, Ω, and ignoring boundary effects, the total work done by the internal stress is equal to the dissipation of mechanical energy. Instead of the bilinear basis functions used by CICE, MPAS-Seaice uses Wachspress basis functions (Dasgupta, 2003), which are integrated with the quadrature rules of Dunavant (1985). -**Horizontal Transport of Ice Area Fraction and Tracers** ---------------------------------------------------------- +## Horizontal Transport of Ice Area Fraction and Tracers Horizontal transport of ice concentration, volume, and tracers is achieved with an incremental remapping (IR) scheme similar to that described in Dukowicz and Baumgardner (2000), Lipscomb and Hunke (2004), and Lipscomb and Ringler (2005). For MPAS-Seaice the IR scheme was generalized to work on either the standard MPAS mesh (hexagons and other n-gons of varying sizes, with a vertex degree of 3, or a quadrilateral mesh with a vertex degree of 4 as in CICE. Since MPAS meshes are unstructured, the IR scheme had to be rewritten from scratch. Most of the code is mesh-agnostic, but a small amount of code is specific to quad meshes. The transport equations describe conservation of quantities such as volume and energy. Fractional ice area (also known as sea ice concentration) is a mass-like quantity whose transport equation forms the basis for all other transported quantities in the model. In particular, ice volume is the product of ice area and thickness; therefore thickness is treated as a tracer on ice area, transported with the continuity equation for conservation of volume. Likewise, snow depth is carried as a tracer on ice area via a conservation of snow volume equation. Ice thickness and snow depth are referred to as “type 1” tracers (carried directly on ice area). Ice and snow enthalpy in each vertical layer are type 2 tracers, carried on ice and snow volume. When run with advanced options (e.g., active melt ponds and biogeochemistry), MPAS-Seaice advects tracers up to type 3. Thus, the mass-like field (area) is the “parent field” for type 1 tracers; type 1 tracers are parents of type 2; and type 2 tracers are parents of type 3. Sources and sinks of mass and tracers (e.g., ice growth and melting) are treated separately from transport. @@ -57,8 +52,7 @@ Since all fields are transported by the same velocity field, the second step is With advanced physics and biogeochemistry (BGC) options, MPAS-Seaice can be configured to include numerous tracer fields, each of which is advected in every thickness category, and many of which are defined in each vertical ice or snow layer. In order to accommodate different tracer combinations and make it easy to add new tracers, the tracer fields are organized in a linked list that depends on which physics and BGC packages are active. The list is arranged with fractional ice area first, followed by the type 1 tracers, type 2 tracers, and finally type 3 tracers. In this way, values computed for parent tracers are always available when needed for computations involving child tracers. -**Column Physics** ------------------- +## Column Physics The Icepack software has replaced the original ``colpkg`` column physics code in MPAS-seaice. The ``config_column_physics_type = 'column_package'`` option is still available but is no longer being supported in MPAS-seaice. @@ -92,8 +86,7 @@ A paper describing the advanced snow physics is in preparation. This section is under construction, pending the full merge of BGC codes in Icepack and the older column physics package. -**Coupling of MPAS-seaice within E3SM** ---------------------------------------- +## Coupling of MPAS-seaice within E3SM This section is under construction. Current text is quoted from the v1 and v2 overview papers. diff --git a/components/mpas-seaice/docs/user-guide/index.md b/components/mpas-seaice/docs/user-guide/index.md index 1612252d1b06..19eba36a0198 100644 --- a/components/mpas-seaice/docs/user-guide/index.md +++ b/components/mpas-seaice/docs/user-guide/index.md @@ -1,10 +1,8 @@ -User's Guide -============ +# User's Guide Guidance for using E3SM is available from [E3SM's public web site](). -**Configuring MPAS-seaice** ---------------------------- +## Configuring MPAS-seaice MPAS-seaice is controlled using namelist options. @@ -43,8 +41,7 @@ Related namelist variables are grouped according to their application. | ``diagnostics`` | diagnostic output | | ``prescribed_ice`` | for testing atmosphere simulations | -**Icepack** ------------ +## Icepack The Icepack software has replaced the original ``colpkg`` column physics code in MPAS-seaice. The ``column_package`` option is still available but is no longer being supported in MPAS-seaice. @@ -56,8 +53,7 @@ The MPAS-seaice driver for Icepack is and the mapping between the names of Icepack's namelist options and those in MPAS-seaice can be found in subroutine ``init_icepack_package_configs`` (see the argument list for ``call subroutine icepack_init_parameters`` and comments at the end of ``init_icepack_package_configs``. -**Configuring Model Input and Output** --------------------------------------- +## Configuring Model Input and Output The reading and writing of model fields in MPAS is handled by user-configurable streams. A stream represents a fixed set of model fields, together with dimensions and attributes, that are all written or read together to or from the same file or set of files. Each MPAS model core may define its own set of default streams that it typically uses for reading initial conditions, for writing and reading restart fields, and for writing additional model history fields. Besides these default streams, users may define new streams to, e.g., write certain diagnostic fields at a higher temporal frequency than the usual model history fields.