Input and output

Import the public classes and record functions below from veris.io. They run in Python on the host that controls the calculation. They stay outside the model calculations through which JAX computes derivatives. See Calendar-aware input and output for complete examples, calendar intervals, sampling rules, defaults from the model’s named tables and limits on reading selected fields.

Output configuration

class veris.io.Stream(name: str = 'instantaneous', variables: tuple[str, ...] = ('hIceMean', 'hSnowMean', 'Area', 'uIce', 'vIce'), sampling_interval: timedelta = datetime.timedelta(seconds=3600), period: str | timedelta = 'instantaneous')

Bases: object

One variable selection with its own sampling and averaging schedule.

class veris.io.OutputSettings(start: datetime | FixedDate = datetime.datetime(2000, 1, 1, 0, 0), calendar: str = 'gregorian', streams: tuple[Stream, ...] = (Stream(name='instantaneous', variables=('hIceMean', 'hSnowMean', 'Area', 'uIce', 'vIce'), sampling_interval=datetime.timedelta(seconds=3600), period='instantaneous'),), sample_initial: bool = True, enabled: bool = True)

Bases: object

Output-only configuration allocated separately from numerical State.

veris.io.STREAM_SETTINGS: dict[str, veris.io.configuration.OutputOption]

Stream defaults and metadata; see Calendar-aware input and output.

veris.io.OUTPUT_SETTINGS: dict[str, veris.io.configuration.OutputOption]

OutputSettings defaults and metadata; see Calendar-aware input and output.

Calendar arithmetic

class veris.io.FixedDate(year: int, month: int, day: int, hour: int = 0, minute: int = 0, second: int = 0, microsecond: int = 0)

Bases: object

A timezone-free date for a fixed calendar, validated further by Calendar.

Years start at one. Basic component ranges are checked here; month lengths depend on the selected calendar and are checked when constructing Calendar.

class veris.io.Calendar(start: datetime | FixedDate, calendar: str = 'gregorian')

Bases: object

A simulation origin and calendar providing exact averaging boundaries.

Gregorian aliases require a timezone-naive datetime; fixed calendars require FixedDate. Daily, monthly and annual windows align to calendar boundaries. Positive timedelta windows align to the simulation origin instead.

property units: str

Return CF seconds-since units preserving a subsecond origin.

date_at(elapsed: timedelta) → datetime | FixedDate

Return the model date at a signed elapsed time from the origin.

window(elapsed: timedelta, period: str | timedelta) → tuple[int, int]

Return containing window bounds as microseconds relative to start.

Calendar-aligned windows may start before the simulation origin. Samples exactly at a right boundary belong to the following window.

Sampling and snapshots

Use OutputManager as a context manager so it closes files and finishes averages for complete averaging windows. Snapshot writing saves values at a single instant, independently of the stream schedules. Existing output paths are rejected.

class veris.io.OutputManager(path: str | Path, settings: OutputSettings | None = None, *, collector: Callable[[State | Mapping[str, Any], tuple[str, ...]], Mapping[str, Any] | None] | None = None, attributes: Mapping[str, str] | None = None)

Bases: object

Sample after concrete model steps; disable explicitly around AD loops.

collector optionally gathers selected arrays collectively and returns physical cells only on the writing rank, with storage halos removed. All ranks must call sample with identical schedules when using collectives.

property buffer_nbytes: int

Current array bytes held for means, independent of sample count.

begin_reduced(*, resume: bool = False) → None

Reserve a fresh manager for records reduced by the scheduled runner.

Reduced writing and direct sampling are exclusive. Disabled output and transformed calls remain inert, as they do for sample().

write_reduced(name: str, fields: Mapping[str, Any], *, time: float, bounds: tuple[float, float], count: int, mean: bool) → None

Collect and write an already reduced, halo-bearing stream record.

Times and bounds are seconds. The scheduled runner owns sampling and window completion; means are already divided by their sample count. Collectors must commute with averaging and remove storage halos. Every rank must enter collection in the same order, including nonwriters.

sample(state: State | Mapping[str, Any], elapsed: timedelta) → None

Process an increasing model time; sample only at exact scheduled times.

Calls during transformations or in disabled mode have no effects, even for constant arrays. Missed samples fail before advancing any stream. Non-sampling calls still flush crossed calendar boundaries.

close(elapsed: timedelta | None = None) → None

Finish at the last observed time or an explicit final boundary.

A close at the next sample time ends the half-open interval without requiring a sample at its right endpoint. Later closes would skip samples and are rejected. Incomplete first and last averaging windows are discarded. Repeated closes are harmless.

veris.io.write_snapshot(path: str | Path, state: State | Mapping[str, Any], *, elapsed: timedelta = datetime.timedelta(0), start: datetime | FixedDate = datetime.datetime(2000, 1, 1, 0, 0), calendar: str = 'gregorian', variables: Sequence[str] | None = None, conf: Configuration | None = None, phys: PhysicalConstants | None = None, collector: Callable[[State | Mapping[str, Any], tuple[str, ...]], Mapping[str, Any] | None] | None = None, attributes: Mapping[str, str] | None = None) → None

Write a concrete final State outside integration/AD, independently of streams.

Reading selected fields

update_state inserts fields sampled at a single instant into an initialized serial State. It preserves the stored halos, the extra cells holding boundary or neighboring values. Refresh halos before advancing the model again. Selected records do not reconstruct everything needed for a complete restart.

class veris.io.Record(fields: dict[str, NDArray[Any]], time: float, bounds: tuple[float, float], count: int, partial: bool, mean: bool, calendar: str, units: str, configuration: dict[str, Any], physical_constants: dict[str, Any])

Bases: object

One materialized record plus calendar, coverage and snapshot metadata.

veris.io.read_record(path: str | Path, *, stream: str = 'snapshot', index: int = -1, variables: Sequence[str] | None = None) → Record

Read a selected record, rejecting unknown fields and incompatible dimensions.

veris.io.update_state(state: State, record: Record) → State

Insert physical fields into a serial State, preserving its existing halos.

Refresh boundary halos with the model boundary exchange before integration. Distributed State reconstruction requires a separate initialization step.

Distributed collection

The collector removes the halos from each partition, or grid piece, and gathers the physical fields from its interior cells. All processes must enter collection in the same order. Only the writing rank, the process assigned to write files, receives fields for file output.

veris.io.distributed.distributed_collector(mesh: Mesh) → Callable[[State | Mapping[str, Any], tuple[str, ...]], Mapping[str, Any] | None]

Build the collective callback accepted by OutputManager and write_snapshot.