Vulnerability Modeller's ToolKit (OQ-VMTK)

This repository contains an open source library that provides modelling of multi-degree-of-freedom systems and assessment via nonlinear time-history analyses for regional vulnerability and risk calculations. The vulnerability toolkit is developed by the Global Earthquake Model (GEM) Foundation and its collaborators.
Explore the docs »

View Demos · Report Bug · Request Feature

✨ Key Features

The OQ-VMTK is a powerful toolkit developed by scientists at the Global Earthquake Model (GEM) Foundation. Designed for earthquake engineers and catastrophe modellers, it provides a comprehensive platform powered by OpenSees for running representative (idealised) models, developing fragility and vulnerability assessments, and offering extensive flexibility in defining seismic demand, structural capacity, damage criteria, and damage-to-loss conversion.

🏗️ Single- and Multi-Degree-of-Freedom Systems Calibration and Modeling

• Define structures with key attributes like storey count, first-mode transformation factors, and force-deformation relationships.
• Effortlessly create and visualize single- (SDOF) and multi-degree-of-freedom (MDOF) stick-and-mass models using intuitive low-level parameters.
• Calibrate multi-degree-of-freedom stick-and-mass models based on SDOF parameters.

🔍 Comprehensive Analysis Suite

📊 Linear & Nonlinear Analysis

• Modal Analysis: Extract vibration periods and mode shapes with precision.
• Gravity Analysis: Perform gravity analysis and ensure system stability before running advanced simulations.
• Nonlinear Static Analyses: Perform static and cyclic pushover tests to assess the system's lateral load resisting capacity, dissipated energy and other metrics.
• Nonlinear Time-History Analyses: Simulate dynamic response of structures using ground-motion records and extract peak response quantities such as peak storey drifts, peak displacements and peak floor accelerations.

🌍 Seismic Fragility & Vulnerability Assessment

• Fragility Analysis: Conduct probabilistic seismic demand modeling to establish relationships between engineering demand parameters (EDPs) and intensity measures (IMs) using nonlinear time-history analyses (e.g., cloud analysis, multiple stripe analyses). Estimate damage exceedance probabilities while accounting for record-to-record variability and modeling uncertainty. Multiple approaches are supported, including conventional methods (e.g., lognormal cumulative distribution functions) and advanced techniques (e.g., generalized linear models and ordinal models).
• Storey Loss Function Generation: Develop storey-level loss functions based on a user-defined inventory of structural components, nonstructural components, and building contents.
• Vulnerability Analysis: Derive vulnerability functions to evaluate both economic and human-centered decision variables. These functions integrate damage-to-loss ratios and/or storey loss functions, with explicit treatment of uncertainties associated with loss conditional on ground-shaking intensity.

📈 Powerful Visualization & Plotting Tools

• Generate insightful plots for:
  • Model Overview: Nodes and elements in your OpenSees model.
  • Cloud Analysis Results: Visualize probabilistic seismic demand models (i.e., IM-EDP data and fitted relationships).
  • Seismic Demand Profiles: Visualize peak storey drifts and peak floor accelerations distributions along the height of idealised systems.
  • Fragility Functions: Visualize probability-based structural performance.
  • Storey Loss Functions: Visualize storey loss function simulations and models.
  • Vulnerability Functions: Understand risk and loss estimates.

🚀 Get Started

👩‍💻🧑‍💻 Installation

Follow these steps to install the oq-vmtk package and its dependencies. Note that this procedure implies the installation of the OpenQuake engine dependencies. This procedure was tested on Windows and Linux OS. It is highly recommended to use a virtual environment to install this tool. A virtual environment is an isolated Python environment that allows you to manage dependencies for this project separately from your system’s Python installation. This ensures that the required dependencies for the OpenQuake engine do not interfere with other Python projects or system packages, which could lead to version conflicts.

1. Clone the Repository

Open your terminal, and run:

cd <virtual_environment_directory>
git clone https://github.com/GEMScienceTools/oq-vmtk.git
cd oq-vmtk

2. Set Up a Virtual Environment (Recommended)

Create a virtual environment to manage dependencies:

python -m venv .venv  # On Windows
python3 -m venv .venv  # On Linux

Activate the virtual environment:

.venv\Scripts\activate  # On Windows
source .venv/Scripts/activate  # On Linux

3. Install Dependencies

Install the required packages listed in requirements.txt.

For Windows Users: Install the appropriate requirements file based on your Python version:

pip install -r requirements-py311-win64.txt  # Python 3.11
pip install -r requirements-py312-win64.txt  # Python 3.12

For Linux Users: Install the appropriate requirements file based on your Python version:

pip install -r requirements-py310-linux64.txt  # Python 3.11
pip install -r requirements-py311-linux64.txt  # Python 3.11
pip install -r requirements-py312-linux64.txt  # Python 3.12

For macOS Users: OpenSeesPy does not currently support macOS versions running on arm64 processors, such as M1 and M2 chips. As a result, newer OpenSeesPy versions are not available for macOS. To use OpenSeesPy on a Mac, it is advised to run a virtual machine with Linux or Windows.

Note: to check your current python version, run the following command

python --version

4. Install the Package

Install the oq-vmtk package in editable mode:

pip install -e .

📼 Demos

The repository includes demo scripts that showcase the functionality of the vulnerability-modellers-toolkit (oq-vmtk). You can find them in the demos folder of the repository.

To run a demo, simply navigate to the demos directory and execute the relevant demo script in Jupyter Lab. Jupyter Lab is automatically installed with oq-vmtk.

1. Activate the virtual environment:

.venv\Scripts\activate  # On Windows
source .venv/Scripts/activate  # On Linux

Note: to deactivate virtual environment:

 deactivate

2. Open Jupyter Lab from the terminal:

 jupyter-lab

3. Navigate to the "demos" folder

4. Run the examples

© License

This work is licensed under an AGPL v3 license (https://www.gnu.org/licenses/agpl-3.0.en.html)

📚 Documentation

For detailed documentation and user guidance on using the toolkit for vulnerability modeling, including installation instructions, key functionalities, and example workflows, please visit: https://gemsciencetools.github.io/oq-vmtk

📑 References

[WIP]

🤝 Contributions

You can follow the instructions indicated in the contributing guidelines

🌟 Contributors

Contributors are gratefully acknowledged.

(back to top)