6.7. Nonlinear Time-History Analysis

modeller.do_nrha_analysis(fnames, dt_gm, sf, t_max, dt_ansys, 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)[source]

Perform nonlinear time-history analysis on a Multi-Degree-of-Freedom (MDOF) system.

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, which is physically correct for assessing acceleration-sensitive non-structural components. Hysteretic energy dissipation is computed via signed force-velocity integration (trapezoidal rule), correctly capturing only dissipated energy and not elastic recovery.

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.

  • dt_gm (float) – Time-step of the ground motion records.

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

  • t_max (float) – The maximum time duration for the analysis.

  • dt_ansys (float) – The integration time-step for the analysis. Typically smaller than dt_gm.

  • 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 (string, optional, default='BandGeneral') – System of equations solver type.

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

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

  • test_type (string, 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 (string, optional, default='Newton') – Nonlinear solution algorithm.

  • save_animation_path (string, 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.

Returns:

  • control_nodes (list) – List of all node tags in the model (base node first, then floor nodes).

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

  • peak_drift (numpy.ndarray) – Peak inter-storey drift ratio per storey, shape (n_storeys, 2). Column 0 = X, column 1 = Y direction.

  • peak_accel (numpy.ndarray) – Peak absolute floor acceleration (in g) per node (base + floors), shape (n_nodes, 2). Column 0 = X, column 1 = Y direction. Row 0 is the base (ground motion PGA).

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

  • max_peak_drift_dir (string) – 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) across all floors and directions.

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

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

  • peak_disp (numpy.ndarray) – Peak relative displacement (m) per node, shape (n_nodes, 2). Column 0 = X, column 1 = Y.

  • hysteretic_energy_per_storey (numpy.ndarray) – Dissipated hysteretic energy per storey (kN·m), shape (n_storeys,). Computed via signed F·v trapezoidal integration to capture only true energy dissipation (not elastic strain energy recovery).

  • total_hysteretic_energy (float) – Total dissipated hysteretic energy summed across all storeys (kN·m).