State fields

veris.model.variables.VARIABLES describes the calculation fields created by veris.execution.initialization.initialize. Every entry has a default, units, long name, description and dimensions that identify its grid location. The grid is staggered: some values sit at cell centers and others at cell faces. State is a frozen dataclass, whose fields cannot be reassigned, and a JAX PyTree, a collection of arrays that JAX can process together. Update arrays by creating a new State with dataclasses.replace.

For an interior of nx by ny cells, horizontal arrays have shape (nx + 4, ny + 4). The interior is field[2:-2, 2:-2]. Axis zero is zonal (east-west); axis one is meridional (north-south). Dimensions identify Cartesian grid locations: x_center, y_center, x_face and y_face. Face and center arrays have equal storage sizes. Both include two halo cells at each boundary, which hold boundary or neighboring data. When arrays are split across devices, each partition keeps its own halos; see Experiment definitions. Boundary conditions are described in Model settings.

State holds the geometry fields and prescribed forcing used by calculations. Output-only diagnostics and configuration do not add arrays to numerical State. Arrays for ice-thickness categories exist only as intermediate values in the thermodynamics calculations, which describe freezing and melting.

NetCDF metadata

The metadata can be used directly with h5netcdf:

from veris.model.variables import VARIABLES
metadata = VARIABLES["uIce"]
variable = output.create_variable(
    "uIce", metadata.dimensions, dtype=state.uIce.dtype
)
variable.attrs.update(metadata.netcdf_attributes())
variable[:] = state.uIce

Here output is an open h5netcdf.File with the horizontal dimensions already defined. The example writes the halos along with the interior. When exporting only the interior, trim the arrays and adjust the dimension lengths together.

Registry defaults

Variable	Dimensions	Units	Default	Description
hIceMean	x_center, y_center	m	0.0	Mean ice thickness
hSnowMean	x_center, y_center	m	0.0	Mean snow thickness
Area	x_center, y_center	1	0.0	Sea ice cover fraction
TSurf	x_center, y_center	K	273.15	Ice/ snow surface temperature
SeaIceMassC	x_center, y_center	kg m-2	0.0	Sea ice mass centered around c point
SeaIceMassU	x_face, y_center	kg m-2	0.0	Sea ice mass centered around u point
SeaIceMassV	x_center, y_face	kg m-2	0.0	Sea ice mass centered around v point
SeaIceStrength	x_center, y_center	N m-1	0.0	Ice strength
os_hIceMean	x_center, y_center	m	0.0	Prepared minus raw ice thickness from advection cleanup
os_hSnowMean	x_center, y_center	m	0.0	Prepared minus raw snow thickness from advection cleanup
AreaW	x_face, y_center	1	0.0	Sea ice cover fraction centered around u point
AreaS	x_center, y_face	1	0.0	Sea ice cover fraction centered around v point
uIce	x_face, y_center	m s-1	0.0	Zonal ice velocity
vIce	x_center, y_face	m s-1	0.0	Meridional ice velocity
sigma1	x_center, y_center	N m-1	0.0	Stress trace sigma11 + sigma22
sigma2	x_center, y_center	N m-1	0.0	Normal-stress difference sigma11 - sigma22
sigma12	x_face, y_face	N m-1	0.0	Stress tensor component
WindForcingX	x_face, y_center	Pa	0.0	Zonal forcing on ice by wind stress
WindForcingY	x_center, y_face	Pa	0.0	Meridional forcing on ice by wind stress
recip_hIceMean	x_center, y_center	m-1	0.0	Reciprocal square root of hIceMean squared plus hIce_reg; refreshed by initialization or growth
SeaIceLoad	x_center, y_center	kg m-2	0.0	Load of sea ice on ocean surface
uOcean	x_face, y_center	m s-1	0.0	Zonal ocean surface velocity
vOcean	x_center, y_face	m s-1	0.0	Meridional ocean surface velocity
theta	x_center, y_center	K	273.15	Ocean surface temperature
ocSalt	x_center, y_center	g kg-1	0.0	Ocean surface salinity
Qnet	x_center, y_center	W m-2	0.0	Net heat flux out of the ocean
R_low	x_center, y_center	m	0.0	Sea floor depth (<0)
ssh_an	x_center, y_center	m	0.0	Sea surface height anomaly
Qsw	x_center, y_center	W m-2	0.0	Surface shortwave heatflux (+ = upwards)
uWind	x_center, y_center	m s-1	0.0	Zonal wind velocity
vWind	x_center, y_center	m s-1	0.0	Meridional wind velocity
wSpeed	x_center, y_center	m s-1	0.0	Total wind speed
surfPress	x_center, y_center	Pa	0.0	Surface pressure
SWdown	x_center, y_center	W m-2	0.0	Downward shortwave radiation
LWdown	x_center, y_center	W m-2	0.0	Downward longwave radiation
ATemp	x_center, y_center	K	273.15	Atmospheric temperature
aqh	x_center, y_center	kg kg-1	0.0	Atmospheric specific humidity
precip	x_center, y_center	m s-1	0.0	Precipitation rate (freshwater flux)
snowfall	x_center, y_center	m s-1	0.0	Snowfall rate
evap	x_center, y_center	m s-1	0.0	Evaporation rate over open ocean (freshwater flux, <0 increases salinity)
runoff	x_center, y_center	m s-1	0.0	Runoff into ocean
maskInC	x_center, y_center	1	1.0	Mask at c-points, used for open boundaries
maskInU	x_face, y_center	1	1.0	Mask at u-points, used for open boundaries
maskInV	x_center, y_face	1	1.0	Mask at v-points, used for open boundaries
iceMask	x_center, y_center	1	1.0	Mask at c-points
iceMaskU	x_face, y_center	1	1.0	Mask at u-points
iceMaskV	x_center, y_face	1	1.0	Mask at v-points
k1AtC	x_center, y_center	m-1	0.0	Zonal metric curvature at cell centers
k2AtC	x_center, y_center	m-1	0.0	Meridional metric curvature at cell centers
k1AtZ	x_face, y_face	m-1	0.0	Zonal metric curvature at cell corners
k2AtZ	x_face, y_face	m-1	0.0	Meridional metric curvature at cell corners
Fu	x_face, y_center	1	0.0	U-component of form factor
Fv	x_center, y_face	1	0.0	V-component of form factor
fCori	x_center, y_center	s-1	0.0	Coriolis parameter
dxG	x_center, y_face	m	1.0	Zonal spacing of cell faces along southern cell wall
dyG	x_face, y_center	m	1.0	Meridional spacing of cell faces along western cell wall
dxU	x_center, y_center	m	1.0	Zonal spacing of u-points through cell center
dyU	x_face, y_face	m	1.0	Meridional spacing of u-points through south-west corner of the cel
dxV	x_face, y_face	m	1.0	Zonal spacing of v-points through south-west corner of the cell
dyV	x_center, y_center	m	1.0	Meridional spacing of v-points through cell center
recip_dxC	x_face, y_center	m-1	1.0	Reciprocal of dxC
recip_dyC	x_center, y_face	m-1	1.0	Reciprocal of dyC
recip_dxU	x_center, y_center	m-1	1.0	Reciprocal of dxU
recip_dyU	x_face, y_face	m-1	1.0	Reciprocal of dyU
recip_dxV	x_face, y_face	m-1	1.0	Reciprocal of dxV
recip_dyV	x_center, y_center	m-1	1.0	Reciprocal of dyV
rAz	x_face, y_face	m2	1.0	Grid cell area centered around z-point
recip_rA	x_center, y_center	m-2	1.0	Reciprocal of rA
recip_rAu	x_face, y_center	m-2	1.0	Reciprocal of rAu
recip_rAv	x_center, y_face	m-2	1.0	Reciprocal of rAv

Coupling diagnostics

advance returns these fields in a separate frozen dataclass. These diagnostics describe the exchange with an ocean model and do not add arrays to the calculation State. When ice salinity is nonzero, the two terms in the legacy combined salt forcing use different freshwater normalizations (scaling factors). Its units are recorded as unknown to avoid misleading units. The move to this metadata keeps the existing equation.

Variable	Dimensions	Units	Default	Description
IcePenetSW	x_center, y_center	W m-2	0.0	Grid-cell mean shortwave heat flux transmitted through sea ice
OceanStressU	x_face, y_center	N m-2	0.0	Zonal ice-ocean stress from the momentum step at zonal velocity faces
OceanStressV	x_center, y_face	N m-2	0.0	Meridional ice-ocean stress from the momentum step at meridional velocity faces
EmPmR	x_center, y_center	kg m-2 s-1	0.0	Total ocean mass loss, including ice/snow and external freshwater exchange
forc_salt_surface	x_center, y_center	g kg-1 m s-1	0.0	Local-salinity virtual forcing: (EmPmR*ocSalt + 1000*ocean_salt_mass_flux)/rhoFresh
physics_status	x_center, y_center	1	0.0	Zero for valid physics; one for invalid physical parameters; two for invalid saline-ice formation
ocean_mass_flux	x_center, y_center	kg m-2 s-1	0.0	Downward total bulk mass input, including retained ice salt mass
ocean_salt_mass_flux	x_center, y_center	kg m-2 s-1	0.0	Downward salt mass input for fixed bulk ice salinity in g/kg
external_mass_flux	x_center, y_center	kg m-2 s-1	0.0	Downward atmospheric/land mass from rain, snow, evaporation, sublimation and runoff
external_heat_flux	x_center, y_center	W m-2	0.0	Downward zero-layer enthalpy input from surface thermal fluxes and boundary mass events