Losses

A loss function scalarizes the deviation between the current equilibrium state and the goals into the objective that an optimizer minimizes.

Loss

losses

Loss

Loss(*args: Error | Regularizer, name: str | None = None)

A scalar objective summing error and regularization terms.

Parameters:

• args (Error | Regularizer, default: () ) –

  The error and regularization terms to sum; they are sorted into the two groups by type.

• name (str | None, default: None ) –

  The name of the loss. If None, defaults to the class name.

terms_error property writable

terms_error: list[Error]

The error terms in the loss function.

terms_regularization property writable

terms_regularization: list[Regularizer]

The regularization terms in the loss function.

terms property

terms: list[Error | Regularizer]

The error and regularization terms of the loss function.

__call__

__call__(params: EquilibriumParametersState, model: EquilibriumModel, structure: EquilibriumStructure) -> Float[Array, '']

Evaluate the loss by solving for equilibrium and summing all terms.

Parameters:

• params (EquilibriumParametersState) –

  The parameters defining the equilibrium problem.

• model (EquilibriumModel) –

  The equilibrium model that computes the equilibrium state.

• structure (EquilibriumStructure) –

  The structure that provides the connectivity.

Returns:

• loss ( Float[Array, ''] ) –

  The scalar loss, the sum of the error terms evaluated on the equilibrium state and the regularization terms evaluated on the parameters.

evaluate

evaluate(datastructure: FDNetwork | FDMesh, sparse: bool = True) -> Float[Array, '']

Evaluate the loss directly on a datastructure, without an optimization.

Parameters:

• datastructure (FDNetwork | FDMesh) –

  The network or mesh to read the equilibrium state from. Its geometry is used as-is; no form-finding is run.

• sparse (bool, default: True ) –

  If True, assemble the equilibrium state with the sparse model.

Returns:

• loss ( Float[Array, ''] ) –

  The scalar loss, the sum of the error terms evaluated on the datastructure's equilibrium state and the regularization terms evaluated on its parameters.

Notes

Builds the equilibrium state once and reuses it across every error term and regularizer. Error terms evaluate their raw goals as singletons, so the loss works before constrained_fdm has grouped them into collections.

number_of_goals

number_of_goals() -> int

The total number of individual goals for all error terms in the loss.

number_of_regularizers

number_of_regularizers() -> int

The total number of regularization terms in the loss.

number_of_collections

number_of_collections() -> int

The total number of goal collections for all error terms in the loss.

---

Error terms

losses

Error

Error(goals: Sequence[Goal], alpha: float = 1.0, name: str | None = None, *args, **kwargs)

The base class for an error term in a loss function.

Parameters:

• goals (Sequence[Goal]) –

  The goals whose gap from their target this term penalizes.

• alpha (float, default: 1.0 ) –

  A scalar weight scaling the whole term in the loss.

• name (str | None, default: None ) –

  The name of the error term. If None, defaults to the class name.

Notes

Goals are grouped into collections in collections: one collection per goal type, its leaves carrying a leading element axis. A goal maps one element to one error, so the term vmaps that per-element error over a collection, sums the mapped result, and aggregates one such sum per collection via errors.

error staticmethod

error(gstate: GoalState) -> Float[Array, '']

The error of a single goal collection.

Parameters:

• gstate (GoalState) –

  The evaluated goal state to measure.

Returns:

• error ( Float[Array, ''] ) –

  The error for the collection.

errors

errors(errors: Float[Array, errors]) -> Float[Array, '']

Aggregate the per-collection errors into a scalar.

Parameters:

• errors (Float[Array, errors]) –

  The error of each goal collection.

Returns:

• error ( Float[Array, ''] ) –

  The aggregate error; the base term returns the sum.

__call__

__call__(eqstate: EquilibriumState, structure: EquilibriumStructure) -> Float[Array, '']

Evaluate the error term against an equilibrium state.

Parameters:

• eqstate (EquilibriumState) –

  The equilibrium state to evaluate the goals on.

• structure (EquilibriumStructure) –

  The structure whose element ordering resolves the goals' indices.

Returns:

• error ( Float[Array, ''] ) –

  The aggregated error scaled by alpha.

Notes

A goal maps one element to one goal state, so each collection is reduced the equinox way: vmap the per-element error over the collection's leading axis and sum the mapped scalars, exactly as one maps any module over a batch. The weight, one scalar per element, broadcasts against the prediction at each element, so no rank alignment is needed. This is the same per-element reduction as evaluate_state, over the batched collections rather than the raw goals.

evaluate

evaluate(datastructure: FDNetwork | FDMesh, sparse: bool = True) -> Float[Array, '']

Evaluate the error term directly on a datastructure, without an optimization.

Parameters:

• datastructure (FDNetwork | FDMesh) –

  The network or mesh to read the equilibrium state from. Its geometry is used as-is; no form-finding is run.

• sparse (bool, default: True ) –

  If True, assemble the equilibrium state with the sparse model.

Returns:

• error ( Float[Array, ''] ) –

  The aggregated error scaled by alpha.

Notes

Evaluates the term's raw goals one by one, rather than the collections the optimizer batches them into, so it works before constrained_fdm has grouped them. The goal count is unchanged, so a mean-style term divides by the same number of goals it would during an optimization.

evaluate_state

evaluate_state(eqstate: EquilibriumState, structure: EquilibriumStructure) -> Float[Array, '']

Evaluate the error term's raw goals on a precomputed equilibrium state.

Parameters:

• eqstate (EquilibriumState) –

  The equilibrium state to evaluate the goals on.

• structure (EquilibriumStructure) –

  The structure whose element ordering resolves the goals' indices.

Returns:

• error ( Float[Array, ''] ) –

  The aggregated error scaled by alpha.

Notes

The state-consuming core shared by evaluate and Loss.evaluate. It evaluates the term's raw goals as singletons rather than the collections the optimizer batches them into. A lone goal's __call__ already returns an unbatched state whose scalar weight broadcasts against the prediction, and the error kernels sum over every axis, so a raw goal state feeds them directly without the collection's (elements, features) formatting.

number_of_goals

number_of_goals() -> int

The total number of individual goals in this error term.

number_of_collections

number_of_collections() -> int

The total number of goal collections in this error term.

PredictionError

PredictionError(goals: Sequence[Goal], alpha: float = 1.0, name: str | None = None, *args, **kwargs)

The prediction error.

You lose when you get too much of something.

Notes

Penalizes the magnitude of the predicted quantity directly rather than its gap from a target, useful for minimizing quantities such as load path.

error staticmethod

error(gstate: GoalState) -> Float[Array, '']

The weighted sum of the predictions in a collection.

Parameters:

• gstate (GoalState) –

  The evaluated goal state to measure.

Returns:

• error ( Float[Array, ''] ) –

  The weighted sum of the predictions.

MeanPredictionError

MeanPredictionError(goals: Sequence[Goal], alpha: float = 1.0, name: str | None = None, *args, **kwargs)

The mean prediction error.

Average out all errors because no single error is important enough.

errors

errors(errors: Float[Array, errors]) -> Float[Array, '']

The mean of the per-collection prediction errors.

Parameters:

• errors (Float[Array, errors]) –

  The error of each goal collection.

Returns:

• error ( Float[Array, ''] ) –

  The summed error divided by the number of goals.

SquaredError

SquaredError(goals: Sequence[Goal], alpha: float = 1.0, name: str | None = None, *args, **kwargs)

The canonical squared error.

It measures the weighted squared L2 gap between each goal's prediction and target.

error staticmethod

error(gstate: GoalState) -> Float[Array, '']

The weighted sum of squared prediction-target gaps in a collection.

Parameters:

• gstate (GoalState) –

  The evaluated goal state to measure.

Returns:

• error ( Float[Array, ''] ) –

  The weighted squared error.

MeanSquaredError

MeanSquaredError(goals: Sequence[Goal], alpha: float = 1.0, name: str | None = None, *args, **kwargs)

The seminal mean squared error.

Average out all errors because no single error is important enough.

errors

errors(errors: Float[Array, errors]) -> Float[Array, '']

The mean of the per-collection squared errors.

Parameters:

• errors (Float[Array, errors]) –

  The error of each goal collection.

Returns:

• error ( Float[Array, ''] ) –

  The summed error divided by the number of goals.

RootMeanSquaredError

RootMeanSquaredError(goals: Sequence[Goal], alpha: float = 1.0, name: str | None = None, *args, **kwargs)

The square root of the mean squared error.

errors

errors(errors: Float[Array, errors]) -> Float[Array, '']

The root of the mean squared error.

Parameters:

• errors (Float[Array, errors]) –

  The error of each goal collection.

Returns:

• error ( Float[Array, ''] ) –

  The square root of the mean squared error.

AbsoluteError

AbsoluteError(goals: Sequence[Goal], alpha: float = 1.0, name: str | None = None, *args, **kwargs)

The canonical absolute error.

It measures the weighted absolute gap between each goal's prediction and target.

error staticmethod

error(gstate: GoalState) -> Float[Array, '']

The weighted sum of absolute prediction-target gaps in a collection.

Parameters:

• gstate (GoalState) –

  The evaluated goal state to measure.

Returns:

• error ( Float[Array, ''] ) –

  The weighted absolute error.

MeanAbsoluteError

MeanAbsoluteError(goals: Sequence[Goal], alpha: float = 1.0, name: str | None = None, *args, **kwargs)

The canonical mean absolute error.

errors

errors(errors: Float[Array, errors]) -> Float[Array, '']

The mean of the per-collection absolute errors.

Parameters:

• errors (Float[Array, errors]) –

  The error of each goal collection.

Returns:

• error ( Float[Array, ''] ) –

  The summed error divided by the number of goals.

LogMaxError

LogMaxError(goals: Sequence[Goal], alpha: float = 1.0, name: str | None = None, *args, **kwargs)

A soft one-sided barrier penalizing goal predictions above their target.

Notes

Only positive overshoots past the target are penalized, through log1p of the violation, so the error is zero while the prediction stays at or below the target. Useful for soft upper-bound constraints.

error staticmethod

error(gstate: GoalState) -> Float[Array, '']

The weighted log-barrier penalty on target overshoot in a collection.

Parameters:

• gstate (GoalState) –

  The evaluated goal state to measure.

Returns:

• error ( Float[Array, ''] ) –

  The weighted log1p penalty on the positive prediction-target gap.

---

Regularizers

losses

Regularizer

Regularizer(alpha: float, name: str | None = None)

The base class for a loss term that penalizes the model parameters.

Parameters:

• alpha (float) –

  A scalar weight scaling the regularization term in the loss.

• name (str | None, default: None ) –

  The name of the regularizer. If None, defaults to the class name.

__call__

__call__(params: EquilibriumParametersState) -> Float[Array, '']

Evaluate the regularization penalty on the parameters.

Parameters:

• params (EquilibriumParametersState) –

  The parameter state to penalize.

Returns:

• penalty ( Float[Array, ''] ) –

  The scalar regularization penalty.

L2Regularizer

L2Regularizer(alpha: float, name: str | None = None)

A penalty on the squared force densities.

Notes

Computes alpha times the sum of squared force densities, the squared L2 norm rather than the norm itself.

__call__

__call__(params: EquilibriumParametersState) -> Float[Array, '']

The weighted sum of squared force densities.

Parameters:

• params (EquilibriumParametersState) –

  The parameter state whose force densities are penalized.

Returns:

• penalty ( Float[Array, ''] ) –

  alpha times the sum of squared force densities.