7.6. Incremental Dynamic Analysis Postprocessing

postprocessor.process_ida_results(ansys_dict, im_matrix, damage_thresholds, edp_key, sigma_build2build=0.3, sigma_ds=0.3, intensities=np.round(np.geomspace(0.05, 10.0, 50), 3), edp_range=np.linspace(0.00, 0.05, 101), collapse_edp=None)[source]

Perform fragility function fitting and statistical processing on Incremental Dynamic Analysis (IDA) results.

For each record and damage state, the IM capacity is taken as the IM at which the monotonic IDA curve first reaches the DS threshold, interpolated between the two bracketing runs. Records that collapse (flatline) before reaching the threshold are assigned the flatline IM, i.e. the IM of the last non-collapsed run. Records that neither reach the threshold nor collapse within the analysed range are treated as right-censored at the highest IM analysed for that record. The lognormal fragility parameters are then estimated by the method of moments when all capacities are observed, or by right-censored maximum likelihood estimation otherwise (Baker, 2015).

Parameters:

  • ansys_dict (dict) –

    A dictionary containing the structural response data with keys:

    • 'max_peak_drift_list' or 'max_peak_accel_list': a list where each entry maps Scale Factors (SF) to peak drift or acceleration values.

    • 'sf_matrix': a 2D numpy array (n_records × max_runs) of scale factors used for each analysis run.

  • im_matrix (numpy.ndarray) – A 2D array of intensity measure levels corresponding to the ground motion records and number of runs carried out in IDA.

  • damage_thresholds (list of float) – A list of EDP-based damage thresholds (e.g., interstorey drift ratios) defining different limit states (e.g., Slight, Moderate, Extensive, Collapse).

  • edp_key (str, optional,) – default=’max_peak_drift_list’ (other: ‘max_peak_accel_list’) The key in ansys_dict used to retrieve the engineering demand parameter data.

  • sigma_build2build (float, optional, default=0.3) – The modeling uncertainty or building-to-building variability. This is combined with the record-to-record variability to calculate total fragility dispersion.

  • sigma_ds (float, optional) – The logarithmic standard deviation representing uncertainty in damage-state thresholds. Default value is 0.30.

  • intensities (numpy.ndarray, optional,) – default=np.geomspace(0.05, 10.0, 50) The array of intensity measure levels over which the final fragility functions (POEs) will be sampled.

  • edp_range (numpy.ndarray, optional,) – default=np.linspace(0.00, 0.05, 101) (0% to 5% drift) The array of engineering demand parameters over which the IDA curves will be evaluated (used for the statistical IDA curves in 'stats' only; capacities are interpolated at the exact damage thresholds).

  • collapse_edp (float, optional, default=None) – EDP value at or above which a run is treated as collapsed (e.g., the target_drift used in do_ida_analysis). Runs flagged as non-converged in ansys_dict ['conv_index_list'] (conv_index == -1) are always treated as collapsed when that key is present. If neither source identifies a collapse, a record that does not reach a threshold is treated as right-censored.

Returns:

ida_dict – A nested dictionary with the following top-level keys:

’ida_inputs’dict

Raw IDA data and analysis configuration.

  • 'target_edps' : array — continuous EDP axis over which IM values are interpolated.

  • 'raw_curves' : list of dicts, one per record, each containing 'im' (sorted IM array) and 'edp' (monotonic EDP array).

  • 'damage_thresholds' : list — EDP values that define each damage state boundary.

  • 'im_matrix' : array — IM values applied to each record at each run.

  • 'n_records' : int — number of ground-motion records in the analysis.

  • 'im_max_analyzed' : float — maximum IM level reached across all records and runs.

’fragility’dict

MLE-fitted fragility parameters and PoEs.

  • 'fragility_method' : str — always ‘mle_ida_censored’.

  • 'intensities' : array — IM levels at which PoEs are evaluated.

  • 'poes' : ndarray, shape (n_IM, n_DS) — probabilities of exceedance per damage state.

  • 'medians' : list, length n_DS — median IM (theta) for each damage state.

  • 'sigma_record2record' : list, length n_DS — record-to-record dispersion per damage state, estimated by the method of moments or censored MLE.

  • 'sigma_build2build' : list, length n_DS — building-to-building modelling uncertainty.

  • 'sigma_ds' : list, length n_DS — uncertainty in the damage-state threshold definition.

  • 'betas_total' : list, length n_DS — total logarithmic standard deviation per damage state.

  • 'fit_method' : list, length n_DS — ‘method_of_moments’, ‘censored_mle’ or ‘insufficient_data’ (fewer than two observed capacities; parameters and PoEs are NaN).

  • 'n_censored' : list, length n_DS — number of right-censored records per damage state.

  • 'capacities' : list, length n_DS — dicts with the IM 'capacities' and boolean 'censored' flags used in the fit.

’stats’dict

Statistical IDA curves across all records.

  • 'fitted_edps' : array — EDP axis shared with 'target_edps' in 'ida_inputs'.

  • 'median_im' : array — median IM across all records at each EDP level (50th percentile curve).

  • 'p16_im' : array — 16th percentile IM across records at each EDP level.

  • 'p84_im' : array — 84th percentile IM across records at each EDP level.

Return type:

dict

Notes

The censored likelihood combines the lognormal density of the observed capacities with the lognormal survival function evaluated at each censored record’s own maximum analysed IM. The total dispersion combines the fitted record-to-record term with sigma_build2build and sigma_ds by SRSS, all in IM space.

References

Baker JW. Efficient Analytical Fragility Function Fitting Using Dynamic Structural Analysis. Earthquake Spectra. 2015;31(1):579-599. doi:10.1193/021113EQS025M

Theoretical Background

Incremental Dynamic Analysis (IDA) scales each record to multiple intensity levels and traces the structural response from elastic behaviour to collapse, producing IDA curves and a statistical basis for fragility derivation (Vamvatsikos & Cornell, 2002).

IDA curves

For each ground-motion record \(r\) and scaling factor \(\lambda\), the scaled IM is \(\text{IM}_{r,\lambda} = \lambda \cdot \text{IM}_{r,1}\) and the resulting peak EDP is recorded. The full set of \((\text{IM}, \text{EDP})\) pairs for record \(r\) forms its IDA curve.

Limit-state capacity

The IM capacity \(C_i^{(r)}\) of record \(r\) for damage state \(i\) is the smallest IM at which the IDA curve first exceeds the threshold \(\delta_i\):

\[C_i^{(r)} = \inf\bigl\{\text{IM} : \text{EDP}(\text{IM}) \geq \delta_i\bigr\}\]

Lognormal fragility fitting

Across all records, the capacities \(\{C_i^{(r)}\}\) are assumed lognormally distributed. The median \(\theta_i\) and logarithmic standard deviation \(\beta_{\text{rr}}\) are estimated by maximum likelihood:

\[\theta_i = \exp\!\left(\frac{1}{N}\sum_{r=1}^{N} \ln C_i^{(r)}\right), \qquad \beta_{\text{r2r}} = \sqrt{\frac{1}{N-1}\sum_{r=1}^{N}\bigl(\ln C_i^{(r)} - \ln \theta_i\bigr)^2}\]

Total dispersion

Additional sources of uncertainty are combined in quadrature:

\[\beta_{\text{total}} = \sqrt{\beta_{\text{r2r}}^2 + \beta_{\text{b2b}}^2 + \beta_{\text{DS}}^2}\]

Fragility function

The probability of exceeding damage state \(i\) at a given IM is:

\[P(\text{DS} \geq ds_i \mid \text{IM}) = \Phi\!\left(\frac{\ln(\text{IM}/\theta_i)}{\beta_{\text{total}}}\right)\]

Example

from openquake.vmtk.postprocessor import postprocessor

pp = postprocessor()
# ansys_dict: IDA results ('max_peak_drift_list', 'sf_matrix');
# im_matrix: IM levels, 2-D array (n_records × n_runs)
ida_dict = pp.process_ida_results(
    ansys_dict=ansys_dict,
    im_matrix=im_matrix,
    damage_thresholds=[0.005, 0.015, 0.040],
    edp_key="max_peak_drift_list",
)
print(ida_dict['fragility']['medians'])