Model data and metadata

State and diagnostics

Create a State for a runnable experiment through veris.initialize_experiment(); veris.execution.initialization.initialize() creates arrays at a lower level. State holds the model’s fields, or values across the grid. Each field is a JAX array that can change during a run. JAX treats each array as a leaf in a PyTree, a nested collection of data. Output-only fields for exchanging results with another model are returned in a separate Diagnostics PyTree. A lifecycle rollout carries both State and Diagnostics, with physics status retained across steps. A carry is the data passed from one step to the next. Field dimensions, units, descriptions and starting defaults are generated from the named tables in State fields.

class veris.model.types.State(hIceMean: Array, hSnowMean: Array, Area: Array, TSurf: Array, SeaIceMassC: Array, SeaIceMassU: Array, SeaIceMassV: Array, SeaIceStrength: Array, os_hIceMean: Array, os_hSnowMean: Array, AreaW: Array, AreaS: Array, uIce: Array, vIce: Array, sigma1: Array, sigma2: Array, sigma12: Array, WindForcingX: Array, WindForcingY: Array, recip_hIceMean: Array, SeaIceLoad: Array, uOcean: Array, vOcean: Array, theta: Array, ocSalt: Array, Qnet: Array, R_low: Array, ssh_an: Array, Qsw: Array, uWind: Array, vWind: Array, wSpeed: Array, surfPress: Array, SWdown: Array, LWdown: Array, ATemp: Array, aqh: Array, precip: Array, snowfall: Array, evap: Array, runoff: Array, maskInC: Array, maskInU: Array, maskInV: Array, iceMask: Array, iceMaskU: Array, iceMaskV: Array, k1AtC: Array, k2AtC: Array, k1AtZ: Array, k2AtZ: Array, Fu: Array, Fv: Array, fCori: Array, dxG: Array, dyG: Array, dxU: Array, dyU: Array, dxV: Array, dyV: Array, recip_dxC: Array, recip_dyC: Array, recip_dxU: Array, recip_dyU: Array, recip_dxV: Array, recip_dyV: Array, rAz: Array, recip_rA: Array, recip_rAu: Array, recip_rAv: Array)

Bases: object

Calculation fields on the halo-inclusive C grid, in registry order.

Construct through veris.execution.initialization.initialize() to allocate defaults. All fields are dynamic array leaves for JAX differentiation; settings, physical constants and output-only diagnostics live separately. Use dataclasses.replace() for immutable numerical updates.

See Ocean boundary budgets for ocean and independent external input units, signs and modeled conservation equations.

class veris.model.diagnostics.Diagnostics(IcePenetSW: Array, OceanStressU: Array, OceanStressV: Array, EmPmR: Array, forc_salt_surface: Array, physics_status: Array, ocean_mass_flux: Array, ocean_salt_mass_flux: Array, external_mass_flux: Array, external_heat_flux: Array)

Bases: object

Per-step coupling outputs in DIAGNOSTICS registry order.

veris.model.arrays.ArrayInput describes numerical JAX and NumPy array inputs. MaskInput also accepts NumPy boolean masks, which mark cells with true or false values. veris.grid.geometry.OceanGeometry defines the expected grid inputs. See Initialization and presets for the adapter that reads these inputs and Experiment definitions for their physical dimensions.

Settings and physical constants

Constructors validate authored host inputs without device discovery. Configuration is static numerical policy. PhysicalConstants is a frozen PyTree of independent physical values with static dtype; dependent laws are reconstructed from its base leaves. Use with_overrides for traced updates and keep the initial State fixed for continuation sensitivities. Pure advance returns runtime physics status; Simulation checks it before committing State/time. The tables in Model settings and Physical constants describe every field and its default. Fields computed from other inputs are not constructor arguments.

class veris.model.configuration.Configuration(deltatTherm: float = 86400.0, deltatDyn: float = 86400.0, nITC: int = 5, noSlip: bool = True, useRelativeWind: bool = True, secondOrderBC: bool = False, extensiveFld: bool = True, useRealFreshWaterFlux: bool = False, useFreedrift: bool = False, useEVP: bool = True, evpAlpha: float = 500.0, evpBeta: float = 500.0, useAdaptiveEVP: bool = False, aEVPalphaMin: float = 5.0, aEvpCoeff: float = 0.5, explicitDrag: bool = True, nEVPsteps: int = 400, computeEvpResidual: bool = False, printEvpResidual: bool = False, geometrySurfaceTemperature: float = 273.0, use_coastline: bool = False, use_sharding: bool = True, CrMax: float = 1000000.0, eps2: float = 1e-20, surfaceTemperatureIterations: int = 6, aEVPmassMin: float = 0.0001, aEVPcStar: float = 4.0, lanlBulkIterations: int = 5, nx: int = 8, ny: int = 12, *, dtype: str = 'float64', enable_cyclic_y: bool = True, spherical_geometry: bool = False)

Bases: object

Validated immutable model settings initialized from the registry.

class veris.model.physical_constants.PhysicalConstants(pressReplFac: float = 1.0, evpStressRelaxation: float = 1.0, evpShearRelaxation: float = 0.25, Area_min: float = 1e-05, Area_reg: float = 0.0225, basalDragMinArea: float = 0.01, basalDragSmoothing: float = 10.0, bulkStabilityLimit: float = 10.0, cDragMin: float = 0.25, deltaMin: float = 2e-09, hIce_min: float = 1e-05, hIce_reg: float = 0.010000000000000002, lanlMinWindSpeed: float = 1.0, maxTIce: float = 30.0, minActualIceThickness: float = 0.05, minLWdown: float = 60.0, minTAir: float = -50.0, minTIce: float = -50.0, seaIceLoadFac: float = 1.0, umin_i: float = 1.0, umin_o: float = 0.5, wSpeedMin: float = 1e-10, zref: float = 10.0, ztref: float = 2.0, rhoIce: float = 900.0, rhoFresh: float = 1000.0, rhoSea: float = 1026.0, rhoAir: float = 1.3, rhoSnow: float = 330.0, dryIceAlb: float = 0.75, dryIceAlb_south: float = 0.75, wetIceAlb: float = 0.66, wetIceAlb_south: float = 0.66, drySnowAlb: float = 0.84, drySnowAlb_south: float = 0.84, wetSnowAlb: float = 0.7, wetSnowAlb_south: float = 0.7, wetAlbTemp: float = 0.0, lhFusion: float = 334000.0, lhEvap: float = 2500000.0, cpAir: float = 1005.0, cpWater: float = 3986.0, stefBoltz: float = 5.67e-08, iceEmiss: float = 0.95, snowEmiss: float = 0.95, iceConduct: float = 2.1656, snowConduct: float = 0.31, shortwave: float = 0.3, tempFrz: float = -1.96, dtempFrz_dS: float = 0.0, saltIce_ref: float = 0.0, dalton: float = 0.00175, celsius2K: float = 273.15, stantonNr: float = 0.0056, uStarBase: float = 0.0125, McPheeTaperFac: float = 12.5, h0: float = 0.5, h0_south: float = 0.5, airTurnAngle: float = 0.0, waterTurnAngle: float = 0.0, airIceDrag: float = 0.0012, airIceDrag_south: float = 0.0012, waterIceDrag: float = 0.0055, waterIceDrag_south: float = 0.0055, gravity: float = 9.81, PlasDefCoeff: float = 2.0, pStar: float = 27500.0, cStar: float = 20.0, basalDragU0: float = 5e-05, basalDragK1: float = 8.0, basalDragK2: float = 0.0, cBasalStar: float = 20.0, tensileStrFac: float = 0.0, sideDragCoeff: float = 0.001, sideDragU0: float = 0.01, bolzc: float = 1.38065e-23, avogad: float = 6.02214e+26, rgas: float = 8314.47, mwdair: float = 28.966, mwwv: float = 18.016, rdair: float = 287.042, rwv: float = 461.505, zvir: float = 0.608, cpdair: float = 1004.64, cpwv: float = 1810.0, cpvir: float = 0.802, karman: float = 0.4, latvap: float = 2501000.0, p0: float = 100000.0, cappa: float = 0.286, zzsice: float = 0.0005, ch: float = 0.001, ce: float = 0.00115, emissivity: float = 1.0, ocean_emissivity: float = 0.985, snow_emissivity: float = 0.98, ice_emissivity: float = 0.98, tf0kel: float = 273.15, gamma_blk: float = 0.01, ocean_albedo: float = 0.1, ice_albedo: float = 0.7, radius: float = 6371000.0, iceVaporPressureTemperature: float = 2663.5, iceVaporPressureLog10Offset: float = 12.537, waterVaporDryAirMassRatio: float = 0.622, iceSurfacePressure: float = 100000.0, iceShortwaveExtinction: float = 1.5, McPheeTaperArea: float = 0.4, McPheeTaperSteepness: float = 7.0, lateralMeltAreaFactor: float = 0.5, cesmSaturationHumidityScale: float = 640380.0, cesmSaturationHumidityTemperature: float = 5107.4, augustVaporPressureLog10Offset: float = 9.4051, augustVaporPressureTemperature: float = 2353.0, mmHgToPa: float = 133.322, neutralDragInverseWind: float = 0.0027, neutralDragConstant: float = 0.000142, neutralDragLinearWind: float = 7.64e-05, cesmUnstableMomentumOffset: float = 1.571, longwaveHumidityPressureScale: float = 1000.0, longwaveClearSkyOffset: float = 0.39, longwaveHumidityCoefficient: float = 0.05, seawaterHumidityFactor: float = 0.98, cesmNeutralHeatUnstable: float = 0.0327, cesmNeutralHeatStable: float = 0.018, cesmNeutralMoisture: float = 0.0346, bulkUnstableStabilityCoefficient: float = 16.0, bulkStableStabilityCoefficient: float = 5.0, lanlSaturationHumidityScale: float = 3.797915, lanlSaturationExponentOffset: float = 7.93252e-06, lanlSaturationExponentTemperature: float = 0.002166847, lanlReferencePressure: float = 1013.0, longwaveCloudLatitudes: tuple[float, ...] = (-90.0, -80.0, -70.0, -60.0, -50.0, -40.0, -30.0, -20.0, -10.0, -5.0, 0.0, 5.0, 10.0, 20.0, 30.0, 40.0, 50.0, 60.0, 70.0, 80.0, 90.0), longwaveCloudCoefficients: tuple[float, ...] = (0.88, 0.84, 0.8, 0.76, 0.72, 0.68, 0.63, 0.59, 0.52, 0.5, 0.5, 0.5, 0.52, 0.59, 0.63, 0.68, 0.72, 0.76, 0.8, 0.84, 0.88), hCut: float = 0.15, *, dtype: str = 'float64')

Bases: object

Frozen physical-parameter PyTree initialized from the native registry.

Independent scalar/table values are leaves; dtype is static metadata. Host constructors validate authored controls without device discovery. Use with_overrides inside AD; dependent laws follow the base values.

classmethod base_parameter_names() → tuple[str, ...]

Return independent registry values, excluding dtype and derived laws.

with_overrides(**parameters: Array | ndarray | bool | number | bool | int | float | complex) → PhysicalConstants

Return owned base parameters with refreshed dependent quantities.

Concrete overrides validate native domains on the host. Scalar tracers retain their dtype/schema for AD; advance reports runtime domain failures through physics_status. Tuples keep the registry’s cloud-table contract.

Registry schemas

class veris.model.types.Parameter(default: float | int | bool | str | tuple[float, ...], type: type[float] | type[int] | type[bool] | type[str] | type[tuple[float, ...]], description: str, units: str = '')

Bases: NamedTuple

Default, declared type, description and units for registry parameters.

Shared by model settings and physical constants. Defaults are immutable scalars or tuples of coefficients; omitted units default to an empty string.

default: float | int | bool | str | tuple[float, ...]

Alias for field number 0

type: type[float] | type[int] | type[bool] | type[str] | type[tuple[float, ...]]

Alias for field number 1

description: str

Alias for field number 2

units: str

Alias for field number 3

class veris.model.variables.Variable(long_name: str, dimensions: tuple[str, str], units: str, description: str, default: float = 0.0)

Bases: object

Allocation defaults and h5netcdf-compatible variable attributes.

netcdf_attributes() → dict[str, str]

Return text attributes suitable for a netCDF variable.

veris.model.configuration.SETTINGS: dict[str, veris.model.types.Parameter]

Model settings defaults and metadata; see Model settings.

veris.model.physical_constants.PHYSICALCONSTANTS: dict[str, veris.model.types.Parameter]

Physical coefficient defaults and metadata; see Physical constants.

veris.model.variables.VARIABLES: dict[str, veris.model.variables.Variable]

Allocation and output metadata for State; see State fields.

veris.model.diagnostics.DIAGNOSTICS: dict[str, veris.model.variables.Variable]

Metadata for output-only coupling fields; see State fields.

Grid dimensions

The C, U, V and Z locations are cell centers for tracers, cell faces for velocity in the x direction, cell faces for velocity in the y direction, and cell corners, respectively. Tracers are values such as ice thickness carried across the grid. All four dimension pairs have the same storage lengths, including halos. Halos are extra cells around a grid piece that hold boundary or neighboring values.

veris.model.variables.C_GRID = ('x_center', 'y_center')

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

veris.model.variables.U_GRID = ('x_face', 'y_center')

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

veris.model.variables.V_GRID = ('x_center', 'y_face')

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

veris.model.variables.Z_GRID = ('x_face', 'y_face')

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.