Model Building Module

The modeller module provides a class modeller that allows users to create, analyze, and visualize structural models for dynamic and static analyses. The module supports various types of analyses, including gravity analysis, modal analysis, static pushover analysis, cyclic pushover analysis, and nonlinear time-history analysis. The module is built on top of the OpenSees framework, enabling advanced structural analysis capabilities.

Classes

class modeller.modeller(number_storeys, floor_heights, floor_masses, storey_disps, storey_forces, degradation)

A class to model and analyze multi-degree-of-freedom (MDOF) oscillators using OpenSees.

Parameters:

  • number_storeys (int) – The number of storeys in the building model.

  • floor_heights (list) – List of floor heights in meters.

  • floor_masses (list) – List of floor masses in tonnes.

  • storey_disps (np.array) – Array of storey displacements (size = number of storeys, CapPoints).

  • storey_forces (np.array) – Array of storey forces (size = number of storeys, CapPoints).

  • degradation (bool) – Boolean to enable or disable hysteresis degradation.

create_Pinching4_material(mat1Tag, mat2Tag, storey_forces, storey_disps, degradation)

Creates a Pinching4 material model for the MDOF oscillator.

Parameters:

  • mat1Tag (int) – Material tag for the first material in the Pinching4 model.

  • mat2Tag (int) – Material tag for the second material in the Pinching4 model.

  • storey_forces (np.array) – Array of storey forces at each storey in the model.

  • storey_disps (np.array) – Array of storey displacements corresponding to the forces.

  • degradation (bool) – Boolean flag to enable or disable hysteresis degradation.

Returns:

None

Return type:

None

compile_model()

Compiles and sets up the MDOF oscillator model in OpenSees.

Returns:

None

Return type:

None

plot_model(display_info=True)

Plots the 3D visualization of the OpenSees model.

Parameters:

display_info (bool, optional) – If True, displays additional information (coordinates and node ID) next to each node in the plot.

Returns:

None

Return type:

None

do_gravity_analysis(nG=100, ansys_soe='UmfPack', constraints_handler='Transformation', numberer='RCM', test_type='NormDispIncr', init_tol=1.0e-6, init_iter=500, algorithm_type='Newton', integrator='LoadControl', analysis='Static')

Performs gravity analysis on the MDOF system.

Parameters:

  • nG (int, optional) – Number of gravity analysis steps to perform.

  • ansys_soe (string, optional) – The system of equations type to be used in the analysis.

  • constraints_handler (string, optional) – The constraints handler determines how the constraint equations are enforced.

  • numberer (string, optional) – The degree-of-freedom numberer defines how DOFs are numbered.

  • test_type (string, optional) – Defines the test type used to check the convergence of the solution.

  • init_tol (float, optional) – The tolerance criterion for checking convergence.

  • init_iter (int, optional) – The maximum number of iterations to check for convergence.

  • algorithm_type (string, optional) – Defines the solution algorithm used in the analysis.

  • integrator (string, optional) – Defines the integrator for the analysis.

  • analysis (string, optional) – Defines the type of analysis to be performed.

Returns:

None

Return type:

None

do_modal_analysis(num_modes=3, solver='-genBandArpack', doRayleigh=False, pflag=False)

Performs modal analysis to determine natural frequencies and mode shapes.

Parameters:

  • num_modes (int, optional) – The number of modes to consider in the analysis.

  • solver (string, optional) – The type of solver to use for the eigenvalue problem.

  • doRayleigh (bool, optional) – Flag to enable or disable Rayleigh damping in the modal analysis.

  • pflag (bool, optional) – Flag to control whether to print the modal analysis report.

Returns:

Periods of vibration and mode shapes.

Return type:

tuple(np.array, list)

do_spo_analysis(ref_disp, disp_scale_factor, push_dir, phi, pflag=True, num_steps=200, ansys_soe='BandGeneral', constraints_handler='Transformation', numberer='RCM', test_type='EnergyIncr', init_tol=1.0e-5, init_iter=1000, algorithm_type='KrylovNewton')

Performs static pushover analysis (SPO) on the MDOF system.

Parameters:

  • ref_disp (float) – The reference displacement at which the analysis starts.

  • disp_scale_factor (float) – The scale factor applied to the reference displacement.

  • push_dir (int) – The direction in which the pushover load is applied.

  • phi (list of floats) – The lateral load pattern shape.

  • pflag (bool, optional) – Flag to print (or not) the pushover analysis steps.

  • num_steps (int, optional) – The number of steps to increment the pushover load.

  • ansys_soe (string, optional) – The type of system of equations solver to use.

  • constraints_handler (string, optional) – The constraints handler object to determine how constraint equations are enforced.

  • numberer (string, optional) – The degree-of-freedom (DOF) numberer object.

  • test_type (string, optional) – The type of test to use for the linear system of equations.

  • init_tol (float, optional) – The tolerance criterion to check for convergence.

  • init_iter (int, optional) – The maximum number of iterations to perform when checking for convergence.

  • algorithm_type (string, optional) – The type of algorithm used to solve the system.

Returns:

Displacements, base shear, and spring forces.

Return type:

tuple(np.array, np.array, np.array, np.array)

do_cpo_analysis(ref_disp, mu, numCycles, push_dir, dispIncr, pflag=True, num_steps=200, ansys_soe='BandGeneral', constraints_handler='Transformation', numberer='RCM', test_type='NormDispIncr', init_tol=1.0e-5, init_iter=1000, algorithm_type='KrylovNewton')

Performs cyclic pushover analysis (CPO) on the MDOF system.

Parameters:

  • ref_disp (float) – Reference displacement for the pushover analysis.

  • mu (float) – Target ductility factor.

  • numCycles (int) – The number of displacement cycles to be performed.

  • push_dir (int) – Direction of the pushover analysis.

  • dispIncr (float) – The number of displacement increments for each loading cycle.

  • pflag (bool, optional) – Flag to print feedback during the analysis steps.

  • num_steps (int, optional) – The number of steps for the cyclic pushover analysis.

  • ansys_soe (string, optional) – System of equations solver to be used for the analysis.

  • constraints_handler (string, optional) – The method used for handling constraint equations.

  • numberer (string, optional) – The numberer method used to assign equation numbers to degrees of freedom.

  • test_type (string, optional) – The type of test to be used for convergence in the solution of the linear system of equations.

  • init_tol (float, optional) – The initial tolerance for convergence.

  • init_iter (int, optional) – The maximum number of iterations for the solver to check convergence.

  • algorithm_type (string, optional) – The type of algorithm used to solve the system of equations.

Returns:

Displacements and base shear.

Return type:

tuple(np.array, np.array)

do_nrha_analysis(fnames, dt_gm, sf, t_max, dt_ansys, nrha_outdir, 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')

Performs nonlinear time-history analysis (NRHA) on the MDOF system.

Parameters:

  • fnames (list) – List of file paths to the ground motion records for each direction (X, Y, Z).

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

  • sf (float) – Scale factor to apply to the ground motion records.

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

  • dt_ansys (float) – The time-step at which the analysis will be conducted.

  • nrha_outdir (string) – Directory where temporary output files are saved during the analysis.

  • pflag (bool, optional) – Flag to print progress updates during the analysis.

  • xi (float, optional) – The inherent damping ratio used in the analysis.

  • ansys_soe (string, optional) – Type of the system of equations solver to be used in the analysis.

  • constraints_handler (string, optional) – The method used to handle constraints in the analysis.

  • numberer (string, optional) – The numberer object determines the equation numbering used in the analysis.

  • test_type (string, optional) – Type of convergence test used during the analysis.

  • init_tol (float, optional) – Initial tolerance for the convergence test.

  • init_iter (int, optional) – Maximum number of iterations allowed during each time step for the analysis to converge.

  • algorithm_type (string, optional) – Type of algorithm used to solve the system of equations.

Returns:

Control nodes, convergence status, peak drifts, peak accelerations, and peak displacements.

Return type:

tuple(list, int, np.array, np.array, float, string, int, float, string, int, np.array)

References

  1. Minjie, Zhu. McKenna, F. and Scott, M.H. (2018). “OpenSeesPy: Python library for the OpenSees finite element framework”, SoftwareX, Volume 7, 2018, Pages 6-11, ISSN 2352-7110, https://doi.org/10.1016/j.softx.2017.10.009.