pystra.loadcomb.LoadCombination#

class LoadCombination(lsf=None, dict_dist_comb=None, list_dist_resist=None, list_dist_other=None, corr=None, list_const=None, opt=None, dict_comb_cases=None, cases=None, constants=None)[source]#

Bases: object

Named load-combination reliability cases.

A load combination is represented as a transparent mapping of named reliability cases. Each case is itself a mapping of limit-state variable names to ordinary Pystra Distribution or Constant objects. This keeps the structural reliability model visible: users can inspect the variables in a case, build a StochasticModel, or use the convenience FORM runner.

Preferred explicit-case interface:

LoadCombination(
    lsf=lsf,
    cases={
        "Q1_leading": {"R": R, "G": G, "Q1": Q1max, "Q2": Q2pit},
        "Q2_leading": {"R": R, "G": G, "Q1": Q1pit, "Q2": Q2max},
    },
)

For variable actions represented by Ferry-Borges-Castanheta processes, use LoadCombination.turkstra() to generate explicit leading-action cases using Turkstra’s rule. The FBC process defines the load magnitude distributions; Turkstra’s rule defines the combination cases.

The old dict_dist_comb / dict_comb_cases constructor interface is still accepted for compatibility, but is normalized internally to explicit cases and emits a deprecation warning.

Initialise a load-combination case set.

Parameters:

  • lsf (callable, optional) – Limit-state function used by run_reliability_case() and eval_lsf_kwargs(). It is optional when the object is only used to inspect or generate cases.

  • cases (mapping, optional) – Preferred interface. Mapping of case name to variables for that case, for example {"Q1_leading": {"R": R, "Q1": Q1max}}. Values may be supplied as mappings or sequences of Pystra variables.

  • constants (mapping or sequence, optional) – Constants included in every stochastic model.

  • corr (pandas.DataFrame, optional) – Correlation matrix indexed and columned by random-variable names.

  • opt (AnalysisOptions, optional) – Options passed to the FORM analysis convenience runner.

  • dict_dist_comb (optional) – Deprecated legacy variables interface.

  • list_dist_resist (optional) – Deprecated legacy variables interface.

  • list_dist_other (optional) – Deprecated legacy variables interface.

  • list_const (optional) – Deprecated legacy variables interface.

  • dict_comb_cases (optional) – Deprecated legacy interface. These inputs are accepted for compatibility and immediately converted to explicit cases.

Methods

case

Return a shallow copy of an explicit load-combination case.

eval_lsf_kwargs

Evaluate the limit-state function with keyword arguments.

get_dict_dist_comb

Get the dictionary of distributions for all load-combination cases.

get_label

Get labels corresponding to label_type.

get_num_comb

Get the number of load-combination cases.

run_reliability_case

Create and run FORM analysis for a load-combination case.

stochastic_model

Create a StochasticModel for a load-combination case.

turkstra

Create leading-action cases using Turkstra's rule.
classmethod turkstra(variable, reference_period, lsf=None, resistance=None, permanent=None, other=None, constants=None, corr=None, opt=None, companion_duration='leading_interval')[source]#

Create leading-action cases using Turkstra’s rule.

The generated object is still a normal LoadCombination. Calling case() reveals the generated distributions for each leading-action case.

This constructor expects variable actions to be represented by FBCProcess objects. The FBC model supplies the maximum and companion distributions; Turkstra’s rule supplies the case structure: each variable action is considered as the leading action in turn, while the remaining variable actions are taken as companion values. A companion value may be a point-in-time value or, for an FBC process with shorter basic intervals, an intermediate maximum over the leading action’s interval.

Parameters:

  • variable (mapping) – Mapping of variable-action names to FBCProcess objects.

  • reference_period (float) – Duration over which the leading action maximum is taken.

  • lsf (function, optional) – Limit-state function.

  • resistance (mapping or sequence, optional) – Common variables included in every case.

  • permanent (mapping or sequence, optional) – Common variables included in every case.

  • other (mapping or sequence, optional) – Common variables included in every case.

  • constants (mapping or sequence, optional) – Constants included in every stochastic model.

  • companion_duration ({"leading_interval", "point_in_time"} or float) – Rule used for non-leading variable actions. The default takes a companion maximum over the leading action’s basic interval.

Returns:

Load-combination object containing explicit leading-action cases.

Return type:

LoadCombination

get_label(label_type)[source]#

Get labels corresponding to label_type.

get_num_comb()[source]#

Get the number of load-combination cases.

get_dict_dist_comb()[source]#

Get the dictionary of distributions for all load-combination cases.

case(lcn=None)[source]#

Return a shallow copy of an explicit load-combination case.

Parameters:

lcn (str, optional) – Case name. If omitted, the first case is returned.

Returns:

Mapping of variable name to Pystra variable for the selected case.

Return type:

OrderedDict

stochastic_model(lcn=None, **kwargs)[source]#

Create a StochasticModel for a load-combination case.

Parameters:

  • lcn (str, optional) – Case name. If omitted, the first case is used.

  • **kwargs – Variable overrides. This is mainly retained for calibration and sensitivity workflows where constants or distributions are varied.

Returns:

Model containing common constants and the selected case variables.

Return type:

StochasticModel

run_reliability_case(lcn=None, **kwargs)[source]#

Create and run FORM analysis for a load-combination case.

This is a convenience wrapper around stochastic_model() and Form. Users who want full control can call stochastic_model() and instantiate the reliability method directly.

Parameters:

  • lcn (str, optional) – Case name. If omitted, the first case is analysed.

  • **kwargs – Variable overrides passed to stochastic_model().

Returns:

Completed FORM analysis object.

Return type:

Form

eval_lsf_kwargs(set_value=0.0, set_const=None, **kwargs)[source]#

Evaluate the limit-state function with keyword arguments.

Missing stochastic variables are assigned set_value. Missing constants are assigned their stored value unless set_const is supplied.

Parameters:

  • set_value (float, optional) – Value assigned to missing random variables.

  • set_const (float, optional) – Value assigned to missing constants.

  • **kwargs – Explicit limit-state function arguments.

Returns:

Limit-state function value.

Return type:

float