pystra.distributions.normal.Normal

Use it: User guide · Worked example · Theory

class Normal(name, mean, std, *, start_point=None)

Bases: Distribution

Normal distribution using direct standard normal formulas.

Parameters:

• name (str) – Name of the random variable, matching a limit-state argument.

• mean (float) – Mean in physical space.

• std (float) – Standard deviation in physical space.

• start_point (float | None) – Starting point for the design-point search. Defaults to the mean.

Methods

cdf	Evaluate the cumulative distribution function.
cdf_gradient	Analytical derivatives of the Normal CDF w.r.t.
get_name	Return the random-variable name.
isf	Inverse survival function.
jacobian	Return the diagonal x-to-u Jacobian for one-dimensional input arrays.
logcdf	Log CDF.
logpdf	Log density.
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 n samples by applying the inverse CDF to uniform random draws.
set_location	Set the stored mean to loc.
set_scale	Set the stored standard deviation to scale.
sf	Survival function.
u_to_x	Transform standard normal coordinates to physical values.
with_parameters	Rebuild an independent marginal, replacing constructor parameters.
x_to_u	Transform physical values to standard normal coordinates.

pdf(x)

Evaluate the probability density function.

Return type:

float | ndarray

cdf(x)

Evaluate the cumulative distribution function.

Return type:

float | ndarray

ppf(p)

Evaluate the inverse cumulative distribution function.

Return type:

float | ndarray

sf(x)

Survival function.

Return type:

float | ndarray

isf(q)

Inverse survival function.

Return type:

float | ndarray

logpdf(x)

Log density.

Return type:

float | ndarray

logcdf(x)

Log CDF.

Return type:

float | ndarray

logsf(x)

Log survival function.

Return type:

float | ndarray

sample(n=1000)

Draw n samples by applying the inverse CDF to uniform random draws.

Return type:

ndarray

u_to_x(u)

Transform standard normal coordinates to physical values.

Return type:

float | ndarray

x_to_u(x)

Transform physical values to standard normal coordinates.

Return type:

float | ndarray

jacobian(u, x)

Return the diagonal x-to-u Jacobian for one-dimensional input arrays.

For a normal marginal the derivative is constant, 1/std (Lemaire, eq. 4.9). The result has shape (u.size, u.size); x is unused.

Return type:

ndarray

cdf_gradient(x)

Analytical derivatives of the Normal CDF w.r.t. μ and σ.

\[ \begin{align}\begin{aligned}\frac{\partial F}{\partial \mu} = -\frac{1}{\sigma}\, \varphi\!\left(\frac{x - \mu}{\sigma}\right)\\\frac{\partial F}{\partial \sigma} = -\frac{x - \mu}{\sigma^2}\, \varphi\!\left(\frac{x - \mu}{\sigma}\right)\end{aligned}\end{align} \]

Return type:

dict[str, float | ndarray]

set_location(loc=0)

Set the stored mean to loc.

Return type:

None

set_scale(scale=1)

Set the stored standard deviation to scale.

Return type:

None

get_name()

Return the random-variable name.

Return type:

str

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

property sensitivity_params: dict[str, float]

Distribution parameters for which sensitivities are computed.

Returns a dict {param_name: current_value} listing every parameter with respect to which \(\partial\beta/\partial\theta\) should be evaluated.

The default implementation returns {"mean": μ, "std": σ}, which is appropriate for most distributions. Distributions with additional parameters of interest (e.g. the GEV shape parameter) should override this property to include them.

Fixed constructor settings such as bounds are separate from these sensitivity coordinates. Native reconstruction parameters can be another representation of the same law: sensitivity analysis perturbs the declared coordinates together, keeping other moments fixed.

Returns:

{param_name: current_value}

Return type:

dict

property start_point: float

Starting point of the design-point search; the mean by default.

property std: float

Standard deviation of the distribution.

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.