diff --git a/scm/doc/TechGuide/chap_cases.rst b/scm/doc/TechGuide/chap_cases.rst index 20cf32a99..a9c9bbdaa 100644 --- a/scm/doc/TechGuide/chap_cases.rst +++ b/scm/doc/TechGuide/chap_cases.rst @@ -351,7 +351,8 @@ Optional arguments: #. ``--save_comp (-sc)``: flag to create UFS reference file for comparison -#. ``--use_nearest (-near)``: flag to indicate using the nearest UFS history file gridpoint +#. ``--use_nearest (-near)``: flag to indicate using the nearest UFS history file gridpoint for calculation + of forcing; only valid for use with -fm=1 or -fm=3 #. ``--forcing_method (-fm)``: method used to calculate forcing (1=total tendencies from UFS dycore, 2=advective terms calculated from UFS history files, 3=total time tendency terms calculated), default=2 @@ -363,6 +364,64 @@ Optional arguments: #. ``--geostrophic (-geos)``: flag to turn on geostrophic wind forcing +Notes Regarding Implemented Forcing Methods + +The ``--forcing_method`` option hides some complexity that should be understood when running this script since +each method has a particular use case and produces potentially very different forcing terms. Forcing method 1 is +designed to be used in concert with the three-dimensional UFS. I.e., the UFS must be run with diagnostic tendencies +activated so that the `nophysics` term is calculated and output for all grid points +(see https://ccpp-techdoc.readthedocs.io/en/latest/ParamSpecificOutput.html#tendencies). This diagnostic term +represents the tendency produced for each state variable by the UFS between calls to the "slow" physics. This +includes the tendency due to advection, but also any tendencies due to other non-physics processes, e.g. "fast" +physics, coupling to external components, data assimilation, etc. Within the SCM, this diagnostic is used as the +forcing term for each state variable. Although one can achieve results as close as possible between a UFS column +and the single column model using this method, it will NOT be bit-for-bit for many reasons. Some of these reasons +include: diagnostic output is not typically instantaneous for every timestep, the UFS' vertical coordinate is +semi-Lagrangian and includes a remapping step as the surface pressure changes for each column, whereas the SCM +uses a Eulerian vertical coordinate without the vertical remapping step, and some interpolation happens in the +UFS_case_gen.py script due to the UFS initial conditions and history files using different grids. This method +can only be used when the UFS has been configured and run with the anticipation of running the SCM using this +forcing method afterward because it requires considerable extra disk space for the additional output. + +The `--forcing_method` 2 option is the most general in the sense that the same method could apply to any three-dimensional +model output. For a given column, it uses a configurable number of neighboring grid points to calculate the horizontal +advective tendencies using the horizontal components of the three-dimensional wind and horizontal derivatives of the +state variables. Note that the script performs some smoothing in the vertical profiles used to calculate the advective +terms in order to eliminate small-scale noise in the forcing terms and the derivatives are calculated using a second- or +fourth-order centered difference scheme, depending on the number of neighboring points used. Vertical advective terms +are calculated based on the specification of `--vertical_method` (-vm). For vertical_method 1, the vertical advective +terms are calculated from the history files using UFS vertical velocities and the same modeled smoothed vertical profiles +of the state variables using the upstream scheme. Note that while the horizontal terms use neighboring points, the vertical +advective terms only use the central, chosen column. This method is sometimes referred to as "total advective forcing" and +tends to be less "responsive" to the SCM-modeled state. I.e., a SCM run using vertical method 2 has a greater chance of +deviating from the UFS column state and not being able to "recover". For this reason, vertical method 2 is often used +in the literature, whereby the vertical velocity profile from the three-dimensional model is provided as forcing to the SCM +and the vertical advective terms are calculated during the SCM integration using the SCM-modeled state variable profiles. + +The final forcing method, 3, uses the three-dimensional history files to calculate profiles of the total time-rate of change +of the state variables to use as forcing for the SCM. Note that this is tantamount to strongly nudging the SCM state to the +UFS state and already intrinsically includes both the physics and dynamics tendencies. While a simulation using this forcing +is more-or-less guaranteed to produce a SCM simulation that closely matches the three-dimensional output of the state variables, +it strongly minimizes the contribution of physics in the SCM simulation. Indeed, an SCM simulation without running a physics suite +at all would still be expected to closely track the mean state of the three-dimensional column, so this method will likely be of +limited use for physics studies. + +Forcing the horizontal components of the wind can be notoriously difficult in SCMs, and the most straightforward method is to +simply nudge them to the three-dimensional modeled state. This method is achieved by using the `--wind_nudge` (-wn) option and uses a nudging +timescale of one hour. It should be possible to calculate a nudging timescale based on the magnitude of the wind in the neighboring +grid cells, although this is not implemented yet. + +The second method to force the horizontal wind components is to calculate the geostrophic wind using the "large scale" pressure +gradient from the three-dimensional model. This is achieved by using the `--geostrophic` (-geos) option. What qualifies as large +enough of a horizontal gridscale to achieve geostrophic balance is when the Rossby number is much less than one. The script uses a +configurable Rossby number (around 0.1) to expand the number of neighboring grid points such that geostrophic balance can be assumed +given the particular UFS history file grid. The geostrophic winds are calculated using the horizontal geopotential gradient and the +local latitude-dependent Coriolis parameter. From the PBL top downward, the geostrophic winds are assumed to go to zero. In testing +with this method, if the initial horizontal winds have a significant ageostrophic component (the initial condition winds are +appreciably different than the calculated geostrophic winds), this often leads to spurious clockwise turning of the mean modeled winds +with time. An option exists within the script to assume that the mean three-dimensional winds are, in fact, identical to the +geostrophic winds as well. Using this option eliminates any spurious turning. + .. _`ufsforcingensemblegenerator`: UFS_forcing_ensemble_generator.py diff --git a/scm/doc/TechGuide/chap_quick.rst b/scm/doc/TechGuide/chap_quick.rst index 19dbfd405..78191f568 100644 --- a/scm/doc/TechGuide/chap_quick.rst +++ b/scm/doc/TechGuide/chap_quick.rst @@ -860,12 +860,12 @@ Running the Docker image #. To run the SCM, you can run the Docker container that was just created and give it the same run commands as discussed in :numref:`Section %s ` - **Be sure to remember to include the ``-d`` - include the option for all run commands**. For example, + **Be sure to remember to include the ``-d`` and ``--mpi_command "mpirun -np 1 --allow-run-as-root"`` + options for all run commands**. For example, .. code:: bash - docker run --rm -it -v ${OUT_DIR}:/home --name run-ccpp-scm ccpp-scm ./run_scm.py -c twpice -d + docker run --rm -it -v ${OUT_DIR}:/home --name run-ccpp-scm ccpp-scm ./run_scm.py -c twpice --mpi_command "mpirun -np 1 --allow-run-as-root" -d will run through the TWPICE case using the default suite and namelist and put the output in the shared directory. @@ -878,7 +878,7 @@ Running the Docker image .. code:: bash - docker run --rm -it -v ${OUT_DIR}:/home --name run-ccpp-scm ccpp-scm ./run_scm.py -f ../../test/rt_test_cases.py --runtime_mult 0.1 -d + docker run --rm -it -v ${OUT_DIR}:/home --name run-ccpp-scm ccpp-scm ./run_scm.py -f ../../test/rt_test_cases.py --runtime_mult 0.1 --mpi_command "mpirun -np 1 --allow-run-as-root" -d The options included in the above ``run`` commands are the following: