Merge branch 'develop' into 401-add-buyout-model-analysis-documentati…

…on-and-example-notebook

CHANGELOG.md

@@ -12,6 +12,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Update flood input to nonstructural damage output for combined wind-wave-surge building damage [#566](https://github.com/IN-CORE/incore-docs/issues/566)
 - pyincore, pyincore-viz and pyincore-data installation instructions to include how to use libmamba solver [#375](https://github.com/IN-CORE/incore-docs/issues/375)
 - Update docs to reflect Non-structural Building Damage change [#562](https://github.com/IN-CORE/pyincore/issues/562)
+- Rename Monte Carlo failure probability analysis to Monte Carlo limit state Probability Analysis [#557](https://github.com/IN-CORE/pyincore/issues/557)
+- Add building structural damage documentation and notebook [#402](https://github.com/IN-CORE/incore-docs/issues/402)
 
 ### Added
 - Gas facility damage analysis documentation and example notebook [#387](https://github.com/IN-CORE/incore-docs/issues/387)

manual_jb/content/_toc.yml

@@ -21,6 +21,7 @@ chapters:
       - file: analyses/building_loss
       - file: analyses/building_nonstructural_dmg
       - file: analyses/buyout_decision
+      - file: analyses/building_structural_dmg
       - file: analyses/capital_shocks
       - file: analyses/combined_wind_wave_surge_building_dmg
       - file: analyses/combined_wind_wave_surge_building_loss
@@ -39,7 +40,7 @@ chapters:
       - file: analyses/joplin_cge
       - file: analyses/joplin_empirical_restoration
       - file: analyses/mean_dmg
-      - file: analyses/mc_failure_prob
+      - file: analyses/mc_limit_state_prob
       - file: analyses/multi_retrofit_optimization
       - file: analyses/nci_functionality
       - file: analyses/pipeline_dmg

manual_jb/content/analyses.md

@@ -3,33 +3,33 @@
 1. [Bridge damage](analyses/bridge_dmg.md)
 2. [Building cluster recovery](analyses/building_cluster_recovery)
 3. [Building damage](analyses/building_dmg)
-4. [Building functionality](analyses/building_func)
-5. [Building economic loss](analyses/building_loss)
+4. [Building economic loss](analyses/building_loss)
+5. [Building functionality](analyses/building_func)
 6. [Building nonstructural damage](analyses/building_nonstructural_dmg)
-7. [Buyout decision](analyses/buyout_decision)
-8. [Capital shocks](analyses/capital_shocks)
-9. [Combined wind wave surge building damage](analyses/combined_wind_wave_surge_building_dmg)
-10. [Combined wind wave surge building loss](analyses/combined_wind_wave_surge_building_loss)
-11. [Commercial building recovery](analyses/commercial_building_recovery)
-12. [Cumulative building damage](analyses/cumulative_building_dmg)
-13. [Electric power facility damage](analyses/epf_dmg)
-14. [Electric power facility repair cost](analyses/epf_repair_cost)
-15. [Electric power facility restoration](analyses/epf_restoration)
-16. [Electric power network functionality](analyses/epn_functionality)
-17. [Galveston Computable General Equilibrium (CGE)](analyses/galveston_cge.md)
-18. [Gas facility damage](analyses/gas_facility_damage)
-19. [Household-level housing sequential recovery](analyses/housing_household_recovery)
-20. [Housing recovery](analyses/housing_recovery)
-21. [Housing unit allocation](analyses/housingunitallocation)
-22. [Interdependent Network Design Problem](analyses/indp)
-23. [Joplin Computable General Equilibrium (CGE)](analyses/joplin_cge)
-24. [Joplin empirical building restoration](analyses/joplin_empirical_building_restoration)
-25. [Machine Learning Enabled Computable General Equilibrium (CGE) - Salt Lake City](analyses/ml_slc_cge.md)
-26. [Mean damage](analyses/mean_dmg)
-27. [Monte Carlo failure probability](analyses/mc_failure_prob)
-28. [Multi-objective retrofit optimization](analyses/multi_retrofit_optimization)
-29. [Network cascading interdependency functionality](analyses/nci_functionality)
-30. [Nonstructural building damage](analyses/non_structural_building_dmg)
+7. [Building structural damage](analyses/building_structural_dmg)
+8. [Buyout decision](analyses/buyout_decision)
+9. [Capital shocks](analyses/capital_shocks)
+10. [Combined wind wave surge building damage](analyses/combined_wind_wave_surge_building_dmg)
+11. [Combined wind wave surge building loss](analyses/combined_wind_wave_surge_building_loss)
+12. [Commercial building recovery](analyses/commercial_building_recovery)
+13. [Cumulative building damage](analyses/cumulative_building_dmg)
+14. [Electric power facility damage](analyses/epf_dmg)
+15. [Electric power facility repair cost](analyses/epf_repair_cost)
+16. [Electric power facility restoration](analyses/epf_restoration)
+17. [Electric power network functionality](analyses/epn_functionality)
+18. [Galveston Computable General Equilibrium (CGE)](analyses/galveston_cge.md)
+19. [Gas facility damage](analyses/gas_facility_damage)
+20. [Household-level housing sequential recovery](analyses/housing_household_recovery)
+21. [Housing recovery](analyses/housing_recovery)
+22. [Housing unit allocation](analyses/housingunitallocation)
+23. [Interdependent Network Design Problem](analyses/indp)
+24. [Joplin Computable General Equilibrium (CGE)](analyses/joplin_cge)
+25. [Joplin empirical building restoration](analyses/joplin_empirical_building_restoration)
+26. [Machine Learning Enabled Computable General Equilibrium (CGE) - Salt Lake City](analyses/ml_slc_cge.md)
+27. [Mean damage](analyses/mean_dmg)
+28. [Monte Carlo limit state probability](analyses/mc_limit_state_prob)
+29. [Multi-objective retrofit optimization](analyses/multi_retrofit_optimization)
+30. [Network cascading interdependency functionality](analyses/nci_functionality)
 31. [Pipeline damage](analyses/pipeline_dmg)
 32. [Pipeline damage with repair rate](analyses/pipeline_dmg_w_repair_rate)
 33. [Pipeline functionality](analyses/pipeline_functionality)

manual_jb/content/analyses/building_func.md

@@ -11,7 +11,7 @@ If both the nearest pole to the building and the substation where buildings belo
 functional, buildings are considered to be able to receive electric power.
 
 The outputs of this analysis are 1) a CSV file with probabilities of functionality samples 
-for direct comparison with [MC failure probability](mc_failure_prob) outputs and 
+for direct comparison with [MC limit state probability](mc_limit_state_prob) outputs and 
 2) a CSV file with probabilities of functionality.
 
 **Input parameters**

manual_jb/content/analyses/building_structural_dmg.md

@@ -0,0 +1,83 @@
+# Building structural damage
+
+**Description**
+
+This analysis computes building structural damage based on a particular hazard. Currently supported hazards are: **earthquake**, 
+**tsunami**, **tornado**, **hurricane** and **flood**.
+
+The process for computing the structural damage is similar to other parts of the built environment. First, a fragility
+is obtained based on the hazard type and attributes of the building. Based on the fragility, the hazard intensity at the 
+location of the building is computed. Using this information, the probability of exceeding each limit state is computed, 
+along with the probability of damage. For the case of an earthquake hazard, soil information can be used to
+modify the damage probabilities to include damage due to liquefaction.  
+
+The outputs of this analysis are CSV file with probabilities of damage and JSON file with information about hazard and fragilities.
+
+**Input parameters**
+
+key name | type | name | description
+--- | --- | --- | ---
+`result_name` <sup>*</sup> | `str` | Result name | Name of the result dataset.
+`hazard_type` <sup>*</sup> | `str` | Hazard type | Hazard type (earthquake, tsunami, tornado, hurricaneWindfields).
+`hazard_id` <sup>*</sup> | `str` | Hazard id | ID of the hazard from the Hazard service.
+`fragility_key` | `str` | Fragility key | Fragility key used in mapping dataset.
+`use_liquefaction` | `bool` | Liquefaction | Use liquefaction, if applicable to the hazard. <br>Default is *False*.
+`use_hazard_uncertainty` | `bool` | Uncertainty | Use hazard uncertainty. <br>Default is *False*.
+`seed` <sup>*</sup> | `int` | Seed | Initial value to seed the random number generator.
+`num_cpu` | `int` | Number of CPUs | Number of CPUs used for parallel computation. <br>Default is *1*.
+`liquefaction_geology_dataset_id` | `str` | Liquefaction id | Liquefaction geology/susceptibility dataset id. <br>If not provided, liquefaction will be ignored.
+
+**Input datasets**
+
+key name | type | name | description
+--- | --- | --- | ---
+`buildings` <sup>*</sup> | [`ergo:buildingInventoryVer4`](https://incore.ncsa.illinois.edu/semantics/api/types/ergo:buildingInventoryVer4)<br>[`ergo:buildingInventoryVer5`](https://incore.ncsa.illinois.edu/semantics/api/types/ergo:buildingInventoryVer5)<br>[`ergo:buildingInventoryVer6`](https://incore.ncsa.illinois.edu/semantics/api/types/ergo:buildingInventoryVer6)<br>[`ergo:buildingInventoryVer7`](https://incore.ncsa.illinois.edu/semantics/api/types/ergo:buildingInventoryVer7) | Building dataset |  A building dataset.
+`dfr3_mapping_set` <sup>*</sup> | [`incore:dfr3MappingSet`](https://incore.ncsa.illinois.edu/semantics/api/types/incore:dfr3MappingSet) | DFR3 Mapping Set | DFR3 Mapping Set.
+`retrofit_strategy` | [`incore:retrofitStrategy`](https://incore.ncsa.illinois.edu/semantics/api/types/incore:retrofitStrategy) | Retrofit Strategy | Building retrofit strategy that contains guid and retrofit method.
+
+**Input Hazards**
+
+key name | type                                                             | name          | description
+--- |------------------------------------------------------------------|---------------| ---
+`hazard` | `earthquake`<br>`tornado`<br>`hurricane`<br>`flood`<br>`tsunami` | Hazard | Supported hazard object for using local and remote hazards.
+
+
+**Output datasets**
+
+key name | type | parent key | name | description
+--- | --- | --- | --- | ---
+`ds_result` <sup>*</sup> | [`ergo:buildingDamageVer5`](https://incore.ncsa.illinois.edu/semantics/api/types/ergo:buildingDamageVer5) | `buildings` | Results | A dataset containing results <br>(format: CSV).
+`damage_result` <sup>*</sup> | [`incore:buildingDamageSupplement`](https://incore.ncsa.illinois.edu/semantics/api/types/incore:buildingDamageSupplement) | `buildings` | Results | Information about applied hazard value and fragility<br>(format: JSON).
+
+<small>(* required)</small>
+
+**Execution**
+
+code snippet:
+
+```
+    # Create building structural damage
+    bldg_dmg = BuildingStructuralDamage(client)
+
+    # Load input dataset
+    bldg_dmg.load_remote_input_dataset("buildings", bldg_dataset_id)
+
+    # Load fragility mapping
+    fragility_service = FragilityService(client)
+    mapping_set = MappingSet(fragility_service.get_mapping(mapping_id))
+    bldg_dmg.set_input_dataset('dfr3_mapping_set', mapping_set)
+
+    # Specify the result name
+    result_name = "memphis_bldg_dmg_result"
+
+    # Set analysis parameters
+    bldg_dmg.set_parameter("result_name", result_name)
+    bldg_dmg.set_parameter("hazard_type", hazard_type)
+    bldg_dmg.set_parameter("hazard_id", hazard_id)
+    bldg_dmg.set_parameter("num_cpu", 10)
+
+    # Run building structural damage analysis
+    bldg_dmg.run_analysis()
+```
+
+full analysis: [building_structural_dmg.ipynb](https://github.com/IN-CORE/incore-docs/blob/main/notebooks/building_structural_dmg.ipynb)

manual_jb/content/analyses/mc_failure_prob.md → manual_jb/content/analyses/mc_limit_state_prob.md

@@ -1,13 +1,13 @@
-# Monte Carlo failure probability
+# Monte Carlo Limit State Probability
 
 **Description**
 
-This analysis calculates a probability of failure using a stochastic process. Failure probability and Failure state are derived 
-using the dictionary of failed damage states in the input infrastructure dataset. Failure probability is calculated from all
-stochastic runs, failure state shows all infrastructure standings as a string of *failed* (0) and *not failed* (1) states 
+This analysis calculates a probability of limit state using a stochastic process. Limit state probability and 
+damage state are derived using the dictionary of failed damage states in the input infrastructure dataset. Limit state 
+probability is calculated from all stochastic runs, limit state shows all infrastructure standings as a string of *failed* (0) and *not failed* (1) states 
 of each individual run.
 
-The output of this analysis are two CSV files; a failure proability *base_name*_failure_probability.csv with allocated house units
+The output of this analysis are two CSV files; a limit state proability *base_name*_failure_probability.csv with allocated house units
 and  *base_name*_failure_state.csv.
 
 **Input Parameters**
@@ -33,6 +33,7 @@ key name | type | name | description
 --- | --- | --- | ---
 `failure_probability` <sup>*</sup> | [`incore:failureProbability`](https://incore.ncsa.illinois.edu/semantics/api/types/incore:failureProbability) | Results | A dataset containing failure probability results <br>(format: CSV).
 `sample_failure_state` <sup>*</sup> | [`incore:sampleFailureState`](https://incore.ncsa.illinois.edu/semantics/api/types/incore:sampleFailureState) | Results | A dataset containing failure state for each sample <br>(format: CSV).
+`sample_damage_states` <sup>*</sup> | [`incore:sampleDamageState`](https://incore.ncsa.illinois.edu/semantics/api/types/incore:sampleDamageState) | Results | A dataset containing damage state for each sample <br>(format: CSV).
 
 <small>(* required)</small>
 
@@ -42,21 +43,21 @@ code snippet:
 
 ```
     # Create instance
-    mc = MonteCarloFailureProbability(client)
+    mc = MonteCarloLimitStateProbability(client)
 
     # Load remote datasets
     mc.load_remote_input_dataset("damage", damage_id)
 
     # Set analysis parameters
-    mc.set_parameter("result_name", "mc_failure_probability")
+    mc.set_parameter("result_name", "mc_limit_state_probability")
     mc.set_parameter("num_cpu", 8)
     mc.set_parameter("num_samples", 10)
     mc.set_parameter("damage_interval_keys", ["DS_0", "DS_1", "DS_2", "DS_3"])
     mc.set_parameter("failure_state_keys", ["DS_1", "DS_2", "DS_3"])
     mc.set_parameter("seed", 1111)
 
-    # Run Monte Carlo failure
+    # Run Monte Carlo limit state analysis
     mc.run_analysis()
 ```
 
-full analysis: [mc_failure_prob.ipynb](https://github.com/IN-CORE/incore-docs/blob/main/notebooks/mc_failure_prob.ipynb)
+full analysis: [mc_limit_state_prob.ipynb](https://github.com/IN-CORE/incore-docs/blob/main/notebooks/mc_limit_state_prob.ipynb)