pystra.distributions.maximum.Maximum#

Use it: User guide · Worked example · Theory

class Maximum(name, parent, N, *, start_point=None)[source]#

Bases: Distribution

Distribution of maxima from a supplied parent distribution.

Moments are computed deterministically by Gauss-Hermite quadrature of the quantile function in standard normal space, with exact identities for Frechet and uniform parents. Successive rules are compared at relative tolerance 1e-7 and absolute tolerance 1e-9 in standardized units; a miss warns and keeps the finest estimate, which serves for start points and finite-difference steps. Nonfinite moments raise ModelError.

Parameters:

name (str) – Name of the random variable, matching a limit-state argument.
parent (Distribution) – Parent distribution whose CDF is raised to the power N.
N (float) – Finite exponent, at least 1. Integer N represents N independent observations.
start_point (float | None) – Starting point for the design-point search. Defaults to the mean.

Methods

`cdf`	Evaluate the cumulative distribution function.
`cdf_gradient`	Derivatives of the CDF w.r.t.
`get_name`	Return the random-variable name.
`isf`	Inverse survival function.
`jacobian`	Diagonal Jacobian of the marginal x-to-u transformation.
`logcdf`	Log CDF, `N` times the parent's.
`logpdf`	Log density, `log N + log f(x) + (N - 1) log F(x)`.
`logsf`	Log survival function.
`pdf`	Evaluate the probability density function.
`plot`	Plot the probability density function.
`ppf`	Evaluate the inverse cumulative distribution function.
`sample`	Draw random samples from the distribution.
`set_location`	Updating the parent distribution location parameter.
`set_scale`	Updating the parent distribution scale parameter.
`sf`	Survival function `1 - F(x)**N`.
`u_to_x`	Transform from standard normal space to physical space.
`update_stats`	Recompute moments after an in-place change to the constructor inputs.
`with_parameters`	Rebuild an independent marginal, replacing constructor parameters.
`x_to_u`	Transform from physical space to standard normal space.

property sensitivity_params: dict[str, float]#: No generic moment perturbation; replace the constructor inputs.

pdf(x)[source]#

Evaluate the probability density function.

Return type:: float | ndarray

cdf(x)[source]#

Evaluate the cumulative distribution function.

Return type:: float | ndarray

ppf(p)[source]#

Evaluate the inverse cumulative distribution function.

Return type:: float | ndarray

isf(q)[source]#

Inverse survival function.

Return type:: float | ndarray

logpdf(x)[source]#

Log density, log N + log f(x) + (N - 1) log F(x).

Return type:: float | ndarray

logcdf(x)[source]#

Log CDF, N times the parent’s.

Return type:: float | ndarray

sf(x)[source]#

Survival function 1 - F(x)**N.

Return type:: float | ndarray

logsf(x)[source]#

Log survival function.

Return type:: float | ndarray

set_location(loc=0)[source]#

Updating the parent distribution location parameter.

Return type:: None

set_scale(scale=1)[source]#

Updating the parent distribution scale parameter.

Return type:: None

update_stats()[source]#

Recompute moments after an in-place change to the constructor inputs.

Return type:: None

cdf_gradient(x)#

Derivatives of the CDF w.r.t. each sensitivity parameter.

Returns ∂F_X(x)/∂θ for every parameter listed by sensitivity_params. The base-class implementation uses central finite differences on the CDF via with_parameters().

Before computing derivatives, a reconstruction sanity check verifies that with_parameters() (with no overrides) reproduces the current distribution. This catches both constructor failures (e.g. composite distributions) and silent mismatches (e.g. distributions whose extra constructor arguments are not stored in parameters).

Subclasses may override this with analytical expressions for better accuracy and performance (see Normal and Lognormal).

Parameters:: x (ArrayLike) – Evaluation point in physical space.
Returns:: {param_name: ∂F/∂θ} for each parameter in sensitivity_params.
Return type:: dict[str, float | ndarray]
Raises:: ValueError – If the distribution cannot be faithfully reconstructed by with_parameters().

get_name()#

Return the random-variable name.

Return type:: str

jacobian(u, x)#

Diagonal Jacobian of the marginal x-to-u transformation.

Returns a diagonal matrix J where the diagonal entry is f_X(x) / phi(u) (Lemaire, eq. 4.9). This is assembled into the full Jacobian by the Transformation class. The ratio is formed from log densities where either density underflows.

Parameters:

u (ArrayLike) – Value(s) in standard normal space.
x (ArrayLike) – Corresponding value(s) in physical space.

Returns:

Diagonal Jacobian matrix of shape (n, n) where n is the length of the input arrays.

Return type:

ndarray

property mean: float#: Mean of the distribution.

property parameters: Mapping[str, object]#

Read-only snapshot of keyword arguments that rebuild this marginal.

type(dist)(**dist.parameters) reproduces its law, name and start point. Built-ins use native parameters where moment fitting could lose precision. Nested marginals and SciPy objects are independent copies, so mutating a snapshot never changes the source distribution. Custom marginals may override this property with their complete constructor mapping. Sensitivity coordinates are specified separately by sensitivity_params.

plot(ax=None, **kwargs)#

Plot the probability density function.

Parameters:

ax (Axes | None) – Axes to plot on. A new figure is created if None.
**kwargs (Any) – Additional keyword arguments forwarded to ax.plot().

Returns:

The axes containing the plot.

Return type:

Axes

sample(n=1000)#

Draw random samples from the distribution.

Uses inverse-transform sampling via ppf.

Parameters:: n (int) – Number of samples (default 1000).
Returns:: Array of shape (n,) with sampled values.
Return type:: ndarray

property start_point: float#: Starting point of the design-point search; the mean by default.

property std: float#: Standard deviation of the distribution.

u_to_x(u)#

Transform from standard normal space to physical space.

Applies the marginal Nataf mapping x = F^{-1}(Phi(u)). Above u = 3 it is evaluated as Fbar^{-1}(Phi(-u)), so the probability passed on is never rounded towards one; far into either tail the log-probability is used (see _tail_quantiles()).

Parameters:: u (ArrayLike) – Value(s) in standard normal (u) space.
Returns:: Corresponding value(s) in physical (x) space.
Return type:: float | ndarray

with_parameters(**changes)#

Rebuild an independent marginal, replacing constructor parameters.

Parameters:

**changes (object) – Replacements for keys of parameters. Built-ins supporting moment sensitivities also accept mean and std; supplying either switches to moment construction, holding the other moment and fixed bounds/shape constant. Native coordinates and moments cannot be supplied together. The start point remains unchanged unless explicitly replaced (None selects the new mean).

Returns:

Independent instance of the same type, including nested marginals. An empty replacement reproduces the distribution.

Return type:

Self

Raises:

TypeError – A replacement is unknown, or mixes moments and native coordinates.
ModelError, ValueError – Constructor parameters do not define a valid distribution.

x_to_u(x)#

Transform from physical space to standard normal space.

Applies the marginal Nataf mapping u = Phi^{-1}(F(x)), as u = -Phi^{-1}(Fbar(x)) above u = 3, with log probabilities where these underflow.

Parameters:: x (ArrayLike) – Value(s) in physical (x) space.
Returns:: Corresponding value(s) in standard normal (u) space.
Return type:: float | ndarray