Merge pull request #7 from mvertens/feature/add_testing_section

Addition of testing section and fixes of sphinx warnings Thanks to the CTSM software engineering team for providing a starting point for this document:
NorESMhub · Jul 26, 2023 · 6d45d89 · 6d45d89
2 parents 75edd19 + 9eaf734
commit 6d45d89
Show file tree

Hide file tree

Showing 20 changed files with 993 additions and 108 deletions.
diff --git a/conf.py b/conf.py
@@ -61,7 +61,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

diff --git a/configurations/model_cost.rst b/configurations/model_cost.rst
@@ -24,6 +24,7 @@ Output:
    Storage size required for model output
 
 .. table:: NorESM2-LM CMIP experiments on Betzy
+
 +----------------+------------+------+---------+--------+-------+--------+--------+
 |Experiment      | Grid       | PES  | Cost    | Thrput | STime | RTime  | Output |
 +================+============+======+=========+========+=======+========+========+
@@ -32,6 +33,7 @@ Output:
 +----------------+------------+------+---------+--------+-------+--------+--------+
 
 .. table:: NorESM2 OMIP experiments on Betzy
+
 +----------------+------------+------+---------+--------+-------+--------+--------+
 |Experiment      | Grid       | PES  | Cost    | Thrput | STime | RTime  | Output |
 +================+============+======+=========+========+=======+========+========+

diff --git a/configurations/output.rst b/configurations/output.rst
@@ -1,38 +1,39 @@
 :orphan:
+
 .. _output:
 
 Output and standard results
-===================================
+===========================
 
 NorESM2 output
 ^^^^^^^^^^^^^^
 
 During a model run, each component (i.e. atm, lnd, ocn, cice, rof) produces its own output datasets consisting of history, restart and output log files. By default, each component periodically writes
 
-- history files (usually monthly) in netCDF format 
-   
+- history files (usually monthly) in netCDF format
+
 - writes netCDF or binary restart files in the RUNDIR directory. The history and log files are controlled independently by each component. History output control (i.e. output fields and frequency) is set in the Build-conf/component.buildnml.csh files.
-   
-- Component history files and restart files are in netCDF format. 
- 
+
+- Component history files and restart files are in netCDF format.
+
 - Restart files are used to either restart the model or to serve as initial conditions for other model cases.
 
-For details about how to modify the user namelists to modify the output, please see **User namelists** in :ref:`experiment_environment`. 
+For details about how to modify the user namelists to modify the output, please see **User namelists** in :ref:`experiment_environment`.
 
-Archiving is a phase of the model run where the generated output data is moved from RUNDIR to the archive folder. This job needs its own cpu time which is set in env_batch.xml. 
+Archiving is a phase of the model run where the generated output data is moved from RUNDIR to the archive folder. This job needs its own cpu time which is set in env_batch.xml.
 
 
 Atmospheric output for some commonly used configurations of NorESM2
 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
-In preparation for CMIP6 and the required model output for the various 
-MIPs, NorESM2 has been set up with different configurations, all run as 
-AMIP using the compset NF2000climo (on 2 degrees) in noresm-dev (2.0: 
-commit 7757f2d from October 30'th 2018; 
-(2.1: COMMIT 35b90aab from March 25'th 
-2019) The given estimates in CPU-time increase are based on 1 month 
-simulations, including model initialization, and are therefore low end 
-estimates. 
+In preparation for CMIP6 and the required model output for the various
+MIPs, NorESM2 has been set up with different configurations, all run as
+AMIP using the compset NF2000climo (on 2 degrees) in noresm-dev (2.0:
+commit 7757f2d from October 30'th 2018;
+(2.1: COMMIT 35b90aab from March 25'th
+2019) The given estimates in CPU-time increase are based on 1 month
+simulations, including model initialization, and are therefore low end
+estimates.
 
 With standard set-up of the model, the monthly output variables (1, 2
 and 3 D) are:

diff --git a/configurations/simplified_models.rst b/configurations/simplified_models.rst
@@ -1,11 +1,12 @@
 :orphan:
+
 .. _simplified_models:
 
 Simplified setup
-'''''''''''''''''''''''
+''''''''''''''''
 
-Slab ocean 
-^^^^^^^^^^^^
+Slab ocean
+^^^^^^^^^^
 
 The slab ocean configuration is under development.
 

diff --git a/contribute/contribute.rst b/contribute/contribute.rst
@@ -31,4 +31,3 @@ of the code.
    vc_github.rst
    fork_workflow.rst
    gitbestpractice.rst
-
diff --git a/faq/tech_faq.rst b/faq/tech_faq.rst
@@ -5,13 +5,13 @@ Technical FAQ
 
 
 How do I check the timing and cost of my experiments?
--------------------------------------------------
+-----------------------------------------------------
 
 You will find a detailed overview of the model cost, throughput and run time for each model component in a subfolder named ``timing`` in the case folder (e.g. in ``~/NorESM/cases/<casename>/timing/``)
 The filename is on the form ``cesm_timing.<casename>.JOBID.yymmdd-hhmmss``
 
 My model experiment/simulation crashes and I don't know why!
--------------------------------------------------------------
+------------------------------------------------------------
 If you experience crashes while setting up, building, submitting or archiving the experiment, you may find useful information in the log file in the casefolder (e.g. in ``~/NorESM/cases/<casename>/``). The filename is the same as the 15 first letters of the casename with no file extension. If you don't find a solution to your problem please post your question here: https://github.com/NorESMhub/NorESM/discussions
 
 

diff --git a/index.rst b/index.rst
@@ -43,6 +43,7 @@ For obtaining news per email register to users@noresm.org at https://www.noresm.
    keyruns/keyruns.rst
    data/data.rst
    contribute/contribute.rst
+   testing/systemtests.rst
    developers/developers.rst
    faq/faq.rst
 

diff --git a/output/aerosol_output.rst b/output/aerosol_output.rst
@@ -1,7 +1,7 @@
 .. _aerosol_output:
 
 Aerosol diagnostics and output
-===============================
+==============================
 
 
 Configuring a run with more aerosol diagnostics in NorESM2
@@ -18,7 +18,7 @@ Adding ``history_aerosol = .true.`` to ``user_nl_cam gives`` additional 577 vari
 Please see an overview of additional output varibales: :ref:`aerosol_output_history_aerosol_variables`
 
 Decomposition of aerosol direct, semidirect and indirect radiative forcing
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 For effective radiative forcing estimates, multiple calls to the radiation code are necessary (see Ghan et al. 2012 for a detailed explanation). To enable this, copy the file ``preprocessorDefinitions.h`` from to the ``SourceMods/src.cam/`` folder in your case directory::
 
@@ -42,7 +42,7 @@ to ``preprocessorDefinitions.h`` gives 8 additionally variables (+ ca. 5% CPU-ti
 
 
 Enable diagnostics for AEROCOM
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 NorESM2 can be set up to take out additional aerosol output for use in AeroCom (https://aerocom.met.no/index.html) or other studies where there is a need for extensive aerosol diagnostics. To enable this, copy the file ``preprocessorDefinitions.h`` from to the ``SourceMods/src.cam/`` folder in your case directory::
 
   cp <noresm_base>/components/cam/src/physics/cam_oslo/preprocessorDefinitions.h <case_folder>/SourceMods/src.cam/.

diff --git a/output/aerosol_output_aerocom_variables.rst b/output/aerosol_output_aerocom_variables.rst
@@ -1,4 +1,5 @@
 :orphan:
+
 .. _aerosol_output_aerocom_variables:
 
 AEROCOM extra output

diff --git a/output/aerosol_output_aeroffl_variables.rst b/output/aerosol_output_aeroffl_variables.rst
@@ -1,4 +1,5 @@
 :orphan:
+
 .. _aerosol_output_aeroffl_variables:
 
 AEROFFL extra output

diff --git a/output/aerosol_output_history_aerosol_variables.rst b/output/aerosol_output_history_aerosol_variables.rst
@@ -1,4 +1,5 @@
 :orphan:
+
 .. _aerosol_output_history_aerosol_variables:
 
 history_aerosol extra output

diff --git a/output/blom_standard_out.rst b/output/blom_standard_out.rst
@@ -1,11 +1,12 @@
 :orphan:
+
 .. _blom_standard_out:
 
-BLOM standard set-up output  
-''''''''''''''''''''''''''''''
+BLOM standard set-up output
+'''''''''''''''''''''''''''
 
-Monthly averaged output  
-^^^^^^^^^^^^^^^^^^^^^^^^
+Monthly averaged output
+^^^^^^^^^^^^^^^^^^^^^^^
 
 | abswnd = "Absolute wind speed"    
 

diff --git a/output/cam_standard_out.rst b/output/cam_standard_out.rst
@@ -1,4 +1,5 @@
 :orphan:
+
 .. _cam_standard_out:
 
 CAM6-Nor standard set-up output

diff --git a/output/cice_standard_out.rst b/output/cice_standard_out.rst
@@ -1,8 +1,9 @@
 :orphan:
+
 .. _cice_standard_out:
 
 CICE stadard set-up output
-'''''''''''''''''''''''''''''
+''''''''''''''''''''''''''
 
 | aice = "ice area  (aggregate)"
 | aicen = "ice area, categories"
@@ -132,4 +133,3 @@ CICE stadard set-up output
 | vicen = "ice volume, categories"
 | vsnon = "snow depth on ice, categories"
 | vvel = "ice velocity (y)"
-
diff --git a/output/clm_standard_out.rst b/output/clm_standard_out.rst
@@ -1,8 +1,9 @@
 :orphan:
+
 .. _clm_standard_out:
 
 CLM5 standard set-up output
-''''''''''''''''''''''''''''
+'''''''''''''''''''''''''''
 
 | mcdate = "current date (YYYYMMDD)"
 | mcsec = "current seconds of current date"
@@ -560,4 +561,3 @@ CLM5 standard set-up output
 | ZWT = "water table depth (vegetated landunits only)"
 | ZWT_CH4_UNSAT = "depth of water table for methane production used in non-inundated area"
 | ZWT_PERCH = "perched water table depth (vegetated landunits only)"
-
diff --git a/output/cosp_extra_output.rst b/output/cosp_extra_output.rst
@@ -1,74 +1,75 @@
 :orphan:
+
 .. _cosp_extra_output:
 
 COSP extra output
 '''''''''''''''''
 
-| cosp_prs:long_name = "COSP Mean ISCCP pressure" 
-| cosp_tau:long_name = "COSP Mean ISCCP optical depth" 
-| cosp_scol:long_name = "COSP subcolumn"  
-| cosp_ht:long_name = "COSP Mean Height for lidar and radar simulator outputs" 
-| cosp_sr:long_name = "COSP Mean Scattering Ratio for lidar simulator CFAD output" 
+| cosp_prs:long_name = "COSP Mean ISCCP pressure"
+| cosp_tau:long_name = "COSP Mean ISCCP optical depth"
+| cosp_scol:long_name = "COSP subcolumn"
+| cosp_ht:long_name = "COSP Mean Height for lidar and radar simulator outputs"
+| cosp_sr:long_name = "COSP Mean Scattering Ratio for lidar simulator CFAD output"
 | cosp_sza:long_name = "COSP Parasol SZA"
-| cosp_dbze:long_name = "COSP Mean dBZe for radar simulator CFADoutput" 
-| cosp_htmisr:long_name = "COSP MISR height" 
-| cosp_tau_modis:long_name = "COSP Mean MODIS optical depth" 
-| cosp_reffice:long_name = "COSP Mean MODIS effective radius (ice)" 
-| cosp_reffliq:long_name = "COSP Mean MODIS effective radius (liquid)" 
+| cosp_dbze:long_name = "COSP Mean dBZe for radar simulator CFADoutput"
+| cosp_htmisr:long_name = "COSP MISR height"
+| cosp_tau_modis:long_name = "COSP Mean MODIS optical depth"
+| cosp_reffice:long_name = "COSP Mean MODIS effective radius (ice)"
+| cosp_reffliq:long_name = "COSP Mean MODIS effective radius (liquid)"
 
 ----------------------------------------------------------------
 
-| CFAD_DBZE94_CS:long_name = "Radar Reflectivity Factor CFAD (94 GHz)" 
-| CFAD_SR532_CAL:long_name = "Lidar Scattering Ratio CFAD (532 nm)" 
+| CFAD_DBZE94_CS:long_name = "Radar Reflectivity Factor CFAD (94 GHz)"
+| CFAD_SR532_CAL:long_name = "Lidar Scattering Ratio CFAD (532 nm)"
 
 -----------------------------------------------------------------
 
-| CLDHGH_CAL:long_name = "Lidar High-level Cloud Fraction" 
-| CLDHGH_CAL_ICE:long_name = "Lidar High-level Ice Cloud Fraction" 
-| CLDHGH_CAL_LIQ:long_name = "Lidar High-level Liquid Cloud Fraction" 
+| CLDHGH_CAL:long_name = "Lidar High-level Cloud Fraction"
+| CLDHGH_CAL_ICE:long_name = "Lidar High-level Ice Cloud Fraction"
+| CLDHGH_CAL_LIQ:long_name = "Lidar High-level Liquid Cloud Fraction"
 | CLDHGH_CAL_UN:long_name = "Lidar High-level Undefined-Phase Cloud Fraction" ;
-| 
-| CLDLOW_CAL:long_name = "Lidar Low-level Cloud Fraction" 
-| CLDLOW_CAL_ICE:long_name = "Lidar Low-level Ice Cloud Fraction" 
-| CLDLOW_CAL_LIQ:long_name = "Lidar Low-level Liquid Cloud Fraction" 
-| CLDLOW_CAL_UN:long_name = "Lidar Low-level Undefined-Phase Cloud Fraction" 
-| 
-| CLDMED_CAL:long_name = "Lidar Mid-level Cloud Fraction" 
-| CLDMED_CAL_ICE:long_name = "Lidar Mid-level Ice Cloud Fraction" 
-| CLDMED_CAL_LIQ:long_name = "Lidar Mid-level Liquid Cloud Fraction" 
-| CLDMED_CAL_UN:long_name = "Lidar Mid-level Undefined-Phase Cloud Fraction" 
-| 
-| CLDTOT_CAL:long_name = "Lidar Total Cloud Fraction" 
-| CLDTOT_CALCS:long_name = " Lidar and Radar Total Cloud Fraction" 
-| CLDTOT_CAL_ICE:long_name = "Lidar Total Ice Cloud Fraction" 
-| CLDTOT_CAL_LIQ:long_name = "Lidar Total Liquid Cloud Fraction" 
-| CLDTOT_CAL_UN:long_name = "Lidar Total Undefined-Phase Cloud Fraction" 
-| CLDTOT_CS:long_name = " Radar total cloud amount" 
-| CLDTOT_CS2:long_name = " Radar total cloud amount without the data for the first kilometer above surface" 
-| CLDTOT_ISCCP:long_name = "Total Cloud Fraction Calculated by the ISCCP Simulator" 
-| 
-| CLD_CAL:long_name = "Lidar Cloud Fraction (532 nm)" 
-| CLD_CAL_ICE:long_name = "Lidar Ice Cloud Fraction" 
-| CLD_CAL_LIQ:long_name = "Lidar Liquid Cloud Fraction" 
-| CLD_CAL_NOTCS:long_name = "Cloud occurrence seen by CALIPSO but not CloudSat" 
-| CLD_CAL_UN:long_name = "Lidar Undefined-Phase Cloud Fraction"  
+|
+| CLDLOW_CAL:long_name = "Lidar Low-level Cloud Fraction"
+| CLDLOW_CAL_ICE:long_name = "Lidar Low-level Ice Cloud Fraction"
+| CLDLOW_CAL_LIQ:long_name = "Lidar Low-level Liquid Cloud Fraction"
+| CLDLOW_CAL_UN:long_name = "Lidar Low-level Undefined-Phase Cloud Fraction"
+|
+| CLDMED_CAL:long_name = "Lidar Mid-level Cloud Fraction"
+| CLDMED_CAL_ICE:long_name = "Lidar Mid-level Ice Cloud Fraction"
+| CLDMED_CAL_LIQ:long_name = "Lidar Mid-level Liquid Cloud Fraction"
+| CLDMED_CAL_UN:long_name = "Lidar Mid-level Undefined-Phase Cloud Fraction"
+|
+| CLDTOT_CAL:long_name = "Lidar Total Cloud Fraction"
+| CLDTOT_CALCS:long_name = " Lidar and Radar Total Cloud Fraction"
+| CLDTOT_CAL_ICE:long_name = "Lidar Total Ice Cloud Fraction"
+| CLDTOT_CAL_LIQ:long_name = "Lidar Total Liquid Cloud Fraction"
+| CLDTOT_CAL_UN:long_name = "Lidar Total Undefined-Phase Cloud Fraction"
+| CLDTOT_CS:long_name = " Radar total cloud amount"
+| CLDTOT_CS2:long_name = " Radar total cloud amount without the data for the first kilometer above surface"
+| CLDTOT_ISCCP:long_name = "Total Cloud Fraction Calculated by the ISCCP Simulator"
+|
+| CLD_CAL:long_name = "Lidar Cloud Fraction (532 nm)"
+| CLD_CAL_ICE:long_name = "Lidar Ice Cloud Fraction"
+| CLD_CAL_LIQ:long_name = "Lidar Liquid Cloud Fraction"
+| CLD_CAL_NOTCS:long_name = "Cloud occurrence seen by CALIPSO but not CloudSat"
+| CLD_CAL_UN:long_name = "Lidar Undefined-Phase Cloud Fraction"
 
 -----------------------------------------------------------------------------------
 
 | CLD_MISR:long_name = "Cloud Fraction from MISR Simulator"
-| CLHMODIS:long_name = "MODIS High Level Cloud Fraction" 
-| CLIMODIS:long_name = "MODIS Ice Cloud Fraction" 
-| CLLMODIS:long_name = "MODIS Low Level Cloud Fraction" 
-| CLMMODIS:long_name = "MODIS Mid Level Cloud Fraction" 
-| CLMODIS:long_name = "MODIS Cloud Area Fraction" 
-| CLRIMODIS:long_name = "MODIS Cloud Area Fraction" 
-| CLRLMODIS:long_name = "MODIS Cloud Area Fraction" 
-| CLTMODIS:long_name = "MODIS Total Cloud Fraction" 
-| CLWMODIS:long_name = "MODIS Liquid Cloud Fraction" 
+| CLHMODIS:long_name = "MODIS High Level Cloud Fraction"
+| CLIMODIS:long_name = "MODIS Ice Cloud Fraction"
+| CLLMODIS:long_name = "MODIS Low Level Cloud Fraction"
+| CLMMODIS:long_name = "MODIS Mid Level Cloud Fraction"
+| CLMODIS:long_name = "MODIS Cloud Area Fraction"
+| CLRIMODIS:long_name = "MODIS Cloud Area Fraction"
+| CLRLMODIS:long_name = "MODIS Cloud Area Fraction"
+| CLTMODIS:long_name = "MODIS Total Cloud Fraction"
+| CLWMODIS:long_name = "MODIS Liquid Cloud Fraction"
 
 ----------------------------------------------------------------
 
-| FISCCP1_COSP:long_name = "Grid-box fraction covered by each ISCCP D level cloud type" 
+| FISCCP1_COSP:long_name = "Grid-box fraction covered by each ISCCP D level cloud type"
 
 ---------------------------------------------------------------------
 
@@ -77,27 +78,27 @@ COSP extra output
 
 ------------------------------------------------------------
 
-| MEANCLDALB_ISCCP:long_name = "Mean cloud albedo*CLDTOT_ISCCP" 
+| MEANCLDALB_ISCCP:long_name = "Mean cloud albedo*CLDTOT_ISCCP"
 | MEANPTOP_ISCCP:long_name = "Mean cloud top pressure*CLDTOT_ISCCP"
-| MEANTAU_ISCCP:long_name = "Mean optical thickness*CLDTOT_ISCCP" 
-| MEANTBCLR_ISCCP:long_name = "Mean Clear-sky Infrared Tb from ISCCP simulator" 
-| MEANTB_ISCCP:long_name = "Mean Infrared Tb from ISCCP simulator" 
+| MEANTAU_ISCCP:long_name = "Mean optical thickness*CLDTOT_ISCCP"
+| MEANTBCLR_ISCCP:long_name = "Mean Clear-sky Infrared Tb from ISCCP simulator"
+| MEANTB_ISCCP:long_name = "Mean Infrared Tb from ISCCP simulator"
 
 ------------------------------------------------------------------------
 
-| PCTMODIS:long_name = "MODIS Cloud Top Pressure*CLTMODIS" 
+| PCTMODIS:long_name = "MODIS Cloud Top Pressure*CLTMODIS"
 
 --------------------------------------------------------------------------
 
-| REFFCLIMODIS:long_name = "MODIS Ice Cloud Particle Size*CLIMODIS" 
-| REFFCLWMODIS:long_name = "MODIS Liquid Cloud Particle Size*CLWMODIS" 
-| RFL_PARASOL:long_name = "PARASOL-like mono-directional reflectance" 
+| REFFCLIMODIS:long_name = "MODIS Ice Cloud Particle Size*CLIMODIS"
+| REFFCLWMODIS:long_name = "MODIS Liquid Cloud Particle Size*CLWMODIS"
+| RFL_PARASOL:long_name = "PARASOL-like mono-directional reflectance"
 
 ----------------------------------------------------------------------------
- 
-| TAUILOGMODIS:long_name = "MODIS Ice Cloud Optical Thickness (Log10 Mean)*CLIMODIS" 
-| TAUIMODIS:long_name = "MODIS Ice Cloud Optical Thickness*CLIMODIS" 
-| TAUTLOGMODIS:long_name = "MODIS Total Cloud Optical Thickness (Log10 Mean)*CLTMODIS" 
-| TAUTMODIS:long_name ="MODIS Total Cloud Optical Thickness*CLTMODIS" 
-| TAUWLOGMODIS:long_name = "MODIS Liquid Cloud Optical Thickness (Log10 Mean)*CLWMODIS" 
-| TAUWMODIS:long_name = "MODIS Liquid Cloud Optical Thickness*CLWMODIS" 
+
+| TAUILOGMODIS:long_name = "MODIS Ice Cloud Optical Thickness (Log10 Mean)*CLIMODIS"
+| TAUIMODIS:long_name = "MODIS Ice Cloud Optical Thickness*CLIMODIS"
+| TAUTLOGMODIS:long_name = "MODIS Total Cloud Optical Thickness (Log10 Mean)*CLTMODIS"
+| TAUTMODIS:long_name ="MODIS Total Cloud Optical Thickness*CLTMODIS"
+| TAUWLOGMODIS:long_name = "MODIS Liquid Cloud Optical Thickness (Log10 Mean)*CLWMODIS"
+| TAUWMODIS:long_name = "MODIS Liquid Cloud Optical Thickness*CLWMODIS"