OQ-VMTK v1.2.0 Release

[mouayed-nafeh]

Release v1.2.0: Latest stable version of OQ-VMTK

This PR prepares v1.2.0, the first stable release of OQ-VMTK. It also contains the corrections made in response to the peer-review comments on the companion EQ Spectra paper.

Release housekeeping

• Version bumped to 1.2.0 in openquake/vmtk/__init__.py and CITATION.cff.
• CHANGELOG.md is rewritten as a single v1.2.0 entry. This version is the starting point of the changelog.
• README and docs now state how to avoid pip download timeouts: pip config set global.timeout 100, as an alternative to --timeout=100.
• slfgenerator: the deprecated pydantic validator is replaced by field_validator (pydantic v2).

Functionality in this release

Module	What it does
calibration	calibrate_model() derives storey force–deformation properties of MDOF stick-and-mass models from SDOF capacity curves, using a power-law or eigenvector first-mode shape and a soft-storey option. It has no OpenSees dependency.
modeller	Builds SDOF and MDOF models in OpenSeesPy. It runs gravity and modal analysis, static and cyclic pushover (SPO, CPO), nonlinear time-history analysis (single records and sequences) and incremental dynamic analysis (IDA). It has collapse detection and animated outputs.
imcalculator	Computes PGA, PGV, PGD, SA, AvgSA, Arias Intensity, CAV, D5–95, FIV3 and RotDxx spectra.
imselection	Ranks intensity measures by efficiency, proficiency, practicality and relative sufficiency measure (RSM).
postprocessor	Builds probabilistic seismic demand models and fragility functions from Modified Cloud Analysis (classical, bootstrap, MCMC), Multiple Stripe Analysis and IDA. It also derives vulnerability functions with explicit uncertainty propagation, and calculate_risk computes AADP and AALR.
slfgenerator	Runs Monte Carlo simulations of storey loss functions from component inventories, with independent or correlated components. It returns the empirical 16th, 50th and 84th percentiles.
plotter	Produces figures for every stage of the workflow, with a uniform plotting grid.
utilities	I/O helpers and OpenQuake Engine interoperability.

There are 13 demo notebooks covering the full workflow, including the new EQSpectraExample. It is the electronic supplement to the paper's illustrative case study.

Updates since v1.1.1

Analysis and collapse detection (modeller)

• do_nrha_analysis and do_nrha_analysis_sequences: collapse detection relied only on eleResponse, which can freeze once a spring fails, so a run could report "ANALYSIS SUCCESSFUL" with absurd drifts. Both methods now also cross-check the nodal inter-storey displacement against the MinMax limit at every step, and they check both X and Y deformation under bidirectional loading.
• do_spo_analysis had no collapse detection and could silently report success after the base shear decayed to about zero. It now has the same checks as the CPO method and returns a conv_index flag.
• The minmax_multiplier argument had no effect on when collapse was reported. It is now applied consistently.
• push_dir was ignored in some checks and recordings, so pushover in directions 2 and 3 inspected the wrong DOF. It now uses push_dir - 1.
• Pinching4 parameters can now be overridden through pinching4_params adding more flexibility for users to define their own calibrated pinching4 parameters instead of only relying on the hard-coded default parameters, and the collapse bound through minmax_multiplier. Defaults are unchanged.

Intensity measures (imcalculator)

• PGV and PGD are now computed from drift-corrected histories with a zero-phase Butterworth high-pass filter (Boore, 2005). On 300 records of the GEM global flatfile, uncorrected PGD had a median 2.6× the database values; with the filter it is 0.95×. PGA is unchanged, and well-processed records change by less than 0.2%.

Fragility and vulnerability (postprocessor)

• Rotated-fragility options are removed, and so is the empirical Silva (2019) COV option. Uncertainty is now propagated explicitly with the law of total variance.
• calculate_average_annual_loss and calculate_average_annual_damage_probability are merged into one calculate_risk. The integration logic is unchanged.
• Generalised fragility models and IDA post-processing bugs are fixed.

Storey loss functions (slfgenerator)

• Components are now identified by Component ID instead of row position. Previously validate_ds_dependence silently mismatched components whenever IDs weren't 1..n in row order.
• Normal repair-cost sampling uses scipy.stats.truncnorm instead of a rejection loop. This removes a possible infinite loop and runs about 100× faster.
• The regression-fitting machinery is removed. generate() now returns empirical percentiles.

Plotting and demos

• plot_slf_model now overlays multiple keys on one set of axes. Before, only the last key was drawn.
• The demos that were affected are re-executed:
  • NonlinearTimeHistoryAnalysis now correctly reports collapse.
  • PushoverAnalysis uses a displacement target that stays in the well-behaved range.

Breaking changes (relative to v1.1.x)

• The class-based calibration API is replaced by calibrate_model(). The 5-tuple return is unchanged, but metadata is reduced to gamma_real, is_sos, is_frame and storey_heights.
• The rotated-fragility methods and options and the Silva COV method are removed.
• slfgenerator output keys change: slf_16th, slf and slf_84th are added, and error_max, error_cum and the fitted-regression keys are removed. The primary curve is now the median, not the mean.
• PGV and PGD values change by default; pass highpass_hz=None to restore plain integration.

Testing

• 265 passed, 0 skipped, on Python 3.11

[antonioettorre]

LGTM