6.9. Nonlinear Time-History Analysis of Record Sequences

modeller.do_nrha_analysis_sequences(fnames, time_vector, sf, pFlag=True, xi=0.05, ansys_soe='BandGeneral', constraints_handler='Plain', numberer='RCM', test_type='NormDispIncr', init_tol=1.0e-6, init_iter=50, algorithm_type='Newton', save_animation_path=None, drift_thresholds=None, padding_duration=40.0, quiescence_threshold=1.0e-6)[source]

Perform nonlinear time-history analysis on a Multi-Degree-of-Freedom (MDOF) system subjected to a concatenated sequence of ground-motion records that may have different time-steps and are separated by zero-acceleration padding intervals.

Unlike do_nrha_analysis which takes a fixed scalar dt_gm and a constant dt_ansys, this method takes an explicit time_vector so that records with different sampling rates can be stitched together and the analysis steps through each point at its native dt.

The method automatically detects individual ground-motion records within the concatenated input by identifying padding (quiescent) zones where the absolute acceleration stays below quiescence_threshold for at least padding_duration seconds. Peak responses and hysteretic energies are reported both for the full sequence and for each individual record.

Supports uni-directional (1 file) and bi-directional (2 files) ground-motion loading. Floor accelerations are recorded as absolute (total) accelerations, including at the base. Hysteretic energy dissipation is computed via signed force-velocity integration (trapezoidal rule), correctly capturing only dissipated energy and not elastic recovery. Collapse is detected via both the MinMax material response and an independent nodal-displacement cross-check (catching cases where a decoupled, zero-stiffness mechanism keeps the material response frozen while the true nodal displacement diverges).

Parameters:

  • fnames (list) – List of file paths to the ground-motion records. One file applies X-direction loading; two files apply bi-directional (X and Y) loading simultaneously. Each file contains a concatenated acceleration time-history (one value per time_vector entry) where individual records are separated by zero-padded intervals.

  • time_vector (array-like) – Monotonically increasing time values (s) corresponding to each acceleration sample in the ground-motion files. This may be irregularly spaced when records with different dt are concatenated.

  • sf (float) – Scale factor to apply to the ground-motion records. Typically equal to gravitational acceleration (9.81 m/s²) when records are in units of g.

  • pFlag (bool, optional, default=True) – If True, prints progress updates during the analysis.

  • xi (float, optional, default=0.05) – Inherent viscous damping ratio (default is 5%).

  • ansys_soe (str, optional, default='BandGeneral') – System of equations solver type.

  • constraints_handler (str, optional, default='Plain') – Method used to enforce constraint equations.

  • numberer (str, optional, default='RCM') – DOF numberer object (Reverse Cuthill-McKee by default).

  • test_type (str, optional, default='NormDispIncr') – Convergence test type.

  • init_tol (float, optional, default=1.0e-6) – Convergence tolerance.

  • init_iter (int, optional, default=50) – Maximum number of iterations per time step.

  • algorithm_type (str, optional, default='Newton') – Nonlinear solution algorithm.

  • save_animation_path (str, optional) – If provided, saves the NRHA animation to this file path (e.g., ‘nrha.gif’).

  • drift_thresholds (list, optional) – Drift thresholds used in the animation for damage-state colour changes.

  • padding_duration (float, optional, default=40.0) – Minimum duration (s) of near-zero acceleration that separates two consecutive ground-motion records within the concatenated file. Used by the automatic sequence detector.

  • quiescence_threshold (float, optional, default=1.0e-6) – Absolute acceleration amplitude below which a sample is considered ‘silent’. Used together with padding_duration to locate record boundaries.

Returns:

  • control_nodes (list) – Node tags (base first, then floors).

  • conv_index (int) – Convergence status: 0 = success, -1 = failure.

  • peak_drift (np.ndarray) – Peak inter-storey drift ratio per storey, shape (n_storeys, 2). Col 0 = X, col 1 = Y. Full sequence.

  • peak_accel (np.ndarray) – Peak absolute floor acceleration (g) per node (base + floors), shape (n_nodes, 2). Col 0 = X, col 1 = Y. Full sequence.

  • max_peak_drift (float) – Maximum peak inter-storey drift ratio across all storeys and directions (full sequence).

  • max_peak_drift_dir (str) – Direction (‘X’ or ‘Y’) of the maximum peak drift.

  • max_peak_drift_loc (int) – Storey number (1-based) of the maximum peak drift.

  • max_peak_accel (float) – Maximum peak absolute floor acceleration (g).

  • max_peak_accel_dir (str) – Direction (‘X’ or ‘Y’) of the maximum peak accel.

  • max_peak_accel_loc (int) – Floor number (0-based, 0 = base) of the maximum peak acceleration.

  • peak_disp (np.ndarray) – Peak relative displacement (m) per node, shape (n_nodes, 2).

  • hysteretic_energy_per_storey (np.ndarray) – Dissipated hysteretic energy per storey (kN·m), shape (n_storeys,). Full sequence.

  • total_hysteretic_energy (float) – Total dissipated hysteretic energy (kN·m). Full sequence.

  • hysteretic_energy_per_storey_per_sequence – list of np.ndarray Per-sequence dissipated hysteretic energy per storey (kN·m), each of shape (n_storeys,). For a two-record sequence these correspond to the original G1 and G2 outputs.

  • total_hysteretic_energy_per_sequence (list of float) – Per-sequence total dissipated hysteretic energy (kN·m).

  • max_peak_drift_per_sequence (list of float) – Per-sequence maximum peak drift ratio.

  • peak_drift_per_sequence (list of np.ndarray) – Per-sequence peak inter-storey drift ratio, each of shape (n_storeys, 2).

  • n_sequences (int) – Number of individual ground-motion records detected in the concatenated file.

  • sequence_boundaries (list of tuple) – List of (t_start, t_end) pairs (in seconds) defining the time window of each detected ground-motion record (excluding padding).

Theoretical Background

do_nrha_analysis takes a fixed time step. This method instead takes an explicit time_vector, so that records with different sampling rates can be concatenated into a single input (for example a mainshock followed by an aftershock, separated by zero-acceleration padding) and the structure is integrated through the whole sequence, carrying its accumulated damage from one record to the next.

Record detection. Individual records are located automatically as the stretches between quiescent zones, where the absolute acceleration stays below quiescence_threshold for at least padding_duration seconds. Their time windows are returned in sequence_boundaries.

Outputs. Peak drifts, accelerations and hysteretic energies are reported for the full sequence and for each record (peak_drift_per_sequence, max_peak_drift_per_sequence, hysteretic_energy_per_storey_per_sequence, …), so the damage accumulated by the second shock can be separated from the first. Hysteretic energy is the dissipated energy only (signed force–velocity integration), and collapse is detected by both the MinMax material response and an independent nodal-displacement check.

Example

import numpy as np

m.compile_model()
m.do_gravity_analysis()
m.do_modal_analysis(num_modes=2)

# ``sequence.txt``: records separated by >= 40 s of zero acceleration;
# ``time.txt``: the matching (possibly irregular) time values [s]
time_vector = np.loadtxt("time.txt")
results = m.do_nrha_analysis_sequences(
    fnames=["sequence.txt"],
    time_vector=time_vector,
    sf=9.81,                  # records in g
    padding_duration=40.0,
    drift_thresholds=[0.0015, 0.0030, 0.0045, 0.0135],
    save_animation_path=None,
)