Model settings¶

veris.model.configuration.SETTINGS defines defaults, scalar types (types of individual values) and descriptions for the frozen Configuration dataclass. Its fields cannot be reassigned. Numerical controls and execution choices are separate from Physical constants. Configuration holds grid sizes, switches for behavior at grid edges, timestep lengths, solver iteration counts and safeguards for convergence (when repeated calculations settle on a solution). PhysicalConstants holds physical thresholds, scales that keep equations well behaved, and reference heights for atmospheric forcing.

Create an updated object instead of changing fields in place. A reciprocal is one divided by a value. Reciprocals calculated from changed values are recalculated:

from dataclasses import replace
from veris.model.configuration import Configuration
settings = replace(Configuration(), deltatDyn=600, nEVPsteps=20)
assert settings.recip_deltatDyn == 1 / 600

JAX treats Configuration objects as fixed inputs during JIT compilation, which turns Python calculations into executable code. Changing a value may require compilation again. The island example changes timestep lengths and the iteration count of the EVP (elastic-viscous-plastic) ice-motion solver.

Horizontal boundaries¶

The x direction is always periodic: crossing one edge returns to the opposite edge. enable_cyclic_y=True (the default) also joins the global y edges this way. Set it to False at initialization to use closed southern and northern walls that nothing can pass through:

import jax
from veris import Experiment, Grid, initialize_experiment

jax.config.update("jax_enable_x64", True)
experiment = Experiment.builtin(
    "island", grid=Grid(8, 12), settings={"enable_cyclic_y": False},
)
state, settings, constants = initialize_experiment(experiment)

Closed walls keep every interior row of tracers, such as ice amount and temperature. Exterior masks mark land. Ice velocity perpendicular to the wall and north-south transport are zero at both walls. noSlip selects the existing coastline treatment for motion along the wall. These are solid walls; they do not form an open boundary or a grid folded across a pole.

Single-device execution and execution split across devices use the same conditions. Only partitions at the global y edges apply walls. Internal partitions still exchange their halos, the extra cells that hold boundary or neighboring data. The fixed switch adds no arrays to State and supports JVP (following a chosen input change forward) and VJP (carrying output sensitivities back to inputs). Generic scalar halos copy the nearest interior value so temperatures and grid metrics remain valid. Masks, ice amounts, velocities and fluxes use their own wall conditions. Wall shear stress, the force per area along the wall, is handled separately. No-slip keeps the calculated traction, including the northern physical face stored in a halo column. Free-slip sets both wall shear stresses to zero.

Choose how the grid edges connect at initialization. Reinitialize the geometry and masks when changing that choice. Switching a closed State back to periodic does not restore the southern face masks that were closed during allocation.

After manually replacing State fields or loading selected physical fields, refresh the whole State before stepping with veris.grid.halos.fill_state_overlap(state, settings). For arrays split across devices, call it inside the active jax.set_mesh(mesh) context. The maintained coupled drivers refresh State and diagnostic halos after each step. Custom low-level drivers should use this helper, which applies each field’s boundary rules, instead of filling every field as a generic scalar. Selected-field snapshots are not complete restarts (see Calendar-aware input and output). Removing halos omits the northern no-slip shear-stress value. Halo refresh preserves that independent traction but cannot reconstruct a missing value.

Floating-point precision¶

Choose settings={"dtype": "float32"} or settings={"dtype": "float64"} when defining an Experiment, then call initialize_experiment. These types store floating-point numbers at different precisions. The general allocator also accepts dtype directly. Both returned static objects keep this choice. Their floating coefficients, calculated values and lookup tables use the selected NumPy scalar type. All state and work arrays use the matching JAX dtype. Integers (whole numbers) and Boolean switches (true or false) keep their types. float64 requires JAX x64 enabled before initialization. Veris rejects silent loss of precision and does not change global JAX configuration. Creating an updated object keeps its precision. Arrays supplied as replacements must use the existing array dtype. NetCDF storage uses the actual array dtype, as shown in State fields.

The Parameter entry at veris.model.configuration.SETTINGS["dtype"] defines precision directly. Configuration objects declare their own keyword-only dtype field with that default. They do not inherit precision from a base class.

Configuration keeps explicitDrag because version-one complete restart files store the full set of settings fields. The current solvers do not read this field, so changing it leaves the numerical calculation unchanged.

Registry defaults¶

Setting	Default	Unit	Description
`dtype`	`'float64'`	`-`	Model floating-point precision: float32 or float64
`nx`	`8`	`-`	Local interior grid extent along the x direction
`ny`	`12`	`-`	Local interior grid extent along the y direction
`enable_cyclic_y`	`True`	`-`	Wrap global y edges; otherwise use closed, impermeable walls
`spherical_geometry`	`False`	`-`	Geometry-owned selection of spherical metrics and operators
`geometrySurfaceTemperature`	`273.0`	\(K\)	Initial surface temperature used by the geometry adapter
`printEvpResidual`	`False`	`-`	Print EVP residual diagnostics during execution
`deltatTherm`	`86400.0`	\(s\)	timestep for thermodynamic equations
`recip_deltatTherm`	`1.1574074074074073e-05`	\(s^{-1}\)	Reciprocal thermodynamic timestep
`deltatDyn`	`86400.0`	\(s\)	timestep for dynamic equations
`recip_deltatDyn`	`1.1574074074074073e-05`	\(s^{-1}\)	Reciprocal dynamic timestep
`nITC`	`5`	`-`	number of ice thickness categories
`recip_nITC`	`0.2`	`-`	1 / nITC
`noSlip`	`True`	`-`	flag for using the no-slip condition
`useRelativeWind`	`True`	`-`	Use wind minus ice velocity for stress; otherwise use wind velocity
`secondOrderBC`	`False`	`-`	flag for using the second order approximation for boundary conditions
`extensiveFld`	`True`	`-`	flag whether the advective fields are extensive
`useRealFreshWaterFlux`	`False`	`-`	flag for using the sea ice load in the calculation of the ocean surface height
`useFreedrift`	`False`	`-`	flag for using the freedrift solver
`useEVP`	`True`	`-`	flag for using the EVP solver
`evpAlpha`	`500.0`	`-`	EVP parameter
`evpBeta`	`500.0`	`-`	EVP parameter
`useAdaptiveEVP`	`False`	`-`	flag for using adaptive relaxation parameters
`aEVPalphaMin`	`5.0`	`-`	lower limit of alpha and beta
`aEvpCoeff`	`0.5`	`-`	largest stabilized frequency for adaptive EVP
`explicitDrag`	`True`	`-`	Reserved legacy explicit-drag flag; currently unused by the solvers
`nEVPsteps`	`400`	`-`	number of sub-cycling iterations of the EVP solver
`computeEvpResidual`	`False`	`-`	flag for computing the residual of stress and velocity in the EVP loop
`use_coastline`	`False`	`-`	flag for using the coastline data for lateral drag
`use_sharding`	`True`	`-`	flag for using parallel execution via sharded arrays
`CrMax`	`1000000.0`	`-`	Absolute cap on the advected-field slope ratio
`eps2`	`1e-20`	\(hPa\)	Additive safeguard for the longwave humidity-pressure square root
`surfaceTemperatureIterations`	`6`	`-`	Number of Newton iterations in the ice surface energy balance
`aEVPmassMin`	`0.0001`	\(kg\,m^{-2}\)	Minimum cell ice mass used in adaptive EVP relaxation
`aEVPcStar`	`4.0`	`-`	Adaptive EVP relaxation multiplier
`lanlBulkIterations`	`5`	`-`	Number of LANL Monin-Obukhov stability iterations