Skip to content

Commit 6d557bf

Browse files
zsarnoczayzsarnoczay
authored
Merge pull request #38 from zsarnoczay/prep_for_v2_release
Prep for v2 release
2 parents 3526033 + fc138aa commit 6d557bf

9 files changed

Lines changed: 306 additions & 28 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
---
11+
12+
## [2.0.0] - 2025-08-15
13+
14+
This release marks a major milestone for the Damage and Loss Model Library and the beginning of a more frequent and structured release schedule. After more than two years of continuous development, `v2.0.0` introduces a significantly improved data schema, a host of new models, and a documentation system for model discovery.
15+
16+
For a comprehensive overview of the library in its current state, please see our completely revamped README.md.
17+
18+
### Changed
19+
- **BREAKING:** The core data schema for models has been updated and rationalized to better support a wider range of hazards and asset types. Older custom tools that relied on the `v1.0.0` schema will need to be updated.
20+
- Renamed `loss_repair.csv` files to `consequence_repair.csv` for consistency
21+
- Updated loss measure units to use ratios instead of percentages for Hazus models
22+
- Improved data validation and multilinear CDF handling in model generation scripts
23+
- **Code Quality:** Comprehensive code formatting and linting improvements using Ruff, enhancing maintainability and consistency across the entire codebase.
24+
25+
### Added
26+
- **Model Library Expansion:**
27+
- **Hurricane Models:**
28+
- Added complete building models for **Hazus Hurricane v5.1** (both original and coupled versions)
29+
- Added **SimCenter Hurricane Wind Component Library** with comprehensive wind pressure components from peer-reviewed research
30+
- **Flood Models:**
31+
- Added complete building models for **Hazus Flood v6.1**
32+
- **Seismic Infrastructure Models:**
33+
- Added **Hazus Seismic Power Network** models (v5.1)
34+
- Added **Hazus Seismic Water Network** models (v6.1)
35+
- Added **Hazus Seismic Transportation Network** models (v5.1)
36+
- Updated **Hazus Seismic Building** models to v6.1 (in addition to existing v5.1)
37+
- Added **Hazus Seismic Building Subassembly** models (v5.1)
38+
- **Documentation System:**
39+
- Added an automated documentation website built with Sphinx that allows for easy discovery and exploration of all models in the library
40+
- Implemented custom Sphinx extensions for automatic generation of model documentation with fragility and consequence curves
41+
- Added caching system for efficient documentation builds
42+
- **Metadata Enhancements:**
43+
- Added rich metadata, including clear citations, for every model to ensure proper credit and academic integrity
44+
- Enhanced model descriptions and parameter documentation
45+
- **Configuration Files:**
46+
- Added Pelicun configuration files for all model libraries to facilitate integration with the Pelicun damage and loss assessment framework
47+
48+
### Fixed
49+
- Multiple bug fixes in Hazus model generation scripts and data processing
50+
- Corrected fragility parameters and damage state definitions across various model libraries
51+
- Fixed issues with multilinear CDF data validation and processing
52+
- Resolved metadata formatting and JSON structure issues
53+
54+
---
55+
56+
## [1.0.0] - 2023-03-01
57+
58+
### Added
59+
- Initial Release
60+
- FEMA P-58 2nd edition
61+
- Hazus Earthquake Model for Buildings

‎LICENSE‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
The Damage and Loss Model Library is licensed under the following copyright and
2+
license:
3+
4+
BSD 3-Clause License
5+
6+
Copyright (c) 2023, Leland Stanford Junior University
7+
Copyright (c) 2023, The Regents of the University of California
8+
9+
All rights reserved.
10+
11+
Redistribution and use in source and binary forms, with or without
12+
modification, are permitted provided that the following conditions are met:
13+
14+
* Redistributions of source code must retain the above copyright notice, this
15+
list of conditions and the following disclaimer.
16+
17+
* Redistributions in binary form must reproduce the above copyright notice,
18+
this list of conditions and the following disclaimer in the documentation
19+
and/or other materials provided with the distribution.
20+
21+
* Neither the name of the copyright holder nor the names of its
22+
contributors may be used to endorse or promote products derived from
23+
this software without specific prior written permission.
24+
25+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
26+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
28+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
29+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
30+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
31+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
32+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
33+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
34+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

‎README.md‎

Lines changed: 55 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,71 @@
1-
# DB Damage and Loss
21

3-
### SimCenter Damage and Loss DataBase
2+
# Damage and Loss Model Library (DLML)
43

5-
This database provides damage and loss model parameters intended for a broad range of applications in Natural Hazards Engineering. In this initial release, it is seeded with collections of models for earthquake damage and loss assessment. Future updates will add models to support studies focused on hurricane wind, storm surge, flood, and tsunami impacts.
4+
[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
65

7-
The model parameters are stored using the damage and loss model schema introduced in SimCenter's Pelicun framework. Models are grouped into collections; each collection is stored in a pair of CSV and JSON files. The CSV files contain model parameters that are required for the calculations, while the JSON files contain corresponding metadata that describe the components and their damage states. The `DB` folder stores the available collections; and, for the sake of transparency and reproducibility, the `data_sources` folder provides the raw data that was used to generate the data in `DB`.
6+
A curated, open-source repository of standardized model parameters and metadata for quantifying the impact of natural hazard events on the built environment.
87

9-
Researchers and practitioners are encouraged to comment on the available data and provide feedback on what additional data they would like to see in the database. Those who have relevant data available are encouraged to contact us and contribute to the database.
8+
---
109

10+
### About This Library
1111

12-
### ChangeLog
12+
The Damage and Loss Model Library (DLML) is a project from the NHERI SimCenter designed to address a critical gap in natural hazards engineering: the lack of a centralized, standardized, and easy-to-use repository for damage and loss models. This library provides the essential data—model parameters, descriptive metadata, and configuration files—that power natural hazard risk assessment simulations.
1313

14-
#### v1.0
14+
This `v2.0.0` release represents a significant evolution of the project, featuring an improved data schema, a host of new and updated models, and a documentation system.
1515

16-
- Initial release, includes the following collections:
17-
+ FEMA P-58 2nd edition
18-
+ Hazus Earthquake Model for Buildings
19-
+ Hazus Earthquake Model for Transportation
16+
**Key Features:**
17+
* **Standardized Data Schema:** A robust yet flexible schema for organizing models by hazard, asset type, and resolution, making it easy to use data and supporting new contributions.
18+
* **Rich Metadata & Clear Citations:** Every model is paired with detailed metadata and a clear citation to the original source.
19+
* **A Broad & Inclusive Collection:** We feature a growing collection of models, from large-scale industry standards like **FEMA P-58** and **FEMA Hazus** to peer-reviewed models from the broader research community. Our goal is to provide a home for all high-quality damage and loss models.
20+
* **Automated Documentation:** The metadata and parameters are used to automatically generate a user-friendly documentation website, complete with model descriptions, parameter tables, and plots of fragility and consequence functions.
2021

22+
---
2123

22-
### Documentation
24+
### Three Ways to Use This Library
2325

24-
Every model available in the database is documented under Damage and Loss DB in: https://nheri-simcenter.github.io/PBE-Documentation/
26+
There are three primary ways to interact with the DLML, depending on your needs.
2527

26-
### Acknowledgement
28+
#### 1. Discover and Explore Models
2729

28-
This material is based upon work supported by the National Science Foundation under Grants No. 1621843 and No. 2131111. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.
30+
The best way to get started is by exploring our documentation website. It provides a searchable, lightweight interface to discover all available models, view their parameters, and understand their assumptions.
31+
32+
[**➡️ Visit the Documentation Website**](https://nheri-simcenter.github.io/DamageAndLossModelLibrary/)
33+
34+
#### 2. Perform Calculations with Pelicun
35+
36+
For performing damage and loss calculations, we recommend using **Pelicun**, the SimCenter's open-source simulation engine or SimCenter's **PBE** and **R2D** desktop applications that utilize Pelicun in the background. Pelicun is designed to seamlessly use the models from this library as its inputs. This library is bundled with Pelicun, so all models are available automatically after installation.
37+
38+
[**➡️ Learn More About Pelicun**](https://github.com/NHERI-SimCenter/Pelicun)
39+
40+
#### 3. Work with the Raw Data
41+
42+
You can also work directly with the raw data files in this repository. The library is structured in a clear hierarchy of `hazard/asset_type/resolution/methodology`. Within each methodology, **model parameters are stored in standardized CSV files** (e.g., for fragility, loss, or consequences) and metadata in corresponding JSON files.
43+
44+
To get a local copy, clone the repository:
45+
```bash
46+
git clone [https://github.com/NHERI-SimCenter/DamageAndLossModelLibrary.git](https://github.com/NHERI-SimCenter/DamageAndLossModelLibrary.git)
47+
````
48+
49+
-----
50+
51+
### Contributing
52+
53+
We welcome contributions of new and improved models from the researchers and practitioners. While we are in the process of creating a formal contributor's guide, the best way to start is by opening a GitHub Issue to discuss the model data you would like to add.
54+
55+
Our vision is to enable a simple workflow where contributors can submit pull requests with data that conforms to our schema. We appreciate your patience and collaboration as we work towards this goal.
56+
57+
-----
58+
59+
### License & Acknowledgments
60+
61+
This library is distributed under the BSD 3-Clause license. See `LICENSE` for more information.
62+
63+
This material is based upon work supported by the National Science Foundation under Grants No. 1612843 2131111. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the authors and do not necessarily reflect the views of the National Science Foundation.
64+
65+
-----
2966
3067
### Contact
3168
32-
NHERI-SimCenter nheri-simcenter@berkeley.edu
69+
For questions or support, please open an issue on the GitHub repository.
70+
71+
Adam Zsarnóczay, NHERI SimCenter, Stanford University, adamzs@stanford.edu

‎doc/source/about/about.rst‎

Lines changed: 64 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,70 @@
11
.. _about:
22

3-
.. admonition:: Coming soon
4-
5-
This section is under construction.
6-
73
*******
84
About
95
*******
106

11-
About the damage and loss model library.
7+
Overview
8+
========
9+
10+
The Damage and Loss Model Library (DLML) is a project from the NHERI SimCenter designed to address a critical gap in natural hazards engineering: the lack of a centralized, standardized, and easy-to-use repository for damage and loss models. This library provides the essential data—model parameters, descriptive metadata, and configuration files—that power natural hazard risk assessment simulations.
11+
12+
This curated, open-source repository contains standardized model parameters and metadata for quantifying the impact of natural hazard events on the built environment. The library serves as a comprehensive resource for researchers, practitioners, and engineers working in natural hazards risk assessment.
13+
14+
Key Features
15+
============
16+
17+
**Standardized Data Schema**
18+
A robust yet flexible schema for organizing models by hazard, asset type, and resolution, making it easy to use data and supporting new contributions.
19+
20+
**Rich Metadata & Clear Citations**
21+
Every model is paired with detailed metadata and a clear citation to the original source, ensuring proper academic integrity and traceability.
22+
23+
**Broad & Inclusive Collection**
24+
A growing collection of models, from large-scale industry standards like **FEMA P-58** and **FEMA Hazus** to peer-reviewed models from the broader research community. The goal is to provide a home for all high-quality damage and loss models.
25+
26+
**Automated Documentation**
27+
The metadata and parameters are used to automatically generate a user-friendly documentation website, complete with model descriptions, parameter tables, and plots of fragility and consequence functions.
28+
29+
Model Coverage
30+
==============
31+
32+
The library includes comprehensive model collections across multiple hazards:
33+
34+
**Seismic Models**
35+
- FEMA P-58 2nd Edition building components
36+
- Hazus Seismic Building models (v5.1 and v6.1)
37+
- Hazus Seismic Infrastructure models (Power, Water, Transportation Networks)
38+
- Hazus Seismic Building Subassembly models
39+
40+
**Hurricane Models**
41+
- Hazus Hurricane building models (v5.1)
42+
- SimCenter Hurricane Wind Component Library with peer-reviewed research components
43+
44+
**Flood Models**
45+
- Hazus Flood building models (v6.1)
46+
47+
Usage
48+
=====
49+
50+
There are three primary ways to interact with the DLML:
51+
52+
1. **Discover and Explore Models**: Use the documentation website to browse and understand available models
53+
2. **Perform Calculations with Pelicun**: Integrate with the SimCenter's Pelicun simulation engine for damage and loss calculations
54+
3. **Work with Raw Data**: Access the standardized CSV and JSON files directly from the repository
55+
56+
Data Organization
57+
=================
58+
59+
The library is structured in a clear hierarchy of ``hazard/asset_type/resolution/methodology``. Within each methodology:
60+
61+
- **Model parameters** are stored in standardized CSV files (e.g., for fragility, loss, or consequences)
62+
- **Metadata** is provided in corresponding JSON files
63+
- **Configuration files** are included for integration with the Pelicun framework
64+
65+
License & Acknowledgments
66+
=========================
67+
68+
This library is distributed under the BSD 3-Clause license.
69+
70+
This material is based upon work supported by the National Science Foundation under Grants No. 1612843 and 2131111. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the authors and do not necessarily reflect the views of the National Science Foundation.

‎doc/source/index.rst‎

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,23 @@
44
Damage and Loss Model Library
55
===============================
66

7-
.. warning::
7+
Welcome to the Damage and Loss Model Library (DLML), a curated, open-source repository of standardized model parameters and metadata for quantifying the impact of natural hazard events on the built environment.
88

9-
Development Preview Only.
10-
This documentation is intended for internal review and demonstration purposes.
11-
It is not finalized or ready for public use.
9+
This library is a project from the NHERI SimCenter designed to address a critical gap in natural hazards engineering: the lack of a centralized, standardized, and easy-to-use repository for damage and loss models. The DLML provides the essential data—model parameters, descriptive metadata, and configuration files—that power natural hazard risk assessment simulations.
10+
11+
**Key Features:**
12+
13+
* **Standardized Data Schema:** A robust yet flexible schema for organizing models by hazard, asset type, and resolution
14+
* **Rich Metadata & Clear Citations:** Every model is paired with detailed metadata and clear citations to original sources
15+
* **Broad & Inclusive Collection:** Growing collection from industry standards like FEMA P-58 and FEMA Hazus to peer-reviewed research models
16+
* **Automated Documentation:** User-friendly documentation with model descriptions, parameter tables, and fragility/consequence function plots
17+
18+
**Model Coverage:**
19+
20+
The library includes comprehensive model collections for **seismic**, **hurricane**, and **flood** hazards, covering buildings, infrastructure networks, and individual components from sources including FEMA P-58, FEMA Hazus, and peer-reviewed academic research.
1221

1322
.. toctree::
14-
:caption: About
23+
:caption: Documentation
1524
:maxdepth: 4
1625

1726
about/about.rst

‎doc/source/release_notes/index.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,5 @@ Version 1
1313
.. toctree::
1414
:maxdepth: 2
1515

16-
v1.0
16+
v2.0.0
17+
v1.0.0

doc/source/release_notes/v1.0.rst renamed to doc/source/release_notes/v1.0.0.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
.. _changes_v1_0:
22

33
==========================
4-
Version 1.0 (May 19, 2023)
4+
Version 1.0.0 (May 19, 2023)
55
==========================
66

77
Initial Release.

0 commit comments

Comments
 (0)