Constraints

A constraint closes a global unknown by driving a quantity computed from the state to a target. The constraints overview shows each form with an example.

The constraint declarations of a recipe, reached as spec.constraint.

galvanostatic

galvanostatic(*, name: str, target_fn: Callable, closes: str, current_fn: Callable | None = None, boundary: Callable | None = None, on: Any = None, tag: str | None = None, integrand_scale: float | None = None) -> None

Close a global by driving a computed scalar, or a boundary integral, to a target.

Pass exactly one of current_fn and boundary. With boundary, the constraint is a boundary integral over exactly one of on and tag.

Parameters:

Name	Type	Description	Default
name	str	Label of the constraint, also its key in spec.scales(integrand=...).	required
target_fn	Callable	Target protocol lambda t: ..., receiving dimensional time.	required
closes	str	Name of the global the constraint determines.	required
current_fn	Callable | None	Closure lambda q: ... returning the constrained scalar.	None
boundary	Callable | None	Closure lambda q: ... returning the integrand over the boundary.	None
on	Any	Boundary to integrate over, as a BoundarySet, a tag name, or node indices.	None
tag	str | None	Name of the boundary tag to integrate over.	None
integrand_scale	float | None	Divisor of the target, or None for the spec.scales(integrand=...) value or 1.	None

domain_integral

domain_integral(*, name: str, field: str, integrand_fn: Callable, target_fn: Callable, closes: str, integrand_scale: float | None = None) -> None

Close a global by driving the domain integral of an integrand to a target.

The integrand returns one value per node, weighted by the node's volume, or a scalar, weighted by the domain's total volume. spec.constraint.integral is the same method.

Parameters:

Name	Type	Description	Default
name	str	Label of the constraint, also its key in spec.scales(integrand=...).	required
field	str	Field whose domain supplies the volume measure.	required
integrand_fn	Callable	Closure lambda q: ... returning the integrand.	required
target_fn	Callable	Target protocol lambda t: ..., receiving dimensional time.	required
closes	str	Name of the global the constraint determines.	required
integrand_scale	float | None	Divisor of the target, or None for the spec.scales(integrand=...) value or 1.	None

reduce_residual

reduce_residual(*, name: str, field: str, reduce_fn: Callable, target_fn: Callable, closes: str, integrand_scale: float | None = None) -> None

Close a global by driving a reduction of a field's residual rows to a target.

reduce_fn receives the field's assembled rows of the right-hand side, which in the mass-matrix form are its rates.

Parameters:

Name	Type	Description	Default
name	str	Label of the constraint, also its key in spec.scales(integrand=...).	required
field	str	Field whose residual rows are reduced.	required
reduce_fn	Callable	Function lambda f: ... returning the constrained scalar.	required
target_fn	Callable	Target protocol lambda t: ..., receiving dimensional time.	required
closes	str	Name of the global the constraint determines.	required
integrand_scale	float | None	Divisor of the target, or None for the spec.scales(integrand=...) value or 1.	None

boundary_integral

boundary_integral(*, name: str, field: str, on: Any = None, tag: str | None = None, integrand_fn: Callable, target_fn: Callable, closes: str, integrand_scale: float | None = None) -> None

Close a global by driving the boundary integral of an integrand to a target.

The integrand returns a scalar, one value per boundary node, per facet, or per mesh node, each weighted by the matching boundary measure. Pass exactly one of on and tag.

Parameters:

Name	Type	Description	Default
name	str	Label of the constraint, also its key in spec.scales(integrand=...).	required
field	str	Field whose domain holds the boundary.	required
on	Any	Boundary to integrate over, as a BoundarySet, a tag name, or node indices.	None
tag	str | None	Name of the boundary tag to integrate over.	None
integrand_fn	Callable	Closure lambda q: ... returning the integrand.	required
target_fn	Callable	Target protocol lambda t: ..., receiving dimensional time.	required
closes	str	Name of the global the constraint determines.	required
integrand_scale	float | None	Divisor of the target, or None for the spec.scales(integrand=...) value or 1.	None

flux_total

flux_total(*, from_bc: str | list[str], closes: str, target_fn: Callable, name: str | None = None, integrand_scale: float | None = None) -> None

Close a global by driving the total flux through named flux conditions to a target.

The total integrates each condition's own flux closure over the facets it acts on, so the constraint and the boundary term agree.

Parameters:

Name	Type	Description	Default
from_bc	str | list[str]	The name= of a spec.bc.flux condition, or a list of names whose totals are summed.	required
closes	str	Name of the global the constraint determines.	required
target_fn	Callable	Target protocol lambda t: ..., receiving dimensional time.	required
name	str | None	Label of the constraint, or None for "flux_total_<closes>".	None
integrand_scale	float | None	Divisor of the target, or None for the spec.scales(integrand=...) value or 1.	None

---

Constraint records

These matter only when you build an EquationSet by hand.

diff_soup.problem.Constraint

Base class of the records that close a global unknown with algebraic rows.

Each record names the global it closes, and its dim property is that global's size. spec.constraint builds them from a recipe.

diff_soup.problem.GalvanostaticConstraint

Constraint record that drives a computed scalar to a target.

The row is current_fn(q, ctx, t) - target_fn(t) / integrand_scale.

Attributes:

Name	Type	Description
name	str	Label of the constraint.
closes	GlobalVariable	Global unknown the row determines.
current_fn	Callable	Function (q, ctx, t) returning the constrained scalar.
target_fn	Callable	Target as a function of dimensional time.
inputs	tuple[Any, ...]	Declared inputs of the closure, left empty by the Recipe API.
integrand_scale	float	Divisor of the target, reconciling a dimensional target with a non-dimensional quantity.

diff_soup.problem.DomainIntegralConstraint

Constraint record that drives the domain integral of an integrand to a target.

The integrand returns one value per node, weighted by the node's volume, or a scalar, weighted by the domain's total volume. Any other length raises ValueError.

Attributes:

Name	Type	Description
name	str	Label of the constraint.
closes	GlobalVariable	Global unknown the row determines.
field	Variable	Field whose domain supplies the volume measure.
integrand_fn	Callable	Function (q, ctx, t) returning the integrand.
target_fn	Callable	Target as a function of dimensional time.
inputs	tuple[Any, ...]	Declared inputs of the closure, left empty by the Recipe API.
integrand_scale	float	Divisor of the target, reconciling a dimensional target with a non-dimensional quantity.

diff_soup.problem.ReduceResidualConstraint

Constraint record that drives a reduction of a field's residual rows to a target.

The row is reduce_fn(f) - target_fn(t) / integrand_scale, where f holds the field's assembled residual rows.

Attributes:

Name	Type	Description
name	str	Label of the constraint.
closes	GlobalVariable	Global unknown the row determines.
field	Variable	Field whose residual rows are reduced.
reduce_fn	Callable	Function of those rows returning the constrained scalar.
target_fn	Callable	Target as a function of dimensional time.
inputs	tuple[Any, ...]	Declared inputs of the closure, left empty by the Recipe API.
integrand_scale	float	Divisor of the target, reconciling a dimensional target with a non-dimensional quantity.

diff_soup.problem.BoundaryIntegralConstraint

Constraint record that drives the boundary integral of an integrand to a target.

The integrand returns a scalar, one value per boundary node, per facet, or per mesh node, each weighted by the matching boundary measure. Any other length raises ValueError.

Attributes:

Name	Type	Description
name	str	Label of the constraint.
closes	GlobalVariable	Global unknown the row determines.
field	Variable	Field whose domain holds the boundary.
integrand_fn	Callable	Function (q, ctx, t) returning the integrand.
target_fn	Callable	Target as a function of dimensional time.
tag	Optional[str]	Name of a single boundary tag, used when selector is None.
selector	Optional[BoundarySet]	BoundarySet choosing the boundary.
inputs	tuple[Any, ...]	Declared inputs of the closure, left empty by the Recipe API.
integrand_scale	float	Divisor of the target, reconciling a dimensional target with a non-dimensional quantity.

diff_soup.problem.OperationalControlConstraint

Constraint record that closes a current unknown with one row of an operating table.

The active row is current - target, voltage - target, or power - target, chosen at run time by the mode and target of an operating ControlState.

Attributes:

Name	Type	Description
name	str	Label of the table.
closes	GlobalVariable	Global current unknown the row determines.
current_fn	Optional[Callable]	Function (q, ctx, t) returning the current, or None when field supplies it.
voltage_fn	Callable	Function (q, ctx, t) returning the voltage.
modes	tuple[str, ...]	Rows of the table, a subset of "current", "voltage", "power", indexed by the mode.
seed_voltage_threshold	float	Voltage magnitude above which a power mode without a current seed starts from target / V.
field	Optional[Variable]	Field whose summed residual rows give the current, or None.