Merge ufs-release/public-v1 into dev/emc (NOAA-EMC#59)

* updating doxygen documentation as requested from EMC for UFS MRW release of version 1.1

* updated documentation for ufs v1.1 specifically: updated d2_bg_k2 description per Jeff Whitaker, and removed sections A.2, A.8, and A.9 from the documentation Parameters List.

* Further updates to ufs documentation

* removing version number form Doxyfile

Co-authored-by: bensonr <[email protected]>

model/fv_control.F90

@@ -1085,16 +1085,20 @@ subroutine read_namelist_fv_core_nml(Atm)
 !!
 !> \param[in] n\_zs\_filter Integer: number of times to apply a diffusive filter to the topography upon startup, if mountain is True and the model is not being cold-started. This is applied every time the model is warm-started, so if you want to smooth the topography make sure this is set to 0 after the first simulation. 0 by default. If initializing the model from cold-start the topography is already being filtered by an amount appropriate for the model resolution. 
 !!
+!> \param[in] read_increment Logical: Read in analysis increment and add to restart following are namelist parameters for Stochastic Energy Baskscatter dissipation estimate. This is useful as part of a data-assimilation cycling system or to use native restarts from the six-tile first guess, after which the analysis increment can be applied. 
+!!
 !> \param[in] res\_latlon\_dynamics character(len=128) If external\_ic =.true. gives the filename of the input IC file. INPUT/fv\_rst.res.nc by default. 
 !!
 !> \param[in] res\_latlon\_tracers character(len=128) If external\_ic =.true. and both ncep\_ic and fv\_diag\_ic are.false., this variable gives the filename of the initial conditions for the tracers, assumed to be a legacy lat-lon FV core restart file. INPUT/atmos\_tracers.res.nc by default. 
 !!
-!> \param[in] warm\_start] Logical; whether to start from restart files, instead of cold-starting the model. True by default; if this is set to true and restart files cannot be found the model will stop.
+!> \param[in] warm\_start Logical: whether to start from restart files, instead of cold-starting the model. True by default; if this is set to true and restart files cannot be found the model will stop.
 !!
 !>###A1.3 I/O and diagnostic options:
 !!
 !> \param[in] agrid\_vel\_rst Logical: whether to write the unstaggered latitude-longitude winds (u<sub>a</sub> and v<sub>a</sub>) to the restart files. This is useful for data assimilation cycling systems which do not handle staggered winds. .false. by default.
 !!
+!> \param[in] bc_update_interval Integer: Default setting for interval (hours) between external regional BC data files.
+!!
 !> \param[in] check\_negative Logical: whether to print the most negative global value of microphysical tracers.
 !!
 !> \param[in] fv\_debug Logical: whether to turn on additional diagnostics in fv\_dynamics..false. by default. 
@@ -1119,6 +1123,8 @@ subroutine read_namelist_fv_core_nml(Atm)
 !!
 !> \param[in] do\_uni\_zfull Logical: whether to compute z\_full (the height of each model layer, as opposed to z\_half, the height of each model interface) as the midpoint of the layer, as is done for the nonhydrostatic solver, instead of the height of the location where <SPAN STYLE="text-decoration:overline">p</SPAN> the mean pressure in the layer. This option is not available for fvGFS or the solo\_core. .false. by default.
 !!
+!> \param[in] do_sat_adj Logical: The same as fast_sat_adj = .false. has fast saturation adjustments
+!!
 !> \param[in] dnats Integer: The number of tracers which are not to be advected by the dynamical core, but still passed into the dynamical core; the last dnats+pnats tracers in field\_table are not advected. 0 by default.
 !!
 !> \param[in] dnrts Integer: the Number of non-remapped consituents. Only makes sense for dnrts <= dnat.
@@ -1127,6 +1133,8 @@ subroutine read_namelist_fv_core_nml(Atm)
 !!
 !> \param[in] fill Logical: Fills in negative tracer values by taking positive tracers from the cells above and below. This option is useful when the physical parameterizations produced negatives. False by default.
 !!
+!> \param[in] gfs_phil Logical: Obsolete - to be removed
+!!
 !> \param[in] inline\_q Logical: whether to compute tracer transport in-line with the rest of the dynamics instead of sub-cycling, so that tracer transport is done at the same time and on the same time step as is `p` and potential temperature. False by default; if true, q\_split and z\_tracer are ignored. 
 !!
 !> \param[in] ncnst Integer: Number of tracer species advected by fv\_tracer in the dynamical core. Typically this is set automatically by reading in values from field\_table, but ncnst can be set to a smaller value so only the first ncnst tracers listed in field\_table are not advected. 0 by default, which will use the value from field\_table. 
@@ -1187,6 +1195,8 @@ subroutine read_namelist_fv_core_nml(Atm)
 !!
 !> \param[in] nestupdate Integer: type of nested-grid update to use; details are given in model/fv\_nesting.F90. 0 by default.
 !!
+!> \param[in] regional Logical: Controls whether this is a regional domain (and thereby needs external BC inputs)
+!!
 !>###A.1.7 Solver options
 !!
 !> \param[in] a2b\_ord Integer: order of interpolation used by the pressure gradient force to interpolate cell-centered (A-grid) values to the grid corners. 4 by default (recommended), which uses fourth-order interpolation; otherwise second-order interpolation is used. 
@@ -1276,7 +1286,7 @@ subroutine read_namelist_fv_core_nml(Atm)
 !!
 !> \param[in] d2\_bg\_k1 Real: strength of second-order diffusion in the top sponge layer. 0.16 by default. This value, and d2\_bg\_k2, will be changed appropriately in the model (depending on the height of model top), so the actual damping may be very reduced. See atmos\_cubed\_sphere/model/dyn\_core.F90 for details. Recommended range is 0. to 0.2. Note that since diffusion is converted to heat if d\_con > 0 larger amounts of sponge-layer diffusion may be *less* stable.
 !!
-!> \param[in] d2\_bg\_k2 Real: strength of second-order diffusion in the second sponge layer from the model top. 0.02 by default. This value should be lower than d2\_bg\_k1.
+!> \param[in] d2\_bg\_k2 Real: strength of second-order diffusion in the second sponge layer from the model top. 0.02 by default. This value should be lower than d2\_bg\_k1. If d2\_bg\_k2=0, then d2\_bg\_k1 is applied throughout the depth of the sponge layer (the bottom of the sponge layer is set by rf_cutoff). The amplitude is d2\_bg\_k1 at the top, then decreases downward with the same vertical dependence as the rayleigh damping, going to zero at rf_cutoff.
 !!
 !> \param[in] d4\_bg Real: Dimensionless coefficient for background higher-order divergence damping. 0.0 by default. If no second-order divergence damping is used, then values between 0.1 and 0.16 are recommended. Requires nord > 0. Note that the scaling for d4\_bg differs from that of d2\_bg; nord >= 1 and d4\_bg = 0.16 will be less diffusive than nord = 0 and d2\_bg = 0.02.
 !!
@@ -1300,39 +1310,29 @@ subroutine read_namelist_fv_core_nml(Atm)
 !!
 !> \param[in] vtdm4 Real: coefficient for background other-variable damping. The value of vtdm4 should be less than that of d4\_bg. A good first guess for vtdm4 is about one-third the value of d4\_bg. 0.0 by default. Requires do\_vort\_damp to be .true. Disabled for values less than 1.e-3. Other-variable damping should not be used if a monotonic horizontal advection scheme is used.
 !!
-!>##A.2 Entries in coupler\_nml
-!!
-!> \param[in] months, days,hours,minutes,seconds Integer: length of the model integration in the corresponding units. All are 0 by default, which initializes the model and then immediately writes out the restart files and halts.
-!!
-!> \param[in] dt\_atmos Integer: time step for the largest atmosphere model loop, corresponding to the frequency at which the top level routine in the dynamics is called, and the physics timestep. Must be set.
-!!
-!> \param[in] current\_date Integer(6): initialization date (in the chosen calendar) for the model, in year, month, day, hour, minute, and second. (0,0,0,0,0,0) by default, a value that is useful for control integrations of coupled models.
-!!
-!> \param[in] calendar Character(17): calendar selection; JULIAN is typically recommended, although the other values (THIRTY\_DAY\_MONTHS, NOLEAP, NO\_CALENDAR) have particular uses in idealized models. Must be set.
+!>###A.1.10 Limited area model (LAM)
 !!
-!> \param[in] force\_date\_from\_namelist Logical: if .true., will read the initialization date from the namelist variable current\_date, rather than taking the value from a restart file. If the model is being cold-started (such as what is typically but not necessarily done if external\_ic = .true.) then the initialization date must be specified in current\_date, otherwise the model will stop. .false. by default.
-!!
-!> \param[in] atmos\_nthreads Integer: number of threads for OpenMP multi-threading. 1 by default.
-!!
-!> \param[in] use\_hyper\_thread Logical: indicates that some of the threads in atmos\_nthreads may be hyperthreads. .false. by default.
+!> \param[in] update\_blend Real: Weights to control how much blending is done during two-way nesting update. Default is 1. 
 !!
-!> \param[in] ncores\_per\_node Integer: number of processor codes per physical compute node. Used when setting up hyperthreading to determine number of virtual vs. hardware threads. 0 by default.
+!> \param[in] regional\_bcs\_from\_gsi Logical: whether DA-updated BC files are used. Default is false. 
 !!
-!> \param[in] debug\_affinity Logical: if .true. prints out a message describing cpu affinity characteristics while initializing OpenMP. .false. by default.
+!> \param[in] write\_restart\_with\_bcs Logical: whether to write restart files with BC rows. 
 !!
-!> \param[in] restart\_days, restart\_secs] Integer: frequency at which to write out "intermediate" restart files, which are useful for checkpointing in the middle of a long run, or to be able to diagnose problems during the model integration. Both are 0 by default, in which case intermediate restarts are not written out.
+!> \param[in] nrows\_blend Integer: Number of blending rows in the files. 
 !!
-!>##A.3 Entries in external\_ic\_nml
+!>##A.2 Entries in external\_ic\_nml
 !!
 !> \param[in] filtered\_terrain Logical: whether to use the terrain filtered by the preprocessing tools rather than the raw terrain. .true. by default. Only active if nggps\_ic = .true. or ecmwf\_ic = .true.
 !!
 !> \param[in] levp Integer: number of levels in the input (remapped) initial conditions. 64 by default. Only active if nggps\_ic = .true.
 !!
+!> \param[in] gfs_dwinds Logical: obsolete - to be removed
+!!
 !> \param[in] checker\_tr Logical: whether to enable the ``checkerboard'' tracer test. .false. by default. Only active if nggps\_ic = .true.
 !!
 !> \param[in] nt\_checker Integer: number of tracers (at the end of the list of tracers defined in field\_table) to initialize with an idealized ``checkerboard'' pattern, with values of either 0 or 1. This is intended to test the monotonicity or positivity constraint in the advection scheme. 0 by default. Only active if nggps\_ic = .true.
 !!
-!>##A.4 Entries in surf\_map\_nml
+!>##A.3 Entries in surf\_map\_nml
 !!
 !> \param[in] surf\_file Character(len=128): File containing topography data. This file must be in NetCDF format. INPUT/topo1min.nc by default. (Previous versions of the model have used 5 minute USGS data, which is not recommended.) 
 !!
@@ -1344,19 +1344,19 @@ subroutine read_namelist_fv_core_nml(Atm)
 !!
 !> \param[in] zs\_filter Logical: whether to apply smoothing to the topography. True by default. 
 !!
-!>##A.5 Entries in fv\_grid\_nml
+!>##A.4 Entries in fv\_grid\_nml
 !!
 !> \param[in] grid\_name Character(len=80): Name of the grid either being read in (if grid\_spec = -1) or being created. This is only used for writing out a binary file in the directory from which the model is run. Gnomonic by default. 
 !!
 !> \param[in] grid\_file Character(len=120): If grid\_type = -1 the name of the grid\_spec file to read in. INPUT/grid\_spec.nc by default; other values will not work. 
 !!
-!>##A.6 Entries in test\_case\_nml
+!>##A.5 Entries in test\_case\_nml
 !!
 !> \param[in] test\_case Integer: number of the idealized test case to run. A number of nest cases are defined in tools/test\_cases.F90, of which numbers 19 are intended for the shallow-water model. Requires warm\_start =.false. 11 by default; this creates a resting atmosphere with a very basic thermodynamic profile, with topography. If you wish to initialize an Aquaplanet simulation (no topography) set to 14. 
 !!
 !> \param[in] alpha Real: In certain shallow-water test cases specifies the angle (in fractions of a rotation, so 0.25 is a 45-degree rotation) through which the basic state is rotated. 0 by default. 
 !!
-!>##A.7 Entries in fv\_nest\_nml
+!>##A.6 Entries in fv\_nest\_nml
 !!
 !> \param[in] grid\_pes Integer(:): Number of processor cores (or MPI ranks) assigned to each grid. The sum of the assigned cores in this array must sum to the number of cores allocated to the model. Up to one of the first ngrids entries may be 0, in which case all remaining cores are assigned to it. 0 by default.
 !!
@@ -1370,7 +1370,7 @@ subroutine read_namelist_fv_core_nml(Atm)
 !!
 !> \param[in] nest\_joffsets Integer(:): as for nest\_ioffsets but in the local y-direction.
 !!
-!>##A.8 Entries in fv\_diag\_column\_nml
+!>##A.7 Entries in fv\_diag\_column\_nml
 !!
 !> \param[in] do\_diag\_sonde Logical: whether to enable sounding output specified by the namelist variables diag_sonde* . The output is intended to match the format of text files produced by the University of Wyoming text soundings, except that output is on uninterpolated model levels. False by default.
 !!
@@ -1386,37 +1386,10 @@ subroutine read_namelist_fv_core_nml(Atm)
 !!
 !> \param[in] do\_diag\_debug Logical: analogous to the functionality of do\_diag\_sonde, as well as including similar parameters: diag\_debug\_lon\_in, diag\_debug\_lat\_in, and diag\_debug\_names, but outputs different diagnostics at every dt_atmos more appropriate for debugging problems that are known to occur at a specific point in the model. This functionality is only implemented for the nonhydrostatic solver
 !!
-!>##A.9 Entries in atmos\_model\_nml (for UFS)
-!!
-!> \param[in] blocksize Integer: Number of columns in each ``block'' sent to the physics. OpenMP threading is done over the number of blocks. For best performance this number should divide the number of grid cells per processor ( (npx-1)*(npy-1) /(layout\_x)*(layout\_y) ) and be small enough so the data can best fit into cache?values around 32 appear to be optimal on Gaea. 1 by default
-!!
-!> \param[in] chksum\_debug Logical: whether to compute checksums for all variables passed into the GFS physics, before and after each physics timestep. This is very useful for reproducibility checking. .false. by default.
-!!
-!> \param[in] dycore\_only Logical: whether only the dynamical core (and not the GFS physics) is executed when running the model, essentially running the model as a solo dynamical core. .false. by default.
-!!
-!>##A.10 Entries in fms\_nml
+!>##A.8 Entries in fms\_nml
 !!
 !> \param[in] domains\_stack\_size Integer: size (in bytes) of memory array reserved for domains. For large grids or reduced processor counts this can be large (>10 M); if it is not large enough the model will stop and print a recommended value of the stack size. Default is 0., reverting to the default set in MPP (which is probably not large enough for modern applications).
 !!
-!>##A.11
-!!
-!> \param[in] regional Logical: Controls whether this is a regional domain (and thereby needs external BC inputs
-!!
-!> \param[in] bc\_update\_interval Integer: Default setting for interval (hours) between external regional BC data files.
-!!
-!> \param[in] update\_blend Real: Weights to control how much blending is done during two-way nesting update. Default is 1. 
-!!
-!> \param[in] regional\_bcs\_from\_gsi Logical: whether DA-updated BC files are used. Default is false. 
-!!
-!> \param[in] write\_restart\_with\_bcs Logical: whether to write restart files with BC rows. 
-!!
-!> \param[in] nrows\_blend Integer: Number of blending rows in the files. 
-!!
-!> \param[in] read\_increment Logical: Read in analysis increment and add to restart following are namelist parameters for Stochastic Energy Baskscatter dissipation estimate. This is useful as part of a data-assimilation cycling system or to use native restarts from the six-tile first guess, after which the analysis increment can be applied. 
-!!
-!> \param[in] do\_sat\_adj Logical: The same as fast\_sat\_adj = .false. has fast saturation adjustments
-!!
-!!
 !!
 !! 
 !> @{