Damage Ratio Calculation#

The damage ratio calculation module provides functionality for calculating damage ratios for structures.

Class Diagram#

classDiagram
    class BaseDamageRatio {
        +Building
        +FailureChecks
        +ComponentConfigurationIndex
        +FloodDepthIndex
        +ComponentCombination_All
        +DamageState_Flood
        +ReplacementRatio
        +ProbDS_Flood
        +update_outputs()
        +load_component_combination_all()
        +load_ProbDS_Flood()
        +load_DS_Flood()
        +load_replacement_ratio()
    }
    class ExplicitDamageRatio {
        +ExplicitDamageRatioWind
        +ResistanceValues
        +fn_damage_ratio_wind()
    }
    class ImplicitDamageRatio {
        +ImplicitDamageRatioWind
        +ImplicitDamageRatioFlood
        +fn_damage_ratio_interior_wind()
        +fn_damage_ratio_utility_wind()
        +fn_damage_ratio_flood()
    }
    class DamageRatioCalculation {
        +update_inputs_and_outputs()
        +get_building_damage_ratio()
        +get_damage_ratio_explicit()
        +get_damage_ratio_implicit()
        +get_damage_ratio_wind_implicit()
        +get_damage_ratio_wind_explicit()
        +get_damage_ratio_flood_implicit()
    }

    BaseDamageRatio <|-- ExplicitDamageRatio
    ExplicitDamageRatio <|-- ImplicitDamageRatio
    ImplicitDamageRatio <|-- DamageRatioCalculation

Base Classes#

base #

Classes:

Name	Description
`BaseDamageRatio`	A class used to represent the BaseDamageRatio.

BaseDamageRatio `dataclass` #

BaseDamageRatio(
    Building: Building,
    FailureChecks: LoadingAndFailureCheck,
    ComponentConfigurationIndex: int,
    FloodDepthIndex: int,
    datasets_loaded: bool = False,
)

A class used to represent the BaseDamageRatio.

Attributes:

Name	Type	Description
`Building`	`Building`	An instance of the Building class.
`FailureChecks`	`LoadingAndFailureCheck`	An instance of the LoadingAndFailureCheck class.
`ComponentConfigurationIndex`	`int`	An index from 0 to the number of combinations - 1.
`FloodDepthIndex`	`int`	An index from 0 to the number of flood depths - 1.
`DamageState_Flood`	`ndarray`	A numpy array representing the damage state for flood, initialized later.
`ComponentCombination_All`	`ndarray`	A numpy array representing the component combination, initialized later.
`ReplacementRatio`	`dict[int, dict[str, float]]`	A dictionary mapping integers to dictionaries, which map strings to floats, representing the replacement ratio for each component for each building type, initialized later.
`ProbDS_Flood`	`ndarray`	A numpy array representing the probability of DS for flood, initialized later.

Methods:

Name	Description
`update_outputs`	Updates the outputs of the class object by calling the `__post_init__` method.
`load_component_combination_all`	Load the component combination matrix.
`load_ProbDS_Flood`	Load the probability of DS for flood.
`load_DS_Flood`	Load the damage state for flood.
`load_replacement_ratio`	Load the replacement ratio for each component.

load_DS_Flood #

load_DS_Flood(path: str = 'Inputs/DamageState_Flood.json')

Load the damage state for flood.

This method updates the DamageState_Flood attribute of the instance by loading data from a JSON file.

Parameters:

Name	Type	Description	Default
`path`	`str`	The path to the JSON file.	`'Inputs/DamageState_Flood.json'`

This method does not return any value and updates the following class attribute:

DamageState_Flood

load_ProbDS_Flood #

load_ProbDS_Flood(path: str = 'Inputs/ProbDS_Flood.json')

Load the probability of DS for flood.

This method updates the ProbDS_Flood attribute of the instance by loading data from a JSON file.

Notes

The curves are adopted from Taggart, M. (2007), "Performance based design of woodframe structures for flooding", Colorado State University. The array is indexed [building type, flood configuration, flood depth, damage state] with shape [8, 4, 136, 6]. Only the storey count distinguishes building types, so types 1-4 share one surface and 5-8 another. Flood configuration 4 (house elevated 24 in.) is configuration 1 translated by 24 in. of depth.

Parameters:

Name	Type	Description	Default
`path`	`str`	The path to the JSON file.	`'Inputs/ProbDS_Flood.json'`

This method does not return any value and updates the following class attribute:

ProbDS_Flood

load_component_combination_all #

load_component_combination_all(
    path: str = "Inputs/ComponentCombination_All.json",
)

Load the component combination matrix.

This method updates the ComponentCombination_All attribute of the instance by loading data from a JSON file.

Parameters:

Name	Type	Description	Default
`path`	`str`	The path to the JSON file.	`'Inputs/ComponentCombination_All.json'`

This method does not return any value and updates the following class attribute:

ComponentCombination_All

load_replacement_ratio #

load_replacement_ratio(
    path: str = "Inputs/ReplacementRatio.json",
)

Load the replacement ratio for each component.

This method updates the ReplacementRatio attribute of the instance by loading data from a JSON file. The components are divided into two categories: Explicit and Implicit: * Explicit components include: [RC, RS, RWC, O, W] * Implicit components include: [Interior, Electrical, Mechanical, Plumbing]

Parameters:

Name	Type	Description	Default
`path`	`str`	The path to the JSON file.	`'Inputs/ReplacementRatio.json'`

This method does not return any value and updates the following class attribute:

ReplacementRatio

Notes

The ReplacementRatio attribute, is a dictionary mapping integers to dictionaries. These dictionaries map strings to floats, representing the replacement ratio for each component.

update_outputs #

update_outputs() -> None

Updates the outputs of the class object by calling the __post_init__ method. This method can be called when a change is made to some of the inputs of the class.

Outputs

Performs initialization or configuration side effects described above.

Returns:

Type	Description
`None`	None

Explicit Damage Ratio#

explicit_damage_ratio #

Classes:

Name	Description
`ExplicitDamageRatio`	This class represents the explicit damage ratio. It inherits from the BaseDamageRatio class.

ExplicitDamageRatio `dataclass` #

ExplicitDamageRatio(
    Building: Building,
    FailureChecks: LoadingAndFailureCheck,
    ComponentConfigurationIndex: int,
    FloodDepthIndex: int,
    datasets_loaded: bool = False,
    ExplicitDamageRatioWind: dict[str, float] = dict(),
)

Bases: BaseDamageRatio

This class represents the explicit damage ratio. It inherits from the BaseDamageRatio class.

ResistanceValues: dict[str, np.ndarray] A dictionary that holds the resistance values for each component. The keys are the component types and the values are numpy arrays of resistance values.

post_init(): This method is called after the class is instantiated. It initializes the ResistanceValues attribute and calls the fn_damage_ratio_wind() method.

fn_damage_ratio_wind(): This method calculates the damage ratio for each component. The damage ratio is calculated as the number of resistance values that are equal to 0 divided by the total number of resistance values. For RC and RS components, there is a threshold of 35%. If the damage ratio is greater than 35%, then the component is considered to be totaled. For walls, a new damage ratio calculation is used. The wall is considered to be failed if any of the four walls fail. If two walls fail, then the wall is considered to be totaled.

Methods:

Name Description

fn_damage_ratio_wind

This method calculates the damage ratio for each component. The damage ratio is calculated as the number of resistance values that are equal to 0 divided by the total number of resistance values. For RC and RS components, there is a threshold of 35%. If the damage ratio is greater than 35%, then the component is considered to be totaled. For walls, a new damage ratio calculation is used. The wall is considered to be failed if any of the four walls fail. If two walls fail, then the wall is considered to be totaled.

fn_damage_ratio_wind #

fn_damage_ratio_wind() -> dict[str, float]

This method calculates the damage ratio for each component. The damage ratio is calculated as the number of resistance values that are equal to 0 divided by the total number of resistance values. For RC and RS components, there is a threshold of 35%. If the damage ratio is greater than 35%, then the component is considered to be totaled. For walls, a new damage ratio calculation is used. The wall is considered to be failed if any of the four walls fail. If two walls fail, then the wall is considered to be totaled.

Attributes:

Name	Type	Description
`ResistanceValues`		dict[str, np.ndarray] A dictionary that holds the resistance values for each component. The keys are the component types and the values are numpy arrays of resistance values.
`ExplicitDamageRatio`		dict[str, float] A dictionary that holds the explicit damage ratio for each component. The keys are the component types and the values are the damage ratios.

Outputs: None beyond the returned value.

dict[str, float]: The explicit wind damage ratio by component.

Implicit Damage Ratio#

implicit_damage_ratio #

Classes:

Name	Description
`ImplicitDamageRatio`	This class represents the implicit damage ratio. It inherits from the ExplicitDamageRatio class.

ImplicitDamageRatio `dataclass` #

ImplicitDamageRatio(
    Building: Building,
    FailureChecks: LoadingAndFailureCheck,
    ComponentConfigurationIndex: int,
    FloodDepthIndex: int,
    datasets_loaded: bool = False,
    ExplicitDamageRatioWind: dict[str, float] = dict(),
    ImplicitDamageRatioWind: dict[str, float] = dict(),
    ImplicitDamageRatioFlood: float = float(),
    rng: object = None,
)

Bases: ExplicitDamageRatio

This class represents the implicit damage ratio. It inherits from the ExplicitDamageRatio class.

post_init(): This method is called after the class is instantiated. It calls the methods to calculate initial loads and perform initial failure check.

fn_damage_ratio_interior_wind(): This method calculates the interior damage ratio based on the damage ratios of various components of the building.

fn_damage_ratio_utility_wind(): This method calculates the utility damage ratio based on the damage ratios of various components of the building.

fn_damage_ratio_flood(): This method calculates the flood damage ratio based on the flood depth and the damage state for flood.

Methods:

Name	Description
`fn_damage_ratio_flood`	This method calculates the flood damage ratio based on the flood depth and the damage state for flood.
`fn_damage_ratio_interior_wind`	This method calculates the interior damage ratio based on the damage ratios of various components of the
`fn_damage_ratio_utility_wind`	This method calculates the utility damage ratio based on the damage ratios of various components of the building.
`fn_helper_damage_ratio_flood`	Build the cumulative flood damage-state probabilities for the current component configuration.

fn_damage_ratio_flood #

fn_damage_ratio_flood() -> float

This method calculates the flood damage ratio based on the flood depth and the damage state for flood.

Attributes:

Name	Type	Description
`FloodDepthIndex`		int The index of the flood depth.
`ProbDS_Flood`		np.ndarray The probability of the damage state for flood.
`DamageState_Flood`		np.ndarray The damage state for flood.
`ImplicitDamageRatioFlood`		float The implicit damage ratio due to flood.

Outputs: None beyond the returned value.

float: The implicit flood damage ratio.

fn_damage_ratio_interior_wind #

fn_damage_ratio_interior_wind() -> float

This method calculates the interior damage ratio based on the damage ratios of various components of the building. Reference: FPHLM Volume III, p35(52).

Attributes:

Name	Type	Description
`ExplicitDamageRatioWind`		dict[str, float] A dictionary that holds the explicit damage ratio for each component. The keys are the component types and the values are the damage ratios.
`ImplicitDamageRatioWind`		dict[str, float] A dictionary that holds the implicit damage ratio for each component due to wind. The keys are the component types and the values are the damage ratios.

Outputs: None beyond the returned value.

float: The interior implicit wind damage ratio.

fn_damage_ratio_utility_wind #

fn_damage_ratio_utility_wind() -> dict[str, float]

This method calculates the utility damage ratio based on the damage ratios of various components of the building.

Attributes:

Name	Type	Description
`ExplicitDamageRatioWind`		dict[str, float] A dictionary that holds the explicit damage ratio for each component. The keys are the component types and the values are the damage ratios.
`ImplicitDamageRatioWind`		dict[str, float] A dictionary that holds the implicit damage ratio for each component due to wind. The keys are the component types and the values are the damage ratios.

Outputs: None beyond the returned value.

dict[str, float]: The implicit wind damage ratio dictionary after utility values are updated.

fn_helper_damage_ratio_flood #

fn_helper_damage_ratio_flood() -> ndarray

Build the cumulative flood damage-state probabilities for the current component configuration.

Outputs

None beyond the returned value.

Returns:

Type	Description
`ndarray`	np.ndarray: The cumulative flood damage-state probability matrix.

Raises:

Type	Description
`IndexError`	If the component configuration or flood configuration index is out of bounds.

Main Calculation#

main #

Classes:

Name	Description
`DamageRatioCalculation`	This class represents the overall damage ratio. It inherits from the ImplicitDamageRatio class.

DamageRatioCalculation `dataclass` #

DamageRatioCalculation(
    Building: Building,
    FailureChecks: LoadingAndFailureCheck,
    ComponentConfigurationIndex: int,
    FloodDepthIndex: int,
    datasets_loaded: bool = False,
    ExplicitDamageRatioWind: dict[str, float] = dict(),
    ImplicitDamageRatioWind: dict[str, float] = dict(),
    ImplicitDamageRatioFlood: float = float(),
    rng: object = None,
)

Bases: ImplicitDamageRatio

This class represents the overall damage ratio. It inherits from the ImplicitDamageRatio class.

post_init(): This method is called after the class is instantiated. It calls the methods to load replacement ratio.

get_building_damage_ratio(): This method calculates the overall building damage ratio.

get_damage_ratio_explicit(): This method calculates the explicit damage ratio for the building.

get_damage_ratio_implicit(): This method calculates the implicit damage ratio for the building.

get_damage_ratio_wind_implicit(): This method calculates the implicit damage ratio for the building due to wind.

get_damage_ratio_wind_explicit(): This method calculates the explicit damage ratio for the building due to wind.

get_damage_ratio_flood_implicit(): This method returns the implicit damage ratio due to flood.

Methods:

Name	Description
`get_building_damage_ratio`	This method calculates the overall building damage ratio.
`get_damage_ratio_explicit`	This method calculates the explicit damage ratio for the building.
`get_damage_ratio_flood_implicit`	This method returns the implicit damage ratio due to flood.
`get_damage_ratio_implicit`	This method calculates the implicit damage ratio for the building.
`get_damage_ratio_wind_explicit`	This method calculates the explicit damage ratio for the building due to wind.
`get_damage_ratio_wind_implicit`	This method calculates the implicit damage ratio for the building due to wind.
`update_inputs_and_outputs`	Given the new inputs, it will update the outputs of the class object.

get_building_damage_ratio #

get_building_damage_ratio() -> float

This method calculates the overall building damage ratio.

Attributes:

Name	Type	Description
`ExplicitDamageRatioWind`		dict[str, float] A dictionary that holds the explicit damage ratio for each component. The keys are the component types and the values are the damage ratios.
`ImplicitDamageRatioWind`		dict[str, float] A dictionary that holds the implicit damage ratio for each component due to wind. The keys are the component types and the values are the damage ratios.
`ImplicitDamageRatioFlood`		float The implicit damage ratio due to flood.

float: The overall building damage ratio.

Outputs

None beyond the returned value.

get_damage_ratio_explicit #

get_damage_ratio_explicit() -> float

This method calculates the explicit damage ratio for the building.

Attributes:

Name	Type	Description
`ExplicitDamageRatioWind`		dict[str, float] A dictionary that holds the explicit damage ratio for each component. The keys are the component types and the values are the damage ratios.

float: The explicit damage ratio for the building.

Outputs

None beyond the returned value.

get_damage_ratio_flood_implicit #

get_damage_ratio_flood_implicit() -> float

This method returns the implicit damage ratio due to flood.

Attributes:

Name	Type	Description
`ImplicitDamageRatioFlood`		float The implicit damage ratio due to flood.

float: The implicit damage ratio due to flood.

Outputs

None beyond the returned value.

get_damage_ratio_implicit #

get_damage_ratio_implicit() -> float

This method calculates the implicit damage ratio for the building.

Attributes:

Name	Type	Description
`ImplicitDamageRatioWind`		dict[str, float] A dictionary that holds the implicit damage ratio for each component due to wind. The keys are the component types and the values are the damage ratios.
`ImplicitDamageRatioFlood`		float The implicit damage ratio due to flood.
`ReplacementRatio`		dict[str, float] A dictionary that holds the replacement ratio for each component. The keys are the component types and the values are the replacement ratios.

float: The implicit damage ratio for the building.

Outputs

None beyond the returned value.

get_damage_ratio_wind_explicit #

get_damage_ratio_wind_explicit() -> float

This method calculates the explicit damage ratio for the building due to wind.

Attributes:

Name	Type	Description
`ExplicitDamageRatioWind`		dict[str, float] A dictionary that holds the explicit damage ratio for each component. The keys are the component types and the values are the damage ratios.
`ReplacementRatio`		dict[str, float] A dictionary that holds the replacement ratio for each component. The keys are the component types and the values are the replacement ratios.

float: The explicit damage ratio for the building due to wind.

Outputs

None beyond the returned value.

get_damage_ratio_wind_implicit #

get_damage_ratio_wind_implicit() -> float

This method calculates the implicit damage ratio for the building due to wind.

Attributes:

Name	Type	Description
`ImplicitDamageRatioWind`		dict[str, float] A dictionary that holds the implicit damage ratio for each component due to wind. The keys are the component types and the values are the damage ratios.
`ReplacementRatio`		dict[str, float] A dictionary that holds the replacement ratio for each component. The keys are the component types and the values are the replacement ratios.

float: The implicit damage ratio for the building due to wind.

Outputs

None beyond the returned value.

update_inputs_and_outputs #

update_inputs_and_outputs(
    inputBuilding: Building,
    FailureChecks: LoadingAndFailureCheck,
    ComponentConfigurationIndex: int,
    FloodDepthIndex: int,
) -> None

Given the new inputs, it will update the outputs of the class object.

Parameters:

Name	Type	Description	Default
`inputBuilding`	`Building`	The input building object.	required
`FailureChecks`	`LoadingAndFailureCheck`	The input failure checks object.	required
`ComponentConfigurationIndex`	`int`	The input component configuration index.	required
`FloodDepthIndex`	`int`	The input flood depth index.	required

Outputs

This method updates the inputs and outputs of the class object by calling the __post_init__ method.

Returns:

Type	Description
`None`	None

Damage Ratio Calculation#

Class Diagram#

Base Classes#

base #

BaseDamageRatio dataclass #

load_DS_Flood #

load_ProbDS_Flood #

load_component_combination_all #

load_replacement_ratio #

update_outputs #

Explicit Damage Ratio#

explicit_damage_ratio #

ExplicitDamageRatio dataclass #

fn_damage_ratio_wind #

Implicit Damage Ratio#

implicit_damage_ratio #

ImplicitDamageRatio dataclass #

fn_damage_ratio_flood #

fn_damage_ratio_interior_wind #

fn_damage_ratio_utility_wind #

fn_helper_damage_ratio_flood #

Main Calculation#

main #

DamageRatioCalculation dataclass #

get_building_damage_ratio #

get_damage_ratio_explicit #

get_damage_ratio_flood_implicit #

get_damage_ratio_implicit #

get_damage_ratio_wind_explicit #

get_damage_ratio_wind_implicit #

update_inputs_and_outputs #

BaseDamageRatio `dataclass` #

ExplicitDamageRatio `dataclass` #

ImplicitDamageRatio `dataclass` #

DamageRatioCalculation `dataclass` #