diff --git a/docs/AdvectionOperators.md b/docs/AdvectionOperators.md new file mode 100644 index 000000000..db24df9a6 --- /dev/null +++ b/docs/AdvectionOperators.md @@ -0,0 +1,19 @@ +A Brief Guide to Advection Operators in FV³ {#advection} +======================== + +By: + +**Lucas Harris, Shian-Jiann Lin, and Xi Chen, GFDL** + +*17 August 2018* + +FV³ is unique among atmospheric dynamical cores in that it is formulated similarly to CFD solvers which treat most processes as the fluxes of some conserved quantity. With the exception of the pressure gradient force, all of the terms in the inviscid Euler equations, formulated along Lagrangian surfaces, can be expressed as fluxes. The fluxes are evaluated through the Lin & Rood (1996) FV advection scheme, extended to the cubed sphere by Putman and Lin (2007), based on a two-dimensional combination of one-dimensional flux operators. The operators in the most recent version of FV³ all use the piecewise-parabolic method (Collella and Woodward 1984), although this method gives great flexibility in choosing the subgrid reconstructions used to evaluate the fluxes.FV³ + +Some understanding of finite-volume methods is necessary to understand the operators. A true finite-volume method treats all variables as cell-mean values, instead of point values. (Fluxes and winds are treated as face-mean values.) To compute the fluxes, a ​reconstruction​ function describing an approximation to the (unknown) subgrid distribution of each variable is needed. In PPM, this reconstruction is a quadratic function, specified by the cell mean value and the values on the interfaces of the cells. The cell-interface values are derived by computing a high-order interpolation from the cell-mean values to point values on the interfaces. The reconstructions can then be altered by various means to enforce different shape preservation properties, such as monotonicity or positivity, by looking at the cell-mean and cell-interface values of the surrounding cells. This process, called ​limiting​ is a ​non-linear​ method, allowing us to create a high-order monotone solution without violating Godunov’s Theorem. (This should not be confused with flux-corrected transport, or FCT, a simpler means of enforcing monotonicity) + +Monotonicity means that the reconstructions are chosen to ensure that no new extrema appear in the variable, in the absence of flow convergence or divergence. This is a property of scalar advection in real flows, and prevents the appearance of unphysical oscillations, or over- and under-shoots (which can create spurious condensates or unphysically rapid chemical reactions). Monotonicity also prevents the appearance of negative values in positive-definite mass scalars, which can rapidly lead to numerical instability. However, the stronger the enforcement of monotonicity, the more diffusive the solution is, so other techniques, such as schemes which only enforce positivity, or simple reconstruction filters. + +Here we briefly describe three PPM operators, all formally the same fourth-order accuracy but with different reconstruction limiters: An unlimited (also called linear) “fifth-order” operator (hord = 5), an unlimited operator with a 2dx filter (hord = 6), and the monotone Lin 2004 operator (hord = 8). We also describe the optional positive-definite limiter which can be applied to methods 5 and 6, which is essential for scalar advection (hord_tr). ​The number indicated by hord is only the selection amongst a series of schemes, ​similar to how different numbers in the physics correspond to different schemes. ​They do not change the order of accuracy of the advection, only the diffusivity and shape-preserving characteristics.Hord = 5 is the “linear” or “unlimited” scheme originally devised by Collella and Woodward, modified with a weak 2dx filter: if the cell-interface values show a 2dx signal (that is, that the interpolated interface values on opposing sides of a cell switch between greater than and less than the cell-mean value) the flux is evaluated as a first-order upwind value. The 2dx filter is necessary to suppress 2dx noise; without this filter the solver is more prone to instability. Hord = 6 uses a much stronger 2dx filter: the hord = 5 method is extended by reverting to first-order upwind flux if the difference in cell-interface values exceeds the mean of the two interface values by a tunable threshold (1.5x by default). + +The optional positive-definite limiter is activated by adding a minus sign to hord (for values <= 6). This forces all cell-interface values to be no more than 0, ensuring a positive-definite flux. The positive-definite hord = 5 further applies the positive-definite constraint of Lin and Rood (1996). + diff --git a/docs/Chapter1.md b/docs/Chapter1.md new file mode 100644 index 000000000..3aebd999f --- /dev/null +++ b/docs/Chapter1.md @@ -0,0 +1,35 @@ +FV³ Introduction {#introduction} +============ + +##Chapter 1 + +###1.1 A brief history of FV³ + + +FV³ is a natural evolution of the hydrostatic Finite-Volume dynamical core (FV core) originally developed in the 90s on the latitude-longitude grid. The FV core started its life at NASA/Goddard Space Flight Center (GSFC) during early and mid 90s as an offline transport model with emphasis on the conservation, accuracy, consistency (tracer to tracer correlation), and efficiency of the transport process. The development and applications of monotonicity preserving Finite-Volume schemes at GSFC were motivated in part by the need to have a solution for the noisy and unphysical negative water vapor and chemical species (L94, LR96). It subsequently has been used by several high-profile Chemistry Transport Models (CTMs), including the NASA community GMI model (Rotman et al., 2001, J. Geophys. Res.), GOCART (Chin et al., 2000, J. Geophys. Res.), and the Harvard University-developed GEOS-CHEM community model (Bey et al, 2001, , J. Geophys. Res.). This transport module has also been used by some climate models, including the ECHAM5 AGCM (Roeckner et al, 2003, MPI-Report No. 349). Motivated by the success of monotonicity-preserving FV schemes in CTM applications, a consistently-formulated shallow-water model was developed. This solver was first presented at the 1994 PDE on the Sphere Workshop, and published in LR97. The Lin-Rood algorithm for shallow-water equations maintains mass conservation and a key Mimetic property of “no false vorticity generation”, and for the first time in computational geophysical fluid dynamics, uses high-order monotonic advection consistently for momentum and all other prognostic variables, instead of the inconsistent hybrid finite difference and finite-volume approach used by practically all other “finite volume” models today. The full 3D hydrostatic dynamical core, the FV core, was constructed based on the LR96 transport algorithm and the Lin-Rood shallow-water algorithm (LR97). The pressure gradient force is computed by the L97 finite-volume integration method, derived from Green’s integral theorem and based directly on first principles, and demonstrated errors an order of magnitude smaller than other pressure-gradient schemes at the time. The vertical discretization is the “vertically Lagrangian” scheme described by L04, the most powerful aspect of FV³, which permits great computational efficiency as well as greater accuracy given the same vertical resolution. The FV core was implemented in the NCAR CESM model in 2001 (Rasch et al, 2006, J. Climate) and in the GFDL CM2 model in 2004 (Delworth et al, 2006, J. Climate). + + +The need to scale to larger number of processors in modern massively parallel environments and the scientific advantage of eliminating the polar filter led to the development of FV³, the cubed-sphere version of FV. The cubed-sphere FV³ is in use in all GFDL and GSFC global models, and the cubed-sphere version of the LR96 advection scheme is used by the most recent version of GEOS-CHEM. Most recently, a computationally efficient non-hydrostatic solver has been implemented using a traditional semi-implicit approach for treating the vertically propagating sound waves. A second option for the non-hydrostatic solver, using a Riemann solver to nearly exactly solve for vertical sound-wave propagation, is also available. The Riemann solver is highly accurate and is very efficient if the Courant number for vertical sound wave propagation is small, and so may be very useful for extremely high (< 1 km) horizontal resolutions. In July 2016 this non-hydrostatic core has been selected for the Next-Generation Global Prediction System (NGGPS), paving the way for the unification of not only weather and climate models but also potentially regional and global models. + + +###1.2 Outline of the solver + +FV³ is the solver that integrates the compressible, adiabatic Euler equations in a weather or climate model. The solver is modular and designed to be called as a largely independent component of a numerical model, consistent with modern standards for model design; however for best results it is recommended that a model using FV³ as its dynamical core should use the provided application programming interface (API) to invoke the solver as well as to use the provided utility routines consistent with the dynamics, particularly for the initialization, updating the model state by time tendencies from the physics, and for incorporating increments from the data assimilation system. + +The leftmost column of Figure 1.1 shows the external API calls used during a typical process-split model integration procedure. First, the solver is called, which advances the solver a full “physics” time step. This updated state is then passed to the physical parameterization package, which then computes the physics tendencies over the same time interval. Finally, the tendencies are then used to update the model state using a forward-in-time evaluation consistent with the dynamics, as described in Chapter 3. + +There are two levels of time-stepping inside FV³. The first is the “remapping” loop, the orange column in Figure 1.1. This loop has three steps: +-# Perform the Lagrangian dynamics, the loop shown in the green column of Figure 1.1 +-# Perform the sub-cycled tracer advection along Lagrangian surfaces,using accumulated mass fluxes from the Lagrangian dynamics. Subcycling is done independently within each layer to maintain local (within each layer) stability. +-# Remap the deformed Lagrangian surfaces on to the reference, or “Eulerian”, coordinate levels. + + + +drawing + +**Figure 1.1:** *FV3 structure, including subroutines and time-stepping. Blue represents external API routines, called once per physics time step; orange routines are called once per remapping time step; green routines once per acoustic time step.* + +This loop is typically performed once per call to the solver, although it is possible to improve the model’s stability by executing the loop (and thereby the vertical remapping) multiple times per solver call. + +The Lagrangian dynamics is the second level of time-stepping in FV³. This is the integration of the dynamics along the Lagrangian surfaces, across which there is no mass transport. Since the time step of the Lagrangian dynamics is limited by horizontal sound-wave processes, this is called the “acoustic” time step loop. (Note that the typical assumption that the advective wind speed is much slower than the sound wave speed is often violated near the poles, since the speed of the polar night jets can exceed two-thirds of the speed of sound.) The Lagrangian dynamics has two parts: the C-grid winds are advanced a half-time step, using simplified (but similarly constructed) core routines, which are then used to provide the advective fluxes to advance the D-grid prognostic fields a full time step. The integration procedure is similar for both grids: the along-surface flux terms (mass, heat, vertical momentum, and vorticity, and the kinetic energy gradient terms) are evaluated forward-in-time, and the pressure-gradient force and elastic terms are then evaluated backwards-in-time, to achieve enhanced stability. + diff --git a/docs/Chapter2.md b/docs/Chapter2.md new file mode 100644 index 000000000..7567b3ad0 --- /dev/null +++ b/docs/Chapter2.md @@ -0,0 +1,110 @@ +Stabilization and filtering options {#stabilization} +========================================= + +##Chapter 2 + +###2.1 Divergence damping +Horizontal divergence (along a Lagrangian surface) is computed as a cell integrated quantity on the dual grid: + +\f[ + D = \frac{1}{\Delta A_c} \left[ \delta_x (u_c \Delta y_c sin\alpha) + \delta_y (v_c \Delta x_c sin \alpha) \right] \\ \tag {2.1} + \f] + +The Laplacian of D can also be computed as a cell-integrated quantity on the dual grid: + +\f[ + \nabla^2 D = \frac{1}{\Delta A_c} \left[ \delta_x \left(\frac{\delta_x D}{\Delta x} \Delta y_c sin\alpha \right) + \delta_y \left(\frac{\delta_y D}{\Delta y} \Delta x_c sin \alpha \right) \right] \\ \tag {2.2} + \f] + +This operator can be applied on ∇2D instead of D to yield ∇4D. The damping is then applied when the forward time step is taken for the horizontal dynamics along vertically-Lagrangian surfaces: + +\f[ + u^{n+1} = u^n + . . . + \nu_D \frac{\delta_x \nabla^{2N} D}{\Delta x} \\ \tag {2.3} + \f] + +\f[ + v^{n+1} = v^n + . . . + \nu_D \frac{\delta_y \nabla^{2N} D}{\Delta y} \\ \tag {2.4} + \f] + +where N (equal to the namelist parameter `nord`) is 1 for fourth-order and 2 for sixth-order damping. The nondimensional damping coefficient is given + +\f[ + \nu_D = (d_4\Delta A_{min} )^{N+1} \\ \tag {2.5} + \f] + +in which d4 is the parameter `d4_bg` in the namelist, and ΔAmin is the *global* minimum grid-cell area. It is recommended that this parameter be set to a value between 0.1 and 0.16, with instability likely for higher or lower values. Note that divergence damping is necessary as there is no implicit damping on the divergence in FV3. An optional second-order ∇2 damping, in addition the higher-order divergence damping, can be applied as well; in this case the added damping is of the form ν2D(δxD/ Δx), where ν2D = d2ΔAmin. Typically, the coefficient for d2 should be much smaller—by at least an order of magnitude—than the higher-order coefficient, if it is used at all, since the second-order damping is only weakly scale-selective and will significantly diffuse even resolved-scale features. + +The divergence damping can also be modified to add an approximate Smagorinsky-type damping, in which second-order divergence damping can be added to the flow dependent on the amount of stretching and dilation in thepflow. In this case, the d2 in the expression for ν2D is replaced by dSΔt(D2 + ζ2)1/2, where dS is the Smagorinsky coefficient (typically set to 0.2 if used) and ζ is the relative vorticity interpolated to cell corners so as to be co-located with the divergence. This form of the damping coefficient is more physical than the artificial damping discussed in the rest of this chapter, and will typically be very weak except in regions of very strong flow deformation. + +Divergence and flux damping (described in the next section) are both applied entirely within Lagrangian surfaces; there is no explicit diffusion applied across the surfaces. However, in regions of vertical motion the Lagrangian surfaces are distorted in the vertical as they follow the flow upward or downward. The amount of the distortion depends on the along-surface gradient of the vertical velocity; so where the distortion is largest is where there is the strongest horizontal shearing of the vertical velocity, which is also where ∇2n of the scalar fields should be the largest. + + +###2.2 Hyperdiffusion (flux, or “vorticity”) damping + +Traditionally in FV3 computational noise is controlled through two means: the explicit divergence damping, and the implicit, nonlinear diffusion from the monotonicity constraint used in computing the fluxes. However, the implicit diffusion may be too heavily damping of marginally-resolved flow features, and for high-resolution applications it may be beneficial to use a nonmonotonic scheme and then add a user-controllable hyperdiffusion instead. This added hyperdiffusion need not be as strong as the divergence damping, since the non-monotonic advection schemes are still weakly diffusive (while no implicit diffusion is applied to the divergence), and often the hyperdiffusion coefficient df (`vtdm4`) should be much less than the divergence damping coefficient d4. + +In FV3 the hyperdiffusion is primarily meant to diffuse the kinetic energy of the rotational component of the flow, similarly to how the divergence damping dissipates the kinetic energy in the divergence component of the flow. (For this reason, the hyperdiffusion is sometimes called “vorticity” damping.) The diffusion is applied to the vorticity *flux*, allowing application of diffusion to only the rotational component fo the flow without needing to explicitly compute the rotational component.To maintain consistent advection of the other prognostic variables—w, θv, and δp*—the fluxes for these quantities are diffused as well, so that the potential vorticity and updraft helicity are still consistently advected as if they were scalars. (There is no way to add diffusion to the tracer mass fluxes, since higher-order diffusion cannot ensure monotonicity preservation without performing an additional flux limiting, adding even more implicit diffusion.) + +The hyperdiffusion is equal to the order of the divergence damping, unless eighth-order divergence damping is used, for which the hyperdiffusion remains sixth-order. The diffusion operator itself is second-order, but higher order diffusion is easily computed by repeatedly applying the diffusion operator, as is done for the divergence damping. + +Vertical vorticity is a cell-integrated quantity on the model grid. The vorticity fluxes vΩ/Δx and -uΩ/Δy are used to update the vector-invariant momentum equations. We can apply damping on the vorticity as well; to maintain consistent advection, the same damping is applied to the mass, heat, and vertical momentum fields, all of which are co-located with the vorticity. This additional damping is beneficial when using a non-monotonic advection scheme, which lacks the implicit diffusion of monotonic advection. + +Since the diffusion added to the vorticity fluxe is known explicitly, the loss of kinetic energy due to this explicit diffusion can be computed. The lost energy optionally can be added back as heat, after applying a horizontal smoother to the energy density field (so as not to restore the grid-scale noise which the damping was intended to remove). This can greatly improve the dynamical activity on marginally-resolved scales. + +###2.3 Energy-, momentum-, and mass-conserving 2Δz filter + +Local Richardson-number dynamic instabilities can create instabilities, especially in higher-top models, if the vertical turbulence scheme in the physical parameterizations is either disabled or insufficiently-strong to relieve these instabilities. These instabilities can grow large enough to crash the model. To relieve these instabilities, FV³ has the option to use a local (2Δz), vertical mixing to release the instability. This is similar to the Richardson number based subgrid-scale diffusion formulations of Lilly (1962, Tellus) and of Smagorinsky (1963), although their isotropic formulations have been simplified so as to only act on vertical gradients and perform diffusion in the vertical. This filter is completely local (2Δz), diagnosing and acting only on adjacent grid cells, and is typically applied only in the stratosphere and above to avoid interference with physical dynamic instabilities in the free troposphere or boundary layer which are more accurately-simulated by a planetary boundary layer scheme or the resolved dynamics. This filter is applied at the same frequency that the physical parameterizations are updated. + +We compute the local Richardson number on cell interfaces. Recall that k = 1 is the top layer of the domain and the index increases downward: + +\f[ + Ri_{k-\frac{1}{2}} = \frac{g\delta z\delta_z\theta_v}{(\theta^{k}_{v}+\theta^{k-1}_{v})((\delta_z u)^2+(\delta_z v)^2)} \\ \tag {2.6} + \f] + + +If Ri < 1, then mixing M is performed, scaled by Ri so that complete mixing occurs if R ≤ 0: + +\f[ + M = max(1, (1-Ri)^2) \frac{\delta p^{*k}\delta p^{*(k-1)}}{\delta p^{*k} +\delta p^{*(k-1)}} \\ \tag {2.7} + \f] + +The mixing is applied to each variable, including the winds interpolated to the A-grid (necessary for application of the physical paramterization tendencies) on a timescale τ (namelist parameter `fv_sg_adj`) which should be larger than the physics timestep to avoid suppressing resolved convective motions. The mixing is applied to the momentum (δp* ua, δp* va), total energy, air mass, and all tracer masses, so that all of these quantities are conserved: + +\f[ + \frac{\partial \phi^k}{\partial t} = - \frac{M}{\delta p^{*k} } \left(\phi^k - \phi^{k-1} \right) \frac{1}{\tau} \\ \tag {2.8} + \f] + + +\f[ + \frac{\partial \phi^{k-1}}{\partial t} = + \frac{M}{\delta p^{*k} } \left(\phi^k - \phi^{k-1} \right) \frac{1}{\tau} \\ \tag {2.9} + \f] + +where ϕ is a generic scalar. Note that since total energy and momentum are both conserved, lost kinetic energy automatically becomes heat. + +This mixing is most useful for removing instabilities caused by vertically propagating waves near the top of the domain. The namelist variable `n_sponge` controls the number of levels at the top of the domain to which the filter is applied. + +###2.4 Model-top sponge layer and energy-conserving Rayleigh damping + +Two forms of damping are applied at the top of the domain to absorb vertically propagating waves nearing the upper boundary. The first is a diffusive sponge layer, which applies second-order damping to the divergence and to the vertical-momentum flux, and optionally also to the vorticity and mass fluxes if the hyperdiffusion is enabled. (This differs from earlier versions of FV³, which instead of adding explicit damping applied first-order upwind advection in the sponge layer, the strength of which is flow-dependent and not user-controllable.) The damping is computed in the same way as described earlier, although typically a very strong value of d2 is used to ensure the vertically-propagating waves are sufficiently damped. The additional ∇2 sponge-layer damping is applied to the top two layers of the model, with a weaker damping also applied in the third layer if dk2 > 0.05. Since the model top is at a constant pressure, not constant height, it acts as a flexible lid, and therefore does not reflect as strongly as a rigid lid would. + +The second form of damping is a Rayleigh damping, which damps all three components of the winds to zero with a timescale which depends on the pressure. Given a minimum timescale τ0 and a cutoff pressure pc the damping timescale is: + +\f[ + \tau(p^*) = \tau_0 sin \left( \frac{\pi}{2} \frac{log(p_c / p^*)}{log(p_c / p_T} \right)^2 \\ \tag {2.10} + \f] + +The strength of the applied damping is then determined by the magnitude of the cell-mean 3D vector wind U3D, including the vertical velocity, divided by a scaling velocity U0. The damping is only applied if the horizontal wind speed exceeds a latitude-dependent threshold (currently 25cosθ) or if the vertical velocity is larger than a given threshold. The damping is then applied, at the beginning of each large (physics) time step and before the Lagrangian dynamics is first called, by: + +\f[ + u \longleftarrow u(1 + \tau U_{3D} / U_0)^{-1} \\ \tag {2.11} + \f] + +The dissipated kinetic energy can then be restored as heat: + +\f[ + T \longleftarrow T + \frac{1}{2} U_{3D} * (1 - (1 + \tau U_{3D} / U_0)^{-2}) / C_v \\ \tag {2.12} + \f] + + + + diff --git a/docs/Chapter3.md b/docs/Chapter3.md new file mode 100644 index 000000000..b32b3eecd --- /dev/null +++ b/docs/Chapter3.md @@ -0,0 +1,63 @@ +Physics-dynamics coupling {#physics} +========================================= + +##Chapter 3 + +###3.1 Staggered wind interpolation + +The coupling to physical parameterizations and surface models is straight forward; the primary complication is interpolating between cell-centered, orthogonal winds used by most physics packages and the FV³ staggered non-orthogonal D-grid. The unstaggered orthogonal wind is defined by horizontal components in longitude and latitude; the staggered non-orthogonal D-grid wind is defined by the winds tangential to the grid-cell interfaces by the horizontal covariant components in the cubed-sphere curvilinear components. A two-stage horizontal re-mapping of the wind is used when coupuling the physics packages to the dynamics. The D-grid winds are first transformed to locally orthogonal and unstaggered wind components at cell centers, as input to the physics. After the physics returns its tendencies, the wind tendencies (du/dt, dv/dt) are then remapped (using high-order algorithm) back to the native grid for updating the prognostic winds. This procedure satisfies the “no data no harm” principle — that the interpolation/remapping procedure creates no tendency on its own if there are no external sources from physics or data assimilation. + +###3.2 Condensate loading and mass conservation + +The mass δm, and thereby also δp*, in FV³ is the total mass of both the dry air and of the water categories, including the vapor and condensate phases; the precise number N of water species is dependent upon the microphysics scheme used, or may be zero. This incorporates the effect of condensate loading into the air mass without a special parameterization for loading. The dry weight (per unit area) can be given as: + +\f[ + g \delta m_d = \delta p^* \left( 1 - \sum_{m=1}^N q_m \right) = \left( \delta p^* - \sum_{m=1}^N Q_m \right) \\ \tag {3.1} + \f] + +where Qm = δp* qm is the tracer mass. Dry mass should be conserved by the physical parameterizations; here we will assume this to be the case, so δmd should be a constant in each grid cell during the physical tendency updates. The condition for dry mass conservation is then given by + +\f[ + \delta p^{*(n+1)} = \delta p^{*n} + \delta \tau \sum_{m=1}^N \frac{dQ_m}{dt} = \delta p^{*n} \Delta M \tag {3.2} +\f] + + +where ΔM = 1 + δτ ΣNm=1 dqi/dt. Physics packages usually return the rate of change in tracer mass dQm /dt, and so is independent of whether the solver uses total air mass or just dry air mass (as is done in many weather models). The tracer update is then done by: + +\f[ + Q^{n+1}_m = Q^n_m + \delta \tau \frac{dQ_m}{dt} \tag {3.3} +\f] + + +or, using (3.2) + +\f[ + q^{n+1}_m = \left( Q^n_m + \delta \tau \frac{dq_m}{dt} \delta p^{*n} \right) / \left( \delta p^{*(n+1)} \right) \\ \tag {3.4} +\f] + +\f[ + = \left( Q^n_m + \delta \tau \frac{dq_m}{dt}\delta p^{*n} \right) / \left( \delta p^{*n} \Delta M \right) \\ \tag {3.5} +\f] + +The full mass-conserving update algorithm is then: + +\f[ + q^{*}_m = q^n_m + \delta \tau \frac{dq_m}{dt} \tag {3.6} +\f] + +\f[ + \Delta M = 1 + \delta \tau \sum_{m=1}^N \frac{dq_m}{dt} \tag {3.7} +\f] + +\f[ + \delta p^{n+1} = \delta p^{n} \Delta M \tag {3.8} +\f] + +\f[ + \delta q^{n+1}_m = q^{*}_m / \Delta M \tag {3.9} +\f] + +Note that often the mass of non-water species, such as ozone or aerosols, are considered so small that they are not included in δm; however, since their mixing ratio is still the quotient of the tracer mass and the total air mass, if the effects of water species are included in the total air mass their mixing ratios must still be adjusted by (3.9). + + + diff --git a/docs/Chapter4.md b/docs/Chapter4.md new file mode 100644 index 000000000..60c344aa6 --- /dev/null +++ b/docs/Chapter4.md @@ -0,0 +1,65 @@ +Grid refinement techniques {#grid} +========================================= + +##Chapter 4 + +There is a need for increasingly high-resolution numerical models for weather and climate simulation, but also an increasing need for coupling the newly resolved scales to the large and global-scale circulations, for which limited area models are only of limited use. However, uniformly-high resolution global models are not always practical on present-day computers. The solution to this problem is to locally refine a global grid, allowing for enhanced resolution over the area of interest while also representing the global grid. FV³ has two variable-resolution methods: a simple Schmidt transformation for grid stretching, and two-way regional-to-global nesting. These methods can be combined for maximum flexibility. + +FV³ can also be configured as a doubly-periodic solver, in which the cubed-sphere is replaced by a Cartesian-coordinate doubly-periodic horizontal grid; otherwise the solver is unchanged. This can be useful for idealized simulations at a variety of resolutions, including very high horizontal resolutions useful for studying explicit convection. + +###4.1 Grid stretching +Here we follow the development of HLT16. A relatively simple variable resolution grid can be created by taking the original cubed-sphere grid and applying the transformation of F. Schmidt (Beitr. Atmos. Phys., 1977) to “pull” grid intersections towards a “target” point, corresponding to the center point of the high-resolution region. This is done in two steps: the grid is distorted towards the south pole to get the desired degree of refinement, and then the south pole is rotated to the target point using a solid-body rotation. Distorting to the south pole means that the longitudes of the points are not changed, only the latitudes, greatly simplifying the transformation. + +The transformation of the latitude θ to ϑ is given by: + +\f[ + sin\vartheta = \frac{D + sin\theta}{1 + Dsin\theta} \\ \tag {4.1} + \f] + +where the distortion is a function of the stretching factor c, which can be any positive number: + +\f[ + D = \frac{1 - c^2}{1 + c^2} \\ \tag {4.2} + \f] + +Using c = 1 causes no stretching. Note that other forms for the transformation could also be used without making any other changes to the solver. + +Although the grid has been deformed, the solver still uses the assumption that the grid cells are bounded by great-circle arcs, which are not strictly identical to a Schmidt transformation of the cubed-sphere arcs of the unstretched grid. + +###4.2 Grid nesting + +Using grid nesting can greatly increase the flexibility of grid refinement in the model, at the cost of greater complexity in the solver. The major strength of grid nesting is its ability to use independent configurations on each grid, including different time steps and physical parameterizations, most appropriate for that particular grid. The ability to use a longer time step on the coarse grid than on the nested grid can greatly improve the efficiency of a nested-grid model; and choosing parameterizations independently allows values appropriate for each resolution without needing compromise or “scale-aware” parameterizations. + +Here we follow the development of HL13, with additional updates necessary for the nonhydrostatic solver. Implementing two-way grid nesting involves two processes: interpolating the global grid variables to create boundary conditions for the nested-grid, and then updating the coarse-grid solution with nested-grid data in the region they overlap. The goal is to do so in as efficient of a manner consistent with the finite-volume methodology. + +A major feature of FV³’s nesting is to use concurrent nesting, in which the nested and coarse grids run simultaneously, akin to how coupled models run their atmosphere and ocean components at the same time on different sets of processors. This can greatly reduce the amount of load imbalance between the different processors. + +The entire nesting cycle is as follows, starting at the beginning of call to the solver: + +- For each `p_split` step: + - Call solver + - Fetch boundary condition data from coarse grid + - In Lagrangian dynamics, update boundary conditions at each ¢t by extrapolating from two earlier coarse-grid states. + - Perform tracer transport and vertical remapping + - Perform two-way update +- Call physics + +Note that we do not do a compile cycle every coarse-grid time step, unlike many regional nested-grid models. The cycling can be carried out multiple times per physics time step, if more frequent updates of the boundary conditions and of the two-way communication are considered necessary. There is also an option to perform the last two-way update after the physics, instead of before, which changes how the physical parameterizations interact with the nested-grid solution passed to the coarse grid. Performing the update before calling the physics has been found to yield better results in real-data forecasts. + +Currently, nested grids in FV³ are constrained to be a proper refinement of a subset of coarse-grid cells; that is, each coarse-grid cell in the nested grid region is subdivided into N x N nested-grid cells. This greatly simplifies the nested-grid boundary condition interpolation and the two-way updating. Nested grids are also static and constrained to lie within one coarse-grid face. However, the algorithm does not require an aligned, static grid in one cube face, and any of these conditions may be relaxed in the future. + +The nested-grid boundary conditions are implemented in a simple way. Coarse-grid data is interpolated from the coarse grid into the halo of the nested grid, thereby providing the nested-grid boundary conditions. Linear interpolation, although it is simple and and is not conserving, does have the advantage of not introducing new extrema in the interpolated field. The boundary conditions for staggered variables are interpolated directly from the staggered coarse grids. Boundary conditions are needed for each prognostic variable, including the tracers; also, boundary conditions are needed for the C-grid winds, available at each half-time step, and for the divergence when using fourth or higher-order divergence damping. + +Finally, boundary conditions for the layer-interface nonhydrostatic pressure anomalies are also needed to evaluate the pressure-gradient force. Instead of interpolating these interface values from the coarse grid, they are instead diagnosed and interpolated from the other boundary condition variables using the same methods as the semi-implicit solver. + +Most nested-grid models perform time-interpolation between two coarse grid states on each time step, but since the grids are integrated concurrently in FV³, interpolation is not possible. Instead, we can extrapolate between two earlier coarse-grid states. If interpolated coarse-grid variables are available at times t and t - Δ τ, where Δ τ = N Δt, then the extrapolation for a given variable φ at time t + nδt (n=1,...,N) is given by: + +\f[ + \phi^{t+n\delta t} = \left( 1 + \frac{n}{N} \right) \phi^t - \frac{n}{N} \phi^{t-\Delta \tau} \\ \tag {4.3} + \f] + +The extrapolation is constrained for positive-definite scalars so that the value of the boundary condition at t + Δτ is non-negative, which is done by the substitution φt - Δτ → min(φt - Δτ , 2φt ). + +Two-way updates from the nested to the coarse grid are performed consistent with the finite-volume numerics. Scalars are updated to the coarse grid by performing an average of nested-grid cells, consistent with the values being cell-averages. The staggered horizontal winds are updated by averaging the winds on the faces of nested-grid cells abutting the coarse-grid cell being updated, so that the update preserves the average of the vorticity on the nested-grid cells. In FV³ only the three wind components and the temperature is updated to the coarse grid; the air and tracer masses are not updated, trivially conserving their masses on the nested grid, and reducing the amount of noise created through overspecification of the solution on the coarse grid. Since the air mass determines the vertical coordinate, which will differ between the two grids, the averaged nested-grid data is remapped onto the coarse-grid’s vertical coordinate. + + diff --git a/docs/Doxyfile b/docs/Doxyfile new file mode 100644 index 000000000..1e2293dd9 --- /dev/null +++ b/docs/Doxyfile @@ -0,0 +1,300 @@ +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = "FV3DYCORE" +PROJECT_LOGO = image/UFSLogo.png +CREATE_SUBDIRS = NO +OUTPUT_LANGUAGE = English +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = NO +QT_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 4 +OPTIMIZE_OUTPUT_FOR_C = NO +OPTIMIZE_OUTPUT_JAVA = NO +OPTIMIZE_FOR_FORTRAN = YES +OPTIMIZE_OUTPUT_VHDL = NO +MARKDOWN_SUPPORT = YES +AUTOLINK_SUPPORT = YES +BUILTIN_STL_SUPPORT = NO +CPP_CLI_SUPPORT = NO +SIP_SUPPORT = NO +IDL_PROPERTY_SUPPORT = YES +DISTRIBUTE_GROUP_DOC = NO +SUBGROUPING = YES +INLINE_GROUPED_CLASSES = NO +INLINE_SIMPLE_STRUCTS = NO +TYPEDEF_HIDES_STRUCT = NO +LOOKUP_CACHE_SIZE = 0 +EXTRACT_ALL = YES +EXTRACT_PRIVATE = YES +EXTRACT_PACKAGE = NO +EXTRACT_STATIC = NO +EXTRACT_LOCAL_CLASSES = YES +EXTRACT_LOCAL_METHODS = NO +EXTRACT_ANON_NSPACES = NO +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = YES +HIDE_SCOPE_NAMES = NO +SHOW_INCLUDE_FILES = YES +SHOW_GROUPED_MEMB_INC = NO +FORCE_LOCAL_INCLUDES = NO +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = NO +SORT_MEMBERS_CTORS_1ST = NO +SORT_GROUP_NAMES = NO +SORT_BY_SCOPE_NAME = NO +STRICT_PROTO_MATCHING = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = YES +SHOW_FILES = YES +SHOW_NAMESPACES = YES +LAYOUT_FILE = +CITE_BIB_FILES = +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = NO +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +INPUT = ./documentation.dox \ + ./Preface.md \ + ./Chapter1.md \ + ./Chapter2.md \ + ./Chapter3.md \ + ./Chapter4.md \ + ./appendixA.md \ + ./appendixB.md \ + ./appendixB1.md \ + ./appendixB2.md \ + ./AdvectionOperators.md \ + ./OverviewFV3Dycore.md \ + ./Links.md \ + ../model/gwdps.f \ + ../model/a2b_edge.F90 \ + ../model/boundary.F90 \ + ../model/dyn_core.F90 \ + ../model/fv_arrays.F90 \ + ../model/fv_cmp.F90 \ + ../model/fv_control.F90 \ + ../model/fv_dynamics.F90 \ + ../model/fv_fill.F90 \ + ../model/fv_grid_utils.F90 \ + ../model/fv_mapz.F90 \ + ../model/fv_nesting.F90 \ + ../model/fv_regional_bc.F90 \ + ../model/fv_sg.F90 \ + ../model/fv_tracer2d.F90 \ + ../model/fv_update_phys.F90 \ + ../model/multi_gases.F90 \ + ../model/nh_core.F90 \ + ../model/nh_utils.F90 \ + ../model/sw_core.F90 \ + ../model/tp_core.F90 \ + ../tools/external_ic.F90 \ + ../tools/external_sst.F90 \ + ../tools/fv_diagnostics.F90 \ + ../tools/fv_eta.F90 \ + ../tools/fv_grid_tools.F90 \ + ../tools/fv_iau_mod.F90 \ + ../tools/fv_io.F90 \ + ../tools/fv_mp_mod.F90 \ + ../tools/fv_nudge.F90 \ + ../tools/fv_restart.F90 \ + ../tools/fv_surf_map.F90 \ + ../tools/fv_timing.F90 \ + ../tools/fv_treat_da_inc.F90 \ + ../tools/init_hydro.F90 \ + ../tools/sim_nc_mod.F90 \ + ../tools/sorted_index.F90 \ + ../tools/test_cases.F90 \ + ../driver/fvGFS/atmosphere.F90 \ + ../driver/fvGFS/DYCORE_typedefs.F90 \ + ../driver/fvGFS/fv_nggps_diag.F90 +INPUT_ENCODING = UTF-8 +FILE_PATTERNS = +RECURSIVE = YES +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXCLUDE_SYMBOLS = +EXAMPLE_PATH = +EXAMPLE_PATTERNS = +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = images/ +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +FILTER_SOURCE_PATTERNS = +USE_MDFILE_AS_MAINPAGE = documentation.dox +SOURCE_BROWSER = yes +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = NO +REFERENCES_RELATION = NO +REFERENCES_LINK_SOURCE = YES +SOURCE_TOOLTIPS = YES +USE_HTAGS = NO +VERBATIM_HEADERS = YES +ALPHABETICAL_INDEX = YES +COLS_IN_ALPHA_INDEX = 5 +IGNORE_PREFIX = +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_EXTRA_STYLESHEET = ccpp_dox_extra_style.css +HTML_EXTRA_FILES = +HTML_COLORSTYLE_HUE = 220 +HTML_COLORSTYLE_SAT = 100 +HTML_COLORSTYLE_GAMMA = 80 +HTML_TIMESTAMP = YES +HTML_DYNAMIC_SECTIONS = NO +HTML_INDEX_NUM_ENTRIES = 100 +GENERATE_DOCSET = NO +DOCSET_FEEDNAME = "Doxygen generated docs" +DOCSET_BUNDLE_ID = org.doxygen.Project +DOCSET_PUBLISHER_ID = org.doxygen.Publisher +DOCSET_PUBLISHER_NAME = Publisher +GENERATE_HTMLHELP = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +CHM_INDEX_ENCODING = +BINARY_TOC = NO +TOC_EXPAND = NO +GENERATE_QHP = NO +QCH_FILE = +QHP_NAMESPACE = org.doxygen.Project +QHP_VIRTUAL_FOLDER = doc +QHP_CUST_FILTER_NAME = +QHP_CUST_FILTER_ATTRS = +QHP_SECT_FILTER_ATTRS = +QHG_LOCATION = +GENERATE_ECLIPSEHELP = NO +ECLIPSE_DOC_ID = org.doxygen.Project +DISABLE_INDEX = YES +GENERATE_TREEVIEW = YES +ENUM_VALUES_PER_LINE = 4 +TREEVIEW_WIDTH = 250 +EXT_LINKS_IN_WINDOW = NO +FORMULA_FONTSIZE = 10 +FORMULA_TRANSPARENT = YES +USE_MATHJAX = YES +MATHJAX_FORMAT = HTML-CSS +MATHJAX_RELPATH = https://cdn.mathjax.org/mathjax/latest +MATHJAX_EXTENSIONS = +MATHJAX_CODEFILE = +SEARCHENGINE = YES +SERVER_BASED_SEARCH = NO +EXTERNAL_SEARCH = NO +SEARCHENGINE_URL = +SEARCHDATA_FILE = searchdata.xml +EXTERNAL_SEARCH_ID = +EXTRA_SEARCH_MAPPINGS = +GENERATE_LATEX = NO +LATEX_OUTPUT = latex +LATEX_CMD_NAME = latex +MAKEINDEX_CMD_NAME = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = a4 +EXTRA_PACKAGES = amsmath \ + amsmath \ + amssymb \ + graphicx +LATEX_HEADER = +LATEX_FOOTER = +LATEX_EXTRA_FILES = +PDF_HYPERLINKS = YES +USE_PDFLATEX = YES +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +LATEX_SOURCE_CODE = NO +LATEX_BIB_STYLE = plain +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +GENERATE_MAN = NO +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_LINKS = NO +GENERATE_XML = NO +XML_OUTPUT = xml +XML_SCHEMA = +XML_DTD = +XML_PROGRAMLISTING = YES +GENERATE_DOCBOOK = NO +DOCBOOK_OUTPUT = docbook +GENERATE_AUTOGEN_DEF = NO +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +PERLMOD_MAKEVAR_PREFIX = +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = NO +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +EXTERNAL_PAGES = YES +PERL_PATH = /usr/bin/perl +CLASS_DIAGRAMS = YES +MSCGEN_PATH = +DIA_PATH = +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = NO +DOT_NUM_THREADS = 0 +DOT_FONTNAME = Helvetica +DOT_FONTSIZE = 10 +DOT_FONTPATH = +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = NO +UML_LIMIT_NUM_FIELDS = 10 +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = NO +CALLER_GRAPH = NO +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DOT_IMAGE_FORMAT = png +INTERACTIVE_SVG = NO +DOT_PATH = +DOTFILE_DIRS = +MSCFILE_DIRS = +DIAFILE_DIRS = +DOT_GRAPH_MAX_NODES = 50 +MAX_DOT_GRAPH_DEPTH = 0 +DOT_TRANSPARENT = NO +DOT_MULTI_TARGETS = YES +GENERATE_LEGEND = YES +DOT_CLEANUP = YES diff --git a/docs/DoxygenLayout.xml b/docs/DoxygenLayout.xml new file mode 100644 index 000000000..171a20ef8 --- /dev/null +++ b/docs/DoxygenLayout.xml @@ -0,0 +1,194 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/Links.md b/docs/Links.md new file mode 100644 index 000000000..0440e7bb9 --- /dev/null +++ b/docs/Links.md @@ -0,0 +1,25 @@ +Useful Links {#link} +=========== + +FV3Dycore Science articles + +https://www.weather.gov/sti/s%20timodeling_nggps_dycoredocumentation + +FV3 Documentation and References + +https://www.gfdl.noaa.gov/fv3/fv3-documentation-and-references/ + +EXPLICIT DIFFUSION IN GFDL FV3 + +https://www.earthsystemcog.org/site_media/projects/dycore_test_group/20160127_Diffusion_operators.pdf + + +Various presentations + + https://vlab.ncep.noaa.gov/web/fv3gfs/training + +Recent FV3 Team Journal Articles and Presentations + +https://www.gfdl.noaa.gov/fv3/fv3-journal-articles-and-presentations/ + + diff --git a/docs/Preface.md b/docs/Preface.md new file mode 100644 index 000000000..ed4d081bf --- /dev/null +++ b/docs/Preface.md @@ -0,0 +1,26 @@ +Preface {#preface} +======================== + +**AUTHORS: SHIAN-JIANN LIN, WILLIAM PUTMAN, LUCAS HARRIS AND THE GFDL FV³ TEAM** + + +**VERSION 1.0 (DRAFT)** + +*Date November 29, 2017* + + +`RESPONSIBLE ORGANIZATION:` **OAR/GFDL** + +**CHANGE RECORD PAGE** + +| Version | Date | Page affected | Description | +| ----: | :----: | :------- | :------------ | +| 1.0 (DRAFT) | 11/28/2017 | all | Draft submitted to EMC | + +##Disclaimer +We have made every effort to ensure that the information in this document is as accurate, complete, and as up-to-date as possible. However, due to the rapid pace of FV³ and FV³-powered model development the document may not always reflect the current state of FV³ capabilities. Often, the code itself is the best description of the current capabilities and the available options, which due to limited space cannot all be described in full detail here. +Contact GFDL FV³ support: oar.gfdl.fv3_dycore_support@noaa.gov for questions regarding the FV3 Dynamical Core +and oar.gfdl.shield_support@noaa.gov for questions regarding the GFDL SHiELD weather prediction model. + + + diff --git a/docs/appendixB.md b/docs/appendixB.md new file mode 100644 index 000000000..5fd437bc5 --- /dev/null +++ b/docs/appendixB.md @@ -0,0 +1,73 @@ +Variables and notation {#variables} +=========== + + +Variables | Notation +------------- | ------------- +`u,v` | (*) D-grid winds +` w` | (*) Explicit vertical velocity + δ p* | (*) Layer hydrostatic pressure thickness, proportional to mass + Θ v | (*) Virtual potential temperature + δ z | (*) Layer geometric depth +ρ | Total (air and all water species) mass density, equal to -δp*/gδz + Qi | (*) Density of tracer i (also written Q as a generic tracer density) +qi | Mixing ratio of tracer i, defined with respect to total air mass; equal to Qi/δp* +qv | Mixing ratio of water vapor +p | Total cell-mean pressure +p* | Cell-mean hydrostatic pressure +p' | Cell-mean nonhydrostatic pressure component, equal to p - p* +ΔA, Δx, Δy | D-grid cell areas and cell face lengths +ΔAc, Δxc, Δyc | Dual-grid cell areas and cell face lengths + Δt | Lagrangian dynamics (or acoustic) time step +ΔT | Vertical remapping interval +Δτ | Physics time step +cpd | Specific heat of dry air at constant pressure +Rd | Gas constant for dry air +cp | Variable specific heat of moist air +κ | R/cp, where R is the (variable) gas constant of moist air +i, j, k | Spatial grid-cell indices for the local x-, y-, and z-directions, respectively, given as subscripts +n | time index +m | tracer index, given as a subscript +n | time index, given as a superscript: tn = nΔt + +Here, a (*) indicates a prognostic variable. All variables are cell-means (or face-means for horizontal winds) unless otherwise noted. The differencing notation used in this document follows that of LR96, LR97, and L04, in which the operator δx φ is defined as a centered-difference operator: + +\f[ +(\delta_x \phi)_{i+1/2} = \phi_{i+1} - \phi_i \tag {B.1} + \f] + + The indices on dependent variables are suppressed unless explicitly needed.) This definition differs from the similar operators of in the literature intended to be second-order discretizations of a derivative; to do this with our definition of δx a 1/Δx term would be needed to complete the discrete derivative. + +======================== + +##B.1 Important Relations + +Cell-mean pressure: +\f[ +p^* = \frac{\delta p^*}{\delta \log p^*} \; \mathrm{(hydrostatic)} \\. \tag {B.2} + \f] + +\f[ +p = \rho R_d T_v = - \frac{R_d}{g} \frac{\delta p^* T_v}{\delta z} \mathrm{(nonhydrostatic)} \tag {B.3} + \f] + +Conversion from temperature *T* to virtual potential temperature Θv : + +\f[ +T_v = T \left ( 1 + \epsilon q_v \right ) \tag {B.4} + \f] + +\f[ +\Theta_v = T_v / p^\kappa \tag {B.5} + \f] +where ε = 1 + Rv/Rd and κ = R/cp. Note that we do *not* include the arbitrary constant factor p0κ in our definition of potential temperature; our form is the equivalent to setting p0 = 1Pa but simpler and more computationally efficient. + + + + + + + + + + diff --git a/docs/appendixB1.md b/docs/appendixB1.md new file mode 100644 index 000000000..a5f74068f --- /dev/null +++ b/docs/appendixB1.md @@ -0,0 +1,34 @@ +References {#references} +=========== + + + + +**[CW84]** Collella, P, and P. R. Woodward, April 2004: The Piecewise Parabolic Method (PPM) for Gas-Dynamical Simulations. *Journal of Computational Physics*, **54**, 174--201. + +**[L94]** Lin, Shian-Jiann, et al., July 1994: A Class of the van Leer-type Transport Schemes and Its Application to the Moisture Transport in a General Circulation Model. *Monthly Weather Review*, **122:7**, 1575--1593. + +**[LR96]** Lin, Shian-Jiann, and R B Rood, September 1996: Multidimensional Flux-Form Semi-Lagrangian Transport Schemes. *Monthly Weather Review*, **124:9**, 2046--2070. + +**[LR97]** Lin, Shian-Jiann, and R B Rood, October 1997: An explicit flux-form semi-lagrangian shallow-water model on the sphere. *Quarterly Journal of the Royal Meteorological Society*, **123:544**, 2477--2498. + +**[L97]** Lin, Shian-Jiann, July 1997: A finite-volume integration method for computing pressure gradient force in general vertical coordinates. *Quarterly Journal of the Royal Meteorological Society*, **123:542**, 1749--1762. + +**[L04]** Lin, Shian-Jiann, 2004: A "vertically Lagrangian" finite-volume dynamical core for global models. *Monthly Weather Review*, **132:10**, 2293--2307. + +**[PL07]** Putman, W M., and Shian-Jiann Lin, 2007: Finite-volume transport on various cubed-sphere grids. *Journal of Computational Physics*, **227:1**, 55--78. + +**[HL13]** Harris, Lucas M., and Shian-Jiann Lin, January 2013: A two-way nested global-regional dynamical core on the cubed-sphere grid. *Monthly Weather Review*, **141:1**. + +**[HLT16]** Harris, L.M., S.-J. Lin, and C.-Y. Tu, 2016: High-Resolution Climate Simulations Using GFDL HiRAM with a Stretched Global Grid. *Journal of Climate*, **29:11**, 4293--4314. + + + + + + + + + + + diff --git a/docs/appendixB2.md b/docs/appendixB2.md new file mode 100644 index 000000000..9bf1c8882 --- /dev/null +++ b/docs/appendixB2.md @@ -0,0 +1,22 @@ +Revision History {#revisionHistory} +=========== + + +| Version | Date | Page affected | Description | +| ----: | :----: | :------- | :------------ | +| **v2.0beta** | *14 Nov 2017* | all | Release candidate to EMC — lmh | + + + + + + + + + + + + + + + diff --git a/docs/documentation.dox b/docs/documentation.dox new file mode 100644 index 000000000..a64bbd814 --- /dev/null +++ b/docs/documentation.dox @@ -0,0 +1,12 @@ +/**@page Desc Description of the GFDL Finite-Volume Cubed-Sphere Dynamical Core + + + @subpage preface + + @subpage introduction + + @subpage stabilization + + @subpage physics + + @subpage grid + + @subpage Parameters_List + + @subpage variables + + @subpage references + + @subpage revisionHistory +*/ \ No newline at end of file