rdb_vcoord Module

Defines vcoord_t, a lightweight config type for the vertical coordinate. Type-bound procedures dispatch via select case on an integer enum (no runtime polymorphism) so the type is GPU-safe.

Implemented (VCOORD_*): - SIGMA — pure terrain-following (no remap). - ZSIGMA — smoothstep blend sigma (shallow) → fixed z-levels (deep); reduces sigma PGE on steep bathymetry. Conservative remap. - ZSTAR — z-lite SSH-tracking: a global z_ref stretched per column by H/z_ref(nz) so sum(dz)=H, relative spacing preserved as η changes (no sigma distortion at large SSH). - ZSTAR_FULL — per-column z_ref from local bathymetry (vanishing layers). - ZSTAR_SIGMA — smoothstep blend of sigma (shallow) and z-lite (deep).


Uses

  • module~~rdb_vcoord~~UsesGraph module~rdb_vcoord rdb_vcoord module~rdb_constants rdb_constants module~rdb_vcoord->module~rdb_constants pic_logger pic_logger module~rdb_vcoord->pic_logger pic_strings pic_strings module~rdb_vcoord->pic_strings pic_types pic_types module~rdb_constants->pic_types

Used by

  • module~~rdb_vcoord~~UsedByGraph module~rdb_vcoord rdb_vcoord module~rdb_ocean_engine rdb_ocean_engine module~rdb_ocean_engine->module~rdb_vcoord module~rdb_ocean_setup rdb_ocean_setup module~rdb_ocean_engine->module~rdb_ocean_setup module~rdb_ocean_stability_audit rdb_ocean_stability_audit module~rdb_ocean_engine->module~rdb_ocean_stability_audit module~rdb_ocean_vcoord rdb_ocean_vcoord module~rdb_ocean_engine->module~rdb_ocean_vcoord module~rdb_ocean_diag_fills rdb_ocean_diag_fills module~rdb_ocean_engine->module~rdb_ocean_diag_fills module~rdb_ocean_dyn rdb_ocean_dyn module~rdb_ocean_engine->module~rdb_ocean_dyn module~rdb_ocean_state rdb_ocean_state module~rdb_ocean_engine->module~rdb_ocean_state module~rdb_ocean_diag_derived rdb_ocean_diag_derived module~rdb_ocean_engine->module~rdb_ocean_diag_derived module~rdb_ocean_setup->module~rdb_vcoord module~rdb_ocean_setup->module~rdb_ocean_vcoord module~rdb_ocean_setup->module~rdb_ocean_dyn module~rdb_ocean_setup->module~rdb_ocean_state module~rdb_ocean_stability_audit->module~rdb_vcoord module~rdb_ocean_vcoord->module~rdb_vcoord proc~validate_config validate_config proc~validate_config->module~rdb_vcoord proc~zfixed_cavity_nu_h_below_envelope zfixed_cavity_nu_h_below_envelope proc~zfixed_cavity_nu_h_below_envelope->module~rdb_vcoord module~rdb_driver rdb_driver module~rdb_driver->module~rdb_ocean_engine module~rdb_driver->module~rdb_ocean_dyn module~rdb_driver->module~rdb_ocean_state module~rdb_handle rdb_handle module~rdb_handle->module~rdb_ocean_engine module~rdb_handle->module~rdb_ocean_state module~rdb_ocean_api rdb_ocean_api module~rdb_ocean_api->module~rdb_ocean_engine module~rdb_ocean_api->module~rdb_handle module~rdb_ocean_api->module~rdb_ocean_diag_fills module~rdb_ocean_api->module~rdb_ocean_dyn module~rdb_ocean_api->module~rdb_ocean_diag_derived module~rdb_ocean_diag_fills->module~rdb_ocean_vcoord module~rdb_ocean_diag_fills->module~rdb_ocean_state module~rdb_ocean_dyn->module~rdb_ocean_vcoord module~rdb_ocean_remap rdb_ocean_remap module~rdb_ocean_dyn->module~rdb_ocean_remap module~rdb_ocean_remap->module~rdb_ocean_vcoord module~rdb_ocean_state->module~rdb_ocean_vcoord module~rdb_ocean_state->module~rdb_ocean_dyn module~rdb_ocean_diag_derived->module~rdb_ocean_diag_fills module~rdb_ocean_diag_derived->module~rdb_ocean_state

Variables

Type Visibility Attributes Name Initial
integer, public, parameter :: STRETCH_LOG = 1
integer, public, parameter :: STRETCH_UNIFORM = 0
integer, public, parameter :: VCOORD_HMIN_INERT = 0

Geometric families (ZSTAR_FULL / Z_FIXED): zstar_h_min is the anti-zero thickness of below-bed FILLER layers, which are meant to read as vanished downstream ⇒ must stay <= H_VANISHED.
integer, public, parameter :: VCOORD_HMIN_KEEPALIVE = 1

Density families (RHO / HYCOM): collapsed layers carry tracer mass and must SURVIVE the remap drain ⇒ that path floors at max(zstar_h_min, 2*H_VANISHED) on purpose.
integer, public, parameter :: VCOORD_HMIN_UNUSED = 2

Every other family never reads zstar_h_min.
integer, public, parameter :: ZFIXED_DZ_ERR_COUNT = 1

List length (leading positive entries) is not nz, or a positive entry follows an unset one.
integer, public, parameter :: ZFIXED_DZ_ERR_PROFILE = 4

Unrecognised profile code.
integer, public, parameter :: ZFIXED_DZ_ERR_TOO_DEEP = 3

tanh: nz*dz_top >= h_ref — no room to stretch.
integer, public, parameter :: ZFIXED_DZ_ERR_VALUE = 2

A tanh parameter is out of range (dz_top <= 0, width <= 0, center outside [0, 1]) or h_ref <= 0.
integer, public, parameter :: ZFIXED_DZ_OK = 0

z_fixed_nominal_dz status: profile built.
integer, public, parameter :: ZFIXED_PROFILE_INVALID = -1

Unrecognised z_fixed_profile string.
integer, public, parameter :: ZFIXED_PROFILE_LIST = 1

Explicit nominal thicknesses, &vcoord_nml z_fixed_dz, surface first.
integer, public, parameter :: ZFIXED_PROFILE_TANH = 2

Hyperbolic-tangent stretching from z_fixed_dz_top at the surface.
integer, public, parameter :: ZFIXED_PROFILE_UNIFORM = 0

max_depth/nz everywhere — the historical (and default) layering.

Derived Types

type, public ::  vcoord_t

Components

Type Visibility Attributes Name Initial
real(kind=wp), public :: blend_width = 50.0_wp

Width of the blending zone (m)
integer, public :: coord_type = VCOORD_SIGMA

Vertical coordinate type (VCOORD_SIGMA, VCOORD_ZSIGMA, etc.)
real(kind=wp), public :: depth_transition = 100.0_wp

Depth (m) where sigma-to-z blending begins
real(kind=wp), public, allocatable :: dsig_target(:)

(nz) Target sigma-like layer fractions, sum = 1.0
integer, public :: nz = 0

Number of vertical layers
integer, public :: remap_method = REMAP_PPM

Remap reconstruction order (REMAP_PCM/PLM/PPM/PPM_H4/PQM). Default PPM. PQM falls back to PPM for nz < 5 (see remap_column_pqm).
real(kind=wp), public, allocatable :: z_ref(:)

(nz+1) Reference interface depths for z-levels (m, positive down). Only allocated for coord types that use z-levels.
real(kind=wp), public :: zstar_h_min = 1.0e-4_wp

Vanishing-layer floor (m). Layers that would land below the local bed get clipped to this thickness rather than going to zero. Deliberately BELOW H_VANISHED (1.5e-4): these are inert filler layers that downstream h-dividing kernels are MEANT to skip, so the floor is anti-zero armour, not a positivity floor. See vcoord_h_min_role for the other contract the same knob carries on the density (RHO/HYCOM) families.
real(kind=wp), public :: zstar_h_surf_target = 0.0_wp

Target physical thickness of the surface layer (m). 0 => auto: uniform per-column (falls back to lite behaviour per column). Set > 0 to anchor the surface layer at a fixed thickness regardless of total depth H.
integer, public :: zstar_n_surf = 0

Number of “fine” near-surface layers using stretching. 0 => auto (use max(1, nz/3))
integer, public :: zstar_stretching = 1

Surface-concentration stretching: 1=log, 0=uniform

Type-Bound Procedures

procedure, public, non_overridable :: cleanup => vcoord_cleanup
procedure, public, non_overridable :: enter_data => vcoord_enter_data
procedure, public, non_overridable :: exit_data => vcoord_exit_data
procedure, public, non_overridable :: init => vcoord_init
procedure, public, non_overridable :: needs_remap => vcoord_needs_remap

Functions

public pure function parse_remap_method(str) result(method)

Convert a namelist string to a REMAP_* constant.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: str

Return Value integer

public pure function parse_stretching_mode(str) result(mode)

Convert a namelist string to a STRETCH_* constant.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: str

Return Value integer

public pure function parse_vcoord_type(str, default_code) result(coord_type)

Convert a namelist string to a VCOORD_* constant (shared by coastal and ocean backends). Unrecognised ⇒ default_code if given, else VCOORD_SIGMA. Ocean callers pass default_code = VCOORD_EULERIAN_Z.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: str
integer, intent(in), optional :: default_code

Return Value integer

public pure function parse_z_fixed_profile(str) result(code)

&vcoord_nml z_fixed_profile string -> ZFIXED_PROFILE_* code (ZFIXED_PROFILE_INVALID for anything else — the caller fails loud).

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: str

Return Value integer

public pure function vcoord_h_min_is_coherent(coord_type, h_min) result(ok)

Is zstar_h_min coherent with the contract coord_type gives it?

Read more…

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: coord_type

VCOORD_* code (from parse_vcoord_type).
real(kind=wp), intent(in) :: h_min

The configured &vcoord_nml zstar_h_min (m).

Return Value logical

public pure function vcoord_h_min_role(coord_type) result(role)

Which of the TWO contracts zstar_h_min carries for coord_type.

Read more…

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: coord_type

VCOORD_* code (from parse_vcoord_type).

Return Value integer

private pure function vcoord_needs_remap(self) result(needs_remap)

Returns .true. if this coordinate type requires conservative vertical remapping after the barotropic step. Pure sigma does not — layers are simply rescaled by dsig(k) * H.

Arguments

Type IntentOptional Attributes Name
class(vcoord_t), intent(in) :: self

Return Value logical


Subroutines

public pure subroutine vcoord_target_dz_column(coord_type, nz, H, dsig, z_ref, depth_transition, blend_width, dz)

Compute target layer thicknesses for a single water column. Pure, called from do concurrent (one thread per column).

Read more…

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: coord_type
integer, intent(in) :: nz
real(kind=wp), intent(in) :: H

Total water depth at this column (m)
real(kind=wp), intent(in) :: dsig(nz)

Reference sigma fractions (sum = 1), ROMS-ordered: dsig(1) bottom, dsig(nz) surface. Currently uniform 1/nz.
real(kind=wp), intent(in) :: z_ref(0:nz)

Reference z-level interface depths (m, positive down). z_ref(0) = 0 is the surface; z_ref(nz) is the deepest reference interface. Used for VCOORD_ZSIGMA and VCOORD_ZSTAR.
real(kind=wp), intent(in) :: depth_transition

Depth (m) below which blending begins
real(kind=wp), intent(in) :: blend_width

Width of the blending zone (m)
real(kind=wp), intent(out) :: dz(nz)

Output target layer thicknesses, ROMS-ordered (sum = H, dz(1) = bottom, dz(nz) = surface)

public pure subroutine vcoord_target_dz_column_zstar_full(nz, H, z_ref_col, h_min, dz)

Compute target layer thicknesses for VCOORD_ZSTAR_FULL. Inputs: z_ref_col(0:nz) local reference (top-down, 0=surface, nz=h_bed); H current total depth (m) = h_bed + η; h_min vanishing-layer floor (m). Output: dz(1:nz) ROMS-ordered (dz(1) bottom, dz(nz) surface), sum(dz) = H exactly, vanishing rows set to h_min. Surface layer absorbs η; if H < h_bed the deepest layers clip to h_min and the surface is trimmed to keep sum = H.

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: nz
real(kind=wp), intent(in) :: H
real(kind=wp), intent(in) :: z_ref_col(0:nz)
real(kind=wp), intent(in) :: h_min
real(kind=wp), intent(out) :: dz(nz)

public pure subroutine z_fixed_nominal_dz(profile, nz, h_ref, dz_list, dz_top, center, width, dz, ierr)

Nominal layer thicknesses of a VCOORD_Z_FIXED column, SURFACE FIRST (dz(1) is the top layer) — the order MOM6 writes ALE_COORDINATE_CONFIG = "PARAM:..." lists and vgrid files in. The caller flips to the bottom-up state convention.

Read more…

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: profile

ZFIXED_PROFILE_* code.
integer, intent(in) :: nz

Number of layers.
real(kind=wp), intent(in) :: h_ref

Reference column depth (m) — &ocean_topo_nml max_depth.
real(kind=wp), intent(in) :: dz_list(:)

&vcoord_nml z_fixed_dz (m), surface first; <= 0 = unset.
real(kind=wp), intent(in) :: dz_top

tanh: surface-layer thickness (m).
real(kind=wp), intent(in) :: center

tanh: transition centre as a fraction of the index span [0, 1].
real(kind=wp), intent(in) :: width

tanh: transition width as a fraction of the index span (> 0).
real(kind=wp), intent(out) :: dz(nz)

Nominal thicknesses (m), surface first.
integer, intent(out) :: ierr

ZFIXED_DZ_* status.

public pure subroutine zstar_full_build_column(nz, h_bed, h_surf_target, n_surf, stretching, z_ref_col)

Build a per-column reference z-level pattern for VCOORD_ZSTAR_FULL. Output z_ref_col(0:nz) monotonically increasing (positive-down), z_ref_col(0)=0 surface, z_ref_col(nz)=h_bed. Built top-down; the caller handles ROMS ordering. Top n_surf_use layers use the stretching mode (log/uniform) toward h_surf_target; below that uniform to the bed; degenerate (h_bed≤0, nz≤0) ⇒ uniform.

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: nz
real(kind=wp), intent(in) :: h_bed

Local bed depth (m, positive down). Must be > 0 in normal use.
real(kind=wp), intent(in) :: h_surf_target

Target thickness of the surface layer (m). ≤ 0 means “auto” and falls back to uniform spacing.
integer, intent(in) :: n_surf

Number of fine near-surface layers. ≤ 0 means auto.
integer, intent(in) :: stretching

STRETCH_LOG or STRETCH_UNIFORM
real(kind=wp), intent(out) :: z_ref_col(0:nz)

private subroutine vcoord_cleanup(self)

Deallocate all arrays. Safe to call on uninitialised instances.

Arguments

Type IntentOptional Attributes Name
class(vcoord_t), intent(inout) :: self

private subroutine vcoord_enter_data(self)

Map read-only coordinate arrays to GPU.

Arguments

Type IntentOptional Attributes Name
class(vcoord_t), intent(inout) :: self

private subroutine vcoord_exit_data(self)

Unmap coordinate arrays from GPU.

Arguments

Type IntentOptional Attributes Name
class(vcoord_t), intent(inout) :: self

private subroutine vcoord_init(self, nz, coord_type, remap_method)

Initialise a vertical coordinate definition. Allocates + populates dsig_target for the given type. Unknown types: error stop.

Arguments

Type IntentOptional Attributes Name
class(vcoord_t), intent(inout) :: self
integer, intent(in) :: nz

Number of vertical layers
integer, intent(in) :: coord_type

Coordinate type constant (VCOORD_SIGMA, etc.)
integer, intent(in) :: remap_method

Remapping method constant (REMAP_PLM, etc.)