zoomy_core.model.basemodel

`zoomy_core.model.basemodel`#

Base class Model of the Model layer, where the user writes the physics as symbolic equations or operator methods. A Model is lifted to a SystemModel by SystemModel.from_model.

Module Contents#

Classes#

`Model`	Base class of the Model layer: named equations plus variables, parameters, boundary and initial conditions, lifted to a SystemModel by `SystemModel.from_model`. Subclasses populate equations in `derive_model` or override the operator methods (`flux`, `source`, …).
`ModelDescription`	Markdown / plain-text rendering of a `Model` returned by `Model.describe`.

Functions#

`clear_derivation_model_cache`	Drop all cached symbolic derivations.
`register_sympy_attribute`	Turn an int or list field spec into a `Zstruct` of sympy Symbols (legacy; prefer `parse_definition_to_zstruct`).
`eigenvalue_dict_to_matrix`	Flatten a sympy `eigenvals()` dict `{eigenvalue: multiplicity}` into a `ZArray`.
`default_simplify`	Default simplifier, `powsimp` with `combine='all'`.
`parse_definition_to_zstruct`	Turn an int, list, dict or `Zstruct` spec into a `Zstruct` of constrained sympy Symbols. List entries are `name` or `(name, constraint)`, dict entries `name: default` or `name: (default, constraint)`; see `SYMBOL_CONSTRAINTS`.
`merge_parameter_overrides`	Merge user `parameters=` over the declared parameter dict, keeping the declared constraint unless the override carries its own `(value, constraint)` pair.
`extract_parameter_defaults`	Numeric defaults of a parameter declaration (feeds `model.parameter_values`).

Data#

SYMBOL_CONSTRAINTS

API#

zoomy_core.model.basemodel.clear_derivation_model_cache()#: Drop all cached symbolic derivations.

zoomy_core.model.basemodel.register_sympy_attribute(definition, prefix='q')#: Turn an int or list field spec into a Zstruct of sympy Symbols (legacy; prefer parse_definition_to_zstruct).

zoomy_core.model.basemodel.eigenvalue_dict_to_matrix(eigenvals_dict)#: Flatten a sympy eigenvals() dict {eigenvalue: multiplicity} into a ZArray.

zoomy_core.model.basemodel.default_simplify(expr)#: Default simplifier, powsimp with combine='all'.

zoomy_core.model.basemodel.SYMBOL_CONSTRAINTS#: None

zoomy_core.model.basemodel.parse_definition_to_zstruct(definition, prefix='q_')#: Turn an int, list, dict or Zstruct spec into a Zstruct of constrained sympy Symbols. List entries are name or (name, constraint), dict entries name: default or name: (default, constraint); see SYMBOL_CONSTRAINTS.

zoomy_core.model.basemodel.merge_parameter_overrides(declared, overrides)#: Merge user parameters= over the declared parameter dict, keeping the declared constraint unless the override carries its own (value, constraint) pair.

zoomy_core.model.basemodel.extract_parameter_defaults(definition)#: Numeric defaults of a parameter declaration (feeds model.parameter_values).

class zoomy_core.model.basemodel.Model(init_functions=True, **params)#

Bases: zoomy_core.misc.options.Configurable, zoomy_core.model.basefunction.SymbolicRegistrar

Base class of the Model layer: named equations plus variables, parameters, boundary and initial conditions, lifted to a SystemModel by SystemModel.from_model. Subclasses populate equations in derive_model or override the operator methods (flux, source, …).

Initialization

Declare variables and parameters, run the derivation, and (unless _finalize_lazy) finalize for the SystemModel.

Args

init_functions: register the operator methods as symbolic functions during finalization.

name#: ‘String(…)’

dimension#: ‘Integer(…)’

disable_differentiation#: ‘Boolean(…)’

quadrature_order#: ‘Integer(…)’

eigenvalue_mode#: ‘Selector(…)’

equilibrium_reconstruction#: ‘Selector(…)’

variables#: ‘Parameter(…)’

aux_variables#: ‘Parameter(…)’

parameters#: ‘Parameter(…)’

boundary_conditions#: ‘ClassSelector(…)’

aux_boundary_conditions#: ‘ClassSelector(…)’

initial_conditions#: ‘ClassSelector(…)’

aux_initial_conditions#: ‘ClassSelector(…)’

property derivation#: The symbolic derivation object, built or restored lazily on first access for cacheable models.

derive_model()#: Subclass hook that populates equations via add_equation and apply; no-op on the base class.

add_equation(name, expression=None, shape=None)#

Insert an equation under name, accessible as self.<name>.

Args

shape: None for a scalar equation, else a shape or list of component labels giving one sub-equation name_i_j per index.

remove_equation(name)#: Remove the equation name.

apply(op, *, level='major', description=None)#

Broadcast an Operation, substitution dict, Relation or callable over every equation (whole-model operations are applied once).

Args

level: history level, "major" or "minor".
description: free text recorded in the history.

describe(*, show_history=False, include_minor=False)#: Return a ModelDescription that renders the equation set (LaTeX in Jupyter, plain text otherwise).

print_boundary_conditions()#: Definition of the boundary-condition function.

flux()#: Flux F(Q, Qaux, p), rank-2 ZArray (n_eq, n_dim); by default tag-extracted from the equations, else zeros.

diffusion_matrix()#: Implicitly treated diffusion tensor A(Q, Qaux, p) of shape (n_var, n_var, dim, dim) with F_diff[i, d] = sum_{j,e} A[i,j,d,e] d_e Q[j]. Default is zero; see diffusion_matrix_explicit for the explicit slot.

diffusion_matrix_explicit()#: Explicitly treated diffusion tensor with the same shape and contract as diffusion_matrix (subject to the parabolic CFL); default zero.

dflux()#: Legacy flux derivative slot; zeros.

hydrostatic_pressure()#: Hydrostatic pressure flux P(Q, Qaux, p), rank-2 (n_eq, n_dim); tag-extracted, else zeros.

nonconservative_matrix()#: Nonconservative matrix B(Q, Qaux, p), rank-3 (n_eq, n_state, n_dim); tag-extracted, else zeros.

source()#: Implicitly treated source (friction, stiff terms), length n_variables; tag-extracted, else zeros.

source_explicit()#: Explicitly treated source (non-stiff body forces), length n_variables; tag-extracted, else zeros.

mass_matrix()#: Mass matrix M[i, j] = coefficient of d_t Q[j] in equation i, extracted from time_derivative-tagged terms. Rows without a time derivative (elliptic constraints) are zero, so M is singular for such models.

residual()#: Residual slot; zeros.

interpolate()#: Interpolation slot; the state itself.

interpolate_to_3d()#: Vertical reconstruction {profile_slot: expr}, taken from the derivation byproduct, else zeros.

project_from_3d()#: Profile-to-state projection {state_field_or_slot: expr}; see interpolate_to_3d.

initial_condition()#: Initial state expression; zeros.

initial_aux_condition()#: Initial aux-state expression; zeros.

update_variables()#: Per-cell state update applied after each step; identity.

update_aux_variables()#: Per-cell aux update applied after each step; identity.

reconstruction_variables()#

Symbolic map from the state to the (primitive, well-balanced) variables the MUSCL reconstruction limits; identity by default. Override to limit primitives such as eta = h + b and u = q/h instead of (h, q).

Returns

ZArray of length n_variables.

References

Audusse et al. 2004, https://doi.org/10.1137/S1064827503431090

state_from_reconstruction()#: Symbolic inverse of reconstruction_variables, auto-derived by invert_reconstruction in terms of WB_<state> symbols; override only if sympy cannot close the inverse.

update_variables_jacobian_wrt_variables()#: Jacobian of update_variables with respect to the state.

update_aux_variables_jacobian_wrt_variables()#: Jacobian of update_aux_variables with respect to the state.

quasilinear_matrix()#: Quasilinear matrix dF/dQ + dP/dQ + B of shape (n_var, n_var, dim).

source_jacobian_wrt_variables()#: Jacobian of the implicit source with respect to the state.

source_jacobian_wrt_aux_variables()#: Jacobian of the implicit source with respect to the aux variables.

eigenvalues()#: Eigenvalues of the normal-projected quasilinear matrix, from the characteristic polynomial; a placeholder of zeros in 'numerical' mode.

left_eigenvectors()#: Left eigenvector slot; zeros.

right_eigenvectors()#: Right eigenvector slot; zeros.

eigensystem()#: Packed eigendecomposition [Lambda(n), R(n*n), L(n*n)] of the normal-projected quasilinear matrix, as opaque eigensystem kernel calls evaluated numerically in the backends.

print_model_functions(function_names=None)#: Print the definitions of the named model functions (default: flux, nonconservative_matrix, source, residual).

summarize_model(tex=False)#

Model summary with the PDE form, Q, Qaux, F, P, B, S, eigenvalues, parameters and configuration.

Args

tex: return sympy objects as LaTeX strings.

Returns

dict keyed by those names.

class zoomy_core.model.basemodel.ModelDescription(model, *, show_history=False, include_minor=False)#

Markdown / plain-text rendering of a Model returned by Model.describe.

Initialization

Store the model and the history options.

zoomy_core.model.basemodel

Contents

zoomy_core.model.basemodel#

Module Contents#

Classes#

Functions#

Data#

API#

`zoomy_core.model.basemodel`#