Equation

Equation(name: str, parameters: list[str], eq_str: str, priority: int = 0, description: str | None = None)

A symbolic equation linking multiple parameters.

The equation is expressed as a string equal to zero. Sympy is used to solve the equation for any of its participating parameters given the others.

Parameters:

• name (str) –

  Unique name given to this equation. Used to identify the equation in a equation registry and for tracking Parameter provenance information.

• parameters (list of str) –

  The names of all parameters that participate in the equation. Names must be exactly the same as those used in the equation string. Internally they are not passed directly to SymPy's parser, i.e. are not subject to the naming restriction of SymPy identifiers.

• eq_str (str) –

  The equation string, using SymPy-compatible syntax. Parameter names must appear exactly as listed in parameters and may include spaces or other special characters, they are not directly passed on to SymPy's parser and can therefore be arbitrary strings. The expression is set to zero, so "a - b*c" represents the relationship a = b*c.

• priority (int, default: 0 ) –

  Priority used when multiple equations can solve the same target. Higher values are preferred. Defaults to 0.

Methods:

• __repr__ –

  Return a concise human-readable representation for REPL usage.

• __str__ –

  Return a human-readable, math-like rendering of the equation.

• can_solve_for –

  Check if an equation can solve for target parameter with the provided available parameters.

• solve_for –

  Solve the equation for the target parameter given the remaining parameters.

Attributes:

• description –
• expr_str –
• name –
• parameters –
• priority –

description instance-attribute

description = description

expr_str instance-attribute

expr_str = eq_str

name instance-attribute

name = name

parameters instance-attribute

parameters = parameters

priority instance-attribute

priority = priority

__repr__

__repr__() -> str

Return a concise human-readable representation for REPL usage.

__str__

__str__() -> str

Return a human-readable, math-like rendering of the equation.

can_solve_for

can_solve_for(target: str, available: dict[str, Parameter]) -> bool

Check if an equation can solve for target parameter with the provided available parameters.

Parameters:

• target (str) –

  The parameter to check.

• available (dict) –

  Known parameter values.

Returns:

• bool –

  True if the equation can solve for target, else False.

solve_for

solve_for(target: str, params: dict[str, Parameter]) -> Parameter

Solve the equation for the target parameter given the remaining parameters.

Parameters:

• target (str) –

  The parameter to solve for.

• params (dict) –

  Known parameter values, i.e. all other equation participants except the target.

Returns:

• Parameter –

  The calculated parameter including provenance information. Unit information from parameters that appear as an exponent are evaluated using their magnitudes only as pint cannot raise a quantity to a dimensioned power; their physical unit label does not flow into the result.

Raises:

• ValueError –

  If SymPy cannot find a closed-form analytical solution.

EquationRegistry

EquationRegistry()

Registry to make :class:Equation available for parameter omni-directional computation.

Each equation in the registry is registered for every parameter it involves. This way the registry can determine the select the equations suitable for calculating a parameter without knowing beforehand which equation to use.

Multiple equations can be associated with the same parameter, e.g. two different methods for computing EAC. Equation selection can be influenced by assigning per-equation priorities.

Attributes:

• _equations_by_parameter (dict[str, list[Equation]]) –

  Index from parameter name to all equations that include this parameter. Used for equation discovery when solving for a target parameter.

• _equations_by_name (dict[str, Equation]) –

  Index from unique equation name to the corresponding equation object. Used for uniqueness checks and global equation listing.

Methods:

• calculate –

  Calculate the target parameter using the available equations in the registry.

• can_calculate –

  Check if the registry has an equation to calculate the target parameter from the provided parameters.

• from_yaml –

  Create a new registry initialized from one or more YAML files.

• get_equation –

  Return the best applicable :class:Equation for the target parameter.

• list_equations –

  List registered equations as serializable summaries.

• load_from_yaml –

  Load equation definitions from one or multiple YAML files.

• register –

  Register an equation linking a set of parameters.

calculate

calculate(target: str, params: dict[str, Parameter], equation_name: str | None = None) -> Parameter

Calculate the target parameter using the available equations in the registry.

If equation_name is provided, the corresponding equation is used. Otherwise, the registry automatically selects an applicable equation based on the provided parameters.

Information on the equation used and calculation performed is recorded in the provenance attribute of the returned :class:Parameter.

Parameters:

• target (str) –

  The parameter to derive.

• params (dict) –

  Names of the known parameters and their corresponding :class:Parameter values.

• equation_name (str, default: None ) –

  Name of a specific equation to use for the calculation. If not provided, an applicable equation is selected automatically.

Returns:

• Parameter –

  The calculated parameter.

can_calculate

can_calculate(target: str, params: dict[str, Parameter]) -> bool

Check if the registry has an equation to calculate the target parameter from the provided parameters.

Parameters:

• target (str) –

  The parameter to calculate.

• params (dict) –

  Names of the known parameters and their corresponding :class:Parameter values.

Returns:

• bool –

  True if any registered formula can solve for target, else False.

from_yaml classmethod

from_yaml(yaml_files: str | Path | Sequence[str | Path]) -> EquationRegistry

Create a new registry initialized from one or more YAML files.

Parameters:

• yaml_files (str | Path | Sequence[str | Path]) –

  Path(s) to YAML file(s) containing equation definitions.

Returns:

• EquationRegistry –

  A new instance of EquationRegistry with equations loaded from the specified YAML files.

get_equation

get_equation(target: str, params: dict[str, Parameter], equation_name: str | None = None) -> Equation

Return the best applicable :class:Equation for the target parameter.

Selection priority: 1. The equation explicitly requested by equation_name 2. Higher-priority equations whose inputs are all present. 3. For equal priority, earlier registration order.

Parameters:

• target (str) –

  The name of the parameter to derive. Must match the name in the registered equation.

• params (dict) –

  Known parameter values, possible participants of the equation. Must contain all parameters except target. Used to determine eligible equations for calculating the target.

• equation_name (str, default: None ) –

  Name of a specific equation variant to use. If not provided, an applicable equation is selected automatically.

Raises:

• KeyError –

  If the equation requested by equation_name is not registered.

• ValueError –

  If there is no equation registered that allows for calculation of the target parameter with the provided params.

list_equations

list_equations(target: str | None = None) -> list[EquationSummary]

List registered equations as serializable summaries.

Parameters:

• target (str, default: None ) –

  If provided, only equations registered for this target parameter are returned.

Returns:

• list[EquationSummary] –

  Equation summaries sorted alphabetically by equation name, case-insensitive.

Raises:

• ValueError –

  If target is provided but no equation is registered for it.

load_from_yaml

load_from_yaml(yaml_files: str | Path | Sequence[str | Path], overwrite: bool = False) -> None

Load equation definitions from one or multiple YAML files.

Parameters:

• yaml_files (str | Path | Sequence[str | Path]) –

  Path(s) to YAML file(s) containing equation definitions.

• overwrite (bool, default: False ) –

  If True, allow replacing existing equations with the same name. Defaults to False.

Raises:

• ValueError –

  If the YAML content is not a list of equation definitions or if conflicting equation names are found and overwrite=False.

register

register(name: str, parameters: list[str], eq_str: str, priority: int = 0, overwrite: bool = False, description: str | None = None) -> None

Register an equation linking a set of parameters.

All the parameters are indexed to this equation for equation discovery.

Parameters:

• name (str) –

  Unique equation name to identify the equation.

• parameters (list of str) –

  All parameter names that participate in this equation.

• eq_str (str) –

  The equation as string representation equal to zero, i.e. LHS of the equation with \(LHS = 0\). The equation must contain the parameter names exactly as listed in parameters (including any spaces).

• priority (int, default: 0 ) –

  Priority used when multiple equations can solve for the same target. Higher values are preferred. Defaults to 0.

• overwrite (bool, default: False ) –

  If True and an equation with the same name already exists, the existing equation is replaced.

• description (str, default: None ) –

  Optional free-text description for documentation or context.