pystra.dependence.transformation.Transformation#

Use it: User guide · Worked example · Theory

class Transformation(transform_type=None)[source]#

Bases: object

Nataf isoprobabilistic transformation between physical space (x) and standard normal space (u).

The transformation relies on a square-root factorization of the modified correlation matrix Ro, such that Ro = inv_T @ inv_T^T. Two factorizations are available:

Cholesky (default): Ro = L @ L^T where L is lower-triangular.
SVD: Ro = (U sqrt(D)) @ (U sqrt(D))^T via the eigendecomposition of the symmetric positive-definite matrix Ro.

The two independent-normal coordinate systems differ by an orthogonal transformation. Corresponding physical design points, beta and probability agree for the same optimum, up to numerical solver error. A fixed numerical u vector generally maps to different physical points under the two factors.

The SVD factorization is generally more robust because it avoids computing the explicit inverse of a triangular factor; instead it works with the orthogonal eigenstructure of Ro. It is recommended when Ro is near-singular or poorly conditioned.

Parameters:: transform_type (str | None) – Matrix factorization, defaulting to Cholesky. Call compute() with the modified normal correlation before transforming a point.

Methods

`compute`	Compute and store the selected correlation factors.
`jacobian_u_wrt_x`	Return physical-to-reference derivatives `du[i] / dx[j]`.
`jacobian_x_wrt_u`	Return `dx[i] / du[j]` at corresponding reference/physical points.
`u_to_x`	Map an independent normal point to physical coordinates.
`x_to_u`	Map a physical point to independent standard normal coordinates.

x_to_u(x, marg)[source]#

Map a physical point to independent standard normal coordinates.

Parameters:

x (ArrayLike) – Physical point, flattened to one dimension before marginal transforms.
marg (Sequence[Distribution]) – Marginals in model variable order, matching the computed correlation.

Returns:

Independent normal coordinates in the same variable order.

Return type:

ndarray

u_to_x(u, marg)[source]#

Map an independent normal point to physical coordinates.

Parameters:

u (ArrayLike) – Reference point, flattened to one dimension before transformation.
marg (Sequence[Distribution]) – Marginals in model variable order, matching the computed correlation.

Returns:

Physical coordinates in marginal order.

Return type:

ndarray

jacobian_u_wrt_x(u, x, marg)[source]#

Return physical-to-reference derivatives du[i] / dx[j].

Parameters:

u (ArrayLike) – Corresponding reference and physical points, shape (dimension,).
x (ArrayLike) – Corresponding reference and physical points, shape (dimension,).
marg (Sequence[Distribution]) – Marginals in model variable order.

Returns:

Shape (dimension, dimension), with reference coordinates in rows and physical variables in columns, both in model order.

Return type:

ndarray

property dimension: int#: Number of coordinates; available after compute().

jacobian_x_wrt_u(u, x, marg)[source]#

Return dx[i] / du[j] at corresponding reference/physical points.

Inputs are vectors of shape (dimension,) in model variable order. The returned matrix has shape (dimension, dimension) with physical variables in rows and reference coordinates in columns. It is the inverse of jacobian_u_wrt_x() at a nonsingular point.

Return type:: ndarray

compute(Ro)[source]#

Compute and store the selected correlation factors.

Parameters:: Ro (ArrayLike) – Symmetric positive-definite modified normal correlation matrix.
Raises:: numpy.linalg.LinAlgError – If factorization or inversion fails.
Return type:: None