overflow
The overflow task group is comprised of seven smoke_test tasks for quick
testing (one for each horizontal advection order, 2, 3, and 4, each with
and without del4 viscosity enabled, plus an additional order-3 task with
FCT disabled), an eighth smoke_test in the nonlinear/pstar tree with
Omega’s centered pressure gradient, and one rpe test which shows how the resting potential
energy changes across forward runs with different del2 viscosities.
The tasks are created in three trees by
polaris.tasks.ocean.overflow.add_overflow_tasks(), which loops
over combinations of the equation of state (EOS) and the vertical
coordinate used for the initial condition:
subdir |
EOS cfg |
init step class |
coord |
|---|---|---|---|
|
|
|
z-star |
|
|
|
p-star |
|
|
|
sigma |
|
|
|
p-star |
|
|
|
sigma |
Each tree has its own shared config parser (combining the shared EOS
config file, overflow.cfg and — for the p-star and sigma trees —
overflow_pstar.cfg or overflow_sigma.cfg) and its own shared init
step.
framework
The shared config options for overflow tests are described in
overflow in the User’s Guide.
Additionally, the tests share a forward.yaml file with a few common model
config options related to time management, time integration, Laplacian
viscosity, and vertical mixing (constant background plus convective
mixing, matching the compass configuration of this test), as well as
defining mesh, input, restart, and output streams.
init_utils
The module polaris.tasks.ocean.overflow.init_utils contains helpers
for the init steps:
polaris.tasks.ocean.overflow.init_utils.build_overflow_mesh()
builds and culls the planar hex mesh, adds the Coriolis parameter and
writes the mesh files;
polaris.tasks.ocean.overflow.init_utils.compute_bottom_depth()
computes the tanh shelf bathymetry;
polaris.tasks.ocean.overflow.init_utils.compute_initial_temperature()
computes the cold-block temperature profile; and
polaris.tasks.ocean.overflow.init_utils.compute_initial_density()
computes the density of the resting initial state on a geometric
coordinate, at its hydrostatic pressure so that it is also valid for a
nonlinear EOS.
init
The class polaris.tasks.ocean.overflow.init.Init
defines a step for setting up the initial state on a geometric vertical
coordinate, z-star or sigma, for each test case.
First, a mesh appropriate for the resolution is generated using
mpas_tools.planar_hex.make_planar_hex_mesh(). Then, the mesh is
culled to remove periodicity in the x and y directions. The bottom topography
is defined along with a vertical grid with 60 z-star or 64 sigma layers by
default. Next, the ocean state is generated with cold water on the
continental shelf. As for the p-star init step, the framework converts the
coordinate to pseudo-thickness for Omega and, in the nonlinear/sigma
tree, the tracers to potential temperature and practical salinity for
MPAS-Ocean.
pstar_init
The class polaris.tasks.ocean.overflow.pstar_init.PStarInit
defines the p-star init step used by the two pstar trees. It builds on
polaris.ocean.vertical.pstar_init.PStarInitStep (see
Vertical coordinate): it builds the same mesh and tanh
shelf bathymetry as Init (via the shared init_utils helpers),
iterates the
p-star coordinate to convergence with zero surface pressure, and
implements init_tracers() as the overflow profile (interpreted as
conservative temperature and absolute salinity) evaluated at the current
p-star layer midpoints. After convergence, the shared
polaris.ocean.init_state helpers add layer thickness, quiescent
velocity and density. In the nonlinear tree, the framework converts
the tracers to potential temperature and practical salinity at the
nominal lon/lat when the model is MPAS-Ocean (see
Initial state); the step itself does nothing
model-specific.
The step writes vert_coord.nc and init.nc with the same filenames as
Init, so the forward, viz and analysis steps need no retargeting.
forward
The class polaris.tasks.ocean.overflow.forward.Forward
defines a step for running the ocean from the initial condition produced in
the init step. Namelist and streams files are updated in
polaris.tasks.ocean.overflow.forward.Forward.dynamic_model_config()
with time steps determined algorithmically based on config options. The
number of cells is approximated from config options in
polaris.tasks.ocean.overflow.forward.Forward.compute_cell_count()
so that this can be used to constrain the number of MPI tasks that Polaris
tasks have as their target and minimum (if the resources are not explicitly
prescribed). For MPAS-Ocean, PIO namelist options are modified and a
graph partition is generated as part of runtime_setup(). Next, the ocean
model is run. The duration is set by run_duration in the config section
corresponding to the task (overflow_smoke_test or overflow_rpe). Finally,
validation of layerThickness, temperature and normalVelocity in the
output.nc file are performed against a baseline if one is provided when
calling polaris setup.
viz
The polaris.tasks.ocean.overflow.viz.Viz plots the initial and
final temperature along a transect perpendicular to the continental slope.
In the nonlinear variants, it asks for conservative temperature so that
MPAS-Ocean and Omega plots mean the same thing (see
Tracer conventions on read).
smoke_test
The polaris.tasks.ocean.overflow.smoke_test.SmokeTest
task runs the init step, a short forward step, and (optionally, not run
by default) the viz step. In each task tree, six instances are created,
one for each horizontal advection order (2, 3, and 4) with and without
del4 viscosity enabled, producing tasks named
smoke_test_horiz_adv_order_{2,3,4} and
smoke_test_horiz_adv_order_{2,3,4}_del4. For Omega, FCT
(horiz_fct_enable_omega) is enabled by default for advection orders 3 and
4 and disabled for order 2; a seventh instance,
smoke_test_horiz_adv_order_3_nofct, reruns order 3 with FCT disabled for
comparison.
Only in the nonlinear/pstar tree, an eighth instance,
smoke_test_horiz_adv_order_4_del4_centered_pgf, is created with
centered_pgf=True. The forward step then sets Omega’s PressureGradType
to Centered, overriding Omega’s default finite-volume scheme, so the
centered scheme keeps coverage in the omega_pr suite next to its
finite-volume twin, smoke_test_horiz_adv_order_4_del4.
rpe
The polaris.tasks.ocean.overflow.rpe.Rpe test performs the init
step, 5 forward steps corresponding to the viscosity values in the config
file, and the analysis step.
analysis
The polaris.tasks.ocean.overflow.rpe.analysis.Analysis
computes the Resting Potential Energy (RPE). This step also produces a
figure with RPE time evolution for each forward run and a figure with each of
the forward run’s transects at the plot_time designated in the config file.