ExeClim · daw538 · Nov 10, 2022 · Nov 10, 2022 · Nov 10, 2022 · Nov 10, 2022
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,6 @@
 # Project-specific
 compilation*/
-docs/source/examples/index.rst
+# docs/source/examples/index.rst
 exec.*/
 exp/st_test*
 exp/archived/*

diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst
@@ -0,0 +1,69 @@
+.. _examples:
+
+Examples
+========
+
+Test Cases
+----------
+
+Isca provides a number of example test cases, located within ``src/test_cases``, which can be used as a basis for constructing your own model. These examples vary in complexity and a number make use of additional scripts which are also listed below.
+
+- **APE Aquaplanet:** Aquaplanet control experiment based off Blackburn et al. 2013, and first described as the control experiment by Neale & Hoskins 2004. [Blackburn2013]_ [Neale2004]_
+- **Axisymmetric:** Model setup with zonal-mean dynamics enforced, i.e. a run without eddies. Uses prescribed SSTs and vertical diffusion.
+- **Bucket Hydrology:** As described in the first Isca paper by Vallis et al., 2017  but without q-fluxes. [Vallis2017]_
+- **Frierson:** Control case of the so-called `Frierson model` described in Frierson et al. 2006. [Frierson2006a]_
+- **Giant Planet:** Control case of the Jupiter simulation defined by Schneider & Liu 2009. [Schneider2009]_
+- **Held Suarez:** Commonly-used dynamical-core test case described by Held & Suarez 1994. [Held1994]_
+- **MiMA:** CNTL case of the MiMA model described by Jucker & Gerber 2007. [Jucker2017]_
+- **Realistic Continents:** A more complex model including realistic continents, realistic topography, a simple ice model, and the option of prescribed AMIP SSTs or prescribed q-fluxes derived from AMIP ssts. Same setup used in Thomson & Vallis  2019; also described in the Isca paper. [Thomson_and_Vallis2019]_
+- **Simple Cloud:** An extension of the above Realistic Continents case, using the SOCRATES radiation scheme and the addition of a simple cloud scheme: SimCloud (described in Liu et al. 2021). [Liu2021]_
+- **SOCRATES:** A number of similar test cases all making use of the SOCRATES radiation scheme described in Manners et al. 2015. [MannersEtAl2015]_
+- **Top Down:** A general thermal relaxation scheme allowing seasonal variation, dependent on atmospheric and orbital parameters.
+- **Variable CO2 Concentration:** Example experiments with a time-varying co2 concentration read-in from an input file. Examples are given with varying co2 in the `Byrne & O'Gorman radiation scheme <https://doi.org/10.1175/JCLI-D-12-00262.1>`_ and RRTM. [Byrne2013]_
+
+.. note::
+
+   These examples provide practical ways to illustrate the usage of the software, and do not necessarily represent the best scientific methods for any particular type of study.
+
+
+Auxiliary Scripts
+-----------------
+
+A number of these scripts can be used to help construct input files for a model, whilst others may be used for verification or post-processing of model data.
+
+- Create land-mask: ``src/extra/python/gfdl/land_generator_fn.py``
+- Make SST climatology: ``src/extra/python/scripts/create_amip_sst_timeseries.py``
+- Make time-varying q-fluxes: ``src/extra/python/scripts/calculate_qflux/calculate_qflux.py``
+- Make CO2 concentration input file: ``src/extra/python/scripts/create_co2_timeseries.py``
+- Interpolate from model sigma levels to pressure levels: ``postprocessing/plevel_interpolation/scripts/run_plevel.py``
+- Explore options for vertical co-ordinates: ``src/extra/python/scripts/vert_coord_options.py``
+- Display options for horizontal resolution: ``src/extra/python/scripts/resolutions.py``
+- Change horizontal resolution part-way through a run: ``src/extra/python/scripts/change_horizontal_resolution_of_restart_file.py``
+- Check if simulation is spun-up: ``src/extra/python/scripts/general_spinup_fn.py``
+- Alter input file so model's linear interpolator preserves monthly-means: ``src/extra/python/scripts/edit_nc_file_to_preserve_monthly_means.py``
+- Plot how long a run is taking to calculate each month: ``src/extra/python/scripts/modified_time_script.py``
+
+
+References
+----------
+
+| [Blackburn2013]_
+| [Byrne2013]_
+| [Frierson2006a]_
+| [Held1994]_
+| [Neale2004]_
+| [Jucker2017]_
+| [Liu2021]
+| [MannersEtAl2015]_
+| [Schneider2009]_
+| [Thomson_and_Vallis2019]_
+| [Vallis2017]_
+
+
+Authors
+-------
+This documentation was written by Daniel Williams and reviewed by <name>
+
+
+
+
diff --git a/docs/source/modules/index.rst b/docs/source/modules/index.rst
@@ -12,13 +12,14 @@ Components of Isca
    physics
    constants
    output
+   diag_manager_mod
    damping_driver
    idealised_moist_phys
+   mixedlayer
+   surface_flux
    two_stream_gray_rad
    convection_simple_betts_miller
    lscale_cond
    topography
    socrates
-   mixedlayer
-   surface_flux
-   diag_manager_mod
+   simcloud
diff --git a/docs/source/modules/simcloud.rst b/docs/source/modules/simcloud.rst
@@ -0,0 +1,65 @@
+Cloud Scheme (SimCloud)
+=======================
+
+Summary
+-------
+Isca provides a simple diagnostic cloud scheme, SimCloud, originally developed and described in [Liu2021]_. The model diagnoses clouds in three different ways: (1) large-scale clouds from the relative humidity; (2) low-level marine stratus clouds from a function of local inversion strength; and (3) a "freeze-dry" adjustment based on a simple function of specific humidity is also available to reduce an excessive cloud bias in polar regions. Cloud properties such as the effective radius of cloud droplet and cloud liquid water content are specified as simple functions of temperature, and parameters of the model may be tuned individually to suit requirements.
+
+The cloud scheme may be found in the directory ``src/atmos_param/cloud_simple``, with tuneable parameters found therein.
+
+A demonstration test case is provided within Isca's test suite of experiments. The scheme is provided on an as-in basis: parameters have been tuned for an Earth-like demonstration so any deviations from such a setup or modifications to the parameterisation are at your own risk. The model should be used with the SOCRATES radiation scheme.
+
+Diagnostics
+-----------
+There are a number of different diagnostic outputs available with the cloud scheme. These are found across different diagnostic groups which are detailed below.
+
+Basic Diagnostics
+^^^^^^^^^^^^^^^^^
+These diagnostics are part of the ``cloud_simple`` module and describe the overall state of the cloud.
+
++--------------------------+-----------------------------------------------------+--------------------+-------------------------------+
+| Name                     | Description                                         | Units              | Dimension (not including time)|
++==========================+=====================================================+====================+===============================+
+|``cf``                    | Cloud fraction for the simple cloud scheme          | dimensionless (0-1)| (pfull, lat, lon)             |
++--------------------------+-----------------------------------------------------+--------------------+-------------------------------+
+|``frac_liq``              | Liquid cloud fraction (liquid, mixed-ice phase, ice)| dimensionless (0-1)| (pfull, lat, lon)             |
++--------------------------+-----------------------------------------------------+--------------------+-------------------------------+
+|``reff_rad``              | Effective cloud particle radius                     | :math:`\mu` m      | (pfull, lat, lon)             |
++--------------------------+-----------------------------------------------------+--------------------+-------------------------------+
+|``qcl_rad``               | Specific humidity of cloud liquid                   | kg kg :math:`^{-1}`| (phalf, lat, lon)             |
++--------------------------+-----------------------------------------------------+--------------------+-------------------------------+
+|``rh_in_cf``              | RH as a percent                                     | :math:`\%`         | (phalf, lat, lon)             |
++--------------------------+-----------------------------------------------------+--------------------+-------------------------------+
+
+Cloud Coverage
+^^^^^^^^^^^^^^
+The module ``cloud_cover`` provides additional diagnostics to show spatial coverage of clouds in the lat-lon direction; additionally split into different levels of clouds.
+
++------------------+-----------------------------+------------+-------------------------------+
+| Name             | Description                 | Units      | Dimension (not including time)|
++==================+=============================+============+===============================+
+|``tot_cld_amt``   | Total cloud amount (%)      | :math:`\%` | (lat, lon)                    |
++------------------+-----------------------------+------------+-------------------------------+
+|``high_cld_amt``  | High level cloud amount (%) | :math:`\%` | (lat, lon)                    |
++------------------+-----------------------------+------------+-------------------------------+
+|``mid_cld_amt``   | Hid-level cloud amount (%)  | :math:`\%` | (lat, lon)                    |
++------------------+-----------------------------+------------+-------------------------------+
+|``low_cld_amt``   | Low level cloud amount (%)  | :math:`\%` | (lat, lon)                    |
++------------------+-----------------------------+------------+-------------------------------+
+
+Marine Stratospheric Clouds
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+There are additional diagnostics specifically relating to marine stratospheric clouds available in the module ``strat_cloud``. These are primarily available for test purposes so are not detailed here, however they may be accessed in the routine ``marine_strat_cloud.F90`` within the cloud scheme directory.
+
+
+Relevant modules and subroutines
+--------------------------------
+The SOCRATES radiation scheme is setup in ``src/atmos_param/socrates/interface/``.
+
+References
+----------
+[Liu2021]_
+
+Authors
+-------
+This documentation was written by Daniel Williams (with thanks to Qun Liu for implementing the model).
diff --git a/docs/source/references.rst b/docs/source/references.rst
@@ -16,6 +16,11 @@ References
            *Quarterly Journal of the Royal Meteorological Society*,
            **112(473)**, 693--709,
            doi: `10.1002/qj.49711247308 <http://dx.doi.org/10.1002/qj.49711247308>`_.
+
+.. [Blackburn2013] Blackburn, M., Williamson, D. L., Nakajima, K., Ohfuchi, W., Takahashi, Y. O., Hayashi, Y., Nakamura, H., Ishiwatari, M., McGregor, J. L., Borth, H., Wirth, V., Frank, H., Bechtold, P., Wedi, N. P., Tomita, H., Satoh, M., Zhao, M., Held, I. M., Suarez, M. J., Lee, M., Watanabe, M., Kimoto, M., Liu, Y., Wang, Z., Molod, A., Rajendran, K., Kitoh, A., Statton, R, 2013: The Aqua-Planet Experiment (APE): CONTROL SST Simulation.
+           *Journal of the Meteorological Society of Japan. Ser. II*
+           **91A**, 17-56
+           doi: `https://doi.org/10.2151/jmsj.2013-A02 <10.2151/jmsj.2013-A02>`_.
 
 .. [Byrne2013] Byrne, M. P. and O’Gorman, P. A., 2013: Land–ocean warming contrast over a wide range of climates: Convective quasi-equilibrium the- ory and idealized simulations, *J. Climate*, **26**, doi.
 
@@ -34,15 +39,27 @@ References
 .. [Gierasch2000] Gierasch, P.J., Ingersoll, A.P., Banfield, D., Ewald, S.P., Helfenstein, P., Simon-Miller, A., Vasavada, A., Breneman,                 H.H., Senske, D.A. and Team, G.I., 2000: 
            Observation of moist convection in Jupiter's atmosphere. 
            *Nature*,
-           **403(6770)**, 628--630.
+           **403(6770)**, 628--630,
            doi: `10.1038/35001017 <https://doi.org/10.1038/35001017>`_.
 
+.. [Held1994] Held, I. M. and Suarez, M. J, 1994:
+           A Proposal for the Intercomparison of the Dynamical Cores of Atmospheric General Circulation Models
+           *Bulletin of the American Meteorological Society*
+           **75(10)**, 1825--1830
+           doi: `10.1175/1520-0477(1994)075\<1825:APFTIO\>2.0.CO;2 <https://doi.org/10.1175/1520-0477(1994)075\<1825:APFTIO\>2.0.CO;2>`_.
+
 .. [Jucker2017] Jucker, M. and Gerber, E. P., 2017:
            Untangling the Annual Cycle of the Tropical Tropopause Layer with an Idealized Moist Model.
            *Journal of Climate*,
            **30(18)**, 7339--7358,
            doi: `10.1175/JCLI-D-17-0127.1 <https://doi.org/10.1175/JCLI-D-17-0127.1>`_.
 
+.. [Neale2004] Neale, R. B. and Hoskins, B. J, 2004:
+           A standard test for AGCMs including their physical parametrizations: I: the proposal.
+           *Atmospheric Science Letters*,
+           **1(2)**, 101-107,
+           doi: `10.1006/asle.2000.0022 <https://doi.org/10.1006/asle.2000.0022>`_.
+
 .. [OGormanSchneider2008] O'Gorman, P. and Schneider, T., 2008:
            The Hydrological Cycle over a Wide Range of Climates Simulated with an Idealized GCM.
            *Journal of Climate*,
@@ -55,6 +72,12 @@ References
            **No. NCAR/TN-460+STR**,
            doi: `10.5065/D6KK98Q6 <http://dx.doi.org/10.5065/D6KK98Q6>`_.
 
+.. [Liu2021] Liu, Q. and Collins, M. and Maher, P. and Thomson, S. I. and Vallis, G. K.:
+           SimCloud version 1.0: a simple diagnostic cloud scheme for idealized climate models.
+           *Geoscientific Model Development*
+           **14**, 2801--2826
+           doi: 10.5194/gmd-14-2801-2021
+
 .. [Manabe1969] Manabe, S. 1969:
            Climate and the Ocean Circulation: I. The Atmopsheric Circulation and the Hydrology of the Earth's Surface.
            *Mon. Wea. Rev.*