simdesign.rcmrf.bnsm.baselib.building

This module provides a base class for Building Nonlinear Structural Models (BNSM) to build and export their OpenSees representations.

class simdesign.rcmrf.bnsm.baselib.building.BuildingBase(design, load_factors={'G': 1.0, 'Q': 0.3}, mass_factors={'G': 1.0, 'Q': 0.3}, scheme='EQL', max_drift=0.05, dincr=0.001, include_infills=True, cyclic_model=False, cracked_beam=None, cracked_column=None, beam_loads='auto')[source]

Bases: ABC

Abstract Base Class for Building Nonlinear Structural Model (BNSM) implementations. It provides methods to define a BNSM in the OpenSees domain and to export equivalent Python and Tcl commands.

Parameters:

  • design (BuildingBase)

  • load_factors (Dict[Literal['G', 'Q'], float])

  • mass_factors (Dict[Literal['G', 'Q'], float])

  • scheme (Literal['FMP', 'EQL', 'MPP', 'TRI', 'UNI'])

  • max_drift (float)

  • dincr (float)

  • include_infills (bool)

  • cyclic_model (bool)

  • cracked_beam (bool | float | None)

  • cracked_column (bool | float | None)

  • beam_loads (Literal['auto', 'uniform', 'point'])

design

Instance of building design information model.

Type:

BuildingBase

foundations

List of foundation instances.

Type:

List[FoundationBase]

floors

List of floor instances.

Type:

List[FloorDiaphragmBase]

floor_joints

List of floor joints instances.

Type:

List[FloorJointBase]

stairs_joints

List of stairs joints instances.

Type:

List[StairsJointBase]

beams

List of beam instances.

Type:

List[BeamBase]

columns

List of column instances.

Type:

List[ColumnBase]

infills

List of infill instances.

Type:

List[InfillBase]

FoundationClass

Foundation class used to instantiate foundation objects.

Type:

type[FoundationBase]

FloorClass

Floor diaphragm class used to instantiate floor objects.

Type:

type[FloorDiaphragmBase]

FloorJointClass

Floor-joint class used to instantiate floor joint objects.

Type:

type[FloorJointBase]

StairsJointClass

Stairs-joint class used to instantiate stairs joint objects.

Type:

type[StairsJointBase]

BeamClass

Beam class used by the building factory to instantiate beam objects.

Type:

type[BeamBase]

ColumnClass

Column class used by the building factory to instantiate column objects.

Type:

type[ColumnBas]

InfillClass

Infill class used to instantiate infill wall objects.

Type:

type[InfillBase]

load_factors

Load factors used to compute gravity loads. - ‘G’ : Permanent load factor - ‘Q’ : Variable load factor

Type:

Dict[Literal[‘G’, ‘Q’], float]

mass_sources

Mass sources used to compute seismic masses. - ‘G’ : Permanent mass factor - ‘Q’ : Variable mass factor

Type:

Dict[Literal[‘G’, ‘Q’], float]

basic_masses

Point masses for the basic building geometry.

Type:

np.ndarray

scheme

The loading scheme considered for retriving pushover loads. - ‘FMP : Fundamental-mode proportional loading. - ‘EQL : Equivalent lateral loading. - ‘MPP : Mass proportional loading. - ‘TRI : Triangular or height propotional loading. - ‘UNI : Uniform loading.

Type:

Literal[‘FMP’, ‘EQL’, ‘MPP’, ‘TRI’, ‘UNI’]

max_drift

The drift value used to calculate maximum disp. of control node.

Type:

float

dincr

First displacement increment considered during nspa.

Type:

float

include_infills

Flag to check whether include infills in the frame model or not.

Type:

bool

cyclic_model

If True, the model parameters will be adjusted for cyclic analysis.

Type:

bool

cracked_beam

Cracked-section (effective) flexural properties of the elastic beam sections: True for My / phi_y of the plastic hinges, or a float as the ratio of effective to gross stiffness. If None or False, gross-section properties are used.

Type:

None | bool | float

cracked_column

Cracked-section (effective) flexural properties of the elastic column sections: True for My / phi_y of the plastic hinges, or a float as the ratio of effective to gross stiffness. If None or False, gross-section properties are used.

Type:

None | bool | float

beam_loads

How the beam gravity loads are applied: ‘uniform’ element loads, ‘point’ loads at the beam element ends, or ‘auto’ (‘point’ if the beam-column joints are inelastic, ‘uniform’ otherwise).

Type:

Literal[‘auto’, ‘uniform’, ‘point’]

property beam_load_type: Literal['uniform', 'point']

How the beam gravity loads are applied, with ‘auto’ resolved from the flexibility model of the floor joints.

Returns:

‘point’ if beam_loads='auto' and the joints are inelastic, ‘uniform’ if beam_loads='auto' otherwise, else beam_loads.

Return type:

Literal[‘uniform’, ‘point’]

build()[source]

Adds the numerical model to the OpenSees domain.

Return type:

None

do_modal(num_modes=3, out_dir=None, print_screen=False, normalisation=True)[source]

Performs modal analysis.

Parameters:

  • num_modes (int, optional) – Number of modes for whose properties are calculated. By default 3.

  • out_dir (bool, optional) – Output directory to save the modal properties and eigen vectors for the floor retained nodes. If None, these are not saved. By default None.

  • print_screen (bool, optional) – Flag to print modal properties on the screen. By default False.

  • normalisation (bool, optional) – Flag to compute the modal properties by using a displacement-normalized version of the eigenvectors. By default True.

Returns:

Dictionary containing modal properties. The per-mode entries (eigen* and parti*) are given for the first num_modes modes.

Return type:

Dict[str, List[float]]

Notes

At least MIN_EIGEN_MODES modes are solved for, because the default ARPACK solver may not converge for a single eigenvalue and then returns unset values (e.g. periods of 1e157 s). Eigenvalues below MIN_EIGEN_VALUE are taken as unset, and the next solver is tried. The modal properties file written to out_dir contains all solved modes.

TODO

For now print screen does not work.

do_nspa(ctrl_dof, out_dir=None, use_recorder=False)[source]

Performs nonlinear static pushover analysis (NSPA).

Parameters:

  • ctrl_dof (Literal[1, 2]) – Control degrees of freedom for loading. 1: X-direction. 2: Y-direction.

  • out_dir (str | Path, optional) – Directory to save outputs. If None, no output is saved. By default None.

  • use_recorder (bool, optional) – If True, OpenSees recorders are used. By default False.

Returns:

  • ctrl_disp (List[float]) – Displacement values of control node.

  • base_shear (List[float]) – Base shear value obtained as sum of the reaction forces.

  • ok (int) – 0 if the analysis ends at the target displacement (max_drift) or after a loss of strength, i.e., a converged step with a base shear below 60% of the maximum (recorded). Negative if it stops earlier (see Notes).

Return type:

Tuple[List[float], List[float], int]

Notes

A step that fails is repeated with alternative algorithms, smaller displacement increments and, as a last resort, relaxed tolerances. The analysis stops before the target displacement, with ok negative, if no step converges, if a step is out of equilibrium (base shear differing from the applied load by more than NSPA_EQUILIBRIUM_TOL), if the tangent stiffness of a step exceeds NSPA_MAX_STIFFNESS_RATIO times the initial stiffness, or if the base shear reaches 1.5 times the seismic weight. The exported nspa.py and nspa.tcl do not include the equilibrium and stiffness checks.

to_py(directory)[source]

Exports the numerical model files in Python format.

Parameters:

directory (Path | str) – Directory in which the files will be written.

Return type:

None

to_tcl(directory)[source]

Exports the numerical model files in Tcl format.

Parameters:

directory (Path | str) – Directory in which the files will be written.

Return type:

None

plot_model(show_nodes='yes', line_width=3, directory=None, show=True)[source]

Plots the structural model, showing nodes and elements grouped by type (nodes, beams, columns, infills).

Parameters:

  • show_nodes (Literal['no', 'yes'], optional) – A flag to control whether to display the nodes in the plot. ‘yes’ to show the nodes, ‘no’ to hide them. By default ‘yes’.

  • line_width (float, optional) – Specifies the line width used to draw the elements in the plot. By default 3.

  • directory (str | Path | None, optional) – Directory to save an image of the model. If None, the image will not be saved. By default None.

  • show (bool, optional) – Flag for showing the figure in an interactive window, by default True.

Return type:

None

plot_mode_shape(mode_number=1, scale=100, line_width=3, contour=None, set_view='3D', directory=None, show=True)[source]

Plots the mode shape of the structure for a given mode number, scaled for visual clarity.

Parameters:

  • mode_number (int, optional) – Specifies the mode number to be plotted. By default 1.

  • scale (float, optional) – A scaling factor to exaggerate the mode shape for better visualization. By default 100.

  • line_width (float, optional) – Specifies the line width used to draw the mode shape. By default 3.

  • contour (Literal['x', 'y', 'z'] | None, optional) – Contours of displacement in x, y, or z. By default None.

  • set_view (Literal['xy', 'yz', 'xz', '3D'], optional) – Camera view plane. By default ‘3D’ (isometric).

  • directory (str | Path | None, optional) – Directory to save an image of the model. If None, the image will not be saved. By default None.

  • show (bool, optional) – Flag for showing the figure in an interactive window, by default True.

Return type:

None