mouayed-nafeh · Oct 9, 2026 · Sep 25, 2026 · Oct 5, 2026 · Oct 5, 2026 · Oct 5, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/CITATION.cff b/CITATION.cff
@@ -16,12 +16,12 @@ authors:
 license: AGPL-3.0-only
 repository-code: "https://github.com/GEMScienceTools/oq-vmtk"
 url: "https://gemsciencetools.github.io/oq-vmtk/"
-version: "1.1.0"
-date-released: "2026-05-12"
+version: "1.2.0"
+date-released: "2026-10-09"
 identifiers:
   - type: doi
     value: 10.5281/zenodo.17524871
-    description: Zenodo archive of the v1.0.0 release
+    description: Zenodo archive of oq-vmtk
 keywords:
   - earthquake-engineering
   - seismic-risk

diff --git a/README.md b/README.md
@@ -19,7 +19,7 @@
   <h3 align="center">Vulnerability Modeller's ToolKit (OQ-VMTK)</h3>
 
   <p align="center">
-    An open-source Python toolkit for earthquake structural modelling, nonlinear analysis, and seismic vulnerability assessment — developed by the Global Earthquake Model (GEM) Foundation.
+    An open-source Python toolkit for regional earthquake vulnerability modelling — developed by the Global Earthquake Model (GEM) Foundation.
     <br /><br />
     <a href="https://gemsciencetools.github.io/oq-vmtk/"><strong>Documentation »</strong></a>
     &nbsp;·&nbsp;
@@ -35,7 +35,7 @@
 
 ## Overview
 
-OQ-VMTK is a Python library for regional seismic vulnerability and risk modelling. It provides a self-contained workflow — from ground motion processing and structural model compilation through nonlinear analysis to fragility and vulnerability function derivation, powered by [OpenSeesPy](https://openseespydoc.readthedocs.io).
+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](https://openseespydoc.readthedocs.io).
 
 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. 
 
@@ -46,11 +46,11 @@ The toolkit is designed for earthquake engineers and model developers, who need
 | Module | Description |
 |--------|-------------|
 | `calibration` | Calibrates storey-based force–deformation relationships for MDOF stick-and-mass models from SDOF capacity curves. |
-| `modeller` | Compiles and runs SDOF and MDOF structural models in OpenSeesPy: modal analysis, gravity, 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). |
+| `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). |
+| `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. |
 
@@ -60,24 +60,24 @@ The toolkit is designed for earthquake engineers and model developers, who need
 
 ### 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 (power-law for frame buildings, eigenvector-derived otherwise) and modal participation.
-- Run modal analysis, static/cyclic pushover, gravity analysis, and nonlinear time-history analysis within a unified API.
+- 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 using the Relative Sufficiency Measure.
+- 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.
-- **Multiple Stripe Analysis (MSA):** Derive fragility functions from hazard-consistent ground motion suites via Maximum Likelihood Estimation.
 - **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 mean vulnerability functions with explicit uncertainty treatment (Beta distribution, law-of-total-variance COV method).
-- Apply storey loss functions to derive component-level and system-level vulnerability models.
-- 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.
+- 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.
 
 ---
 
@@ -99,6 +99,7 @@ The `demos/` directory contains thirteen self-contained Jupyter notebooks coveri
 | `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) |
 
 ---
 
@@ -146,6 +147,12 @@ To deactivate later: `deactivate`
    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:
+   ```bash
+   pip config set global.timeout 100
+   ```
+
    **Note:** to check your current python version, run the following command
    ```bash
    python --version
@@ -175,7 +182,7 @@ pip install -e .
 python -c "import openquake.vmtk; print(openquake.vmtk.__version__)"
 ```
 
-Expected output: `1.1.0`
+Expected output: `1.2.0`
 
 ---
 
@@ -216,16 +223,16 @@ If you use OQ-VMTK in academic or professional work, please cite both the softwa
 
 ### Software
 
-The v1.1.0 release is archived on Zenodo:
+The software is archived on Zenodo:
 
 [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.17524871-1082c3)](https://doi.org/10.5281/zenodo.17524871)
 
 ```bibtex
 @software{oq_vmtk_2025,
   author    = {{GEM Foundation}},
   title     = {{OpenQuake Vulnerability Modeller's Toolkit (oq-vmtk)}},
-  version   = {1.1.0},
-  year      = {2025},
+  version   = {1.2.0},
+  year      = {2026},
   doi       = {10.5281/zenodo.17524871},
   url       = {https://github.com/GEMScienceTools/oq-vmtk}
 }
@@ -235,22 +242,24 @@ A `CITATION.cff` file is provided at the repository root; GitHub displays a **Ci
 
 ### Companion Paper
 
-> Nafeh, A.M.B., Aljawhari, K., Ettorre, A., Silva, V., and Crowley, H. (2026). *The OpenQuake Vulnerability Modellers' Toolkit: An Open-Source Toolkit for Earthquake Vulnerability Modelling Applications*. (In Press)
+> 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)
 
 ```bibtex
 @article{nafeh2026vmtk,
   author  = {Nafeh, Al Mouayed Bellah and Aljawhari, Karim and Ettorre, Antonio and Silva, Vitor and Crowley, Helen},
-  title   = {The {OpenQuake} {Vulnerability} {Modellers}' {Toolkit}: An Open-Source Toolkit for Earthquake Vulnerability Modelling Applications},
+  title   = {The {OpenQuake} {Vulnerability} {Modeller's} {Toolkit}: An Open-Source Toolkit for Earthquake Vulnerability Modelling Applications},
   journal = {(In Press)},
-  year    = {2026}
+  year    = {202x}
 }
 ```
 
 ---
 
 ## References
 
-- Nafeh, A.M.B., Aljawhari, K., Ettorre, A., Silva, V., and Crowley, H. (2026). *The OpenQuake Vulnerability Modellers' Toolkit: An Open-Source Toolkit for Earthquake Vulnerability Modelling Applications*. (In Press)
+- 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](https://doi.org/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)
 
 ---
 

diff --git a/demos/EQSpectraExample/EQSpectraExample.ipynb b/demos/EQSpectraExample/EQSpectraExample.ipynb
diff --git a/demos/EQSpectraExample/README.md b/demos/EQSpectraExample/README.md
@@ -0,0 +1,3 @@
+# Illustrative Case Study Application for OQ-VMTK
+
+This notebook is the electronic supplement to the example provided in the *Illustrative Case Study Application for OQ-VMTK* section of the EQ Spectra paper. It calibrates an MDOF stick-and-mass model from an SDOF capacity curve, verifies it through modal and static pushover analyses, runs Modified Cloud Analysis, and derives fragility and vulnerability functions using the `calibration`, `modeller`, `postprocessor` and `plotter` modules.
diff --git a/demos/EQSpectraExample/in/hazard_curves.csv b/demos/EQSpectraExample/in/hazard_curves.csv
@@ -0,0 +1,28 @@
+SA(0.3),Vancouver,San Salvador,Athens,Istanbul,Lisbon,Beirut,Wellington
+0.0012,0.3566568,0.9998763,0.9945741,0.9320585,0.6310164,0.8062105,0.6196702
+0.011,0.2325410060509561,0.8950322,0.6281378,0.4926407,0.2065586,0.1753377,0.5074626
+0.014,0.1988215276782985,0.8397072,0.544744,0.4275885,0.168679,0.1350309,0.4706536
+0.019,0.1596550045335299,0.748252,0.4416365,0.3494594,0.1270943,0.09433711,0.4165477
+0.025,0.1282416582770787,0.6498937,0.3563864,0.2854617,0.09605354,0.06648892,0.3626776
+0.033,0.100283897668865,0.5425679,0.2804304,0.2281792,0.07060409,0.04541492,0.3058389
+0.043,0.0774361220961892,0.4410995,0.2188129,0.1812292,0.05147767,0.03076988,0.2523006
+0.057,0.0569343849492382,0.3417256,0.1647354,0.139559,0.03592098,0.01977181,0.1990055
+0.075,0.0409961702629856,0.2585319,0.1226339,0.106795,0.02473813,0.01250917,0.1531686
+0.098,0.0289755420608506,0.1921897,0.09037751,0.08147585,0.01683712,0.007807314,0.1155868
+0.13,0.0195199285961198,0.1374156,0.0642302,0.06071723,0.01095778,0.004623234,0.08383204
+0.17,0.0130297879476064,0.0981428,0.04557931,0.04560113,0.007124484,0.002748191,0.0607156
+0.22,0.0085771954964898,0.06996358,0.03219414,0.03435534,0.004607797,0.001638532,0.0440081
+0.29,0.0052694268013364,0.04790746,0.02173382,0.02503216,0.002815604,0.0009296536,0.03089338
+0.37,0.0033066706525576,0.03377217,0.01509172,0.01861012,0.001780272,0.0005609393,0.02247347
+0.49,0.0018075849588927,0.02202802,0.00969255,0.01284289,0.001017332,0.0003119111,0.01544829
+0.64,0.0009529182865914,0.01418129,0.00621289,0.008686185,0.0005770922,0.0001763701,0.01069337
+0.83,0.0004791751880546,0.008834074,0.003930628,0.0056777,0.0003202558,9.834766e-05,0.007351048
+1.09,0.0002174882616429,0.005058607,0.002358735,0.003442347,0.0001648664,5.078316e-05,0.004836115
+1.42,9.413113230342077e-05,0.002740449,0.001386523,0.001996577,8.225441e-05,2.509356e-05,0.003112315
+1.85,3.786103942376808e-05,0.001372469,0.0007816553,0.001088381,3.880262e-05,1.138449e-05,0.001918233
+2.42,1.3822976640745236e-05,0.0006263785,0.0004155636,0.0005503297,1.698732e-05,4.768372e-06,0.00111252
+3.16,4.608041946631542e-06,0.0002658707,0.0002096891,0.0002613664,6.973743e-06,1.788139e-06,0.0006086435
+4.12,1.3544016305932912e-06,0.0001061099,9.989738e-05,0.0001164675,2.682209e-06,7.152557e-07,0.000311858
+5.38,3.44674723516966e-07,3.994144e-05,4.428625e-05,4.816055e-05,8.940697e-07,2.980232e-07,0.0001475321
+7.02,7.545899171432829e-08,1.446651e-05,1.829863e-05,1.853704e-05,3.576279e-07,5.960464e-08,6.452214e-05
+9.36,3.4695400000000016e-08,4.626456e-06,6.496906e-06,6.079674e-06,5.960464e-08,0.0,2.401849e-05
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Illustrative Case Study Application for OQ-VMTK

		This notebook is the electronic supplement to the example provided in the Illustrative Case Study Application for OQ-VMTK section of the EQ Spectra paper. It calibrates an MDOF stick-and-mass model from an SDOF capacity curve, verifies it through modal and static pushover analyses, runs Modified Cloud Analysis, and derives fragility and vulnerability functions using the `calibration`, `modeller`, `postprocessor` and `plotter` modules.