Vulnerability Modeller's ToolKit (OQ-VMTK)

An open-source Python toolkit for regional earthquake vulnerability modelling — developed by the Global Earthquake Model (GEM) Foundation.

Documentation »  ·  Demos  ·  Report a Bug  ·  Request a Feature

---

Overview

OQ-VMTK is a Python library for regional seismic vulnerability modelling. It provides a self-contained workflow — from compiling idealised structural models, running nonlinear analysis to fragility and vulnerability function derivation, powered by OpenSeesPy.

The toolkit is designed for earthquake engineers and model developers, who need a reproducible and standardised library of functions to integrate to their structural assessment workflows.

---

Modules

Module	Description
calibration	Calibrates storey-based force–deformation relationships for MDOF stick-and-mass models from SDOF capacity curves.
modeller	Compiles and runs idealised stick-and-mass structural models (SDOFs and MDOFs) in OpenSeesPy: gravity, modal analysis, static/cyclic pushover, and nonlinear time-history analysis (including incremental dynamic analyses).
imcalculator	Reads ground motion record files and computes a wide range of intensity measures (PGA, PGV, PGD, SA, AvgSA, Arias Intensity, CAV, D5–95, FIV3), including their RotD50/RotDxx versions from two horizontal components.
imselection	Evaluates and ranks intensity measure candidates for seismic demand modelling using Efficiency, Proficiency, Practicality, and the Relative Sufficiency Measure (RSM).
postprocessor	Derives probabilistic seismic demand models, fragility and vulnerability functions from nonlinear analysis results (Modified Cloud Analysis, Multiple Stripe Analysis, Incremental Dynamic Analysis). Supports lognormal CDFs, GLMs, ordinal CLMs, and MCMC methods.
slfgenerator	Generates storey loss functions (SLFs) from damageable component inventory data (structural, nonstructural, and contents) via Monte Carlo simulations.
plotter	Produces publication-quality figures for all stages of the workflow: model geometry, seismic demand profiles, fragility functions, vulnerability curves, SLFs, and more.
utilities	Helper functions for I/O, data format conversion, and interoperability with OpenQuake Engine outputs.

---

Key Features

Structural Modelling

• Compile idealised SDOF and MDOF stick-and-mass models directly in Python via OpenSeesPy.
• Calibrate MDOF inter-storey force-deformation properties from SDOF capacity curves via a first-mode shape assumption and modal participation.
• Run gravity and modal analysis, static/cyclic pushover, and nonlinear time-history analysis.

Ground Motion Processing

• Batch-process ground motion record files to extract scalar and spectral intensity measures.
• Compute response spectra and a full suite of IMs (SA, AvgSA, PGA, PGV, PGD, AI, CAV, D5–95, FIV3).
• Rank and select optimal IMs for seismic demand modelling.

Fragility Assessment

• Modified Cloud Analysis (MCA): Fit probabilistic seismic demand models (log-linear regression) and derive fragility functions, with bootstrapped and Bayesian (MCMC) uncertainty quantification.
• Incremental Dynamic Analysis (IDA): Scale records to collapse using the Hunt, Trace and Fill algorithm and derive fragility functions by the Method of Moments.
• Nine fragility fitting approaches including lognormal CDF variants, GLM (logit/probit), ordinal CLMs (constant and variable dispersion), and MCMC.
• Multiple Stripe Analysis (MSA): Derive fragility functions from hazard-consistent ground motion suites via Maximum Likelihood Estimation.

Vulnerability & Loss Assessment

• Combine fragility functions with consequence models (damage-to-loss ratios) to derive vulnerability functions with explicit uncertainty treatment (Beta distribution, law-of-total-variance COV method).
• Apply SLFs to derive component-level and system-level vulnerability models.
• Perform classical risk calculations to compute average annual damage probability (AADP) and average annual loss ratio (AALR) via a single calculate_risk method, by integrating fragility or vulnerability curves with site hazard curves to understand in a rapid manner the influence of fragility and vulnerability models on downstream analyses.

---

Demo Notebooks

The demos/ directory contains thirteen self-contained Jupyter notebooks covering the full vulnerability workflow:

Demo	Description
IntensityMeasureProcessing	Ground motion record processing and intensity measure extraction
IntensityMeasureSelection	IM selection using the Relative Sufficiency Measure (MCA and IDA)
ModelCompilation	SDOF and MDOF model calibration and compilation
ModalAnalysis	Modal analysis and dynamic property verification
PushoverAnalysis	Monotonic and cyclic static pushover analysis
NonlinearTimeHistoryAnalysis	Nonlinear time-history analysis and demand profile extraction
ModifiedCloudAnalysis	End-to-end vulnerability assessment using Modified Cloud Analysis
MultipleStripeAnalysis	End-to-end vulnerability assessment using Multiple Stripe Analysis
IncrementalDynamicAnalysis	End-to-end vulnerability assessment using Incremental Dynamic Analysis
FragilityAnalysis	Comparison of all supported fragility fitting methods
StoreyLossFunctionGeneration	Generating storey loss functions from component inventory data
StoreyLossFunctionApplication	Deriving system-level vulnerability models using storey loss functions
EQSpectraExample	Illustrative case study accompanying the EQ Spectra paper (end-to-end workflow)

---

Installation

It is strongly recommended to install OQ-VMTK inside a virtual environment to avoid dependency conflicts with the OpenQuake Engine requirements.

1. Clone the Repository

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

2. Create and Activate a Virtual Environment

# Create
python -m venv .venv          # Windows
python3 -m venv .venv         # Linux / macOS

# Activate
.venv\Scripts\activate        # Windows
source .venv/bin/activate     # Linux / macOS

To deactivate later: deactivate

3. Install Dependencies

Install the appropriate requirements file based on your operating system and Python version. In case you are using version Python 3.12.

For Windows Users:

pip install -r requirements-py312-win64.txt   --timeout=100 

For Linux Users:

pip install -r requirements-py312-linux.txt  --timeout=100

**For macOS (Apple Silicon) Users: **

pip install -r requirements-py312-macos_arm64.txt  --timeout=100 

Tip: if you prefer the conventional installation via pip without passing --timeout=100 each time, set the timeout globally once, before installing:

pip config set global.timeout 100

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

python --version

To check your Python version: python --version

4. Install the Package

Standard install (recommended):

pip install .

Editable install (for contributors modifying the source):

pip install -e .

5. Verify

python -c "import openquake.vmtk; print(openquake.vmtk.__version__)"

Expected output: 1.2.0

---

Running the Demos

Jupyter Lab is installed automatically with OQ-VMTK.

# Activate your virtual environment first, then:
jupyter-lab

Navigate to the demos/ folder and open any notebook. Each demo is fully self-contained with input data included.

---

Documentation

Full API reference, module guides, and worked examples are available at:

https://gemsciencetools.github.io/oq-vmtk

---

License

OQ-VMTK is released under the GNU Affero General Public License v3.0 (AGPL-3.0).

You are free to use, modify, and distribute this software under the terms of the AGPL v3. Any modifications made to the source code must also be released under the same licence. See the LICENSE file for the full licence text.

---

Citation

If you use OQ-VMTK in academic or professional work, please cite both the software release and the companion paper.

Software

The software is archived on Zenodo:

@software{oq_vmtk_2025,
  author    = {{GEM Foundation}},
  title     = {{OpenQuake Vulnerability Modeller's Toolkit (oq-vmtk)}},
  version   = {1.2.0},
  year      = {2026},
  doi       = {10.5281/zenodo.17524871},
  url       = {https://github.com/GEMScienceTools/oq-vmtk}
}

A CITATION.cff file is provided at the repository root; GitHub displays a Cite this repository widget automatically.

Companion Paper

Nafeh, A.M.B., Aljawhari, K., Ettorre, A., Silva, V., and Crowley, H. (2026). The OpenQuake Vulnerability Modeller's Toolkit: An Open-Source Toolkit for Earthquake Vulnerability Modelling Applications. (In Press)

@article{nafeh2026vmtk,
  author  = {Nafeh, Al Mouayed Bellah and Aljawhari, Karim and Ettorre, Antonio and Silva, Vitor and Crowley, Helen},
  title   = {The {OpenQuake} {Vulnerability} {Modeller's} {Toolkit}: An Open-Source Toolkit for Earthquake Vulnerability Modelling Applications},
  journal = {(In Press)},
  year    = {202x}
}

---

References

• Nafeh, A.M.B., Aljawhari, K., Ettorre, A., Silva, V., and Crowley, H. (2026). The OpenQuake Vulnerability Modeller's Toolkit (OQ-VMTK) (v1.2.0). Zenodo. DOI: 10.5281/zenodo.17524871

• Nafeh, A.M.B., Aljawhari, K., Ettorre, A., Silva, V., and Crowley, H. (2026). The OpenQuake Vulnerability Modeller's Toolkit: An Open-Source Toolkit for Earthquake Vulnerability Modelling Applications. (In Press)

---

Contributing

Contributions are welcome. Please read the contributing guidelines before opening a pull request.

---

Contributors

(back to top)