Contact: B. Wyman
Reviewers:
Change history: WebCVS Log for bgrid_core.f90
The top-level module for the B-grid atmospheric dynamical core.
This module controls many of the time integration options while
calling other modules to compute individual terms.
The B-grid dynamical core updates the tendencies of the
prognostic variables, the variables themselves are not modified.
The prognostic variables are surface pressure, the zonal and
meridional momentum components, temperature, and optionally an
arbitrary number of tracers. The core recognizes the tracer
specific humidity (sphum) when computing virtual temperature.
This version of the B-grid dynamics use a two time level scheme
with time splitting. The gravity waves are integrated using a
forward-backward scheme with a relatively short time step and
the advection terms are integrated with a longer time step.
Horizontal diffusion is done on the advective time step.
The B-grid core uses data structures (derived-type variables)
to group similar data and passes these data structures between
subroutines. Data structures for the horizontal and vertical
constants must be initialized before initializing the B-grid core.
The initialization routine returns a data structure that is needed
by subsequent calls when updating the prognostic variables tendencies.
The prognostic variables are also contained as a data structure.
Here is a detailed write-up of the finite differencing used in the
B-grid atmospheric dynamical core.
bgrid_prog_var_mod bgrid_horiz_mod bgrid_vert_mod bgrid_masks_mod bgrid_advection_mod bgrid_horiz_diff_mod bgrid_horiz_adjust_mod bgrid_vert_adjust_mod bgrid_polar_filter_mod bgrid_halo_mod bgrid_sponge_mod fms_mod constants_mod field_manager_mod tracer_manager_mod
use bgrid_core_mod [ ,only: bgrid_dynam_type,
bgrid_core_init,
update_bgrid_core,
bgrid_core_end ]
bgrid_dynam_type
A data structure (i.e., derived-type variable) that contains
grid constants, time step information, and other pre-computed terms
that are needed by the dynamical core. This includes other data
structures and pointers to the physical data, but does not include
the prognostic variables.
bgrid_core_init
Initializes the B-grid core data structure (bgrid_dynam_type) and
other modules used by the core. There is no namelist for bgrid_core_mod,
all runtime options are controlled with optional arguments to the
initialization subroutine. This subroutine must be called before
calling update_bgrid_core.
update_bgrid_core
Called once for every (atmospheric) time step to update only the
tendencies of the prognostic variables. No time differencing is done.
bgrid_core_end
Called at the end of the model run to terminate the module.
Currently this call does nothing.
type bgrid_dynam_type
-- derived data types contained in bgrid_dynam_type --
(see the appropriate module for details)
Hgrid = horizontal grid constants, initialized by horiz_grid_mod
[horiz_grid_type]
Vgrid = vertical grid constants, initialized by vert_grid_mod
[vert_grid_type]
Masks = eta coordinate topography masks and indices,
initialized by grid_masks_mod [grid_mask_type]
Pfilt = polar filter constants, initialized by polar_filter_mod
[pfilt_control_type]
-- real, dimension(:,:) --
fis = geopotential height of the surface (m2/s2)
fisl = geopotential height at eta=1. (for eta coord = 0.0,
res = reciprocal of eta at the surface
-- scalars --
nt_adj = no. of adjustment time steps per advection step [integer]
nt_adv = no. of advection time steps per atmospheric step [integer]
dt_adj = adjustment time step in seconds [real]
fopt = filtering option [integer]
pgf_method = identifier for pressure gradient algorithm [integer]
sphum = tracer index for specific humidity [integer]
coeff_ddamp = coefficient for divergence damping [real]
avg_omega = omega averaging flag [logical]
verbose = verbose flag [integer]
NOTE
Hgrid, Vgrid, fis, and res are pointers to the arguments passed
via the initialization call (bgrid_core_init).
call bgrid_core_init ( Dynam, Hgrid, Vgrid, fis, res, dt, ntadj, ntadv
[, pgf_scheme, filter_option, filter_weight,
ref_lat_filter, ddamp_coeff, avg_omega, verbose ] )
DESCRIPTION
Initializes the B-grid core data structure (bgrid_dynam_type) and other
modules used. Runtime options are controlled with optional arguments.
This subroutine must be called before calling update_bgrid_core.
INPUT
Hgrid Data structure containing horizontal grid constants (see horiz_grid_mod).
[type(horiz_grid_type)]
Vgrid Data structure containing vertical grid constants (see vert_grid_mod).
[type(vert_grid_type)]
fis Geopotential height of the surface (m2/s2).
Should have horizontal indexing consistent with the B-grid core.
[real, dimension(:,:)]
res Reciprocal of eta at the surface. Used at a switch for sigma vs. eta.
For the sigma coordinate, all res = 0.
Should have horizontal indexing consistent with the B-grid core.
[real, dimension(:,:)]
dtadv Time step in seconds for each call to update_bgrid_core.
This should be the atmospheric time step.
[real]
ntadj The number of adjustment time steps for each advective time step.
[integer]
ntadv The number of advection time steps for each call to update bgrid_core.
[integer]
INPUT/OUTPUT
Dynam Data structure that contains grid constants, time step information,
and other quantities needed by the dynamical core.
[type(bgrid_dynam_type)]
OPTIONAL INPUT (Note: These argument can be modified through a
namelist interface in the bgrid_core_driver_mod)
pgf_scheme The pressure gradient force scheme used.
Possible values are: 'default' or 'finite_volume'.
[character, default: pgf_scheme = 'default']
filter_option Determines how polar filtering is performed.
filter_option = 0, NO filtering (reduce time step approx 1/10)
= 1, obsolete scheme (not recommended)
= 2, ddefault scheme (see technical documention)
[integer, default: filter_option = 2]
filter_weight Weight applied to the polar filter that will
increase (or decrease) the strength of the standard
polar filter response function.
SS(new) = SS(std)**filter_weight,
where SS(std) is the Arakawa and Lamb response function.
[integer, default: filter_weight = 1 ]
ref_lat_filter The reference latitude at which polar filtering
(in each hemisphere) will begin to be applied.
Setting this argument >= 90. will turn off
polar filtering.
[real, default: ref_lat_filter = 60.]
ddamp_coeff Coefficient for divergence damping.
Use ddamp_coeff > 0 for second-order, and
use ddamp_coeff < 0 for fourth-order.
If ddamp_coeff = 0 then no divergence damping is done.
[real, default: ddamp_coeff = 0.]
avg_omega Flag that determines whether the returned omega diagnostic
is averaged over all adjustment time steps. If avg_omega=FALSE
then the value of omega for the last adjustment step is returned.
[logical, default: avg_omega = FALSE]
verbose Flag that control additional printed output.
Currently, this option is not being used.
[integer, default: verbose = 0]
NOTES
fis and res should be dimension by the size of the global grid,
the number of longitude points by number of latitude points.
The declaration of fis and res must have the target attribute
and the storage must be static.
---------------------------------------------------------------
call update_bgrid_core ( Var, Var_dt, Dynam, omega, div, mfew, mfns )
INPUT
Var Data structure that contains the B-grid prognostic variables.
[prog_var_type, see prog_var_mod]
INPUT/OUTPUT
Var_dt Data structure that contains the TENDENCIES of the B-grid
prognostic variables.
[prog_var_type]
Dynam Data structure returned by a previous call to bgrid_core_init.
[type(bgrid_dynam_type)]
OUTPUT
omega The omega diagnostic (from the thermodynamic equation) in
pascals per second. See the description of optional argument
"avg_omega" in interface bgrid_core_init.
[real, dimension(ilb:,jlb:,:)]
div The average divergence in 1/seconds.
This quantity is the actual mass divergence after
polar filtering. It has been divded by the layer mass
and averaged over all adjustment time steps.
[real, dimension(ilb:,jlb:,:)]
mfew The average zonal mass flux in Pascals-meters^2/second.
It is located on the east and west faces of a temperature
grid box and has been averaged over all adjustment time steps.
[real, dimension(ilb:,jlb:,:)]
mfns The average meridional mass flux in Pascals-meters^2/second.
It is located on the south and north faces of a temperature
grid box and has been averaged over all adjustment time steps.
[real, dimension(ilb:,jlb:,:)]
NOTES
Arrays omega, div, mfew, mfns should have horizontal dimensions
that are consistent with the B-grid dynamical core.
---------------------------------------------------------------
call bgrid_core_end ( Dynam )
DESCRIPTION
This interface currently does nothing.
It is provided for possible future use.
INPUT/OUTPUT
Dynam Data structure returned by a previous call to bgrid_core_init.
[type(bgrid_dynam_type)]
FATAL ERRORS in bgrid_core_init
input argument ntadj must be >= 1
If you were using the namelist interface &bgrid_core_driver_nml
then check the namelist variable corresponding to this variable.
input argument ntadv must be >= 1
If you were using the namelist interface &bgrid_core_driver_nml
then check the namelist variable corresponding to this variable.
input argument dt must be > 0.
The model time step usually is set at the highest program level.
Check the namelist for the main program.
invalid PGF scheme
The optional argument for "pgf_scheme" must be set to one of the
following: 'DEFAULT', 'FINITE_VOLUME', or 'SIMMONS_BURRIDGE'.
The default scheme is Simmons and Burridge.
Here is a detailed write-up of the finite differencing used in the
B-grid atmospheric dynamical core.
There are no known bugs.
internal option:
---------------
alpha_implicit determines how the coriolis and press grad force
terms are solved
= 0.5 trapezoidal implicit
= 1.0 fully implicit
[real, default: alpha_implicit = 0.5]
Eta/Step-Mountain Coordinate (UNSUPPORTED)
----------------------------
The B-grid model can be run with either "sigma" (terrain following)
coordinates or "eta" (the step-mountain coordinate). In the sigma
coordinate system, the coordinate surfaces follow the topography,
there is always the same number of model levels above ground at all
grid boxes. In the eta coordinate system, the coordinate surfaces
are nearly horizontal, model grid boxes will be beneath the topography.
The step-mountain topography can be thought of as "building blocks".
The model levels below the topography are masked out.
None.