pystra.model.LimitState#

Use it: User guide · Worked example · Theory

class LimitState(expression=None)[source]#

Bases: object

A physical limit-state callable and its evaluation interface.

The limit-state function can be defined in two main ways:

1. Numerical differentiation (FFD): the limit-state function need only return its value at a set of evaluation points, X. In this form, the function can be either:

  1. A python lambda object;

  2. A python function object.

2. Using the Direct Differentiation Method (DDM): the limit-state function is a Python function object returning both its value and gradient vector at each of the evaluation points.

Note in both cases that each parameter (i.e. function argument) may be passed as a vector, depending on the algorithm being called.

Where a function returns a gradient vector, it is only utilized when DDM is specified.

Argument matching: the function is called as expression(**kwargs) where each keyword argument is a variable name from the StochasticModel. Arguments may therefore be declared explicitly (def lsf(X1, X2, X3): ...) or collected with **kwargs for a dimension-agnostic definition:

def lsf(**kwargs):
    return sum(v**2 for v in kwargs.values())
Parameters:

expression (Callable[..., Any] | None) – Physical response called with named variables and constants. Set an expression before evaluation. In DDM mode it also returns derivatives in random-variable order; see evaluate() for shapes.

Methods

evaluate

Evaluate physical points, with optional physical-space gradients.

get_expression

Return the stored limit-state callable.

set_expression

Replace the limit-state callable without evaluating it.
expression#

Expression of the limit-state function

get_expression()[source]#

Return the stored limit-state callable.

Return type:

Callable[..., Any] | None

set_expression(expression)[source]#

Replace the limit-state callable without evaluating it.

Return type:

None

evaluate(x, model, *, differentiation='no', ffd_parameter=1000, block_size=1000)[source]#

Evaluate physical points, with optional physical-space gradients.

Parameters:

  • x (ArrayLike) – One point of shape (n_variables,) or a batch of shape (n_samples, n_variables). Columns follow random-variable insertion order in model; constants have no column. A square batch always contains rows of points.

  • model (StochasticModel) – Named random variables and constants passed to the expression.

  • differentiation (str) – Zero gradients, forward differences, or analytic gradients returned with the expression value. Analytic gradients follow model variable order; the expression is evaluated point by point.

  • ffd_parameter (float) – Positive divisor of each marginal standard deviation for the forward-difference step, in that variable’s physical units.

  • block_size (int) – Positive maximum number of points per value-only expression call.

Return type:

tuple[float | NDArray[float64], NDArray[float64]]

Returns:

  • values (float or ndarray) – Scalar for one point, or shape (n_samples,) for a batch. Failure is the event values <= 0.

  • gradients (ndarray) – Physical derivatives, shape (n_variables,) for one point or (n_samples, n_variables) for a batch. Zero in "no" mode.

Raises:

  • ModelError – Input or expression output shapes or settings are invalid.

  • AnalysisError – Points, values or gradients are nonfinite, or the expression raises an exception (retained as the cause).

Notes

Inputs are not modified. The limit state stores no evaluation state. Numerical algorithms use a private adapter for their column batches.