Merge pull request CICE-Consortium#235 from duvivier/releasedoc

doc mods for Icepack release

doc/source/conf.py

@@ -121,7 +121,12 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-html_theme_options = {"stickysidebar": "true"}
+html_theme_options = {
+      "stickysidebar": "true",
+      "externalrefs" : "true",
+      "bodyfont" : "tahoma",
+      "headfont" : "tahoma"
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []

doc/source/intro/about.rst

@@ -5,6 +5,13 @@
 About Icepack
 =============
 
+Modern sea ice models have evolved into highly complex collections of physical parameterizations and
+infrastructural elements to support various configurations and computational approaches.  In particular,
+numerical models may now be implemented for unstructured grids, requiring new approaches for referencing
+information in neighboring grid cells and communication information across grid elements.  However, a
+large portion of the physics in sea ice models can be described in a vertical column, without reference
+to neighboring grid cells.
+
 The column physics package of the sea ice model CICE, "Icepack", is maintained by the
 CICE Consortium. This code includes several options for simulating sea ice
 thermodynamics, mechanical redistribution (ridging) and associated area and thickness
@@ -17,6 +24,8 @@ The purpose of Icepack is to provide the column physics model as a separate
 library for use in other host models such as CICE.
 Development and testing of CICE and Icepack may be done together,
 but the repositories are independent.
+This document describes the Icepack model. The Icepack code is 
+available from https://github.com/CICE-Consortium/Icepack.
 
 Icepack consists of three independent parts, the column physics code,
 the icepack driver that supports stand-alone testing of the column physics code, and the
@@ -26,10 +35,14 @@ on a gridpoint by gridpoint basis.  Each gridpoint is independent
 and the host model stores and passes the model state and forcing to
 the column physics.
 
-This document uses the following text conventions:
-Variable names used in the code are ``typewritten``.
-Subroutine names are given in *italic*.
-File and directory names are in **boldface**.
-Code and scripts are contained in a literal box or ``typewritten``.
-A comprehensive :ref:`index`, including glossary of symbols with many of their values, appears
-at the end of this guide.
+Major changes with each Icepack release (https://github.com/CICE-Consortium/Icepack/releases) 
+will be detailed with the included release notes. Enhancements and bug fixes made to 
+Icepack since the last numbered release can be found on the Icepack wiki
+(https://github.com/CICE-Consortium/Icepack/wiki/Icepack-Recent-changes).
+**Please cite any use of the Icepack code.** More information can be found at :ref:`citing`. 
+
+This document uses the following text conventions: Variable names used in 
+the code are ``typewritten``. Subroutine names are given in *italic*. File 
+and directory names are in **boldface**. A comprehensive :ref:`index`, 
+including glossary of symbols with many of their values, appears at the 
+end of this guide.

doc/source/intro/acknowledgements.rst

@@ -6,31 +6,19 @@ Acknowledgements
 =============================
 
 This work has been completed through the CICE Consortium and its members with funding 
-through the 
-Department of Energy,
-Department of Defense (Navy),
-Department of Commerce (NOAA),
-National Science Foundation
-and Environment and Climate Change Canada.
-Special thanks are due to the following people:
+through the
 
--  Elizabeth Hunke, Nicole Jeffery, Adrian Turner and Chris Newman at Los Alamos National Laboratory
-
--  David Bailey, Alice DuVivier and Marika Holland at the National Center for Atmospheric Research
+- Department of Energy (Los Alamos National Laboratory)
 
--  Rick Allard, Matt Turner and David Hebert at the Naval Research Laboratory, Stennis Space Center,
+- Department of Defense (Navy)
 
--  Andrew Roberts of the Naval Postgraduate School,
+- Department of Commerce (National Oceanic and Atmospheric Administration)
 
--  Michael Winton and Anders Damsgaard of the Geophysical Fluid Dynamics Laboratory,
+- National Science Foundation (the National Center for Atmospheric Research)
 
--  Jean-Francois Lemieux and Frederic Dupont of Environment and Climate Change Canada,
+- Environment and Climate Change Canada.
 
--  Tony Craig and his supporters at the National Center for Atmospheric Research, the Naval Postgraduate School, and NOAA National Weather Service,
+Special thanks are due to participants from these institutions and many others 
+who contributed to previous versions of CICE or Icepack.
 
--  Jessie Carman and Robert Grumbine of the National Oceanographic and Atmospheric Administration
-
--  Cecilia Bitz of the University of Washington, for her column forcing data,
-
--  and many others who contributed to previous versions of CICE.
 

doc/source/intro/citing.rst

@@ -0,0 +1,18 @@
+:tocdepth: 3
+
+.. _citing:
+
+Citing the Icepack code
+=======================
+
+If you use the Icepack code, please cite the version you are using 
+with the Icepack Digital Object Identifier (DOI):
+
+DOI:10.5281/zenodo.1213462 (https://zenodo.org/record/1213462) 
+
+This DOI can be used to cite all Icepack versions and the URL will default to the most recent version. 
+However, each released version of Icepack will also receive its own, unique DOI that can be 
+used for citations as well.
+
+Please also make the CICE Consortium aware of any publications and model use.
+

doc/source/intro/copyright.rst

@@ -5,12 +5,12 @@
 Copyright
 =============================
 
-© Copyright 2018, Los Alamos National Security LLC. All rights reserved. 
+© Copyright 2018, Triad National Security LLC. All rights reserved. 
 This software was produced under U.S. Government contract 
-DE-AC52-06NA25396 for Los Alamos National Laboratory (LANL), which is
-operated by Los Alamos National Security, LLC for the U.S. Department
+89233218CNA000001 for Los Alamos National Laboratory (LANL), which is
+operated by Triad National Security, LLC for the U.S. Department
 of Energy. The U.S. Government has rights to use, reproduce, and distribute
-this software. NEITHER THE GOVERNMENT NOR LOS ALAMOS NATIONAL SECURITY, LLC
+this software. NEITHER THE GOVERNMENT NOR TRIAD NATIONAL SECURITY, LLC
 MAKES ANY WARRANTY, EXPRESS OR IMPLIED, OR ASSUMES ANY LIABILITY FOR THE USE
 OF THIS SOFTWARE. If software is modified to produce derivative works, such
 modified software should be clearly marked, so as not to confuse it with the
@@ -24,9 +24,9 @@ are met:
 
 - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
 
-- Neither the name of Los Alamos National Security, LLC, Los Alamos National Laboratory, LANL, the U.S. Government, nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+- Neither the name of Triad National Security, LLC, Los Alamos National Laboratory, LANL, the U.S. Government, nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
 
-THIS SOFTWARE IS PROVIDED BY LOS ALAMOS NATIONAL SECURITY, LLC AND
+THIS SOFTWARE IS PROVIDED BY TRIAD NATIONAL SECURITY, LLC AND
 CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
 NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL LOS ALAMOS NATIONAL

doc/source/intro/index.rst

@@ -13,7 +13,7 @@ Introduction - Icepack
 
    about.rst
    quickstart.rst
-   major_updates.rst
    acknowledgements.rst
+   citing.rst
    copyright.rst
 

doc/source/intro/quickstart.rst

@@ -10,7 +10,7 @@ Download the model from the CICE-Consortium repository,
     https://github.com/CICE-Consortium/Icepack
 
 Instructions for working in github with Icepack (and CICE) can be
-found in the `CICE Git and Workflow Guide <https://docs.google.com/document/d/1rR6WAvZQT9iAMUp-m_HZ06AUCCI19mguFialsMCYs9o>`_.
+found in the `CICE Git and Workflow Guide <https://github.com/CICE-Consortium/About-Us/wiki/Git-Workflow-Guidance>`_.
 
 From your main Icepack directory, execute::
 
@@ -23,6 +23,8 @@ From your main Icepack directory, execute::
 The local machine name will have to be substituted for ``testmachine`` and
 there are working ports for several different machines.  However, it may be necessary
 to port the model to a new machine.  See :ref:`porting` for 
-more information about how to port and :ref:`scripts` for more information about 
-how to use the icepack.setup script.
+more information about how to port. See :ref:`scripts` for more information about 
+how to use the icepack.setup and icepack.submit scripts.
+
+Please cite any use of the Icepack code. More information can be found at :ref:`citing`.
 

doc/source/science_guide/index.rst

@@ -9,7 +9,7 @@ Science Guide
 -----------------
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
 
    sg_boundary_forcing.rst
    sg_itd.rst

doc/source/science_guide/sg_boundary_forcing.rst

@@ -11,37 +11,38 @@ Atmosphere and ocean boundary forcing
    :header: "Variable", "Description", "External Interactions"
    :widths: 10, 25, 25
 
-   ":math:`z_o`", "Atmosphere level height", "From *atmosphere model*  **to** *sea ice model*"
-   ":math:`\vec{U}_a`", "Wind velocity", "From *atmosphere model*  **to** *sea ice model*"
-   ":math:`Q_a`", "Specific humidity", "From *atmosphere model*  **to** *sea ice model*"
-   ":math:`\rho_a`", "Air density", "From *atmosphere model*  **to** *sea ice model*"
-   ":math:`\Theta_a`", "Air potential temperature", "From *atmosphere model*  **to** *sea ice model*"
-   ":math:`T_a`", "Air temperature", "From *atmosphere model*  **to** *sea ice model*"
-   ":math:`F_{sw\downarrow}`", "Incoming shortwave radiation (4 bands)", "From *atmosphere model*  **to** *sea ice model*"
-   ":math:`F_{L\downarrow}`", "Incoming longwave radiation", "From *atmosphere model*  **to** *sea ice model*"
-   ":math:`F_{rain}`", "Rainfall rate", "From *atmosphere model*  **to** *sea ice model*"
-   ":math:`F_{snow}`", "Snowfall rate", "From *atmosphere model*  **to** *sea ice model*"
-   ":math:`F_{frzmlt}`", "Freezing/melting potential", "From *ocean model*  **to** *sea ice model*"
-   ":math:`T_w`", "Sea surface temperature", "From *ocean model*  **to** *sea ice model*"
-   ":math:`S`", "Sea surface salinity", "From *ocean model*  **to** *sea ice model*"
-   ":math:`\vec{U}_w`", "Surface ocean currents", "From *ocean model*  **to** *sea ice model* (available in Icepack driver, not used directly in column physics)"
-   ":math:`\vec{\tau}_a`", "Wind stress", "From *sea ice model*  **to** *atmosphere model*"
-   ":math:`F_s`", "Sensible heat flux", "From *sea ice model*  **to** *atmosphere model*"
-   ":math:`F_l`", "Latent heat flux", "From *sea ice model*  **to** *atmosphere model*"
-   ":math:`F_{L\uparrow}`", "Outgoing longwave radiation", "From *sea ice model*  **to** *atmosphere model*"
-   ":math:`F_{evap}`", "Evaporated water", "From *sea ice model*  **to** *atmosphere model*"
-   ":math:`\alpha`", "Surface albedo (4 bands)", "From *sea ice model*  **to** *atmosphere model*"
-   ":math:`T_{sfc}`", "Surface temperature", "From *sea ice model*  **to** *atmosphere model*"
-   ":math:`F_{sw\Downarrow}`", "Penetrating shortwave radiation", "From *sea ice model*  **to** *ocean model*"
-   ":math:`F_{water}`", "Fresh water flux", "From *sea ice model*  **to** *ocean model*"
-   ":math:`F_{hocn}`", "Net heat flux to ocean", "From *sea ice model*  **to** *ocean model*"
-   ":math:`F_{salt}`", "Salt flux", "From *sea ice model*  **to** *ocean model*"
-   ":math:`\vec{\tau}_w`", "Ice-ocean stress", "From *sea ice model*  **to** *ocean model*"
-   ":math:`F_{bio}`", "Biogeochemical fluxes", "From *sea ice model*  **to** *ocean model*"
-   ":math:`a_{i}`", "Ice fraction", "From *sea ice model*  **to** both *ocean and atmosphere models*"
-   ":math:`T^{ref}_{a}`", "2m reference temperature (diagnostic)", "From *sea ice model*  **to** both *ocean and atmosphere models*"
-   ":math:`Q^{ref}_{a}`", "2m reference humidity (diagnostic)", "From *sea ice model*  **to** both *ocean and atmosphere models*"
-   ":math:`F_{swabs}`", "Absorbed shortwave (diagnostic)", "From *sea ice model*  **to** both *ocean and atmosphere models*"
+   ":math:`z_o`", "Atmosphere level height", "From *atmosphere model* to *sea ice model*"
+   ":math:`\vec{U}_a`", "Wind velocity", "From *atmosphere model* to *sea ice model*"
+   ":math:`Q_a`", "Specific humidity", "From *atmosphere model* to *sea ice model*"
+   ":math:`\rho_a`", "Air density", "From *atmosphere model* to *sea ice model*"
+   ":math:`\Theta_a`", "Air potential temperature", "From *atmosphere model* to *sea ice model*"
+   ":math:`T_a`", "Air temperature", "From *atmosphere model* to *sea ice model*"
+   ":math:`F_{sw\downarrow}`", "Incoming shortwave radiation (4 bands)", "From *atmosphere model* to *sea ice model*"
+   ":math:`F_{L\downarrow}`", "Incoming longwave radiation", "From *atmosphere model* to *sea ice model*"
+   ":math:`F_{rain}`", "Rainfall rate", "From *atmosphere model* to *sea ice model*"
+   ":math:`F_{snow}`", "Snowfall rate", "From *atmosphere model* to *sea ice model*"
+   ":math:`F_{frzmlt}`", "Freezing/melting potential", "From *ocean model* to *sea ice model*"
+   ":math:`T_w`", "Sea surface temperature", "From *ocean model* to *sea ice model*"
+   ":math:`S`", "Sea surface salinity", "From *ocean model* to *sea ice model*"
+   ":math:`\nabla H_o`", "Sea surface slope", "From *ocean model* via flux coupler to *sea ice model*"
+   ":math:`\vec{U}_w`", "Surface ocean currents", "From *ocean model* to *sea ice model* (available in Icepack driver, not used directly in column physics)"
+   ":math:`\vec{\tau}_a`", "Wind stress", "From *sea ice model* to *atmosphere model*"
+   ":math:`F_s`", "Sensible heat flux", "From *sea ice model* to *atmosphere model*"
+   ":math:`F_l`", "Latent heat flux", "From *sea ice model* to *atmosphere model*"
+   ":math:`F_{L\uparrow}`", "Outgoing longwave radiation", "From *sea ice model* to *atmosphere model*"
+   ":math:`F_{evap}`", "Evaporated water", "From *sea ice model* to *atmosphere model*"
+   ":math:`\alpha`", "Surface albedo (4 bands)", "From *sea ice model* to *atmosphere model*"
+   ":math:`T_{sfc}`", "Surface temperature", "From *sea ice model* to *atmosphere model*"
+   ":math:`F_{sw\Downarrow}`", "Penetrating shortwave radiation", "From *sea ice model* to *ocean model*"
+   ":math:`F_{water}`", "Fresh water flux", "From *sea ice model* to *ocean model*"
+   ":math:`F_{hocn}`", "Net heat flux to ocean", "From *sea ice model* to *ocean model*"
+   ":math:`F_{salt}`", "Salt flux", "From *sea ice model* to *ocean model*"
+   ":math:`\vec{\tau}_w`", "Ice-ocean stress", "From *sea ice model* to *ocean model*"
+   ":math:`F_{bio}`", "Biogeochemical fluxes", "From *sea ice model* to *ocean model*"
+   ":math:`a_{i}`", "Ice fraction", "From *sea ice model* to both *ocean and atmosphere models*"
+   ":math:`T^{ref}_{a}`", "2m reference temperature (diagnostic)", "From *sea ice model* to both *ocean and atmosphere models*"
+   ":math:`Q^{ref}_{a}`", "2m reference humidity (diagnostic)", "From *sea ice model* to both *ocean and atmosphere models*"
+   ":math:`F_{swabs}`", "Absorbed shortwave (diagnostic)", "From *sea ice model* to both *ocean and atmosphere models*"
 
 The ice fraction :math:`a_i` (aice) is the total fractional ice
 coverage of a grid cell. That is, in each cell,
@@ -65,25 +66,25 @@ treated identically (land also may occupy less than 100% of an
 atmospheric grid cell). These fluxes are "per unit ice area" rather than
 "per unit grid cell area."
 
-In some coupled climate models (for example, recent versions of the U.K.
-Hadley Centre model) the surface air temperature and fluxes are computed
-within the atmosphere model and are passed to CICE for use in the column physics. In this case the
-logical parameter ``calc_Tsfc`` in *ice_therm_vertical* is set to false.
-The fields ``fsurfn`` (the net surface heat flux from the atmosphere), ``flatn``
-(the surface latent heat flux), and ``fcondtopn`` (the conductive flux at
-the top surface) for each ice thickness category are copied or derived
-from the input coupler fluxes and are passed to the thermodynamic driver
-subroutine, *thermo_vertical*. At the end of the time step, the surface
-temperature and effective conductivity (i.e., thermal conductivity
-divided by thickness) of the top ice/snow layer in each category are
-returned to the atmosphere model via the coupler. Since the ice surface
-temperature is treated explicitly, the effective conductivity may need
-to be limited to ensure stability. As a result, accuracy may be
-significantly reduced, especially for thin ice or snow layers. A more
-stable and accurate procedure would be to compute the temperature
-profiles for both the atmosphere and ice, together with the surface
-fluxes, in a single implicit calculation. This was judged impractical,
-however, given that the atmosphere and sea ice models generally exist on
+In some coupled climate models (for example, recent versions of the U.K.	
+Hadley Centre model) the surface air temperature and fluxes are computed	
+within the atmosphere model and are passed to CICE for use in the column physics. In this case the	
+logical parameter ``calc_Tsfc`` in *ice_therm_vertical* is set to false.	
+The fields ``fsurfn`` (the net surface heat flux from the atmosphere), ``flatn``	
+(the surface latent heat flux), and ``fcondtopn`` (the conductive flux at	
+the top surface) for each ice thickness category are copied or derived	
+from the input coupler fluxes and are passed to the thermodynamic driver	
+subroutine, *thermo_vertical*. At the end of the time step, the surface	
+temperature and effective conductivity (i.e., thermal conductivity	
+divided by thickness) of the top ice/snow layer in each category are	
+returned to the atmosphere model via the coupler. Since the ice surface	
+temperature is treated explicitly, the effective conductivity may need	
+to be limited to ensure stability. As a result, accuracy may be	
+significantly reduced, especially for thin ice or snow layers. A more	
+stable and accurate procedure would be to compute the temperature	
+profiles for both the atmosphere and ice, together with the surface	
+fluxes, in a single implicit calculation. This was judged impractical,	
+however, given that the atmosphere and sea ice models generally exist on	
 different grids and/or processor sets.
 
 .. _atmo: