Skip to content

Core constraints¤

For the mathematical conventions used by sampled constraints (residual norms, reduction modes, measures, and over= semantics), see Guides → Constraints and objectives.

Constraint containers¤

phydrax.constraints.FunctionalConstraint ¤

A sampled objective term defined by a residual DomainFunction.

A FunctionalConstraint represents one term in a physics/data objective. It is defined by:

  • a DomainComponent (or union) describing the integration/sampling region \(\Omega_{\text{comp}}\) and measure \(\mu\);
  • a residual operator producing a DomainFunction \(r(z)\) from the current set of field functions.

The pointwise squared residual is taken as a Frobenius norm:

\[ \rho(z) = \|r(z)\|_F^2 = \sum_{i} r_i(z)^2, \]

and the scalar loss is computed using either reduction mode.

If weight is a scalar/array-like, it is treated as a global multiplier \(w\). If weight is a DomainFunction, it is applied pointwise inside the reduction.

For reduction="mean" with scalar weight:

\[ \ell = w\,\frac{1}{\mu(\Omega_{\text{comp}})}\int_{\Omega_{\text{comp}}} \rho(z)\,d\mu(z), \]

For reduction="integral" with scalar weight:

\[ \ell = w\int_{\Omega_{\text{comp}}} \rho(z)\,d\mu(z), \]

where \(w\) is the scalar global weight.

Sampling is performed according to structure (paired blocks) or coord-separable mapping specs encoded directly in num_points.

Sampling policy is controlled by sampling_mode:

  • "resample": draw a new batch every loss evaluation (default).
  • "fixed": build one batch once (from fixed_batch or fixed_batch_key) and reuse it.
__init__(*, component: DomainComponent | DomainComponentUnion, residual: Callable[[Mapping[str, DomainFunction]], DomainFunction], num_points: SamplingNumPoints, structure: ProductStructure, dense_structure: ProductStructure | None = None, constraint_vars: Sequence[str] | None = None, sampler: str = 'latin_hypercube', weight: DomainFunction | ArrayLike = 1.0, label: str | None = None, over: str | tuple[str, ...] | None = None, reduction: Literal[mean, integral] = 'mean', sampling_mode: Literal[resample, fixed] = 'resample', fixed_batch: PointsBatch | CoordSeparableBatch | tuple[PointsBatch, ...] | None = None, fixed_batch_key: Key[Array, ''] = jr.key(0)) ¤
from_operator(*, component: DomainComponent | DomainComponentUnion, operator: Callable[..., DomainFunction], constraint_vars: str | Sequence[str], num_points: SamplingNumPoints, structure: ProductStructure, dense_structure: ProductStructure | None = None, sampler: str = 'latin_hypercube', weight: DomainFunction | ArrayLike = 1.0, label: str | None = None, over: str | tuple[str, ...] | None = None, reduction: Literal[mean, integral] = 'mean', sampling_mode: Literal[resample, fixed] = 'resample', fixed_batch: PointsBatch | CoordSeparableBatch | tuple[PointsBatch, ...] | None = None, fixed_batch_key: Key[Array, ''] = jr.key(0)) -> FunctionalConstraint classmethod ¤

Create a FunctionalConstraint from an operator mapping DomainFunctions to a residual.

This wraps an operator(u1, u2, ...) -> r into a residual callable residual(functions) -> r using the provided constraint_vars.

sample(*, key: Key[Array, ''] = jr.key(0)) -> PointsBatch | CoordSeparableBatch | tuple[PointsBatch, ...] ¤

Sample points from the configured component.

  • Returns a PointsBatch for paired sampling.
  • Returns a CoordSeparableBatch when num_points requested coord-separable sampling.
  • Returns a tuple of PointsBatch when sampling from a DomainComponentUnion.
  • In sampling_mode="fixed", this returns the same stored batch every call.
loss(functions: Mapping[str, DomainFunction], /, *, key: Key[Array, ''] = jr.key(0), batch: PointsBatch | CoordSeparableBatch | tuple[PointsBatch, ...] | None = None, **kwargs: Any) -> Array ¤

Evaluate the scalar loss for this constraint.

This samples the configured component, evaluates the residual, forms a squared Frobenius norm, and reduces via mean(...) or integral(...) depending on reduction and over.

If batch is provided, it is used directly (overriding sampling_mode).

This: 1) builds the residual DomainFunction \(r\) from functions, 2) samples points \(z_i\) on component, 3) computes \(\rho(z_i)=\|r(z_i)\|_F^2\), 4) reduces using either a mean or an integral estimator.

phydrax.constraints.PointSetConstraint ¤

A constraint evaluated on an explicit finite set of points.

Given a fixed collection of points \(\{z_i\}_{i=1}^N\) (encoded as a PointsBatch) and a residual DomainFunction \(r(z)\), the pointwise squared residual is

\[ \rho(z_i)=\|r(z_i)\|_F^2. \]

The scalar loss is then

For reduction="mean" with scalar global weight:

\[ \ell = w\,\frac{1}{N}\sum_{i=1}^N \rho(z_i), \]

For reduction="sum" with scalar global weight:

\[ \ell = w\sum_{i=1}^N \rho(z_i), \]

where \(w\) is the scalar global weight.

If weight is provided as a DomainFunction, it is evaluated pointwise on the stored points and multiplied into the per-point squared residual before reduction.

__init__(*, points: PointsBatch, residual: Callable[[Mapping[str, DomainFunction]], DomainFunction], constraint_vars: Sequence[str] | None = None, weight: DomainFunction | ArrayLike = 1.0, label: str | None = None, reduction: Literal['mean', 'sum'] = 'mean', eval_kwargs: Mapping[str, Any] | None = None) ¤

Create a point-set constraint from points and a residual callable.

from_points(*, component: DomainComponent, points: Mapping[str, ArrayLike] | ArrayLike, residual: Callable[[Mapping[str, DomainFunction]], DomainFunction], constraint_vars: Sequence[str] | None = None, weight: DomainFunction | ArrayLike = 1.0, label: str | None = None, reduction: Literal['mean', 'sum'] = 'mean', eval_kwargs: Mapping[str, Any] | None = None) -> PointSetConstraint classmethod ¤

Build a PointSetConstraint from raw point coordinates.

from_operator(*, points: PointsBatch, operator: Callable[..., DomainFunction], constraint_vars: str | Sequence[str], weight: DomainFunction | ArrayLike = 1.0, label: str | None = None, reduction: Literal['mean', 'sum'] = 'mean', eval_kwargs: Mapping[str, Any] | None = None) -> PointSetConstraint classmethod ¤

Build a PointSetConstraint from an operator applied to named fields.

loss(functions: Mapping[str, DomainFunction], /, *, key: Key[Array, ''] = jr.key(0), **kwargs: Any) -> Array ¤

Evaluate the point-set loss.

This evaluates the residual on the stored points and applies the configured reduction (mean or sum).

phydrax.constraints.IntegralEqualityConstraint ¤

A constraint enforcing an integral equality.

Given an integrand DomainFunction \(f(z)\) on a component \(\Omega_{\text{comp}}\), this enforces the scalar equality

\[ \int_{\Omega_{\text{comp}}} f(z)\,d\mu(z) = c, \]

by minimizing the squared error

\[ \ell = w\left\|\int_{\Omega_{\text{comp}}} f(z)\,d\mu(z) - c\right\|_2^2, \]

where \(w\) is weight and \(c\) is equal_to.

__init__(*, component: DomainComponent | DomainComponentUnion, integrand: Callable[[Mapping[str, DomainFunction]], DomainFunction], equal_to: ArrayLike = 0.0, num_points: SamplingNumPoints, structure: ProductStructure, dense_structure: ProductStructure | None = None, constraint_vars: Sequence[str] | None = None, sampler: str = 'latin_hypercube', weight: ArrayLike = 1.0, label: str | None = None, over: str | tuple[str, ...] | None = None) ¤

Create an integral equality constraint from an integrand callable.

loss(functions: Mapping[str, DomainFunction], /, *, key: Key[Array, ''] = jr.key(0), batch: PointsBatch | CoordSeparableBatch | tuple[PointsBatch, ...] | None = None, **kwargs: Any) -> Array ¤

Evaluate the squared integral mismatch loss.

Computes the integral estimate \(\widehat{I} \approx \int f\,d\mu\) and returns \(w\|\widehat{I}-c\|_2^2\).