pystra.distributions.lognormal.Lognormal#

Use it: User guide · Worked example · Theory

class Lognormal(name, mean=None, std=None, *, log_mean=None, log_std=None, start_point=None)[source]#

Bases: Distribution

Lognormal distribution using direct PDF and CDF formulas.

Supply either mean and std or log_mean and log_std. The two parameterizations cannot be combined.

Parameters:

name (str) – Name of the random variable, matching a limit-state argument.
mean (float | None) – Mean in physical space.
std (float | None) – Standard deviation in physical space.
log_mean (float | None) – Mean of the underlying normal variable, log(X). Supply with the other native parameters instead of mean and std.
log_std (float | None) – Standard deviation of the underlying normal variable, log(X). Supply with the other native parameters instead of mean and std.
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 Lognormal CDF w.r.t.
`get_name`	Return the random-variable name.
`isf`	Inverse survival function, accurate for small upper-tail `q`.
`jacobian`	Diagonal Jacobian of the marginal x-to-u transformation.
`logcdf`	Log CDF.
`logpdf`	Log density.
`logsf`	Log survival function.
`pdf`	Evaluate the probability density function.
`plot`	Plot the probability density function.
`ppf`	Percent-point function (inverse CDF).
`sample`	Draw random samples from the distribution.
`set_location`	Set the physical mean to loc and update the underlying normal parameters.
`set_scale`	Set the physical standard deviation to scale and update normal parameters.
`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)[source]#

Evaluate the probability density function.

Return type:: float | ndarray

logpdf(x)[source]#

Log density.

Return type:: float | ndarray

cdf(x)[source]#

Evaluate the cumulative distribution function.

Return type:: float | ndarray

sf(x)[source]#

Survival function.

Return type:: float | ndarray

logcdf(x)[source]#

Log CDF.

Return type:: float | ndarray

logsf(x)[source]#

Log survival function.

Return type:: float | ndarray

u_to_x(u)[source]#

Transform standard normal coordinates to physical values.

Return type:: float | ndarray

x_to_u(x)[source]#

Transform physical values to standard normal coordinates.

Return type:: float | ndarray

cdf_gradient(x)[source]#

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

The CDF is F(x) = Φ((ln x - λ) / ζ) where ζ = sqrt(ln(1 + (σ/μ)²)) and λ = ln(μ) - ζ²/2.

The chain rule gives:

\[\frac{\partial F}{\partial \theta} = \frac{\varphi(z)}{\zeta} \left(-\frac{\partial\lambda}{\partial\theta} - z\,\frac{\partial\zeta}{\partial\theta}\right)\]

where z = (ln x - λ) / ζ.

Return type:: dict[str, float | ndarray]

set_location(loc=0)[source]#

Set the physical mean to loc and update the underlying normal parameters.

Return type:: None

set_scale(scale=1)[source]#

Set the physical standard deviation to scale and update normal parameters.

Return type:: None

get_name()#

Return the random-variable name.

Return type:: str

isf(q)#

Inverse survival function, accurate for small upper-tail q.

Return type:: float | ndarray

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

ppf(u)#

Percent-point function (inverse CDF).

Parameters:: u (ArrayLike) – Probability value(s) in (0, 1).
Returns:: Quantile(s) in physical space.
Return type:: float | ndarray

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 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.