2.1.6. pelicun.model module¶
This module has classes and methods that define and access the model used for loss assessment.
Contents
|
Returns a constant median Decision Variable (DV) function. |
|
Returns a bounded linear median Decision Variable (DV) function. |
|
Returns a bounded multilinear median Decision Variable (DV) function. |
|
Describes the relationship between asset response and damage. |
|
Describes the relationship between damage and a decision variable. |
|
Characterizes one type of damage that corresponds to a particular DSG. |
|
A set of similar component damages that are controlled by the same EDP. |
|
A group of similar components that experience the same demands. |
|
Groups a set of similar components from a loss-assessment perspective. |
-
class
pelicun.model.FragilityFunction(EDP_limit)[source]¶ Bases:
objectDescribes the relationship between asset response and damage.
Asset response is characterized by a Demand value that represents an engineering demand parameter (EDP). Only a scalar EDP is supported currently. The damage is characterized by a set of DamageStateGroup (DSG) objects. For each DSG, the corresponding EDP limit (i.e. the EDP at which the asset is assumed to experience damage described by the DSG) is considered uncertain; hence, it is described by a random variable. The random variables that describe EDP limits for the set of DSGs are not necessarily independent.
We assume that the EDP limit will be approximated by a probability distribution for each DSG and these variables together form a multivariate distribution. Following common practice, the correlation between variables is assumed perfect by default, but the framework allows the users to explore other, more realistic options.
- Parameters
- EDP_limit: list of RandomVariable
A list of correlated random variables where each variable corresponds to an EDP limit that triggers a damage state. The number of list elements shall be equal to the number of DSGs handled by the Fragility Function (FF) and they shall be in ascending order of damage severity.
Methods
DSG_given_EDP(EDP[, force_resampling])Given an EDP, get a damage level based on the fragility function.
P_exc(EDP, DSG_ID)Return the probability of damage state exceedance.
-
P_exc(EDP, DSG_ID)[source]¶ Return the probability of damage state exceedance.
Calculate the probability of exceeding the damage corresponding to the DSG identified by the DSG_ID conditioned on a particular EDP value.
- Parameters
- EDP: float scalar or ndarray
Single EDP or numpy array of EDP values.
- DSG_ID: int
Identifies the conditioning DSG. The DSG numbering is 1-based, because zero typically corresponds to the undamaged state.
- Returns
- P_exc: float scalar or ndarray
DSG exceedance probability at the given EDP point(s).
-
DSG_given_EDP(EDP, force_resampling=False)[source]¶ Given an EDP, get a damage level based on the fragility function.
The damage is evaluated by sampling the joint distribution of fragilities corresponding to all possible damage levels and checking which damage level the given EDP falls into. This approach allows for efficient damage state evaluation for a large number of EDP realizations.
- Parameters
- EDP: float scalar or ndarray or Series
Single EDP, or numpy array or pandas Series of EDP values.
- force_resampling: bool, optional, default: False
If True, the probability distribution is resampled before evaluating the damage for each EDP. This is not recommended if the fragility functions are correlated with other sources of uncertainty because those variables will also be resampled in this case. If False, which is the default approach, we assume that the random variable has already been sampled and the number of samples greater or equal to the number of EDP values.
- Returns
- DSG_ID: Series
Identifies the damage that corresponds to the given EDP. A DSG_ID of 0 means no damage.
-
pelicun.model.prep_constant_median_DV(median)[source]¶ Returns a constant median Decision Variable (DV) function.
- Parameters
- median: float
The median DV for a consequence function with fixed median.
- Returns
- f: callable
A function that returns the constant median DV for all component quantities.
-
pelicun.model.prep_bounded_linear_median_DV(median_max, median_min, quantity_lower, quantity_upper)[source]¶ Returns a bounded linear median Decision Variable (DV) function.
The median DV equals the min and max values when the quantity is outside of the prescribed quantity bounds. When the quantity is within the bounds, the returned median is calculated by a linear function with a negative slope between max and min values.
- Parameters
- median_max: float, optional
- median_min: float, optional
Minimum and maximum limits that define the bounded_linear median DV function.
- quantity_lower: float, optional
- quantity_upper: float, optional
Lower and upper bounds of component quantity that define the bounded_linear median DV function.
- Returns
- f: callable
A function that returns the median DV given the quantity of damaged components.
-
pelicun.model.prep_bounded_multilinear_median_DV(medians, quantities)[source]¶ Returns a bounded multilinear median Decision Variable (DV) function.
The median DV equals the min and max values when the quantity is outside of the prescribed quantity bounds. When the quantity is within the bounds, the returned median is calculated by linear interpolation.
- Parameters
- medians: ndarray
Series of values that define the y coordinates of the multilinear DV function.
- quantities: ndarray
Series of values that define the component quantities corresponding to the series of medians and serving as the x coordinates of the multilinear DV function.
- Returns
- f: callable
A function that returns the median DV given the quantity of damaged components.
-
class
pelicun.model.ConsequenceFunction(DV_median, DV_distribution)[source]¶ Bases:
objectDescribes the relationship between damage and a decision variable.
Indicates the distribution of a quantified Decision Variable (DV) conditioned on a component, an element, or the system reaching a given damage state (DS). DV can be reconstruction cost, repair time, casualties, injuries, etc. Its distribution might depend on the quantity of damaged components.
- Parameters
- DV_median: callable
Describes the median DV as an f(quantity) function of the total quantity of damaged components. Use the prep_constant_median_DV, and prep_bounded_linear_median_DV helper functions to conveniently prescribe the typical FEMA P-58 functions.
- DV_distribution: RandomVariable
A random variable that characterizes the uncertainty in the DV. The distribution shall be normalized by the median DV (i.e. the RV is expected to have a unit median). Truncation can be used to prescribe lower and upper limits for the DV, such as the (0,1) domain needed for red tag evaluation.
Methods
median([quantity])Return the value of the median DV.
sample_unit_DV([quantity, sample_size, …])Sample the decision variable quantity per component unit.
-
median(quantity=None)[source]¶ Return the value of the median DV.
The median DV corresponds to the component damage state (DS). If the damage consequence depends on the quantity of damaged components, the total quantity of damaged components shall be specified through the quantity parameter.
- Parameters
- quantity: float scalar or ndarray, optional
Total quantity of damaged components that determines the magnitude of median DV. Not needed for consequence functions with a fixed median DV.
- Returns
- median: float scalar or ndarray
A single scalar for fixed median; a scalar or an array depending on the shape of the quantity parameter for bounded_linear median.
-
sample_unit_DV(quantity=None, sample_size=1, force_resampling=False)[source]¶ Sample the decision variable quantity per component unit.
The Unit Decision Variable (UDV) corresponds to the component Damage State (DS). It shall be multiplied by the quantity of damaged components to get the total DV that corresponds to the quantity of the damaged components in the asset. If the DV depends on the total quantity of damaged components, that value shall be specified through the quantity parameter.
- Parameters
- quantity: float scalar, ndarray or Series, optional, default: None
Total quantity of damaged components that determines the magnitude of median DV. Not needed for consequence functions with a fixed median DV.
- sample_size: int, optional, default: 1
Number of samples drawn from the DV distribution. The default value yields one sample. If quantity is an array with more than one element, the sample_size parameter is ignored.
- force_resampling: bool, optional, default: False
If True, the DV distribution (and the corresponding RV if there are correlations) is resampled even if there are samples already available. This is not recommended if the DV distribution is correlated with other sources of uncertainty because those variables will also be resampled in this case. If False, which is the default approach, we assume that the random variable has already been sampled and the number of samples is greater or equal to the number of samples requested.
- Returns
- unit_DV: float scalar or ndarray
Unit DV samples.
-
class
pelicun.model.DamageState(ID, weight=1.0, description='', repair_cost_CF=None, reconstruction_time_CF=None, injuries_CF_set=None, affected_area=0.0, red_tag_CF=None)[source]¶ Bases:
objectCharacterizes one type of damage that corresponds to a particular DSG.
The occurrence of damage is evaluated at the DSG. The DS describes one of the possibly several types of damages that belong to the same DSG and the consequences of such damage.
- Parameters
- ID:int
- weight: float, optional, default: 1.0
Describes the probability of DS occurrence, conditioned on the damage being in the DSG linked to this DS. This information is only used for DSGs with multiple DS corresponding to them. The weights of the set of DS shall sum up to 1.0 if they are mutually exclusive. When the set of DS occur simultaneously, the sum of weights typically exceeds 1.0.
- description: str, optional
Provides a short description of the damage state.
- affected_area: float, optional, default: 0.
Defines the area over which life safety hazards from this DS exist.
- repair_cost_CF: ConsequenceFunction, optional
A consequence function that describes the cost necessary to restore the component to its pre-disaster condition.
- reconstruction_time_CF: ConsequenceFunction, optional
A consequence function that describes the time, necessary to repair the damaged component to its pre-disaster condition.
- injuries_CF_set: ConsequenceFunction array, optional
A set of consequence functions; each describes the number of people expected to experience injury of a particular severity when the component is in this DS. Any number of injury-levels can be considered.
- red_tag_CF: ConsequenceFunction, optional
A consequence function that describes the proportion of components (within a Performance Group) that needs to be damaged to trigger an unsafe placard (i.e. red tag) for the building during post-disaster inspection.
- Attributes
descriptionReturn the damage description.
weightReturn the weight of DS among the set of damage states in the DSG.
Methods
red_tag_dmg_limit([sample_size])Sample the red tag consequence function and return the proportion of components that needs to be damaged to trigger a red tag.
unit_injuries([severity_level, sample_size])Sample the injury consequence function that corresponds to the specified level of severity and return the injuries per component unit.
unit_reconstruction_time([quantity, sample_size])Sample the reconstruction time distribution and return the unit reconstruction times.
unit_repair_cost([quantity, sample_size])Sample the repair cost distribution and return the unit repair costs.
-
property
description¶ Return the damage description.
-
property
weight¶ Return the weight of DS among the set of damage states in the DSG.
-
unit_repair_cost(quantity=None, sample_size=1, **kwargs)[source]¶ Sample the repair cost distribution and return the unit repair costs.
The unit repair costs shall be multiplied by the quantity of damaged components to get the total repair costs for the components in this DS.
- Parameters
- quantity: float scalar, ndarray or Series, optional, default: None
Total quantity of damaged components that determines the median repair cost. Not used for repair cost models with fixed median.
- sample_size: int, optional, default: 1
Number of samples drawn from the repair cost distribution. The default value yields one sample.
- Returns
- unit_repair_cost: float scalar or ndarray
Unit repair cost samples.
-
unit_reconstruction_time(quantity=None, sample_size=1, **kwargs)[source]¶ Sample the reconstruction time distribution and return the unit reconstruction times.
The unit reconstruction times shall be multiplied by the quantity of damaged components to get the total reconstruction time for the components in this DS.
- Parameters
- quantity: float scalar, ndarray or Series, optional, default: None
Total quantity of damaged components that determines the magnitude of median reconstruction time. Not used for reconstruction time models with fixed median.
- sample_size: int, optional, default: 1
Number of samples drawn from the reconstruction time distribution. The default value yields one sample.
- Returns
- unit_reconstruction_time: float scalar or ndarray
Unit reconstruction time samples.
-
red_tag_dmg_limit(sample_size=1, **kwargs)[source]¶ Sample the red tag consequence function and return the proportion of components that needs to be damaged to trigger a red tag.
The red tag consequence function is assumed to have a fixed median value that does not depend on the quantity of damaged components.
- Parameters
- sample_size: int, optional, default: 1
Number of samples drawn from the red tag consequence distribution. The default value yields one sample.
- Returns
- red_tag_trigger: float scalar or ndarray
Samples of damaged component proportions that trigger a red tag.
-
unit_injuries(severity_level=0, sample_size=1, **kwargs)[source]¶ Sample the injury consequence function that corresponds to the specified level of severity and return the injuries per component unit.
The injury consequence function is assumed to have a fixed median value that does not depend on the quantity of damaged components (i.e. the number of injuries per component unit does not change with the quantity of components.)
- Parameters
- severity_level: int, optional, default: 1
Identifies which injury consequence to sample. The indexing of severity levels is zero-based.
- sample_size: int, optional, default: 1
Number of samples drawn from the injury consequence distribution. The default value yields one sample.
- Returns
- unit_injuries: float scalar or ndarray
Unit injury samples.
-
class
pelicun.model.DamageStateGroup(ID, DS_set, DS_set_kind)[source]¶ Bases:
objectA set of similar component damages that are controlled by the same EDP.
Damages are described in detail by the set of Damage State objects. Damages in a DSG are assumed to occur at the same EDP magnitude. A Damage State Group (DSG) might have only a single DS in the simplest case.
- Parameters
- ID: int
- DS_set: DamageState array
- DS_set_kind: {‘single’, ‘mutually_exclusive’, ‘simultaneous’}
Specifies the relationship among the DS in the set. When only one DS is defined, use the ‘single’ option to improve calculation efficiency. When multiple DS are present, the ‘mutually_exclusive’ option assumes that the occurrence of one DS precludes the occurrence of another DS. In such a case, the weights of the DS in the set shall sum up to 1.0. In a ‘simultaneous’ case the DS are independent and unrelated. Hence, they can occur at the same time and at least one of them has to occur.
-
class
pelicun.model.PerformanceGroup(ID, location, quantity, fragility_functions, DSG_set, csg_weights=[1.0], direction=0)[source]¶ Bases:
objectA group of similar components that experience the same demands.
FEMA P-58: Performance Groups (PGs) are a sub-categorization of fragility groups. A performance group is a subset of fragility group components that are subjected to the same demands (e.g. story drift, floor acceleration, etc.).
In buildings, most performance groups shall be organized by story level. There is no need to separate performance groups by direction, because the direction of components within a group can be specified during definition, and it will be taken into consideration in the analysis.
- Parameters
- ID: int
- location: int
Identifies the location of the components that belong to the PG. In a building, location shall typically refer to the story of the building. The location assigned to each PG shall be in agreement with the locations assigned to the Demand objects.
- quantity: RandomVariable
Specifies the quantity of components that belong to this PG. Uncertainty in component quantities is considered by assigning a random variable to this property.
- fragility_functions: FragilityFunction list
Each fragility function describes the probability that the damage in a subset of components will meet or exceed the damages described by each damage state group in the DSG_set. Each is a multi-dimensional function if there is more than one DSG. The number of functions shall match the number of subsets defined by the csg_weights parameter.
- DSG_set: DamageStateGroup array
A set of sequential Damage State Groups that describe the plausible set of damage states of the components in the FG.
- csg_weights: float ndarray, optional, default: [1.0]
Identifies subgroups of components within a PG, each of which have perfectly correlated behavior. Correlation between the damage and consequences among subgroups is controlled by the correlation parameter of the FragilityGroup that the PG belongs to. Note that if the components are assumed to have perfectly correlated behavior at the PG level, assigning several subgroups to the PG is unnecessary. This input shall be a list of weights that are applied to the quantity of components to define the amount of components in each subgroup. The sum of assigned weights shall be 1.0.
- directions: int ndarray, optional, default: [0]
Identifies the direction of each subgroup of components within the PG. The number of directions shall be identical to the number of csg_weights assigned. In buildings, directions typically correspond to the orientation of components in plane. Hence, using 0 or 1 to identify ‘X’ or ‘Y’ is recommended. These directions shall be in agreement with the directions assigned to Demand objects.
Methods
P_exc(EDP, DSG_ID)This is a convenience function that provides a shortcut to fragility_function.P_exc().
-
P_exc(EDP, DSG_ID)[source]¶ This is a convenience function that provides a shortcut to fragility_function.P_exc(). It calculates the exceedance probability of a given DSG conditioned on the provided EDP value(s). The fragility functions assigned to the first subset are used for this calculation because P_exc shall be identical among subsets.
- Parameters
- EDP: float scalar or ndarray
Single EDP or numpy array of EDP values.
- DSG_ID: int
Identifies the DSG of interest.
- Returns
- P_exc: float scalar or ndarray
Exceedance probability of the given DSG at the EDP point(s).
-
class
pelicun.model.FragilityGroup(ID, demand_type, performance_groups, directional=True, correlation=True, demand_location_offset=0, incomplete=False, name='', description='', unit='ea')[source]¶ Bases:
objectGroups a set of similar components from a loss-assessment perspective.
Characterizes a set of structural or non-structural components that have similar construction characteristics, similar potential modes of damage, similar probability of incurring those modes of damage, and similar potential consequences resulting from their damage.
- Parameters
- ID: int
- demand_type: {‘PID’, ‘PFA’, ‘PSD’, ‘PSA’, ‘ePGA’, ‘PGD’}
The type of Engineering Demand Parameter (EDP) that controls the damage of the components in the FG. See Demand for acronym descriptions.
- performance_groups: PerformanceGroup array
A list of performance groups that contain the components characterized by the FG.
- directional: bool, optional, default: True
Determines whether the components in the FG are sensitive to the directionality of the EDP.
- correlation: bool, optional, default: True
Determines whether the components within a Performance Group (PG) will have correlated or uncorrelated damage. Correlated damage means that all components will have the same damage state. In the uncorrelated case, each component in the performance group will have its damage state evaluated independently. Correlated damage reduces the required computational effort for the calculation. Incorrect correlation modeling will only slightly affect the mean estimates, but might significantly change the dispersion of results.
- demand_location_offset: int, optional, default: 0
Indicates if the location for the demand shall be different from the location of the components. Damage to components of the ceiling, for example, is controlled by demands on the floor above the one that the components belong to. This can be indicated by setting the demand_location_offset to 1 for such an FG.
- incomplete: bool, optional, default: False
Indicates that the FG information is not complete and corresponding results shall be treated with caution.
- name: str, optional, default: ‘’
Provides a short description of the fragility group.
- description: str, optional, default: ‘’
Provides a detailed description of the fragility group.
- Attributes
descriptionReturn the fragility group description.
nameReturn the name of the fragility group.
-
property
description¶ Return the fragility group description.
-
property
name¶ Return the name of the fragility group.