MPAS-seaice documentation

components/mpas-seaice/docs/index.md

@@ -0,0 +1,44 @@
+The E3SM Sea Ice Model (MPAS-seaice)
+====================================
+
+MPAS-seaice is an unstructured-mesh sea-ice model that uses the Modeling for Prediction Across Scales (MPAS) framework, allowing enhanced horizontal resolution in regions of interest. MPAS-seaice incorporates many of the methods used in the Los Alamos CICE sea-ice model, but adapted to the Spherical Centroidal Vornoi Tesselation (SCVT) meshes used by the MPAS framework.
+
+* The [MPAS-seaice User's Guide](user-guide/index.md) outlines the MPAS Framework, on which MPAS-seaice is built, and Icepack, the column physics submodule in MPAS-seaice, and it provides guidance for controlling MPAS-seaice within E3SM.
+* The [MPAS-seaice Technical Guide](tech-guide/index.md) describes the mesh and major physics components underlying MPAS-seaice code and its coupling to E3SM.
+* The [MPAS-seaice Developer's Guide](dev-guide/index.md) provides additional information relevant for model development, including the Icepack interface and development/testing scripts.
+
+**Icepack**
+-----------
+
+MPAS-seaice incorporates the Icepack software package for sea ice column physics, developed by the [CICE Consortium](https://github.com/cice-consortium), as a submodule. [Icepack documentation](https://e3sm-icepack.readthedocs.io/en/latest/). provides a complete description of the column physics and instructions for using Icepack as a standalone model. The source code for this documentation is maintained in [E3SM's Icepack fork](https://github.com/E3SM-Project/Icepack/) (navigate to the desired branch, then to doc/source/, etc).  This is the documentation associated with the latest Icepack version that has been merged into E3SM, plus any documentation changes made within E3SM itself. This documentation is fully rendered in [E3SM's Icepack readthedocs](https://e3sm-icepack.readthedocs.io/en/latest/).
+
+<!--
+If needed, documentation for the most recent Icepack release incorporated in E3SM can be found in the CICE Consortium's readthedocs project area:
+
+* Check the [release tags](https://github.com/E3SM-Project/Icepack/tags) to get the release number.
+* Choose the release version of the documentation from the [Icepack release table](https://github.com/CICE-Consortium/Icepack/wiki/Icepack-Release-Table).
+-->
+
+[Guidance for developing Icepack documentation](https://github.com/CICE-Consortium/About-Us/wiki/Documentation-Workflow-Guide) includes instructions for building the readthedocs documentation yourself.
+
+**MPAS-seaice code structure**
+------------------------------
+
+Some MPAS-seaice functionality is sourced from the MPAS Framework:
+``E3SM/components/mpas-framework``.  In particular, see ``E3SM/components/mpas-framework/core_seaice``.
+
+Code structure within the ``mpas-seaice/``component-level directory:
+
+| Directories | Function |
+| ----------- | -------- |
+| ``bld``         | namelist configuration files |
+| ``cime_config`` | build and configuration scripts |
+| ``docs``        | this documentation |
+| ``driver``      | coupling modules |
+| ``src``         | source code for the model physics and output |
+| ``src/analysis_members`` | source code for model output |
+| ``src/column``           | source code for the (original) ``column_package`` |
+| ``src/icepack``          | link to the icepack submodule |
+| ``src/model_forward``    | top-level mpas-seaice modules |
+| ``src/shared``           | dynamics and general-purpose modules (e.g. mesh, constants) |
+| ``testing``     | testing scripts |

components/mpas-seaice/docs/references.md

@@ -0,0 +1,47 @@
+References
+==========
+
+Bitz, C. M., and W. H. Lipscomb (1999). An energy-conserving thermodynamic model of sea ice, Journal of Geophysical Research: Oceans, 104(C7), 15,669–15,677, doi: 10.1029/1999JC900100.
+
+Briegleb, B. P., and B. Light (2007). A Delta-Eddington multiple scattering parameterization for solar radiation in the sea ice component of the Community Climate Sys- tem Model, Tech. Rep. NCAR/TN-472+STR, National Center for Atmospheric Research, Boulder, Colorado USA.
+
+Dang, C., C. S. Zender, and M. G. Flanner (2019). Intercomparison and improvement of two-stream shortwave radiative transfer schemes in earth system models for a unified treatment of cryospheric surfaces. The Cryosphere, 13:2325–2343. doi:10.5194/tc-13-2325-2019.
+
+Dasgupta, G. (2003). Interpolants within convex polygons: Wachpress' shape functions. Journal of Aerospace Engineering, 16, 1–8. <https://doi.org/10.1061/(ASCE)0893-1321(2003)16:1(1)>
+
+Dukowicz, J. K., & Baumgardner, J. R. (2000). Incremental remapping as a transport/advection algorithm. Journal of Computational Physics, 160(1), 318–335. <https://doi.org/10.1006/jcph.2000.6465>
+
+Dunavant, D. A. (1985). High degree efficient symmetrical Gaussian quadrature rules for the triangle. International Journal for Numerical Methods in Engineering, 21(6), 1129–1148. <https://doi.org/10.1002/nme.1620210612>
+
+Flocco, D., D. L. Feltham, and A. K. Turner (2010). Incorporation of a physically based melt pond scheme into the sea ice component of a climate model, Journal of Geophysi- cal Research: Oceans, 115(C8), doi:10.1029/2009JC005568, C08012.
+
+Golaz, J.-C., Caldwell, P. M.,
Van Roekel, L. P., Petersen, M. R., Tang, Q., Wolfe, J. D., et al. (2019). The DOE E3SM coupled model version 1: Overview and evaluation at
standard resolution. Journal of Advances in Modeling Earth
Systems, 11, 2089–2129. <https://doi.org/10.1029/2018MS001603>
+
+Golaz, J.-C., Van Roekel, L. P., Zheng, X., Roberts, A. F., Wolfe, J. D., Lin, W., et al. (2022). The DOE E3SM Model version 2: Overview of the physical model and initial model evaluation. Journal of Advances in Modeling Earth Systems, 14, e2022MS003156. <https://doi.org/10.1029/2022MS003156>
+
+Hibler, W. D. III (1979). A dynamic thermodynamic sea ice model. Journal of Physical Oceanography, 9(4), 815–846. <https://doi.org/10.1175/1520-0485(1979)009&lt;0815:ADTSIM&gt;2.0.CO;2>
+
+Holland, M. M., D. A. Bailey, B. P. Briegleb, B. Light, and E. Hunke (2012). Improved sea ice shortwave radiation physics in CCSM4: The impact of melt ponds and aerosols on arctic sea ice, Journal of Climate, 25(5), 1413–1430, doi:10.1175/JCLI-D-11-00078.1.
+
+<!-- Elizabeth Hunke, Richard Allard, David Bailey, Anthony Craig, Anders Damsgaard, Frederic Dupont, Alice DuVivier, Marika Holland, Nicole Jeffery, Jean-Francois Lemieux, Christopher Newman, Andrew Roberts, Adrian Turner, Matthew Turner, & Michael Winton.-->
+Hunke, E., et al. (2018). CICE-Consortium/Icepack. Zenodo. <https://doi.org/10.5281/zenodo.1213462>
+
+Hunke, E. C., & Dukowicz, J. K. (1997). An elastic-viscous-plastic model for sea ice dynamics. Journal of Physical Oceanography, 27(9), 1849–1867. <https://doi.org/10.1175/1520-0485(1997)027&lt;1849:AEVPMF&gt;2.0.CO;2>
+
+Hunke, E. C., & Dukowicz, J. K. (2002). The elastic-viscous-plastic sea ice dynamics model in general orthogonal curvilinear coordinates on a sphere—Incorporation of metric terms. Monthly Weather Review, 130(7), 1848–1865.
+
+Hunke, E. C., Hebert, D. A., & Lecomte, O. (2013). Level-ice melt ponds in the Los Alamos sea ice model, CICE. Ocean Modelling, 71, 26–42. <https://doi.org/10.1016/j.ocemod.2012.11.008>
+
+Lipscomb, W. H. (2001). Remapping the thickness distribution in sea ice models, Journal of Geophysical Research: Oceans, 106(C7), 13,989–14,000, doi:10.1029/2000JC000518.
+
+Lipscomb, W. H., & Hunke, E. C. (2004). Modeling sea ice transport using incremental remapping. Monthly Weather Review, 132(6), 1341–1354.
+
+Lipscomb, W. H., Hunke, E. C., Maslowski, W., & Jakacki, J. (2007). Ridging, strength, and stability in high-resolution sea ice models. Journal of Geophysical Research, 112. C03S91. <https://doi.org/10.1029/2005JC003355>
+
+Lipscomb, W. H., & Ringler, T. D. (2005). An incremental remapping transport scheme on a spherical geodesic grid. Monthly Weather Review, 133(8), 2335–2350. <https://doi.org/10.1175/MWR2983.1>
+
+Turner, A. K., and E. C. Hunke (2015). Impacts of a mushy-layer thermodynamic ap- proach in global sea-ice simulations using the CICE sea-ice model, Journal of Geophys- ical Research: Oceans, 120(2), 1253–1275, doi:10.1002/2014JC010358.
+
+Turner, A. K., E. C. Hunke, and C. M. Bitz (2013). Two modes of sea-ice gravity drainage: A parameterization for large-scale modeling, Journal of Geophysical Research: Oceans, 118(5), 2279–2294, doi:10.1002/jgrc.20171.
+
+Turner, A. K., Lipscomb, W. H., Hunke, E. C., Jacobsen, D. W., Jeffery, N., Engwirda, D., Ringer, T. D., Wolfe, J. D. (2021). MPAS-seaice (v1.0.0): Sea-ice dynamics on unstructured Voronoi meshes. Geoscientific Model Development Discussions, 1–46. <https://doi.org/10.5194/gmd-2021-355>