Skip to content

d_sw

DGridShallowWaterLagrangianDynamics

Fortran name is the d_sw subroutine

__call__(delpc, delp, pt, u, v, w, uc, vc, ua, va, divgd, mfx, mfy, cx, cy, crx, cry, xfx, yfx, q_con, zh, heat_source, diss_est, dt)

D-Grid shallow water routine, peforms a full-timestep advance of the D-grid winds and other prognostic variables using Lagrangian dynamics on the cubed-sphere.

Described by Lin 1997, Lin 2004 and Harris 2013.

Parameters:

Name Type Description Default
delpc inout

C-grid vertical delta in pressure

required
delp inout

D-grid vertical delta in pressure

required
pt inout

D-grid potential teperature

required
u inout

D-grid x-velocity

required
v inout

D-grid y-velocity

required
w inout

vertical velocity

required
uc in

C-grid x-velocity

required
vc in

C-grid y-velocity

required
ua in

A-grid x-velocity

required
divgd inout

D-grid horizontal divergence, used for divergence damping. TODO: Variable gets re-used for other purposes causing it to be inout, can we refactor those? corner handling, higher-order divergence damping temporary

required
mfx inout

accumulated x mass flux

required
mfy inout

accumulated y mass flux

required
cx inout

accumulated Courant number in the x direction

required
cy inout

accumulated Courant number in the y direction

required
crx out

local courant number in the x direction

required
cry out

local courant number in the y direction

required
xfx out

flux of area in x-direction, in units of m^2

required
yfx out

flux of area in y-direction, in units of m^2

required
q_con inout

total condensate mixing ratio, used for ideal gas law calculation

required
zh in

geopotential height defined on layer interfaces

required
heat_source inout

accumulated heat source

required
diss_est inout

dissipation estimate

required
dt in

acoustic timestep in seconds

required

adjust_w_and_qcon(w, delp, dw, q_con, damp_w)

Parameters:

Name Type Description Default
w inout
required
delp in
required
dw in
required
q_con inout
required
damp_w in
required

apply_fluxes(q, delp, gx, gy, rarea)

Update q according to fluxes gx and gy.

Changes the units of q to be pressure-weighted.

Parameters:

Name Type Description Default
q inout

any scalar, the fluxes gx and gy are applied and the output is mass-weighted (replaced with units of q * delp)

required
delp in

pressure thickness of layer

required
gx in

x-flux of q in units of q * Pa * area

required
gy in

y-flux of q in units of q * Pa * area

required
rarea in

1 / area

required

apply_pt_delp_fluxes(pt_x_flux, pt_y_flux, rarea, delp_x_flux, delp_y_flux, pt, delp)

Parameters:

Name Type Description Default
fx in
required
fy in
required
pt inout
required
delp inout
required
gx in
required
gy in
required
rarea in
required

apply_pt_delp_fluxes_stencil_defn(fx, fy, pt, delp, gx, gy, rarea)

Parameters:

Name Type Description Default
fx in
required
fy in
required
pt inout
required
delp inout
required
gx in
required
gy in
required
rarea in
required

compute_kinetic_energy(vc, uc, cosa, rsina, v, vc_contra, u, uc_contra, dx, dxa, rdx, dy, dya, rdy, dt_kinetic_energy_on_cell_corners, dt)

Parameters:

Name Type Description Default
vc in

y-wind on c-grid

required
uc in

x-wind on c-grid

required
cosa in
required
rsina in
required
v in

y-wind on d-grid

required
vc_contra in

contravariant y-wind on c-grid

required
u in

x-wind on d-grid

required
uc_contra in

contravariant x-wind on c-grid

required
dx in
required
dxa in
required
rdx in
required
dy in
required
dya in
required
rdy in
required
dt_kinetic_energy_on_cell_corners out

kinetic energy on cell corners, as defined in FV3 documentation by equation 6.3, multiplied by dt

required
dt Float

timestep

required

compute_vorticity(u, v, dx, dy, rarea, vorticity)

Compute cell mean vorticity using Stokes' theorem (using average circulation).

Parameters:

Name Type Description Default
u in
required
v in
required
dx in
required
dy in
required
rarea in
required
vorticity out
required

flux_capacitor(cx, cy, xflux, yflux, crx_adv, cry_adv, fx, fy)

Accumulates the flux capacitor and courant number variables Saves the mass fluxes to the "flux capacitor" variables for tracer transport Also updates the accumulated courant numbers Args: cx (inout): accumulated courant number in the x direction cy (inout): accumulated courant number in the y direction xflux (inout): flux capacitor in the x direction, accumulated mass flux yflux (inout): flux capacitor in the y direction, accumulated mass flux crx_adv (in): local courant number, dtut/dx cry_adv (in): local courant number dtvt/dy fx (in): 1-D x-direction flux fy (in): 1-D y-direction flux

flux_increment(gx, gy, rarea)

Parameters:

Name Type Description Default
gx

x-direction flux of some scalar q in units of q * area defined on cell interfaces

required
gy

y-direction flux of some scalar q in units of q * area defined on cell interfaces

required
rarea

1 / area

required

Returns:

Type Description

tendency increment in units of q defined on cell centers

get_column_namelist(config, quantity_factory)

Generate a dictionary of columns that specify how parameters (such as nord, damp) used in several functions called by D_SW vary over the k-dimension.

heat_diss(fx2, fy2, w, rarea, heat_source, diss_est, dw, damp_w, ke_bg, dt)

Calculate heat generation due to loss of kinetic energy due to damping of vertical wind.

Does nothing for levels where damp_w <= 1e-5.

diss_est used for stochastic physics only

Parameters:

Name Type Description Default
fx2 in

x-flux of vertical wind to apply damping

required
fy2 in

y-flux of vertical wind to apply damping

required
w in

vertical wind

required
rarea in
required
heat_source out

heat source due to loss of kinetic energy

required
diss_est out

heat source due to loss of kinetic energy

required
dw inout

diffusive update to vertical wind, does not include convergence correction, since damping is numerical and not physical it's not necessary to include.

required
damp_w in
required
ke_bg in
required

heat_source_from_vorticity_damping(vort_x_delta, vort_y_delta, ut, vt, u, v, delp, rsin2, cosa_s, rdx, rdy, heat_source, dissipation_estimate, kinetic_energy_fraction_to_damp)

Calculates heat source from vorticity damping implied by energy conservation.

Described in Section 8.5 of FV3 docs.

Parameters:

Name Type Description Default
vort_x_delta in

x finite difference of damped b-grid vorticity

required
vort_y_delta in

y finite difference of damped b-grid vorticity

required
ut in

damping flux in x-direction of a-grid relative vorticity

required
vt in

damping flux in y-direction of a-grid relative vorticity

required
u in

d-grid x-velocity

required
v in

d-grid y-velocity

required
delp in

pressure thickness of layer

required
rsin2 in
required
cosa_s in
required
rdx in

1 / dx

required
rdy in

1 / dy

required
heat_source inout

heat source from vorticity damping implied by energy conservation

required
dissipation_estimate inout

dissipation estimate, only calculated if calculate_dissipation_estimate is 1. Used for stochastic kinetic energy backscatter (skeb) routine.

required
kinetic_energy_fraction_to_damp in

the fraction of kinetic energy to explicitly damp and convert into heat.

required

interpolate_uc_vc_to_cell_corners(uc_cov, vc_cov, cosa, rsina, uc_contra, vc_contra)

Convert covariant C-grid winds to contravariant B-grid (cell-corner) winds.

rel_vorticity_to_abs(relative_vorticity, f0, absolute_vorticity)

Parameters:

Name Type Description Default
relative_vorticity in

a-grid relative vorticity computed before divergence damping

required
f0 in

planetary vorticity

required
absolute_vorticity out

absolute vorticity on cell center (a-grid)

required

u_and_v_from_ke(ke, fx, fy, u, v, dx, dy)

Update the u and v velocities from the kinetic energy and flux of absolute vorticity.

Does not include the pressure gradient force update to the winds.

Converts u and v to udx and vdy.

Parameters:

Name Type Description Default
ke in

dt*kinetic_energy defined on cell corners

required
fx in

flux of absolute vorticity in x-direction

required
fy in

flux of absolute vorticity in y-direction

required
u inout

On input, u. On output, u * dx

required
v inout

On input, v. On output, v * dy

required
dx in
required
dy in
required

u_from_ke(ke, u, dx, fy)

Described in section 5.2 eq 5.3d and 5.3e of FV3 docs.

Can re-write the velocity equation in a vector-invariant form where no derivatives of velocity are taken:

du/dt = (y-flux of absolute vorticity) - d/dx(KE) + (pressure gradient term) dv/dt = -(x-flux of absolute vorticity) - d/dy(KE) + (pressure gradient term)

Equations 6.1d and 6.1e are the discrete form of the above equations.

The pressure gradient term is added later, not here.

This is important because then you don't need to worry about how the coordinate vectors are being advected, all advected terms are scalar.

Parameters:

Name Type Description Default
ke in

dt * kinetic energy defined on cell corners

required
u in

x-velocity

required
dx in

grid cell width

required
fy in

flux of absolute vorticity in y-direction

required

update_u_and_v(ut, vt, u, v, damp_vt)

Updates u and v with fluxes resulting from the diffusive flux of vorticity.

See docstring of u_from_ke for description of equations.

Parameters:

Name Type Description Default
ut in

x-direction diffusivie vorticity flux

required
vt in

y-direction diffusivie vorticity flux

required
u inout

d-grid x-velocity

required
v inout

d-grid y-velocity

required
damp_vt in

column scalar for damping vorticity

required

vort_differencing(vort, vort_x_delta, vort_y_delta, dcon)

Intermediate operation for computing heating due to diffusion

Parameters:

Name Type Description Default
vort in
required
vort_x_delta out
required
vort_y_delta out
required
dcon in
required