zoomy_core.systemmodel.roles

`zoomy_core.systemmodel.roles`#

Declared state roles of a SystemModel (depth, bed, stationary, positive, momentum, gravity), stored as sm.history records of field names. Generic code reads Roles instead of guessing from field names; a model with no declaration gets no free-surface specialisation.

Module Contents#

Classes#

Roles

Resolved roles: row indices into sm.state for depth, bed, stationary, positive and momentum rows, plus the gravity parameter name.

Functions#

`assumption_positive_names`	State fields whose symbol carries a positive or non-negative assumption. Valid on a `SystemModel` only, because the `NumericalSystemModel` strips state assumptions.
`declare_roles`	Record a role declaration on `sm` (a `history` record) and return `sm`.
`declared_role_record`	All role declarations on `sm` merged in order (later wins per key).
`resolve_roles`	Resolve the declared roles against the current state; undeclared `stationary`/`positive` fall back to structure and sign assumptions, never to names.
`derive_momentum_directions`	Momentum rows per direction as name lists, derived from the model’s `interpolate_to_3d` lift or, failing that, from the depth row’s mass-balance flux; `None` if neither applies.
`declare_free_surface_roles`	Declare the free-surface roles (depth, bed as stationary row, gravity, momentum groups, positive rows) and tag `sm` as `free_surface`.
`infer_sigma_map_roles`	Declare depth and bed from a sigma-mapped model’s relation `z = b + h*zeta`; returns True when a declaration was made.

Data#

ROLE_RECORD

API#

zoomy_core.systemmodel.roles.ROLE_RECORD#: ‘declare_roles’

class zoomy_core.systemmodel.roles.Roles#

Resolved roles: row indices into sm.state for depth, bed, stationary, positive and momentum rows, plus the gravity parameter name.

depth: Optional[int]#: None

bed: Optional[int]#: None

stationary: Tuple[int, ...]#: ()

positive: Tuple[int, ...]#: ()

momentum: Tuple[Tuple[int, ...], ...]#: ()

gravity: Optional[str]#: None

declared: bool#: False

declared_keys: frozenset#: ‘field(…)’

names: Tuple[str, ...]#: ‘field(…)’

property depth_declared: bool#: True iff the model made a statement about its depth row (possibly “none”).

property is_free_surface: bool#: True iff the model declares a depth row.

property momentum_vectors: Tuple[Tuple[int, ...], ...]#: Momentum rows grouped per vector (one tuple per moment/layer, one entry per direction); the transpose of momentum.

as_names() → dict#: The roles with row indices replaced by state names (diagnostics).

zoomy_core.systemmodel.roles.assumption_positive_names(sm) → list#: State fields whose symbol carries a positive or non-negative assumption. Valid on a SystemModel only, because the NumericalSystemModel strips state assumptions.

zoomy_core.systemmodel.roles.declare_roles(sm, *, depth=_UNSET, bed=_UNSET, stationary=_UNSET, positive=_UNSET, momentum=_UNSET, gravity=_UNSET, description: Optional[str] = None)#

Record a role declaration on sm (a history record) and return sm.

Args

depth, bed, stationary, positive, momentum, gravity: only the keys passed are recorded; None clears a scalar role.
description: label of the history record.

zoomy_core.systemmodel.roles.declared_role_record(sm) → dict#: All role declarations on sm merged in order (later wins per key).

zoomy_core.systemmodel.roles.resolve_roles(sm) → zoomy_core.systemmodel.roles.Roles#: Resolve the declared roles against the current state; undeclared stationary/positive fall back to structure and sign assumptions, never to names.

zoomy_core.systemmodel.roles.derive_momentum_directions(sm, depth=None) → Optional[list]#: Momentum rows per direction as name lists, derived from the model’s interpolate_to_3d lift or, failing that, from the depth row’s mass-balance flux; None if neither applies.

zoomy_core.systemmodel.roles.declare_free_surface_roles(sm, *, depth, bed=None, gravity=None, momentum='derive', positive='assumptions', description=None)#

Declare the free-surface roles (depth, bed as stationary row, gravity, momentum groups, positive rows) and tag sm as free_surface.

Returns

sm.

zoomy_core.systemmodel.roles.infer_sigma_map_roles(sm, model) → bool#: Declare depth and bed from a sigma-mapped model’s relation z = b + h*zeta; returns True when a declaration was made.