API reference

The public Python API of nwm-gdrom is intentionally small: one function for loading a catalog, one dataclass for the catalog itself, one exception, and three numeric-code enums. Everything else lives in submodules and is considered internal. The build-side helpers, the parser, the OOD-threshold computation, and the reference evaluator may evolve without notice.

The names below are all importable as attributes of the top-level nwm_gdrom namespace; resolution is lazy via PEP 562 so import nwm_gdrom itself is cheap and does not pull in pandas unless a catalog is actually loaded.

import nwm_gdrom

catalog = nwm_gdrom.load_catalog("nwm_gdrom_catalog.npz")

Loading a catalog

nwm_gdrom.load_catalog

load_catalog(
    path: Path | str,
    *,
    expected_rule_version: str | None = None,
    expected_crosswalk_version: str | None = None,
) -> GDROMCatalog

Load a catalog from disk and validate its version stamps.

Reads a compressed NumPy archive previously written by :func:save_catalog and returns a :class:GDROMCatalog. The archive is opened with allow_pickle=False so loading never executes arbitrary code. If the caller provides expected_rule_version or expected_crosswalk_version, those are validated against the embedded stamps and a mismatch raises :class:CatalogVersionMismatchError rather than silently continuing with an unexpected catalog. This is the recommended consumption pattern for operational T-Route deployments.

Parameters:

Name	Type	Description	Default
path	Path	Path to a .npz file produced by :func:save_catalog.	required
expected_rule_version	str	If provided, the catalog's embedded rule_version must equal this string exactly; otherwise the load aborts. Pass None (the default) to skip the check, which is appropriate during catalog development but not for archived or operational runs.	None
expected_crosswalk_version	str	If provided, the catalog's embedded crosswalk_version must equal this string exactly. Defaults to None.	None

Returns:

Type	Description
GDROMCatalog	Fully populated catalog with all array fields cast to their canonical dtypes.

Raises:

Type	Description
FileNotFoundError	If path does not exist.
ValueError	If the archive is missing any required array field or version stamp.
CatalogVersionMismatchError	If either expected version is provided and does not match the embedded stamp.

Examples:

>>> from pathlib import Path
>>> import nwm_gdrom
>>> catalog = nwm_gdrom.load_catalog(
...     Path("dist/nwm_gdrom_catalog.npz"),
...     expected_rule_version="v0.1.0",
... )
>>> catalog.n_reservoirs
2017

The catalog dataclass

nwm_gdrom.GDROMCatalog dataclass

GDROMCatalog(
    grand_ids: NDArray[int64],
    state: NDArray[bytes_],
    category: NDArray[int8],
    storage_cap_m3: NDArray[float32],
    min_storage_m3: NDArray[float32],
    ood_inflow_p01_af: NDArray[float32],
    ood_inflow_p99_af: NDArray[float32],
    reservoir_modules_start: NDArray[int32],
    modules_kind: NDArray[int8],
    modules_ptr: NDArray[int32],
    modules_flat: NDArray[float64],
    conditions_branch_start: NDArray[int32],
    conditions_ptr: NDArray[int32],
    conditions_flat: NDArray[float64],
    rule_version: str,
    crosswalk_version: str,
)

Flat-array catalog of GDROM rules for N reservoirs.

Per-reservoir fields (all length N, sorted by ascending grand_ids):

field	dtype	description
grand_ids	int64	GRanD identifier (≥10000 for non-GRanD).
state	S2	2-letter state code for PDSI mapping; empty.
category	int8	0=Res_R, 1=Res_L, 2=Res_M.
storage_cap_m3	float32	Capacity in m³ (acre-ft x 1233.48 at build time).
min_storage_m3	float32	Dead-pool / minimum operating storage in m³.
ood_inflow_p01_af	float32	Lower OOD threshold, acre-ft/day; -inf disables.
ood_inflow_p99_af	float32	Upper OOD threshold, acre-ft/day; +inf disables.

Modules (flat-packed, CSR-indexed):

field	dtype	description
reservoir_modules_start	int32[N+1]	First module index per reservoir.
modules_kind	int8[M_total]	See ModuleKind (EXPR / TREE).
modules_ptr	int32[M_total+1]	Offsets into modules_flat.
modules_flat	float64[...]	Packed params; see module docstring.

Dispatcher conditions (flat-packed, CSR-indexed):

field	dtype	description
conditions_branch_start	int32[N+1]	First branch per reservoir; empty range = no dispatcher.
conditions_ptr	int32[B+1]	Offsets into conditions_flat.
conditions_flat	float64[...]	Packed branches; see module docstring.

Versioning: rule_version and crosswalk_version strings, validated on load_catalog against an optional expected value.

n_reservoirs property

n_reservoirs: int

Number of reservoirs in the catalog.

Returns:

Type	Description
int	Length of the grand_ids array.

n_modules

n_modules(reservoir_idx: int) -> int

Return the number of modules for a reservoir.

Parameters:

Name	Type	Description	Default
reservoir_idx	int	Row index in [0, n_reservoirs). Use :func:nwm_gdrom.evaluator.find_reservoir_index to resolve a GRanD identifier to its row index.	required

Returns:

Type	Description
int	Number of modules attached to this reservoir (always at least one).

Raises:

Type	Description
IndexError	If reservoir_idx is outside [0, n_reservoirs).

has_dispatcher

has_dispatcher(reservoir_idx: int) -> bool

Return whether a reservoir has a dispatcher tree.

Reservoirs with a single module have no dispatcher; reservoirs with multiple modules have a dispatcher CART that selects among them on each daily evaluation.

Parameters:

Name	Type	Description	Default
reservoir_idx	int	Row index in [0, n_reservoirs).	required

Returns:

Type	Description
bool	True if the reservoir's dispatcher branch range is non-empty, False otherwise.

Raises:

Type	Description
IndexError	If reservoir_idx is outside [0, n_reservoirs).

category_name

category_name(reservoir_idx: int) -> str

Return the human-readable GDROM category for a reservoir.

Parameters:

Name	Type	Description	Default
reservoir_idx	int	Row index in [0, n_reservoirs).	required

Returns:

Type	Description
str	One of "Res_R", "Res_L", or "Res_M".

Raises:

Type	Description
IndexError	If reservoir_idx is outside [0, n_reservoirs).

Version-mismatch exception

nwm_gdrom.CatalogVersionMismatchError

Bases: ValueError

Raised when a loaded catalog's version stamps do not match expectations.

Either rule_version or crosswalk_version (or both) on disk differ from the values the caller passed to :func:load_catalog via expected_rule_version / expected_crosswalk_version. Inherits from :class:ValueError so callers that only catch ValueError still handle it.

Numeric-code enums

nwm_gdrom.ModuleKind

Bases: IntEnum

nwm_gdrom.OpCode

Bases: IntEnum

Comparison operator code used in predicate triples.

nwm_gdrom.VarCode

Bases: IntEnum

Variable index used in predicate triples; matches input-tuple ordering.

Build-side helpers (submodule, internal)

Build-side functions live in submodules (nwm_gdrom.metadata, nwm_gdrom.rule_parser, nwm_gdrom.rule_catalog, nwm_gdrom.timeseries, nwm_gdrom.evaluator) and are considered internal. They remain importable for ad-hoc programmatic builds, but the recommended way to produce a catalog is the nwm-gdrom CLI. The internal submodule structure may change between releases without notice.