# SPDX-License-Identifier: Apache-2.0
# Copyright 2026 Caleb Buahin
"""Discoverable, lazy result fields over the native 1D and 2D readers."""
from __future__ import annotations
from collections.abc import Iterator, Mapping
from contextlib import ExitStack
from dataclasses import dataclass
import operator
from os import PathLike
import re
from types import MappingProxyType
from typing import TYPE_CHECKING, Any, Literal, cast
if TYPE_CHECKING:
import pandas as pd
import xarray as xr
import numpy as np
from numpy.typing import NDArray
from ._enums import FlowUnits, OutNodeVar, OutLinkVar, OutSubcatchVar, OutSystemVar
from ._output_reader import OutputReader
from ._output2d import Output2DReader
def _indices(selection: Any, size: int, names: tuple[str, ...] = ()) -> tuple[list[int], bool]:
"""Resolve Python selectors without allocating an array the size of an axis."""
if selection is None:
selection = slice(None)
if isinstance(selection, slice):
return list(range(*selection.indices(size))), False
if isinstance(selection, str) or np.isscalar(selection):
if isinstance(selection, str):
try:
return [names.index(selection)], True
except ValueError:
raise KeyError(selection) from None
index = operator.index(cast(Any, selection))
index += size if index < 0 else 0
if index < 0 or index >= size:
raise IndexError('Result index out of range')
return [index], True
return [_indices(key, size, names)[0][0] for key in selection], False
def _selection_axes(selection: Any, rank: int) -> tuple[Any, ...]:
keys = selection if isinstance(selection, tuple) else (selection,)
ellipses = sum(key is Ellipsis for key in keys)
if ellipses > 1:
raise IndexError('Only one ellipsis is allowed')
if ellipses:
at = next(i for i, key in enumerate(keys) if key is Ellipsis)
keys = keys[:at] + (slice(None),) * (rank - len(keys) + 1) + keys[at + 1:]
if len(keys) > rank:
raise IndexError('Too many selection axes')
return keys + (slice(None),) * (rank - len(keys))
[docs]
class ResultField:
"""A lazy numeric field. Inspect metadata, then call read() to load values.
Fields retain their reader; arrays returned by read() remain valid after
close. Missing optional conversion packages raise ImportError on use only.
"""
name: str
units: str | None
dimensions: tuple[str, ...]
@property
def shape(self) -> tuple[int, ...]:
raise NotImplementedError
@property
def times(self) -> NDArray[Any] | None:
raise NotImplementedError
[docs]
def read(self, *, periods: Any = None, objects: Any = None,
species: str | int | None = None, selection: Any = None) -> NDArray[Any]:
raise NotImplementedError
def __getitem__(self, selection: Any) -> NDArray[Any]:
return self.read(selection=selection)
[docs]
def to_pandas(self) -> pd.Series[Any] | pd.DataFrame:
"""Load as a Series or DataFrame; available for one or two dimensions."""
import pandas as pd
values = self.read()
times = self.times
result: pd.Series[Any] | pd.DataFrame
if values.ndim == 1:
result = pd.Series(values, index=times, name=self.name)
elif values.ndim == 2:
columns = getattr(self, 'object_ids', None)
result = pd.DataFrame(values, index=times, columns=columns)
else:
raise ValueError('Use to_xarray() for fields with more than two dimensions')
result.attrs['units'] = self.units
return result
[docs]
def to_xarray(self) -> xr.DataArray:
"""Load as an xarray.DataArray, retaining named dimensions and units."""
import xarray as xr
coords: dict[str, NDArray[Any] | list[str]] = {}
if self.times is not None:
coords['time'] = self.times
if hasattr(self, 'object_ids') and 'object' in self.dimensions:
coords['object'] = list(self.object_ids)
if hasattr(self, 'species_names') and 'species' in self.dimensions:
coords['species'] = list(self.species_names)
return xr.DataArray(self.read(), dims=self.dimensions, coords=coords,
name=self.name, attrs={'units': self.units})
def __repr__(self) -> str:
return f'{type(self).__name__}({self.name!r}, shape={self.shape}, units={self.units!r})'
def _units(reader: OutputReader, kind: str, name: str) -> str | None:
si = int(reader.flow_units) >= int(FlowUnits.CMS)
length, rain = ('m', 'mm') if si else ('ft', 'in')
if name in {'evap', 'pet'}:
return rain + '/day'
if name in {'rainfall', 'infil'}:
return rain + '/h'
if name in {'snow_depth'}:
return rain
if name in {'depth', 'head', 'gw_elev'}:
return length
if name in {'volume', 'storage'}:
return length + '3'
if name == 'velocity':
return length + '/s'
if name in {'capacity', 'soil_moist', 'snow_albedo', 'snow_cover'}:
return '1'
if name in {'temperature'}:
return 'degC' if si else 'degF'
if name in {'snow_surface_temp', 'snow_bulk_temp'}:
return 'degC'
if name == 'snow_energy':
return 'kJ/m2'
if name == 'snow_swe':
return 'm'
if name in {'snow_melt', 'snow_input', 'snow_sublimation'}:
return 'm/s'
if name == 'snow_time':
return 's'
return {'CFS': 'ft3/s', 'GPM': 'gal/min', 'MGD': 'million gal/day',
'CMS': 'm3/s', 'LPS': 'L/s', 'MLD': 'million L/day'}[reader.flow_units.name]
[docs]
class SeriesField(ResultField):
"""One recorded 1D variable, optionally bound to one object."""
def __init__(self, collection: ResultCollection, name: str, code: int,
units: str | None, object_index: int | None = None):
self._collection = collection
self.name, self._code, self.units = name, code, units
self._object_index = object_index
self.dimensions = ('time',) if object_index is not None or collection.kind == 'system' else ('time', 'object')
@property
def shape(self) -> tuple[int, ...]:
size = self._collection.reader.period_count
return (size,) if len(self.dimensions) == 1 else (size, len(self._collection))
@property
def times(self) -> NDArray[Any]:
return self._collection.reader.period_times.copy()
@property
def object_ids(self) -> tuple[str, ...]:
return self._collection.ids
[docs]
def read(self, *, periods: Any = None, objects: Any = None,
species: str | int | None = None, selection: Any = None) -> NDArray[Any]:
if species is not None:
raise ValueError('Select a named species through the species mapping first')
if selection is not None:
if periods is not None or objects is not None:
raise ValueError('Use selection or named selectors, not both')
keys = _selection_axes(selection, len(self.dimensions))
periods = keys[0] if keys else None
objects = keys[1] if len(keys) > 1 else None
collection = self._collection
reader = collection.reader
time_indices, scalar_time = _indices(periods, reader.period_count)
scalar_field = len(self.dimensions) == 1
if objects is not None and scalar_field:
raise ValueError('This field is already bound to one object or the system')
indices, scalar_object = ([self._object_index], True) if scalar_field else _indices(objects, len(collection), collection.ids)
values = np.empty((len(time_indices), len(indices)), dtype=np.float32)
if time_indices and indices:
low, high = min(time_indices), max(time_indices)
take = np.asarray(time_indices) - low
# Bulk snapshots are efficient when reading every object. Small
# selections use native object histories and never load other IDs.
if not scalar_field and objects is None:
method = getattr(reader, collection.kind + '_result')
for row, period in enumerate(time_indices):
values[row] = method(period, self._code)
else:
method = getattr(reader, collection.kind + '_series')
for col, index in enumerate(indices):
args = (self._code,) if collection.kind == 'system' else (index, self._code)
values[:, col] = method(*args, start=low, end=high)[take]
if scalar_field or scalar_object:
values = values[:, 0]
if scalar_time:
values = values[0]
return np.asarray(values)
class _ResultObject:
def __init__(self, collection: ResultCollection, index: int):
self._collection, self._index = collection, index
@property
def id(self) -> str:
return self._collection.ids[self._index]
@property
def variables(self) -> Mapping[str, SeriesField]:
return MappingProxyType({name: self._bound(field) for name, field in self._collection.variables.items()})
@property
def species(self) -> Mapping[str, SeriesField]:
return MappingProxyType({name: self._bound(field) for name, field in self._collection.species.items()})
def _bound(self, field: SeriesField) -> SeriesField:
return SeriesField(self._collection, field.name, field._code, field.units, self._index)
def __getattr__(self, name: str) -> SeriesField:
if name.startswith('_'):
raise AttributeError(name)
try:
return self.variables[name]
except KeyError:
raise AttributeError(name) from None
def __dir__(self) -> list[str]:
return sorted(set(super().__dir__()) | set(self._collection.variables))
[docs]
class ResultCollection(Mapping[str, _ResultObject]):
"""Recorded objects and named variables; indexing accepts an ID or index."""
def __init__(self, reader: OutputReader, kind: str):
self.reader, self.kind = reader, kind
enum: Any = {'node': OutNodeVar, 'link': OutLinkVar,
'subcatchment': OutSubcatchVar, 'system': OutSystemVar}[kind]
self.ids: tuple[str, ...] = tuple(getattr(reader, kind + '_ids')) if kind != 'system' else ()
fields = {}
for member in enum:
if member.name == 'POLLUT_BASE':
continue
if kind == 'subcatchment' and not reader.has_subcatch_variable(member.value):
continue
name = member.name.lower()
fields[name] = SeriesField(self, name, member.value, _units(reader, kind, name))
self.variables = MappingProxyType(fields)
self.species = MappingProxyType({
name: SeriesField(self, name, enum.POLLUT_BASE + i, units)
for i, (name, units) in enumerate(zip(reader.pollutant_ids, reader.pollutant_units))
}) if kind != 'system' else MappingProxyType({})
def __len__(self) -> int:
return len(self.ids)
def __iter__(self) -> Iterator[str]:
return iter(self.ids)
def __getitem__(self, key: str | int) -> _ResultObject:
indices, scalar = _indices(key, len(self.ids), self.ids)
if not scalar:
raise TypeError('Select one object by name or index')
return _ResultObject(self, indices[0])
def __getattr__(self, name: str) -> SeriesField:
if name.startswith('_'):
raise AttributeError(name)
try:
return self.variables[name]
except KeyError:
raise AttributeError(name) from None
def __dir__(self) -> list[str]:
return sorted(set(super().__dir__()) | set(self.variables))
[docs]
@dataclass(frozen=True)
class ResultMesh:
"""Stored mesh in SI coordinates. Cells retain native order and padding -1."""
vertices: NDArray[np.float64]
cells: NDArray[np.int64]
vertex_counts: NDArray[np.int64]
crs: str | None
metres_per_model_unit: float | None
coordinate_units: str | None
def _axis_names(reader: Output2DReader, path: str, shape: tuple[int, ...],
attrs: Mapping[str, str]) -> tuple[str, ...]:
rank = len(shape)
names = [f'axis_{i}' for i in range(rank)]
layout = re.search(r'\[([^]]+)\]', attrs.get('layout', ''))
if layout:
tokens = [v.strip().lower() for v in layout.group(1).split(',')]
if len(tokens) == rank:
aliases = {'face': 'cell', 'nface': 'cell', 'ntime': 'time',
'nspecies': 'species', 'node': 'vertex', 'nnode': 'vertex'}
names = [aliases.get(token, token) for token in tokens]
timed = 0 in reader.unlimited_axes(path) and path.count('/') == 1
if timed:
names[0] = 'time'
if attrs.get('location') == 'face' and 'cell' not in names and rank:
names[-1] = 'cell'
if path == '/Mesh2_edge_flux':
names = ['time', 'cell', 'edge']
elif path.startswith('/Mesh2_node_') and timed and rank == 2:
names = ['time', 'vertex']
elif path == '/Mesh2_face_nodes':
names = ['cell', 'corner']
elif rank == 1 and path.startswith('/Mesh2_face_'):
names = ['cell']
elif path.startswith('/Mesh2_edge_') and rank == 2:
names = ['cell', 'edge']
if rank >= 3 and 'species_names' in attrs and 'species' not in names:
names[1] = 'species'
# Unknown diagnostics keep positional axes rather than inventing a clock.
return tuple(names)
[docs]
class SurfaceField(ResultField):
"""A stored 2D dataset with named axes and optional bound cell/species."""
def __init__(self, surface: SurfaceResults, path: str,
fixed: Mapping[str, int] | None = None):
self._surface, self.path = surface, path
self._fixed = dict(fixed or {})
self.name = path.rsplit('/', 1)[-1].removeprefix('Mesh2_face_')
self.attributes = MappingProxyType(surface.reader.attributes(path))
self.units = self.attributes.get('units')
shape, _ = surface.reader.shape(path)
self._axes = _axis_names(surface.reader, path, shape, self.attributes)
self.dimensions = tuple(axis for axis in self._axes if axis not in self._fixed)
self.species_names = tuple(v.strip() for v in self.attributes.get('species_names', '').split(',') if v.strip())
if 'species' in self._fixed:
labels = self.attributes.get('species_units', '').split(',')
index = self._fixed['species']
self.units = labels[index].strip() if index < len(labels) and labels[index].strip() else None
@property
def shape(self) -> tuple[int, ...]:
shape, _ = self._surface.reader.shape(self.path)
return tuple(size for axis, size in zip(self._axes, shape) if axis not in self._fixed)
@property
def times(self) -> NDArray[Any] | None:
if 'time' not in self.dimensions:
return None
times = self._surface.period_times
if len(times) != self.shape[self.dimensions.index('time')]:
raise ValueError(f'{self.path} has incomplete report rows; inspect it with selection= explicitly')
return times
[docs]
def bind(self, **axes: int) -> SurfaceField:
unknown = set(axes) - set(self._axes)
if unknown:
raise ValueError(f'Field has no axes: {sorted(unknown)}')
return SurfaceField(self._surface, self.path, {**self._fixed, **axes})
[docs]
def read(self, *, periods: Any = None, objects: Any = None,
species: str | int | None = None, selection: Any = None) -> NDArray[Any]:
reader = self._surface.reader
shape, dtype = reader.shape(self.path)
keys: list[Any] = [self._fixed.get(axis, slice(None)) for axis in self._axes]
if selection is not None:
if periods is not None or objects is not None or species is not None:
raise ValueError('Use selection or named selectors, not both')
selected = _selection_axes(selection, len(self.dimensions))
free_axes = [i for i, axis in enumerate(self._axes) if axis not in self._fixed]
for i, key in zip(free_axes, selected):
keys[i] = key
for axis, key in (('time', periods), ('cell', objects), ('species', species)):
if key is None:
continue
if axis not in self.dimensions:
raise ValueError(f'Field has no unbound {axis} axis')
if axis == 'species' and isinstance(key, str):
try:
key = self.species_names.index(key)
except ValueError:
raise KeyError(key) from None
keys[self._axes.index(axis)] = key
# Preserve ordered/duplicate cell lists using bounded per-cell slabs.
if 'cell' in self._axes:
cell_axis = self._axes.index('cell')
key = keys[cell_axis]
if not isinstance(key, slice) and not np.isscalar(key):
indices, _ = _indices(key, shape[cell_axis])
out_axis = sum(isinstance(k, slice) for k in keys[:cell_axis])
if indices:
chunks = []
for index in indices:
slab = keys.copy()
slab[cell_axis] = index
chunks.append(reader.read(self.path, tuple(slab)))
return np.stack(chunks, axis=out_axis)
keys[cell_axis] = slice(0, 0)
return reader.read(self.path, tuple(keys))
class _SurfaceCell:
def __init__(self, surface: SurfaceResults, index: int):
self._surface, self.index = surface, index
def __getattr__(self, name: str) -> SurfaceField:
field = cast(SurfaceField, getattr(self._surface, name))
return field.bind(cell=self.index)
@property
def species(self) -> Mapping[str, SurfaceField]:
return MappingProxyType({name: field.bind(cell=self.index) for name, field in self._surface.species.items()})
class _SurfaceCells:
def __init__(self, surface: SurfaceResults):
self._surface = surface
def __len__(self) -> int:
return self._surface.reader.shape('/Mesh2_face_nodes')[0][0]
def __getitem__(self, index: int) -> _SurfaceCell:
indices, scalar = _indices(index, len(self))
if not scalar:
raise TypeError('Select one cell by its native zero-based index')
return _SurfaceCell(self._surface, indices[0])
[docs]
class SurfaceResults:
"""Saved 2D results. Each recorded dataset is accessible through field()."""
def __init__(self, reader: Output2DReader):
self.reader = reader
self.cells = _SurfaceCells(self)
self._paths = frozenset(reader.datasets)
self._fields: dict[str, SurfaceField] = {}
@property
def variables(self) -> Mapping[str, SurfaceField]:
return MappingProxyType({path[1:].removeprefix('Mesh2_face_'): self.field(path)
for path in sorted(self._paths) if path.count('/') == 1 and path != '/time'})
[docs]
def field(self, path: str) -> SurfaceField:
"""Access a full dataset path, including nested diagnostic groups."""
path = '/' + path.lstrip('/')
if path not in self._paths:
raise KeyError(f'Variable was not recorded: {path}')
if path not in self._fields:
self._fields[path] = SurfaceField(self, path)
return self._fields[path]
def __getattr__(self, name: str) -> SurfaceField:
if name.startswith('_'):
raise AttributeError(name)
for path in ('/Mesh2_face_' + name, '/' + name):
if path in self._paths:
return self.field(path)
raise AttributeError(f'No recorded 2D variable {name!r}; inspect variables')
def __dir__(self) -> list[str]:
names = {path[1:].removeprefix('Mesh2_face_') for path in self._paths if path.count('/') == 1}
return sorted(set(super().__dir__()) | names)
@property
def period_times(self) -> NDArray[Any]:
"""Report dates from the file's declared CF units, at microsecond precision."""
values = self.reader.read('/time')
units = self.reader.attributes('/time').get('units', '')
match = re.fullmatch(r'(days|hours|minutes|seconds) since (.+)', units)
if match is None:
raise ValueError(f'Unsupported or missing time units: {units!r}')
scale = {'days': 86400, 'hours': 3600, 'minutes': 60, 'seconds': 1}[match[1]]
if not np.isfinite(values).all():
raise ValueError('Non-finite report dates in output')
return np.datetime64(match[2], 'us') + np.rint(values * scale * 1e6).astype('timedelta64[us]')
@property
def mesh(self) -> ResultMesh:
reader = self.reader
vertices = np.column_stack([reader.read('/Mesh2_node_' + axis) for axis in 'xyz'])
cells = reader.read('/Mesh2_face_nodes')
attrs = reader.attributes('/Mesh2_face_nodes')
fill = int(attrs.get('_FillValue', '-1'))
valid = (cells != fill) & (cells >= 0)
cells = np.where(valid, cells - int(attrs.get('start_index', '0')), -1)
if '/Mesh2_face_nv' in self._paths:
counts = reader.read('/Mesh2_face_nv')
if np.any((counts < 3) | (counts > cells.shape[1])):
raise ValueError('Invalid mesh cell vertex counts')
cells[np.arange(cells.shape[1])[None, :] >= counts[:, None]] = -1
else:
counts = np.sum(cells >= 0, axis=1)
if np.any(cells >= len(vertices)):
raise ValueError('Mesh connectivity exceeds vertex count')
try:
crs = reader.attributes('/crs')
except IndexError:
crs = {}
return ResultMesh(vertices, cells, counts,
crs.get('model_crs'),
float(crs['metres_per_model_unit']) if 'metres_per_model_unit' in crs else None,
crs.get('units') or reader.attributes('/Mesh2_node_x').get('units'))
@property
def species(self) -> Mapping[str, SurfaceField]:
path = '/Mesh2_face_species_conc'
if path not in self._paths:
return MappingProxyType({})
field = self.field(path)
return MappingProxyType({name: field.bind(species=i) for i, name in enumerate(field.species_names)})
@property
def mass_balance(self) -> Mapping[str, float]:
prefix = '/mass_balance_2d/'
result = {path[len(prefix):]: float(self.reader.read(path))
for path in sorted(self._paths) if path.startswith(prefix)}
if result:
attrs = self.reader.attributes('/mass_balance_2d')
if 'continuity_error' in attrs:
result['continuity_error'] = float(attrs['continuity_error'])
return MappingProxyType(result)
[docs]
class Results:
"""Own independent readers for a 1D output, a 2D output, or both.
Open explicitly named paths; their reporting clocks remain independent.
Use a context manager or close(). 2D files must be closed/immutable;
live=True applies only to the binary 1D output.
"""
def __init__(self, path: str | PathLike[str] | None = None, *,
surface: str | PathLike[str] | None = None, live: bool = False):
if path is None and surface is None:
raise ValueError('Provide a 1D output path, a 2D surface path, or both')
self._stack = ExitStack()
self.output: OutputReader | None = None
self.surface: SurfaceResults | None = None
try:
if path is not None:
self.output = self._stack.enter_context(OutputReader(path, live=live))
self.nodes = ResultCollection(self.output, 'node')
self.links = ResultCollection(self.output, 'link')
self.subcatchments = ResultCollection(self.output, 'subcatchment')
self.system = ResultCollection(self.output, 'system')
if surface is not None:
self.surface = SurfaceResults(self._stack.enter_context(Output2DReader(surface)))
except BaseException:
self.close()
raise
[docs]
@classmethod
def open(cls, path: str | PathLike[str] | None = None, *,
surface: str | PathLike[str] | None = None, live: bool = False) -> Results:
return cls(path, surface=surface, live=live)
@property
def times(self) -> NDArray[Any]:
"""1D report dates. The surface has its own period_times coordinate."""
if self.output is None:
raise ValueError('No 1D output was opened; use surface.period_times')
return self.output.period_times.copy()
[docs]
def refresh(self) -> int:
"""Refresh complete 1D report periods; does not tail the 2D HDF5 file."""
if self.output is None:
raise ValueError('No 1D output was opened')
return self.output.refresh()
[docs]
def close(self) -> None:
self._stack.close()
def __enter__(self) -> Results:
if self.output is not None:
_ = self.output.period_count
if self.surface is not None:
_ = self.surface.reader.datasets
return self
def __exit__(self, *args: Any) -> Literal[False]:
self.close()
return False