cosapp.core.numerics.basics

Functions

default_array_factory([shape, dtype])

Default factory for dataclass fields.

Classes

MathematicalProblem(name, context)	Container object for unknowns and equations.
SolverResults(x, fun, success, message, tol, ...)	Data class for solver solution
WeakDeferredResidue(deferred, weak)

class cosapp.core.numerics.basics.MathematicalProblem(name: str, context: 'System' | None)

Bases: object

Container object for unknowns and equations.

Parameters:

• name (str) – Name of the mathematical problem

• context (cosapp.systems.System) – Context in which the mathematical problem will be evaluated.

activate_targets() → None

Activate deferred residues (targets) and incorporate them in the mathematical problem residue list. Warning: This operation is irreversible, as targets are purged.

add_equation(equation: str | Iterable[dict | str | Tuple[str, str]], name: str | None = None, reference: Number | ndarray | str = 1) → MathematicalProblem

Add residue equation.

You can add residue equation one by one or provide a list of dictionary to add multiple equation at once. The dictionary key are the arguments of this method.

Parameters:

• equation (str or Iterable of str of the kind 'lhs == rhs') – Equation or list of equations to add

• name (str, optional) – Name of the equation; default None => ‘lhs == rhs’

• reference (Number, numpy.ndarray or "norm", optional) – Reference value(s) used to normalize the equation; default is 1. If value is “norm”, actual reference value is estimated from order of magnitude.

Returns:

The modified MathematicalSystem

Return type:

MathematicalProblem

add_rate(name: str, source: Any, initial_value: Any = None) → MathematicalProblem

Add a time derivative.

Parameters:

• name (str) – Name of the new time-dependent (transient) variable

• source (Any) – Name of the variable or evaluable expression whose time derivative will be computed

Returns:

The modified MathematicalSystem

Return type:

MathematicalProblem

add_target(expression: str | Iterable[str], reference: Number | ndarray | str = 1, weak=False) → MathematicalProblem

Add deferred equation.

Parameters:

• expression (str) – Targetted expression

• reference (Number, numpy.ndarray or "norm", optional) – Reference value(s) used to normalize the (deferred) equation; default is 1. If value is “norm”, actual reference value is estimated from order of magnitude.

• weak (bool, optional) – If True, the target is disregarded if the corresponding variable is connected; default is False.

Returns:

The modified MathematicalSystem

Return type:

MathematicalProblem

add_transient(name: str, der: Any, max_time_step: Number | str = inf, max_abs_step: Number | str = inf, pulled_from: VariableReference | None = None) → MathematicalProblem

Add a time-dependent unknown.

Parameters:

• name (str) – Name of the new time-dependent (transient) variable

• der (Any) – Name of the variable or evaluable expression defining the time derivative of transient variable

• max_time_step (Number or evaluable expression (str), optional) – Maximal time step for the time integration of the transient variable; numpy.inf by default.

• max_abs_step (Number or evaluable expression compatible with transient variable, optional) – Maximum variable step admissible over one time step; numpy.inf by default.

• pulled_from (VariableReference, optional) – Original time unknown before pulling; None by default.

Returns:

The modified MathematicalSystem

Return type:

MathematicalProblem

add_unknown(name: str | Iterable[dict | str | Unknown], max_abs_step: Number = inf, max_rel_step: Number = inf, lower_bound: Number = -inf, upper_bound: Number = inf, mask: ndarray | None = None) → MathematicalProblem

Add unknown variables.

You can set variable one by one or provide a list of dictionary to set multiple variable at once. The dictionary key are the arguments of this method.

Parameters:

• name (str or Iterable of dictionary or str) – Name of the variable or list of variable to add

• max_rel_step (float, optional) – Maximal relative step by which the variable can be modified by the numerical solver; default numpy.inf

• max_abs_step (float, optional) – Maximal absolute step by which the variable can be modified by the numerical solver; default numpy.inf

• lower_bound (float, optional) – Lower bound on which the solver solution is saturated; default -numpy.inf

• upper_bound (float, optional) – Upper bound on which the solver solution is saturated; default numpy.inf

• mask (numpy.ndarray or None) – Mask of unknown values in the vector variable

Returns:

The modified MathematicalSystem

Return type:

MathematicalProblem

clear() → None

Clear all mathematical elements in this problem.

property context: 'cosapp.systems.System' | None

Context in which mathematical objects are evaluated.

Type:

cosapp.systems.System or None

copy(activate_targets=False) → MathematicalProblem

Copy the MathematicalSystem object.

Returns:

The duplicated mathematical problem.

Return type:

MathematicalProblem

property deferred_residues: Dict[str, WeakDeferredResidue]

Dict of deferred residues defined for this system.

Type:

Dict[str, WeakDeferredResidue]

extend(other: MathematicalProblem, copy=True, unknowns=True, equations=True, overwrite=False, unknown_wrapper: Callable[[str], str] | None = None, residue_wrapper: Callable[[str], str] | None = None) → MathematicalProblem

Extend the current mathematical system with the other one.

Parameters:

• [MathematicalProblem] (- other) – The other mathematical system to add

• [bool (- overwrite) – Should the objects be copied; default is True.

• optional] – Should the objects be copied; default is True.

• [bool – If False, unknowns are discarded; default is True.

• optional] – If False, unknowns are discarded; default is True.

• [bool – If False, equations are discarded; default is True.

• optional] – If False, equations are discarded; default is True.

• [bool – If False (default), common unknowns/equations raise ValueError. If True, attributes are silently overwritten.

• optional] – If False (default), common unknowns/equations raise ValueError. If True, attributes are silently overwritten.

Returns:

The resulting mathematical system

Return type:

MathematicalProblem

get_target_equations() → List[str]

get_target_residues() → Dict[str, Residue]

is_empty() → bool

property n_equations: int

Number of equations (including deferred equations).

Type:

int

property n_unknowns: int

Number of unknowns.

Type:

int

property name: str

Mathematical system name.

Type:

str

property rates: Dict[str, TimeDerivative]

Time derivatives computed during system evolution.

Type:

Dict[str, TimeDerivative]

residue_names() → Tuple[str]

Tuple[str]: Names of residues, flattened to have the same size as residue_vector().

residue_vector() → ndarray

numpy.ndarray: Residue values stacked into a vector.

property residues: Dict[str, Residue]

Residue dictionary defined in problem.

Type:

Dict[str, Residue]

property shape: Tuple[int, int]

Number of unknowns and equations.

Type:

(int, int)

static target_key(target: str) → str

Returns dict key to be used for targetted quantity target

to_dict() → Dict[str, Any]

Returns a JSONable representation of the mathematical problem.

Returns:

JSONable representation

Return type:

Dict[str, Any]

property transients: Dict[str, TimeUnknown]

Unknown time-dependent numerical features defined for this system.

Type:

Dict[str, TimeUnknown]

unknown_names() → Tuple[str]

Tuple[str]: Names of unknowns flatten to have the same size as unknown_vector().

unknown_vector()

numpy.ndarray: Unknown values stacked into a vector.

property unknowns: Dict[str, Unknown]

Unknown dictionary defined in problem.

Type:

Dict[str, Unknown]

validate() → None

Verifies that there are as much unknowns as equations defined.

Raises:

ArithmeticError – If the mathematical system is not closed.

class cosapp.core.numerics.basics.SolverResults(x: ~numpy.ndarray = <factory>, fun: ~numpy.ndarray = <factory>, success: bool = False, message: str = '', tol: float = nan, jac: ~numpy.ndarray | None = None, jac_lup: ~typing.Tuple[~numpy.ndarray, ~numpy.ndarray] | None = (None, None), jac_calls: int = 0, fres_calls: int = 0, jac_errors: dict = <factory>, trace: ~typing.List[~typing.Dict[str, ~typing.Any]] = <factory>)

Bases: object

Data class for solver solution

- x [numpy.ndarray[float]]

Solution vector.

- fun [numpy.ndarray[float]]

Values of the objective function.

- success [bool]

Whether or not the solver exited successfully.

- message [str]

Description of the cause of the termination.

- tol [float, optional]

Tolerance level; NaN if not available.

- jac [numpy.ndarray[float], optional]

Values of function Jacobian; None if not available.

- jac_lup [tuple(numpy.ndarray[float], numpy.ndarray[int]), optional]

LU decomposition of Jacobian given as tuple (LU, perm); (None, None) if not available.

- jac_calls [int]

Number of calls to the Jacobian matrix calculation.

- fres_calls [int]

Number of calls to the residues function.

- jac_errors [dict, optional]

Dictionary with singular Jacobian matrix error indexes.

- trace [list[dict[str, Any]]]

Resolution history (if requested) with the evolution of x, residues and jacobian.

fres_calls: int = 0

fun: ndarray

jac: ndarray | None = None

jac_calls: int = 0

jac_errors: dict

jac_lup: Tuple[ndarray, ndarray] | None = (None, None)

message: str = ''

success: bool = False

tol: float = nan

trace: List[Dict[str, Any]]

x: ndarray

class cosapp.core.numerics.basics.WeakDeferredResidue(deferred, weak)

Bases: NamedTuple

property context

evaluation context of residue

Type:

System

deferred: DeferredResidue

Alias for field number 0

equation() → str

Returns target equation with updated lhs value

make_residue(reference=None) → Residue

Generates the residue corresponding to equation ‘target == value(target)’

property target: str

targetted quantity

Type:

str

target_value() → Any

Evaluates and returns current value of target

property variables: Set[str]

names of variables involved in residue

Type:

Set[str]

weak: bool

Alias for field number 1

cosapp.core.numerics.basics.default_array_factory(shape=0, dtype=<class 'float'>)

Default factory for dataclass fields.