pystra.model.StochasticModel

Use it: User guide · Worked example · Theory

class StochasticModel(joint_distribution=None)

Bases: object

Named random variables, constants and their dependence model.

Random variables and constants are added with add_variable(). Random-variable insertion order defines correlation rows and columns and the columns accepted by LimitState.evaluate().

Parameters:

joint_distribution (JointDistribution | None) – Initial marginals and explicit copula. Omit it to add variables individually and specify physical correlation or a copula later.

Notes

The names and marginal-distribution properties expose the stored lists; the constants property is a read-only view of stored constant values.

Methods

add_call_function	Add to the cumulative number of limit-state evaluations.
add_variable	Add a random variable or constant to the model.
get_call_function	Return the cumulative number of limit-state evaluations.
get_copula	Return the explicit copula, or None for physical Pearson input.
get_correlation	Return the stored physical Pearson matrix, or None before variables exist.
get_joint_distribution	Return marginals plus the explicit or calibrated Gaussian copula.
get_len_marginal_distributions	Return the number of random variables, excluding constants.
get_marginal_distributions	Return the stored marginal list in random-variable insertion order.
get_modified_correlation	Return the stored Nataf correlation, or None before it is computed.
get_names	Return the stored names in variable and constant insertion order.
get_variables	Return the stored mapping of random-variable names to distributions.
set_copula	Replace legacy Pearson dependence with an explicit copula.
set_correlation	Set the physical correlation matrix, replacing any copula.
set_marginal_distributions	Replace the stored marginal list without copying or reordering it.
set_modified_correlation	Store a Nataf correlation matrix without copying or validating it.
variable	Return the random variable called name.

add_variable(obj)

Add a random variable or constant to the model.

Parameters:

obj (Distribution | Constant) – The variable to add. Distributions are treated as random variables; Constants are stored separately and passed as fixed values to the limit-state function.

Raises:

ModelError – If obj is not a Distribution or Constant, or if a variable with the same name already exists. Add all random variables before explicitly setting correlation or a copula.

Return type:

None

property constants: Mapping[str, float]

Read-only mapping of constant names to values.

property names: list[str]

List of all variable and constant names, in insertion order.

property n_marg: int

Number of marginal (stochastic) distributions.

property marginal_distributions: list[Distribution]

List of marginal Distribution objects.

property correlation: ndarray | None

Correlation matrix (n × n numpy array).

Setter accepts:

CorrelationMatrix | ArrayLike

property copula: Copula | None

Explicit dependence specification, or None for legacy Pearson input.

Setter accepts:

Copula

property modified_correlation: ndarray | None

Modified (Nataf) correlation matrix Ro.

property call_function: int

Cumulative number of limit-state function evaluations.

get_variables()

Return the stored mapping of random-variable names to distributions.

Return type:

OrderedDict[str, Distribution]

variable(name)

Return the random variable called name.

Return type:

Distribution

get_names()

Return the stored names in variable and constant insertion order.

Return type:

list[str]

get_len_marginal_distributions()

Return the number of random variables, excluding constants.

Return type:

int

get_marginal_distributions()

Return the stored marginal list in random-variable insertion order.

Return type:

list[Distribution]

set_marginal_distributions(marg)

Replace the stored marginal list without copying or reordering it.

This low-level setter does not update names, the variable mapping or dependence. Callers must keep those structures consistent.

Return type:

None

set_correlation(obj)

Set the physical correlation matrix, replacing any copula.

Accepts a CorrelationMatrix, or an array that is valid as one, and raises ModelError otherwise.

Return type:

None

get_correlation()

Return the stored physical Pearson matrix, or None before variables exist.

Raises ValueError when dependence is specified by an explicit copula, which does not in general determine the physical Pearson matrix.

Return type:

ndarray | None

set_copula(copula)

Replace legacy Pearson dependence with an explicit copula.

Return type:

None

get_copula()

Return the explicit copula, or None for physical Pearson input.

Return type:

Copula | None

get_joint_distribution()

Return marginals plus the explicit or calibrated Gaussian copula.

Return type:

JointDistribution

set_modified_correlation(correlation)

Store a Nataf correlation matrix without copying or validating it.

Return type:

None

get_modified_correlation()

Return the stored Nataf correlation, or None before it is computed.

Return type:

ndarray | None

add_call_function(add)

Add to the cumulative number of limit-state evaluations.

Return type:

None

get_call_function()

Return the cumulative number of limit-state evaluations.

Return type:

int