zoomy_core.model.derivation.model

The derivation Model: ordered coordinates, parameters, scalar/vector equations, the unknown registry Q/Qaux and the operation history. It is the entry point of the derivation chain Model -> SystemModel (SystemModel.from_model).

Module Contents

Classes

VectorEquation	Vector equation: ordered component Equations with named-axis (.x/.y/.z) and index access. Components are also flattened into the model’s _equations as <name>_<axis>.
MomentFamily	Indexed family of moment rows produced by resolve_modes (model.mass[l], model.momentum.x[l]). Rows are also flattened into the model’s _equations as <base>_<mode>.
FieldHandle	Handle on a model field (typically the sigma-mapped applied form) exposing .head, .expr, .at(value) and call syntax. Sympifiable; handles live on Model.functions only.
Model	Computational-graph spine of a symbolic derivation: coordinates, parameters, equations, unknowns (Q declared, Qaux derived) and history. Operations are applied with model.apply(op); the result is lifted to a SystemModel.
ResolveModes	Tracked-operation form of resolve_modes; it does not close the basis brackets.

Functions

resolve_modes

Moment-axis shape bump: specialise the abstract Galerkin test index of a row to concrete modes and group the rows as a MomentFamily (scalar (1,) -> (N+1,), vector component (n,) -> (n, N+1)).

API

class zoomy_core.model.derivation.model.VectorEquation(name, shape, components)

Vector equation: ordered component Equations with named-axis (.x/.y/.z) and index access. Components are also flattened into the model’s _equations as <name>_<axis>.

Initialization

Wrap the component equations of a vector row of length 1, 2 or 3.

property components

List of component equations.

replace_axis(axis, replacement)

Swap the component at axis (name or index), e.g. for a MomentFamily after a moment-axis bump.

apply(*args, **kwargs)

Broadcast an operation across every component.

describe(strip_args=False)

Markdown description of the components.

class zoomy_core.model.derivation.model.MomentFamily(name, modes, components, index=None)

Indexed family of moment rows produced by resolve_modes (model.mass[l], model.momentum.x[l]). Rows are also flattened into the model’s _equations as <base>_<mode>.

Initialization

Store the family name, mode list, per-mode rows and the symbolic index.

property components

List of moment rows.

apply(*args, **kwargs)

Broadcast an operation across every moment row.

describe(strip_args=False)

Markdown description of the moment rows.

class zoomy_core.model.derivation.model.FieldHandle(applied)

Handle on a model field (typically the sigma-mapped applied form) exposing .head, .expr, .at(value) and call syntax. Sympifiable; handles live on Model.functions only.

Initialization

Wrap the applied field.

property head

Function class of the field.

property expr

Applied field expression.

at(value)

Field evaluated at value in its last (vertical) argument.

class zoomy_core.model.derivation.model.Model(coords=(_coords.t, _coords.x, _coords.z), parameters=None, name='model')

Computational-graph spine of a symbolic derivation: coordinates, parameters, equations, unknowns (Q declared, Qaux derived) and history. Operations are applied with model.apply(op); the result is lifted to a SystemModel.

Initialization

Create an empty model over coords (default t, x, z) with positive-Symbol parameters given as {name: default}.

parameter(name, default=0.0)

Return the positive Symbol for parameter name, creating it with default if it is not yet declared.

property coords

Ordered tuple of coordinates.

property vertical

Vertical coordinate: the mapped zeta after a PDETransformation, else the last coordinate.

property horizontal

Horizontal coordinates: all but time and vertical.

declare_state(*fields)

Add fields to Q as primary (state) unknowns; used by equation blueprints.

declare_closure(*fields)

Record fields as closure variables (present in the equations, routed to Qaux unless substituted).

add_equation(name, shape_or_expr=None, expr=None, *, group='model', _refresh=True)

Register a scalar equation, a vector equation (name, shape, [exprs]), a blueprint, or an oriented relation such as a KinematicBC (stored as an assumption).

Args

• group: "model" for the final PDE system or "aux" for auxiliary relations that never reach the SystemModel.

Returns

The Equation, VectorEquation or stored relation.

remove(name)

Remove a named equation, vector row or stored assumption; returns self.

apply(op, **kwargs)

Apply an operation: system_level ops once to the model, whole_model_op ops via apply_to_model, all others broadcast over every scalar equation.

property Q

Declared unknowns as a Zstruct.

property Qaux

Derived auxiliaries: every field in the equations that is not in Q, not a coordinate and not a parameter.

explicit_state()

One applied field per time-derivative row of the primary equations, with modal families flattened; the state vector for SystemModel.from_model.

property functions

Registry of every field by its original name as a FieldHandle (bulk form, vertical argument normalised to zeta after the sigma map).

move_to_aux(*fields)

Demote fields (given data such as the bed b) from Q to Qaux even if they stay in a primary equation; returns self.

register_group(slot, index, relation)

Record relation as component index of function group slot (e.g. 'interpolate', 'project'), parsed into the matching SystemModel slot by from_model.

Args

• relation: oriented relation, Equation, FieldHandle or bare sympy expression; only its right-hand side is stored.

Returns

self

redeclare_unknown(old_field, new_fields, rename_key=False)

Transfer unknown status from old_field to new_fields, keeping the logical key (decoration) or renaming it to the new family (rename_key=True).

register_index(name)

Mint and register a Galerkin test/moment index Symbol; the same name returns the same symbol and clashes with modal indices raise.

modal_index(target)

Modal-mode index assigned to a field or coefficient family by separation_of_variables.

modal_basis(target)

Basis registered with the field’s separation-of-variables expansion, or None.

describe(strip_args=False, show='model', show_tags=False, show_history=False, max_log_level=5)

Markdown description of the model: parameters, Q and equations; show selects "model", "aux" or "all" rows.

zoomy_core.model.derivation.model.resolve_modes(equation, *, index, modes, test_weight=None, basis_cls=None, level=None, var=None, resolver=None)

Moment-axis shape bump: specialise the abstract Galerkin test index of a row to concrete modes and group the rows as a MomentFamily (scalar (1,) -> (N+1,), vector component (n,) -> (n, N+1)).

Args

• equation: row carrying the abstract index (model.mass or model.momentum.x).

• modes: concrete moment indices.

• test_weight, basis_cls, level, var: if given, each row is also closed by closure.Resolve.

• resolver: custom per-mode closer (row, test_weight_k, k) used instead of Resolve.

Returns

The MomentFamily.

class zoomy_core.model.derivation.model.ResolveModes(index, modes, name='resolve_modes')

Bases: zoomy_core.model.operations.Operation

Tracked-operation form of resolve_modes; it does not close the basis brackets.

Initialization

Store the abstract index and the concrete modes.

apply_to_equation(equation)

Bump the equation via resolve_modes.