cosapp.core.numerics.basics

Functions

default_array_factory([shape, dtype])

Default factory for dataclass fields.

Classes

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

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

Bases: ABC

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.

abstract clear() → None

Clear all mathematical elements in problem.

property context: System

Context in which mathematical objects are evaluated.

Type:

cosapp.systems.System or None

copy() → Self

Copy the problem into a new one.

Returns:

The duplicated problem.

Return type:

BaseProblem

abstract extend(other: Self, copy=True, overwrite=False, **kwargs) → Self

Extend the current problem with another one.

Parameters:

• [BaseProblem] (- 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 (default), common attributes raise ValueError. If True, attributes are silently overwritten.

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

Returns:

The resulting problem

Return type:

BaseProblem

abstract is_empty() → bool

property name: str

Mathematical system name.

Type:

str

abstract to_dict() → Dict[str, Any]

Returns a JSONable representation of the problem.

Returns:

JSONable representation

Return type:

dict[str, Any]

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

Bases: BaseProblem

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_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_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.

copy(activate_targets=False) → MathematicalProblem

Copy the MathematicalProblem 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, overwrite=False, unknowns=True, equations=True, unknown_wrapper: Callable[[str], str] | None = None, residue_wrapper: Callable[[str], str] | None = None) → MathematicalProblem

Extend the current mathematical problem with another one.

Parameters:

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

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

• optional] – Should the objects be copied; 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.

• [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.

Returns:

The merged mathematical problem

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

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]

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 many unknowns as equations defined.

Raises:

ArithmeticError – If the mathematical problem is not square.

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.TimeProblem(name: str, context: System | None)

Bases: BaseProblem

Container object for time-dependent variables.

Parameters:

• name (str) – Name of the mathematical problem

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

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

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_transient(name: str, der: Any, max_time_step: Number | str = inf, max_abs_step: Number | str = inf, pulled_from: VariableReference | None = None) → TimeProblem

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

clear() → None

Clear all mathematical elements in this problem.

extend(other: TimeProblem, copy=True, overwrite=False) → TimeProblem

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

is_empty() → bool

property n_unknowns: int

Number of unknowns.

Type:

int

property rates: Dict[str, TimeDerivative]

Time derivatives computed during system evolution.

Type:

Dict[str, TimeDerivative]

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]

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

Bases: NamedTuple

property context: System

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.