Initialization and presets

Common experiment initialization

initialize_experiment creates model arrays for a serial run on a single device or for the parts of a device mesh that the current process can access. A mesh groups devices that share the grid. Registered providers supply starting field values for each grid region. Veris checks inputs, applies overrides, computes quantities from other inputs and handles the outer grid boundaries. The maintained presets specify their archived startup rules so all 70 initial fields remain reproducible. The island, dynamics and growth presets all use this initializer. Set the grouped controls through Experiment before creating arrays:

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},
    scenario={"islandWindSpeed": 5.0},
    constants={"rhoIce": 900.0},
)
state, settings, constants = initialize_experiment(experiment)

veris.initialize_experiment(experiment: Experiment, *, mesh: Mesh | None = None) → tuple[State, Configuration, PhysicalConstants]

Validate and initialize one experiment using global physical dimensions.

This host operation is outside differentiated computation. Enable JAX x64 explicitly before allocation when requesting float64. Distributed setup and meshes must be prepared explicitly before device enumeration. All presets and custom geometry support explicitly supplied meshes using addressable regional callbacks, followed by global field-aware halo exchange.

class veris.setups.presets.SetupPreset(name: str, physics: str, scenario_registry: ~collections.abc.Mapping[str, ~veris.model.types.Parameter], scenario_factory: ~veris.setups.presets.ScenarioFactory, field_factory: ~veris.setups.presets.FieldFactory, numerical_defaults: ~veris.setups.presets.NumericalDefaults = <factory>, grid: tuple[int, int] | None = None, profiles: ~collections.abc.Mapping[str, ~veris.setups.presets.Controls] = <factory>, minimum_shape: tuple[int, int] = (2, 2), forcing_defaults: ~veris.setups.presets.Controls | ~collections.abc.Callable[[~veris.setups.presets.Controls], ~veris.setups.presets.Controls] = <factory>, initial_defaults: ~veris.setups.presets.InitialDefaults | None = None, startup_excluded_forcing: frozenset[str] = frozenset({}), preserve_startup: bool = False)

Bases: object

Host schema, declarative startup policies and a regional data factory.

field_factory accepts baseline State, Configuration, PhysicalConstants, scenario, global shape, x/y indices and keyword regional. It supplies field replacements without allocation, global halos or execution resources.

veris.setups.presets.register_preset(preset: SetupPreset) → None

Register an explicit provider without replacing another default owner.

General allocation

The general allocator creates arrays using defaults from the model’s named parameter tables. To define a physical experiment, supply consistent grid distances and areas, masks that mark wet cells, and prescribed external inputs through state_overrides. For an existing example, construct its builtin Experiment and use initialize_experiment.

veris.execution.initialization.initialize(nx: int | None = None, ny: int | None = None, *, dtype: str | None = None, mesh: Mesh | None = None, settings_overrides: Mapping[str, Any] | None = None, physical_overrides: Mapping[str, Any] | None = None, state_overrides: Mapping[str, Any] | None = None) → tuple[State, Configuration, PhysicalConstants]

Allocate all fields for an nx by ny interior Cartesian grid.

Omitted extents use Configuration defaults or settings_overrides. Explicit nx/ny take precedence and are recorded on the returned Configuration instance. Configuration constructors validate scalar overrides and recompute derived values. State overrides must contain numeric arrays with the full storage shape, including halos; they are converted to the initialization dtype. Each interior extent must be at least two cells to supply the periodic halos. Enable jax_enable_x64 before calling when selecting 64-bit arrays; allocation rejects silent dtype truncation. Unknown keys and invalid grid extents fail before allocation. Setup-specific forcing and geometry can be supplied through state_overrides during allocation.

With an explicit mesh, nx and ny are interior extents per partition. Every partition owns two halo cells at each edge; global storage therefore has shape (mesh.shape['x'] * (nx + 4), mesh.shape['y'] * (ny + 4)). Overrides must already use this packed layout. Arrays are placed with NamedSharding(mesh, PartitionSpec(‘x’, ‘y’)); run sharded kernels inside jax.set_mesh(mesh). Mesh resources remain outside numerical State.

Ocean geometry adapter

The adapter checks ocean grid information supplied from outside Veris. It runs in Python and creates a Veris State without requiring an ocean-model container. See Prescribed ocean geometry for array shapes and a usage example. Masks must lie in [0, 1], grid spacing and area must be positive, and prescribed ice amounts, ice-covered fractions and temperatures must satisfy the Experiment physical bounds. Before creating device arrays, Python checks also reject numbers or their reciprocals that the selected numerical precision cannot represent.

Supply latitude (ny centers in degrees), latitude_edges (ny+1 edges) and radius (positive metres) together to select spherical geometry. These coordinate vectors exclude halos in both direct and Experiment inputs. Omit all three for the existing planar contract. Zonal spacing vectors describe equatorial distances; supplied tracer and face areas retain their own quadrature. The adapter derives the geometry-owned static spherical_geometry setting. It must agree with the selected geometry. Spherical inputs default to closed latitude boundaries; explicitly cyclic latitude is rejected because strictly monotone, nonsingular latitude coordinates cannot form a periodic ring.

Spherical normal strain has a finite-volume trace using those stored tracer areas. Tensor divergence is its negative area-weighted adjoint, including the maintained slip stencil. Corner dual areas use the actual corner lengths and wet quadrants, so a straight wall owns half a dual cell. Immutable face metrics retain the true northern face through closed-wall halo refresh. Singular polar edges, partial coordinates and invalid radius/coordinate shapes fail on the host.

class veris.grid.geometry.OceanGeometry(maskT: ArrayInput, maskU: ArrayInput, maskV: ArrayInput, ht: ArrayInput, coriolis_t: ArrayInput, dxt: ArrayInput, dxu: ArrayInput, dyt: ArrayInput, dyu: ArrayInput, area_t: ArrayInput, area_u: ArrayInput, area_v: ArrayInput, latitude: ArrayInput | None = None, latitude_edges: ArrayInput | None = None, radius: ArrayInput | float | None = None)

Bases: object

Read-only ocean grid inputs, independent of any ocean-model container.

maskT, maskU and maskV are volume masks; dxt and dxu are x-spacing vectors, and dyt and dyu are y-spacing vectors (m). ht is depth (m), coriolis_t is Coriolis frequency (s-1), and the three horizontal cell-area arrays are in m2. Shapes and finite positive metrics are checked by the host adapter before any reciprocal is computed. Optional latitude/latitude_edges contain ny/ny+1 physical degrees, excluding halos; radius is a positive scalar in metres. Supply all three for spherical geometry. Zonal spacing vectors then specify equatorial distances, while meridional spacing remains physical distance.

veris.grid.ocean.initialize_from_ocean(geometry: OceanGeometry, *, dtype: str | None = None, settings_overrides: Mapping[str, Any] | None = None, physical_overrides: Mapping[str, Any] | None = None, state_overrides: Mapping[str, Any] | None = None) → tuple[State, Configuration, PhysicalConstants]

Allocate Veris state, numerical policy and a physical-parameter PyTree.

Geometry includes two halo cells at each boundary. Its horizontal shape determines nx and ny, taking precedence over settings overrides. Additional state overrides supply ocean forcing and initial ice fields; geometry-derived fields take precedence. Unspecified fields use VARIABLES defaults. The shared initializer validates overrides and allocates every field at the selected precision. No pre-existing State is required or updated.

Island experiment

The serial island setup combines dynamics, which computes ice motion, transport, which carries ice and snow across the grid, and thermodynamics, which computes freezing and melting. Scenario controls are separate from model Configuration and PhysicalConstants. Their defaults are generated from ISLAND_SETTINGS in Island. Use veris.advance() for one combined update without Python side effects and veris.step() to repeat a fixed number of updates.

class veris.setups.island.IslandSettings(saltOcn_ref: float = 34.7, islandGridSpacing: float = 8000.0, islandWindSpeed: float = 5.0, islandAirTemperature: float = 260.0, islandIceThickness: float = 1.0, islandSnowThickness: float = 0.05, islandIceArea: float = 0.8, islandOceanDepth: float = -100.0, islandCoriolis: float = 0.0001, islandCooling: float = 100.0, islandTimeStep: float = 600.0, islandEVPsteps: int = 5, *, dtype: str = 'float64')

Bases: object

Validated scenario defaults kept outside model configuration and AD State.

veris.setups.island.ISLAND_SETTINGS: dict[str, veris.model.types.Parameter]

Island scenario defaults and metadata; see Island.

Dynamics experiment

This setup computes ice motion and transport using supplied ocean and wind fields. Set the full grid dimensions with Grid. The Configuration returned by initialize_experiment records the interior size of each local grid piece. When given a mesh, the general allocator instead accepts interior sizes per partition, or grid piece. See Dynamics only and Parallel dynamics for the scenario registry and runs.

class veris.setups.run_dyn.DynamicsSettings(length: float = 512000.0, wind_time: float = 5.875, wind_speed: float = 15.0, wind_angle: float = 1.2566370614359172, wind_scale: float = 50000.0, wind_decay: float = 100000.0, center_offset: float = 0.1, center_rate: float = 0.1, ocean_speed: float = 0.01, depth: float = 1000.0, ice_thickness: float = 0.3, surface_temperature: float = 273.0, coriolis_start: float = 0.00014604, coriolis_offset: float = 0.00014596, coriolis_increment: float = 8e-08)

Bases: object

Immutable reference scenario controls, separate from differentiable State.

veris.setups.run_dyn.DYNAMICS_SETTINGS: dict[str, veris.model.types.Parameter]

Dynamics scenario defaults and metadata; see Dynamics only.

Growth experiment

The serial growth column computes freezing and melting. Its heat-flux fields describe heat exchanged with the ice and feed results from one step into the next. Its GROWTH_SETTINGS defaults and command-line usage appear in Growth only.

class veris.setups.run_growth.GrowthSettings(hIceMean: float = 1.3, hSnowMean: float = 0.1, Area: float = 0.9, TSurf: float = 273.0, wSpeed: float = 2.0, ocSalt: float = 29.0, oceanTemperatureC: float = -1.66, Qnet: float = 173.03212617345582, LWdown: float = 80.0, ATemp: float = 253.0, *, dtype: str = 'float64')

Bases: object

Registry-backed reference column controls kept outside differentiable State.

veris.setups.run_growth.GROWTH_SETTINGS: dict[str, veris.model.types.Parameter]

Growth scenario defaults and metadata; see Growth only.

Select physics="thermodynamics" with veris.advance() to update the initialized column, or use its builtin Experiment with Simulation.