update documentation in master branch

NOAA-PSL · Aug 26, 2022 · f16f3f5 · f16f3f5
1 parent 3bfa446
commit f16f3f5
Show file tree

Hide file tree

Showing 6 changed files with 62 additions and 27 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -17,7 +17,10 @@ branches:
   only:
     - ufs_public_release
     - release/public-v1
+    - release/public-v2
+    - release/public-v2
     - release/ufs-v1.1.0
+    - master
 
 # Environment variables
 env:

diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
@@ -5,6 +5,3 @@ The stochastic physics currently only works with the UFS-atmosphere model
 You should get the full system at https://github.com/ufs-community/ufs-weather-model, which will include the stochastic physics code.
 
 In order to enable stochastic physics in a model run, you will need to turn it on via `namelist options <namelist_options.html>`_
-
-If using the CIME workflow decribed at https://ufs-mrweather-app.readthedocs.io/en/latest/, please add do_sppt=T, etc. to user_nl_ufsatm in the case directory.
-
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -14,5 +14,5 @@ Welcome to UFS stochastic physics's documentation!
 Source Code Documentation
 ==========================
 
-Doxygen generated `content <https://noaa-psd.github.io/stochastic_physics/doxygen/index.html>`_
+#Doxygen generated (out of date) `content <https://noaa-psd.github.io/stochastic_physics/doxygen/index.html>`_
 
diff --git a/docs/source/namelist_options.rst b/docs/source/namelist_options.rst
@@ -8,11 +8,11 @@ General options
    :header: "Option", "Description"
    :widths: 30, 50
 
+   "NEW_LSCALE", "Recommended, set to true if use the correct calculation for decorrelation length scale."
    "NTRUNC", "Optional, Spectral resolution (e.g. T126) of random patterns, default is for model to determine proper truncation"
    "LAT_S", "Optional, number of latitude points for the gaussian grid  (must be even), default is for model to determine gaussian grid"
    "LON_S", "Optional, number of longitude points for the gaussian grid (recommend 2xLAT_S, default is for model to determine gaussian grid"
-   "FHSTOCH", "Optional, forecast hour to write out random pattern in order to restart the pattern for a different forecast (used in DA), file is stoch_out.F<HHH>"
-   "STOCHINI", "Optional, set to true if wanting to read in a previous random pattern (input file needs to be named stoch_ini)."
+   "STOCHINI", "Optional, set to true if wanting to read in a previous random pattern"
 
 SPPT options 
 """"""""""""
@@ -21,31 +21,31 @@ SPPT options
    :header: "Option", "Description"
    :widths: 30, 50
 
-   "DO_SPPT", "logical to tell parent atmospheric model to use SPPT"
-   "SPPT", "Amplitudes of random patterns (0.8,0.4,0.2,0.08,0.04) *"
-   "SPPT_TAU", "Decorrelation timescales in seconds (21600,1.728E5,6.912E5,7.776E6,3.1536E7) *"
-   "SPPT_LSCALE", "Decorrelation spatial scales in meters  (250.E3,1000.E3,2000.E3,2000.E3,2000.E3) *"
+   "SPPT", "Amplitudes of random patterns."
+   "SPPT_TAU", "Decorrelation timescales in seconds."
+   "SPPT_LSCALE", "Decorrelation spatial scales in meters."
    "SPPT_LOGIT", "Should be true to limit the SPPT perturbations between 0 and 2.  Otherwise model will crash."
    "ISEED_SPPT", "Seeds for setting the random number sequence (ignored if stochini is true)"
    "SPPT_SIGTOP1", "lower sigma level to taper perturbations to zero (default is 0.1)"
-   "SPPT_SIGTOP2", "upper sigma level to taper perturbations to zero (0.025)"
+   "SPPT_SIGTOP2", "upper sigma level to taper perturbations to zero (default is 0.025)"
    "SPPT_SFCLIMIT", ".T.=tapers the SPPT perturbations to zero at model’s lowest level (helps reduce model crashes)"
    "SPPTINT", "Optional, interval in seconds to update random pattern.  Perturbations still get applied every time-step"
    "USE_ZMTNBLCK", ".T.=do not apply perturbations below the dividing streamline that is diagnosed by the gravity wave drag, mountain blocking scheme"
+   "PERT_MP", ".T.=apply SPPT perturbations to all microphysics specis. If .F. the SPPT is only applied to u,v,t,qv"
+   "PERT_RADTEND", ".T.=apply SPPT perturbations to cloudy sky radiation tendencies. If .F. then do not perturb any radiative tendencies"
+   "PERT_CLDS", ".T.=apply SPPT perturbations to fraction (only works for RRTMG radiation),  if using this option set PERT_RADTEND=.F."
 
-``*``  **SPPT** uses 5 different patterns of varying time/length scales that are added together before being passed to physics
 
 SHUM options 
 """"""""""""
 
 .. csv-table::
    :header: "Option", "Description"
-   :widths: 20, 50
+   :widths: 30, 50
 
-   "DO_SHUM", "logical to tell parent atmospheric model to use SHUM"
-   "SHUM", "Amplitudes of random patterns (0.004)"
-   "SHUM_TAU", "Decorrelation timescales in seconds (21600)"
-   "SHUM_LSCALE", "ecorrelation spatial scales in meters (250000)"
+   "SHUM", "Amplitudes of random pattern."
+   "SHUM_TAU", "Decorrelation timescales in seconds."
+   "SHUM_LSCALE", "ecorrelation spatial scales in meters."
    "SHUM_SIGEFOLD", "e-folding lengthscale (in units of sigma) of specific humidity perturbations, default is 0.2)"
    "SHUMINT", "Optional, interval in seconds to update random pattern.  Perturbations still get applied every time-step"
    "ISEED_SHUM", "Seeds for setting the random number sequence (ignored if stochini is true)."
@@ -57,9 +57,8 @@ SKEB options
    :header: "Option", "Description"
    :widths: 30, 50
 
-   "DO_SKEB", "logical to tell parent atmospheric model to use SKEB"
-   "SKEB", "Amplitudes of random patterns (0.5)"
-   "SKEB_TAU", "Decorrelation timescales in seconds (21600)"
+   "SKEB", "Amplitudes of random patterns."
+   "SKEB_TAU", "Decorrelation timescales in seconds"
    "SKEB_LSCALE", "Decorrelation spatial scales in meters  (250)"
    "ISEED_SKEB", "Seeds for setting the random number sequence (ignored if stochini is true)."
    "SKEBNORM", "0-random pattern is stream function, 1-pattern is K.E. norm, 2-pattern is vorticity (default is 0)"
@@ -70,3 +69,34 @@ SKEB options
    "SKEB_SIGTOP2", "upper sigma level to taper perturbations to zero (0.025)"
    "SKEBINT", "Optional, interval in seconds to update random pattern.  Perturbations still get applied every time-step"
 
+SPP options
+""""""""""""
+
+.. csv-table::
+   :header: "Option", "Description"
+   :widths: 30, 50
+
+   "SPP_VAR_LIST", "List of parameterizations to be perturbed. Check compns_stochy.F90 for options."
+   "SPP_PRT_LIST", "SPP perturbation magnitudes used in each parameterization."
+   "SPP_TAU", "Decorrelation timescales in seconds."
+   "SPP_LSCALE", "Decorrelation spatial scales in meters."
+   "ISEED_SPP", "Seeds for setting the random number sequence (ignored if stochini is true)."
+   "SPP_SIGTOP1", "Lower sigma level to taper perturbations to zero (default is 0.1)"
+   "SPP_SIGTOP2", "Upper sigma level to taper perturbations to zero (0.025)"
+   "SPP_STDDEV_CUTOFF", "Limit for possible perturbation values in standard deviations from the mean."
+
+
+Land perturbation options
+""""""""""""
+
+.. csv-table::
+   :header: "Option", "Description"
+   :widths: 30, 50
+
+   "LNDP_TYPE", "0, no perturbations. 1, old scheme (Gehne et al. 2019); 2, new scheme (Draper 2021)"
+   "LNDP_VAR_LIST", "List of land perturbations parameters. Check compns_stochy.F90 for options"
+   "LNDP_PRT_LIST", "Perturbation magnitudes used for each parameter perturbations."
+   "LNDP_TAU", "Decorrelation timescales in seconds."
+   "LNDP_LSCALE", "Decorrelation spatial scales in meters."
+   "ISEED_LNDP", "Seeds for setting the random number sequence (ignored if stochini is true)."
+
diff --git a/docs/source/references.rst b/docs/source/references.rst
@@ -1,13 +1,15 @@
 References     
 ==========
 
-Berner, J., G. Shutts, M. Leutbecher, and T. Palmer, 2009: A spectral stochastic kinetic energy backscatter scheme and its impact on flow- dependent predictability in the ECMWF ensemble prediction system. J. Atmos. Sci., 66, 603–626, `doi:10.1175/2008JAS2677.1 <https://journals.ametsoc.org/doi/full/10.1175/2008JAS2677.1>`_
+Bengtsson, L., J. Dias, M. Gehne, P. Bechtold, J. Whitaker, 2019: Convectively Coupled Equatorial Wave Simulations Using the ECMWF IFS and the NOAA GFS Cumulus Convection Schemes in the NOAA GFS Model. *Mon. Wea. Rev.* **147**, 4005 - 4025, `doi:10.1175/MWR-D-19-0195.1 <https://journals.ametsoc.org/view/journals/mwre/147/11/mwr-d-19-0195.1.xml>`_
 
-Draper, C, 2021: Accounting for Land Model Uncertainty in Numerical Weather Prediction Ensemble Systems: Toward Ensemble-Based Coupled Land–Atmosphere Data Assimilation, J Hydromet, 22(8), 2089-2104, `<https://journals.ametsoc.org/view/journals/hydr/22/8/JHM-D-21-0016.1.xml>`_
+Berner, J., G. Shutts, M. Leutbecher, and T. Palmer, 2009: A spectral stochastic kinetic energy backscatter scheme and its impact on flow- dependent predictability in the ECMWF ensemble prediction system. *J. Atmos. Sci.,* **66**, 603–626, `doi:10.1175/2008JAS2677.1 <https://journals.ametsoc.org/doi/full/10.1175/2008JAS2677.1>`_
 
+Draper, C., 2021: Accounting for Land Model Uncertainty in Numerical Weather Prediction Ensemble Systems: Toward Ensemble-Based Coupled Land–Atmosphere Data Assimilation. *J. Hydromet.,* **22**, 2089–2104,  `doi:10.1175/JHM-D-21.0016.1 <https://doi.org/10.1175/JHM-D-21-0016.1>`_
 
-Palmer, T. N., R. Buizza, F. Doblas-Reyes, T. Jung, M. Leutbecher, G. J. Shutts,M. Steinheimer, and A.Weisheimer, 2009: Stochastic parametrization and model uncertainty. ECMWF Tech. Memo. 598, 42 pp `doi:10.21957/ps8gbwbdv <https://www.ecmwf.int/node/11577>`_
+Gehne, M., T. Hamill, G. Bates, P. Pegion, W. Kolczynski 2019: Land-surface parameter and state perturbations in the Global Ensemble Forecast System. *Mon. Wea. Rev.* **147**, 1319–1340 `doi:10.1175/MWR-D-18-0057.1 <https://journals.ametsoc.org/doi/10.1175/MWR-D-18-0057.1>`_
 
+Palmer, T. N., R. Buizza, F. Doblas-Reyes, T. Jung, M. Leutbecher, G. J. Shutts,M. Steinheimer, and A.Weisheimer, 2009: Stochastic parametrization and model uncertainty. *ECMWF Tech. Memo.* **598**, 42 pp `doi:10.21957/ps8gbwbdv <https://www.ecmwf.int/node/11577>`_
 
-Tompkins, A. M., and J. Berner, 2008: A stochastic convective approach to account for model uncertainty due to unresolved humidity variability. J. Geophys. Res., 113, D18101, `doi:10.1029/2007JD009284 <https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2007JD009284>`_
+Tompkins, A. M., and J. Berner, 2008: A stochastic convective approach to account for model uncertainty due to unresolved humidity variability. *J. Geophys. Res.,* **113**, D18101, `doi:10.1029/2007JD009284 <https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2007JD009284>`_
 
diff --git a/docs/source/users_guide.rst b/docs/source/users_guide.rst
@@ -2,7 +2,7 @@ Users Guide
 ==================================================
 The stochastic physics currently only works with the UFS-atmosphere model
 
-Currently, 3 stochastic schemes are used operationally at NCEP/EMC: Stochastic Kinetic Energy Backscatter (SKEB; Berner et al., 2009), Stochastically Perturbed Physics Tendencies (SPPT; Palmer et al., 2009), and Specific Humidity perturbations (SHUM), which is inspired by Tompkins and Berner, 2008. In addition there is the ability to perturb certain land model/surface parameters (Draper, 2021), and a cellular automata scheme (Bengtsson et al. 2019) which interacts directly with the convective parameterization.
+Currently, 3 stochastic schemes are used operationally at NCEP/EMC: Stochastic Kinetic Energy Backscatter (SKEB; Berner et al., 2009), Stochastically Perturbed Physics Tendencies (SPPT; Palmer et al., 2009), and Specific Humidity perturbations (SHUM), which is inspired by Tompkins and Berner, 2008. In addition there is the ability to perturb certain land model/surface parameters (Gehne et al., 2019 and Draper 2021), and a cellular automata scheme (Bengtsson et al. 2019) which interacts directly with the convective parameterization.
 
 SKEB adds wind perturbations to model state.  Perturbations are random in space/time, but amplitude is determined by a smoothed dissipation estimate provided by the dynamical core. 
 Addresses errors in the dynamics  - more active in the mid-latitudes
@@ -11,9 +11,12 @@ SPPT multiplies the physics tendencies by a random number O [0,2] before updatin
 
 SHUM multiply the low-level specific humidity by a small random number each time-step. It attempts to address missing physics (cold pools, gust fronts), most active in convective regions
 
-Land surface perturbations can be applied to the land model parameters and land model prognostic variables. The scheme is intended to address errors in the land model and land-atmosphere interactions.  
+Land surface perturbations allow for land surface parameters such as Albedo, Soil Hydraulic Conductivity, LAI, and roughness lengths to vary in space. Addresses error in the land model and land-atmosphere interactions. The perturbation options are only available to NOAH and RUC-LSM land models.
 
 Due to the model’s numerics, any stochastic perturbation needs to be correlated in space and time in order to have the desired effect of upscale growth of the perturbations. This is achieved by creating a random pattern that has a specified decorrelation length-scale and is a first order auto-regressive process AR(1) in time with a specified decorrelation time-scale.  (The CA random pattern generator also satisfies this condition)
 
-Currently the Land surface perturbations and cellular automata are not supported at the workflow level.  
+Cellular automata is enabled through the physics namelist
+
+
+Stochastic Paramter Perturbation (SPP) is avaiable for the FV3_HRRR physics suite