API Reference

SDF

class structdyn.sdf.sdf.SDF(m, k, ji=0, fd=None)

Bases: object

Single Degree of Freedom (SDF) System for Structural Dynamics

find_response(time, load, method='newmark_beta', **kwargs)

Computes the dynamic response of the SDF system.

Solves the equation of motion: m u’’ + c u’ + f_s(u) = p(t).

Parameters:

• time (array-like) – Array of time points.

• load (array-like) – Array of generalized force values at each time point.

• method (str, optional) – Numerical method for solving the equation of motion, by default “newmark_beta”. Available methods: ‘newmark_beta’, ‘central_difference’, ‘interpolation’.

• **kwargs (dict, optional) – Additional parameters for the numerical solver.

Returns:

A DataFrame containing the time history of the system’s response (e.g., displacement, velocity, acceleration).

Return type:

pandas.DataFrame

find_response_ground_motion(gm, method='newmark_beta', **kwargs)

Computes the response of the SDF system to ground motion.

Solves the equation of motion for a base-excited system subjected to ground motion.

Parameters:

• gm (GroundMotion) – A GroundMotion object representing the ground motion record.

• method (str, optional) – Numerical method to use, by default “newmark_beta”.

• **kwargs (dict, optional) – Additional parameters for the numerical solver.

Returns:

A DataFrame containing the time history of the system’s response.

Return type:

pandas.DataFrame

property plot

Provides access to visualization methods for the SDF system.

Returns:

An instance of the SDFVisualizer class, which can be used to generate plots and animations of the system.

Return type:

SDFVisualizer

Analytical Response

class structdyn.sdf.analytical_methods.analytical_response.AnalyticalResponse(sdf)

Bases: object

Provides analytical solutions for the dynamic response of a linear SDF system.

This class is applicable to underdamped linear systems (0 <= ji < 1). It serves as a tool for verification against numerical methods and for solving classical problems with known closed-form solutions, such as free vibration and harmonic (sine or cosine) excitation.

free_vibration(u0, v0=0, time=None)

Calculates the free vibration response of the underdamped system.

Parameters:

• u0 (float) – Initial displacement at time t=0.

• v0 (float, optional) – Initial velocity at time t=0, by default 0.

• time (array-like, optional) – The time vector for the analysis. If None, a default vector is generated covering 10 natural periods with 100 steps per period.

Returns:

A DataFrame with the time history of the response, including columns: ‘time’, ‘displacement’, ‘velocity’, and ‘acceleration’.

Return type:

pandas.DataFrame

harmonic_response(p0, w, u0=0.0, v0=0.0, time=None, excitation='sine')

Calculates the response to a harmonic forcing function p(t).

The forcing function can be either p(t) = p0 * sin(wt) or p(t) = p0 * cos(wt).

Parameters:

• p0 (float) – Amplitude of the harmonic force.

• w (float) – Frequency of the harmonic force in radians per second.

• u0 (float, optional) – Initial displacement at time t=0, by default 0.0.

• v0 (float, optional) – Initial velocity at time t=0, by default 0.0.

• time (array-like, optional) – The time vector for the analysis. If None, a default vector is generated covering 10 natural periods.

• excitation ({"sine", "cosine"}, optional) – Type of the harmonic excitation, by default “sine”.

Returns:

A DataFrame with the time history of the response, including columns: ‘time’, ‘displacement’, ‘velocity’, and ‘acceleration’.

Return type:

pandas.DataFrame

Numerical Methods

class structdyn.sdf.numerical_methods.central_difference.CentralDifference(sdf, dt, u0=0.0, v0=0.0)

Bases: object

Implements the Central Difference Method for solving the equation of motion for an SDF system.

This method is an explicit time-stepping algorithm suitable for both linear and nonlinear Single Degree of Freedom (SDF) systems. It is conditionally stable and requires the time step dt to be smaller than a critical value (dt_crit = T_n / pi).

compute_solution(time, p)

Executes the time-stepping solution.

This method iterates through the time vector, calculating the displacement, velocity, and acceleration of the system at each step.

Parameters:

• time (array-like) – An array representing the time vector of the analysis.

• p (array-like) – An array representing the external force applied at each time step.

Returns:

A DataFrame containing the full time history of the response, including: - ‘time’: Time points. - ‘displacement’: Displacement at each time point. - ‘velocity’: Velocity at each time point. - ‘acceleration’: Acceleration at each time point. - ‘resisting_force’: Internal resisting force at each time point.

Return type:

pandas.DataFrame

class structdyn.sdf.numerical_methods.newmark_beta.NewmarkBeta(sdf, dt, u0=0.0, v0=0.0, acc_type='linear')

Bases: object

Implements the Newmark-Beta time integration scheme for solving the equation of motion for both linear and nonlinear Single Degree of Freedom (SDF) systems.

This class provides a robust and widely used numerical method for dynamic analysis. It supports both the constant-average-acceleration and the linear-acceleration methods.

Reference: Chopra, A. K. (2020). Dynamics of Structures: Theory and Applications to Earthquake Engineering. Pearson Education. (See Table 5.4.2 for linear systems and Table 5.7.1 for nonlinear systems)

compute_solution(time_steps, load_values)

Computes the dynamic response by dispatching to the appropriate solver based on the system’s linearity.

Parameters:

• time_steps (array-like) – An array representing the time vector of the analysis.

• load_values (array-like) – An array representing the external force applied at each time step.

Returns:

A DataFrame containing the time history of the response.

Return type:

pandas.DataFrame

compute_solution_linear(time_steps, load_values)

Computes the response of a linear system using the Newmark-Beta method.

Parameters:

• time_steps (array-like) – Time discretization.

• load_values (array-like) – External force p(t) at each time step.

Returns:

Time history of displacement, velocity, and acceleration.

Return type:

pandas.DataFrame

compute_solution_nonlinear(time_steps, load_values, tol=1e-06, max_iter=50)

Computes the response of a nonlinear system using the Newmark-Beta method with a Newton-Raphson iteration scheme.

Parameters:

• time_steps (array-like) – Time discretization.

• load_values (array-like) – External force p(t) at each time step.

• tol (float, optional) – Tolerance for the convergence of the Newton-Raphson iteration, by default 1e-6.

• max_iter (int, optional) – Maximum number of iterations for the Newton-Raphson algorithm, by default 20.

Returns:

Time history of displacement, velocity, and acceleration.

Return type:

pandas.DataFrame

Raises:

RuntimeError – If the Newton-Raphson iteration fails to converge.

structdyn.sdf.numerical_methods.newmark_beta.get_newmark_parameters(acc_type='linear')

Returns Newmark-beta parameters (beta, gamma).

Parameters:

acc_type (str) – ‘average’ : Constant-average acceleration (unconditionally stable) ‘linear’ : Linear acceleration

class structdyn.sdf.numerical_methods.interpolation.Interpolation(sdf, dt)

Bases: object

Solves the equation of motion for a linear SDOF system using an exact integration method assuming linear interpolation of the excitation force.

This method is based on the recurrence formulas derived from the exact solution of the differential equation for a given time step. It is unconditionally stable and highly accurate for linear systems.

Reference: Chopra, A. K. (2020). Dynamics of Structures: Theory and Applications to Earthquake Engineering. Pearson Education. (See Eq. 5.2.5a-b and Table 5.2.1 for ji < 1)

compute_solution(time, p, u0=0.0, v0=0.0)

Performs the time-stepping solution using the pre-computed coefficients.

Parameters:

• time (array-like) – An array representing the time vector of the analysis.

• p (array-like) – An array representing the external force applied at each time step.

• u0 (float, optional) – Initial displacement at time t=0, by default 0.0.

• v0 (float, optional) – Initial velocity at time t=0, by default 0.0.

Returns:

A DataFrame containing the full time history of the response, including: - ‘time’: Time points. - ‘displacement’: Displacement at each time point. - ‘velocity’: Velocity at each time point. - ‘acceleration’: Acceleration at each time point. - ‘resisting_force’: Internal resisting force at each time point.

Return type:

pandas.DataFrame

Visualization (SDF)

class structdyn.sdf.sdf_helpers.visualization.SDFVisualizer(sdf, tower_height=5.0, mass_size=(1.0, 0.5))

Bases: object

Provides methods for visualizing a Single-Degree-of-Freedom (SDF) system.

This class is not intended to be instantiated directly. Instead, it should be accessed through the plot property of an SDF instance (e.g., sdf.plot.structure()) which will be added in a subsequent step.

animate_response(response_df, scale_factor=1.0, ground_motion=None, speed_up=1.0, repeat=True, save_path=None)

Animates the dynamic response of the SDF system.

Parameters:

• response_df (pandas.DataFrame) – The response DataFrame from a solver. Must contain ‘time’ and ‘displacement’ columns.

• scale_factor (float, optional) – Factor to scale displacements for visualization, by default 1.0.

• ground_motion (tuple, optional) – Tuple (time, acceleration) for the ground motion history. If provided, a plot of the ground motion is shown below the animation. By default None.

• speed_up (float, optional) – Factor to speed up the animation, by default 1.0.

• repeat (bool, optional) – Whether the animation should repeat when finished, by default True.

• save_path (str, optional) – File path to save the animation (e.g., ‘animation.mp4’). If provided, the animation is saved instead of being shown. By default None.

plot_system()

Plots the undeformed SDF system.

Ground Motion

class structdyn.ground_motions.ground_motion.GroundMotion(acc_g, dt, name=None, component=None)

Bases: object

Represents a ground motion acceleration time history.

This class provides a container for ground motion data, typically acceleration time histories. It includes methods for reading data from common file formats (like AT2), scaling the motion, and accessing its properties.

acc_g

The acceleration time history in units of g (acceleration due to gravity).

Type:

numpy.ndarray

dt

The time step of the acceleration data.

Type:

float

time

The time vector corresponding to the acceleration data.

Type:

numpy.ndarray

name

A name for the ground motion event.

Type:

str, optional

component

The component of the ground motion (e.g., ‘h1’, ‘h2’, ‘v’).

Type:

str, optional

classmethod from_arrays(acc_g, dt, name='user_motion')

Creates a GroundMotion object directly from arrays.

Parameters:

• acc_g (array-like) – Acceleration time history in units of g.

• dt (float) – Time step of the acceleration data.

• name (str, optional) – A name for the motion, by default “user_motion”.

Returns:

A new GroundMotion instance.

Return type:

GroundMotion

classmethod from_at2(file_path)

Creates a GroundMotion object from a PEER NGA (AT2) file.

Parameters:

file_path (str or pathlib.Path) – The path to the .AT2 file.

Returns:

A new GroundMotion instance with data from the file.

Return type:

GroundMotion

classmethod from_event(event_name, component='hor1', base_dir=None)

Loads a ground motion from the built-in event database.

Parameters:

• event_name (str) – The name of the earthquake event. Currently available are (e.g., ‘imperialValley_elCentro_1940’, ‘lomaPrieta_corralitos_1989’, ‘northridge_sylmar_1994’, ‘sanFernando_pacoidaDam_1971’ ).

• component (str) – The specific component to load (e.g., ‘hor1’, ‘hor2’, ‘up’).

• base_dir (str or pathlib.Path, optional) – The base directory of the ground motion data. If None, it uses the package’s default data directory.

Returns:

A new GroundMotion instance for the specified event and component.

Return type:

GroundMotion

Raises:

FileNotFoundError – If the specified event or component is not found.

scale(factor)

scale_to_pga(target_pga_g)

to_dataframe()

Response Spectrum (SDF)

class structdyn.sdf.response_spectrum.ResponseSpectrum(periods, damping_ratio, ground_motion, method='interpolation')

Bases: object

Generates a linear elastic response spectrum for a given ground motion.

This class calculates the displacement, pseudo-velocity, and pseudo-acceleration response spectra for a range of periods and a specified damping ratio.

compute()

Computes the response spectrum.

This method iterates through the specified periods, creates an SDF system for each, and calculates the peak displacement response to the ground motion. It then computes the pseudo-velocity and pseudo-acceleration spectra.

Returns:

A DataFrame containing the response spectrum, with columns for period (T), spectral displacement (Sd), pseudo-spectral velocity (pSv), and pseudo-spectral acceleration in g (pSa (g)).

Return type:

pandas.DataFrame

MDF

class structdyn.mdf.mdf.MDF(M, K, C=None, elements=None)

Bases: object

Represents a linear Multi-Degree-of-Freedom (MDF) system.

This class defines a structural system with multiple degrees of freedom governed by the second-order linear differential equation:

M ü + C u̇ + K u = f(t)

where: - M is the mass matrix - C is the damping matrix - K is the stiffness matrix - u is the displacement vector - f(t) is the external force vector

Parameters:

• M ((n, n) array-like) – The mass matrix of the system.

• K ((n, n) array-like) – The stiffness matrix of the system.

• C ((n, n) array-like, optional) – The damping matrix. If not provided, it is initialized as a zero matrix.

assemble_resisting_force_and_tangent(u, v, dt)

Assembles the global resisting force and tangent stiffness matrix.

This method is called by a non-linear solver at each iteration within a time step. It iterates through all elements defined in self.elements, gets their trial force and stiffness, and assembles them into the global resisting force vector Fs and tangent stiffness matrix Kt.

Parameters:

• u (np.ndarray) – The trial displacement vector for the current iteration.

• v (np.ndarray) – The trial velocity vector for the current iteration.

• dt (float) – The time step size.

Returns:

• Fs (np.ndarray) – The global internal resisting force vector.

• Kt (np.ndarray) – The global tangent stiffness matrix.

commit_elements(u)

Commits the state of all non-linear elements.

This method is called by a non-linear solver at the end of a converged time step. It iterates through all elements and calls their commit method, passing the final converged displacement vector u. This allows each element to update its internal history variables.

Parameters:

u (np.ndarray) – The converged displacement vector for the time step.

find_response(time, load, method='central_difference', elements=None, **kwargs)

Computes the dynamic response of the system to an external force.

Parameters:

• time (array-like) – A uniformly spaced time vector.

• load ((nt, ndof) ndarray) – The external force history, where nt is the number of time steps and ndof is the number of degrees of freedom.

• method (str, optional) – The numerical integration method to use. Options are ‘central_difference’ or ‘newmark_beta’. The default is “central_difference”.

• **kwargs – Additional keyword arguments to be passed to the numerical solver.

Returns:

A pandas DataFrame containing the displacement, velocity, and acceleration response history.

Return type:

DataFrame

find_response_ground_motion(gm, inf_vec=None, method='central_difference', **kwargs)

Computes the dynamic response of the system to ground motion.

Parameters:

• gm (GroundMotion) – A GroundMotion object containing the ground acceleration history.

• inf_vec (array-like, optional) – The influence vector, which relates the ground motion to the degrees of freedom. If None, it is assumed to be a vector of ones (all DOFs are equally affected). The default is None.

• method (str, optional) – The numerical integration method to use. Options are ‘central_difference’ or ‘newmark_beta’. The default is “central_difference”.

• **kwargs – Additional keyword arguments to be passed to the numerical solver.

Returns:

A pandas DataFrame containing the displacement, velocity, and acceleration response history.

Return type:

DataFrame

classmethod from_shear_building(masses, stiffnesses)

Creates an MDF system representing a shear building model.

Parameters:

• masses (list or array) – A list of lumped masses at each floor, starting from the bottom floor.

• stiffnesses (list or array) – A list of story stiffnesses, starting from the bottom story. The length must be equal to the number of masses.

Returns:

A new MDF instance representing the shear building.

Return type:

MDF

property plot

Provides access to plotting methods for the shear building.

set_modal_damping(zeta, n_modes=None)

Sets the damping matrix C based on modal damping ratios (Rayleigh damping).

This method constructs a classical damping matrix C using the natural frequencies and mode shapes of the undamped system.

Parameters:

• zeta (array-like) – An array or list of modal damping ratios for the modes to be included.

• n_modes (int, optional) – The number of modes to use for constructing the damping matrix. If None, all modes are used. The default is None.

Returns:

C – The resulting (n, n) damping matrix.

Return type:

ndarray

Modal Analysis

class structdyn.mdf.analytical_methods.modal_analysis.ModalAnalysis(mdf)

Bases: object

Performs modal analysis of a multi-degree-of-freedom system.

This class solves the eigenvalue problem to determine the natural frequencies and mode shapes of a system. It also provides methods for normalizing mode shapes, calculating modal coordinates, and determining the response of the system to free vibration.

free_vibration_response(u0, v0, time=None, n_modes=None)

Calculates the free vibration response of the system.

Parameters:

• u0 (array-like) – Initial displacement vector.

• v0 (array-like) – Initial velocity vector.

• time (array-like, optional) – Time vector. If None, a default time vector is used. The default is None.

• n_modes (int, optional) – The number of modes to use in the analysis. If None, all modes are used. The default is None.

Returns:

df – A pandas DataFrame containing the time history of the displacement of each degree of freedom.

Return type:

DataFrame

get_Mn_Cn_Kn()

Calculates the generalized modal mass, damping, and stiffness matrices.

The modal matrices are stored in the instance variables self.Mn_full, self.Cn_full, and self.Kn_full.

mass_normalize_modes()

Mass-normalize mode shapes such that φᵀ M φ = I.

Returns:

phi – The mass-normalized mode shape matrix.

Return type:

ndarray

modal_analysis(n_modes=None, dof_normalize=None)

Solves the eigenvalue problem K φ = λ M φ to find the natural frequencies and mode shapes.

The natural frequencies and mode shapes are stored in the instance variables self.omega and self.phi.

Parameters:

• n_modes (int, optional) – The number of modes to compute. If None, all modes are computed. The default is None.

• dof_normalize (int, optional) – The degree of freedom to use for normalization. If None, the modes are not normalized. The default is None.

Returns:

• omega (ndarray) – Natural circular frequencies (rad/s)

• phi (ndarray) – Mode shape matrix (columns are modes)

modal_coordinates(u)

Calculates the modal coordinates for a given displacement vector.

Parameters:

u (ndarray) – The displacement vector.

Returns:

qn – The modal coordinates.

Return type:

ndarray

normalize_modes(dof=-1)

Normalize the mode shapes with respect to a specific degree of freedom.

Parameters:

dof (int, optional) – The degree of freedom to normalize to. The default is -1 (the last dof).

Returns:

phi – The normalized mode shape matrix.

Return type:

ndarray

Response Spectrum Analysis (MDF)

class structdyn.mdf.analytical_methods.response_spectrum_analysis.ResponseSpectrumAnalysis(mdf, ji=0.05, n_modes=None, gm=None, Sd=None)

Bases: object

Performs Response Spectrum Analysis (RSA) for a given MDOF system.

This class first computes the modal properties (natural frequencies, mode shapes, participation factors) of the structure. It then uses a design response spectrum to determine the peak response (displacements, forces) for each mode.

mdf

The multi-degree-of-freedom system object to be analyzed.

Type:

MDOF_System

ji

The modal damping ratio (e.g., 0.05 for 5%).

Type:

float

n_modes

The number of modes to consider in the analysis.

Type:

int

gm

A GroundMotion object used to generate the response spectrum internally. Provide this OR Sd. The default is None.

Type:

GroundMotion, optional

Sd

An array of pre-computed spectral displacement values corresponding to the system’s modal periods. The order must match the periods from lowest to highest. Provide this OR gm. The default is None.

Type:

array-like, optional

combine_modal_responses(responses, method='SRSS')

Combines peak modal responses to estimate the total response.

Parameters:

• responses (np.ndarray) – An array where each column represents the peak response of a mode. For example, the output from modal_displacements.

• method (str, optional) – The modal combination rule to use. Currently supported: ‘SRSS’. The default is “SRSS”.

Returns:

A 1D array of the combined response, with length ndof.

Return type:

np.ndarray

compute_modal_participation_factors()

compute_spectral_displacement(T)

modal_base_shear()

Calculates the base shear for each individual mode.

Returns:

A 1D array of shape (n_modes,) where each element is the base shear for the corresponding mode.

Return type:

np.ndarray

modal_diplacements(Sd=None)

Calculates the peak modal displacements for each mode.

Each column in the returned array represents the peak displacement vector for the corresponding mode.

Parameters:

Sd (array-like, optional) – Can be provided here if not given during initialization. The default is None.

Returns:

An array of shape (ndof, n_modes) containing the peak modal displacements.

Return type:

np.ndarray

modal_equivalent_forces()

Calculates the peak equivalent static forces for each mode.

These forces, when applied statically to the structure, would produce the same peak modal displacements.

Returns:

An array of shape (ndof, n_modes) containing the peak modal equivalent static forces.

Return type:

np.ndarray

plot_response_spectrum()

Numerical Methods

class structdyn.mdf.numerical_methods.central_difference.CentralDifferenceMDF(mdf, dt, u0=None, v0=None, use_modal=False, n_modes=None)

Bases: object

Solves the equation of motion for a linear MDOF system using the Central Difference method.

This class implements the explicit, conditionally stable Central Difference time integration algorithm. The integration can be performed either in the physical coordinates of the system or in modal coordinates, which can be more efficient for systems where the response is dominated by a few modes.

compute_solution(time, P)

Integrates the equations of motion over the given time and force history.

Parameters:

• time (array-like) – An array of time points of shape (nt,).

• P (array-like) – The external force history as an array of shape (nt, ndof).

Returns:

A DataFrame containing the response history. The columns include: - ‘time’: The time points. - ‘u1’, ‘u2’, …: Displacement for each degree of freedom. - ‘v1’, ‘v2’, …: Velocity for each degree of freedom. - ‘a1’, ‘a2’, …: Acceleration for each degree of freedom.

Return type:

pd.DataFrame

Raises:

ValueError – If the shape of the force array P is not compatible with the time vector and the number of DOFs. If use_modal is True and the requested number of modes exceeds the available modes.

class structdyn.mdf.numerical_methods.newmark_beta.NewmarkBetaMDF(mdf, dt, u0=None, v0=None, acc_type='linear', use_modal=False, n_modes=None)

Bases: object

Solves the equation of motion for a linear MDOF system using the Newmark-beta method.

This class implements the implicit, unconditionally stable Newmark-beta time integration algorithm. The integration can be performed either in the physical coordinates of the system or in modal coordinates.

compute_solution(time, P)

Integrates the equations of motion over the given time and force history.

Parameters:

• time (array-like) – An array of time points of shape (nt,).

• P (array-like) – The external force history as an array of shape (nt, ndof).

Returns:

A DataFrame with the response history, including columns for ‘time’, displacements (‘u1’, ‘u2’, …), velocities (‘v1’, ‘v2’, …), and accelerations (‘a1’, ‘a2’, …).

Return type:

pd.DataFrame

Raises:

ValueError – If P has an incorrect shape or if use_modal is True and the number of requested modes exceeds the available modes.

structdyn.mdf.numerical_methods.newmark_beta.get_newmark_parameters(acc_type='linear')

class structdyn.mdf.numerical_methods.newmark_beta_non_linear.NewmarkBetaNonLinear(system, dt, beta=0.25, gamma=0.5, tol=1e-06, max_iter=50)

Bases: object

Solves the equations of motion for a non-linear MDOF system using the Newmark-Beta method.

This class implements an implicit, step-by-step time integration algorithm. For non-linear systems, an iterative Newton-Raphson procedure is used within each time step to satisfy equilibrium.

system

A system object that represents the structure. It must provide the mass matrix (M), damping matrix (C), number of DOFs (ndof), and methods to compute the resisting force and tangent stiffness.

Type:

object

dt

The time step for the integration.

Type:

float

beta

The Newmark-Beta parameter ‘beta’. Defaults to 1/4 (average acceleration).

Type:

float

gamma

The Newmark-Beta parameter ‘gamma’. Defaults to 1/2 (average acceleration).

Type:

float

compute_solution(time, p, tol=None, max_iter=None)

Performs the step-by-step non-linear time history analysis.

This method iterates through each time step, using a Newton-Raphson scheme to solve for the displacements that satisfy the dynamic equilibrium equation.

Parameters:

• time (np.ndarray) – A 1D array of time points for the analysis.

• p (np.ndarray) – An array of external forces, p(t), with shape (len(time), ndof).

• tol (float, optional) – The convergence tolerance for the norm of the residual force vector in the Newton-Raphson iteration. The default is 1e-6.

• max_iter (int, optional) – The maximum number of iterations allowed per time step for the Newton-Raphson solver. The default is 20.

Returns:

A pandas DataFrame containing the full time history of the response. Columns include ‘time’, displacements (‘u1’, ‘u2’, …), velocities (‘v1’, ‘v2’, …), accelerations (‘a1’, ‘a2’, …), and internal resisting forces (‘fs1’, ‘fs2’, …).

Return type:

pd.DataFrame

Visualization (MDF)

class structdyn.mdf.mdf_helpers.visualization.ShearBuildingVisualizer(mdf, story_height=3.0, building_width=5.0)

Bases: object

Provides methods for visualizing shear buildings.

This class is not intended to be instantiated directly. Instead, it should be accessed through the plot property of an MDF instance that represents a shear building (e.g., mdf.plot.structure()).

animate_response(response_df, scale_factor=20, ground_motion=None, speed_up=1.0, repeat=True, save_path=None)

Animates the dynamic response of the shear building.

Parameters:

• response_df (pandas.DataFrame) – The response DataFrame, as returned by a solver like find_response.

• scale_factor (int, optional) – A factor to scale the displacements for better visualization, by default 20.

• ground_motion (tuple, optional) – A tuple (time, acceleration) for the ground motion history. If provided, a plot of the ground motion will be shown below the building animation. By default None.

• speed_up (float, optional) – The factor by which to speed up the animation, by default 1.0.

• repeat (bool, optional) – Whether the animation should repeat when finished, by default True.

• save_path (str, optional) – The file path to save the animation (e.g., ‘animation.mp4’). If provided, the animation is saved to file instead of being shown. By default None.

mode_shape(mode_number=[1])

Plots one or more specified mode shapes of the shear building.

Parameters:

mode_number (int or list of int, optional) – A single mode number or a list of mode numbers to plot (1-indexed). If not provided, defaults to plotting the first mode, i.e., [1].

structure()

Plots the undeformed structure of the shear building.

Non-Linear Modelling

Material Models

class structdyn.utils.material_models.Bilinear(uy, fy, alpha=0.0)

Bases: MaterialModel

Bilinear hysteretic model with kinematic hardening.

Parameters:

• uy (float) – Yield displacement.

• fy (float) – Yield force.

• alpha (float, optional) – Hardening ratio (post‑yield stiffness / initial stiffness), by default 0.0. For alpha = 0 the model reduces to elastic‑perfectly plastic.

commit_state(u)

Update plastic displacement after convergence.

reset()

Reset to virgin state.

trial_response(u, v, dt)

Compute trial force and tangent stiffness.

class structdyn.utils.material_models.BoucWen(k0, alpha=0.05, A=0.02, beta=0.5, gamma=0.5, n=1)

Bases: MaterialModel

Bouc-Wen hysteretic model.

This is a highly versatile model that can represent a wide range of smooth hysteretic behaviors. The restoring force is given by: fs = alpha*k0*u + (1-alpha)*k0*z where z is the hysteretic displacement governed by a differential equation.

Parameters:

• k0 (float) – Initial stiffness.

• alpha (float) – Post-yield to pre-yield stiffness ratio.

• A (float, optional) – Controls the scale of the hysteretic component. Default is 0.02.

• beta (float, optional) – Controls the shape of the hysteresis loop. Default is 0.5.

• gamma (float, optional) – Controls the shape of the hysteresis loop. Default is 0.5.

• n (int, optional) – Controls the sharpness of the transition from elastic to plastic. Default is 1.

commit_state(u)

Update internal state after convergence.

trial_response(u, v, dt)

Compute trial force and tangent stiffness. Returns (fs_trial, kt_trial, flag).

class structdyn.utils.material_models.ElasticPerfectlyPlastic(uy=0.02, fy=36000)

Bases: MaterialModel

Elastic-Perfectly Plastic hysteretic material model.

This is a non-linear model characterized by an initial linear elastic response followed by a plateau where the force remains constant upon further deformation.

Parameters:

• uy (float) – Yield displacement.

• fy (float) – Yield force.

commit_state(u)

Update internal state after convergence.

trial_response(u, v, dt)

Compute trial force and tangent stiffness. Returns (fs_trial, kt_trial, flag).

class structdyn.utils.material_models.LinearElastic(stiffness)

Bases: MaterialModel

Linear elastic material model.

Parameters:

stiffness (float) – Elastic stiffness (force per unit displacement).

commit_state(u)

No internal state to update.

reset()

Reset to initial state (nothing to do except base).

trial_response(u, v, dt)

Return force = k*u, constant stiffness, and flag=False.

class structdyn.utils.material_models.MaterialModel

Bases: ABC

Abstract base class for all material models.

This class defines the interface that all material models must implement. It ensures that any material can be seamlessly integrated into a non-linear analysis element.

trial_response(u, v, dt)

Computes the trial resisting force and tangent stiffness for a given displacement and velocity.

commit_state(u)

Updates the internal history variables of the material after a time step has converged.

get_state(u, dt)

A high-level convenience method for single-step updates where velocity is computed automatically.

reset()

Resets the material to its initial, undeformed state.

abstractmethod commit_state(u)

Update internal state after convergence.

get_state(u, dt)

High‑level method: compute restoring force for a single step. Velocity is estimated from the stored previous displacement. The state is committed automatically.

reset()

Reset internal state and previous displacement.

abstractmethod trial_response(u, v, dt)

Compute trial force and tangent stiffness. Returns (fs_trial, kt_trial, flag).

class structdyn.utils.material_models.RambergOsgood(E, sigma_y, alpha=1, n=10)

Bases: MaterialModel

Ramberg‑Osgood steel material model with kinematic hardening (Masing rule).

Parameters:

• E (float) – Initial elastic stiffness (force/displacement).

• sigma_y (float) – Yield strength (force at yield).

• alpha (float, optional) – Yield offset parameter (default 1). The plastic strain at yield is alpha * (sigma_y / E).

• n (float, optional) – Exponent controlling the sharpness of the transition (default 10). Higher values give a sharper yield and less hardening.

commit_state(u)

Update internal state after convergence.

reset()

Reset to virgin state.

trial_response(u, v, dt)

Compute trial force, tangent stiffness, and a flag (always False).

Parameters:

• u (float) – Trial displacement (total strain).

• v (float) – Trial velocity.

• dt (float) – Time step (unused in this rate‑independent model).

Returns:

• fs_trial (float) – Trial resisting force.

• kt_trial (float) – Trial tangent stiffness.

• flag (bool) – Always False (for interface compatibility).

class structdyn.utils.material_models.Takeda(K0, Fy, alpha=0.0, beta=0.3)

Bases: MaterialModel

Takeda peak-oriented degrading hysteresis model.

Parameters:

• K0 (float) – Initial elastic stiffness

• Fy (float) – Yield force

• alpha (float) – Post-yield stiffness ratio

• beta (float) – Unloading stiffness degradation exponent

commit_state(u)

Update internal state after convergence.

envelope_force(u)

reset()

Reset internal state and previous displacement.

trial_response(u, v, dt)

Compute trial force and tangent stiffness. Returns (fs_trial, kt_trial, flag).

Element Models

class structdyn.mdf.mdf_helpers.element_models.Element(material_model, dof_indices)

Bases: ABC

Base class for a finite element with a material model.

commit(u_global)

Commit the material state after convergence.

abstractmethod compute_deformation(u_global, v_global)

Given global displacement and velocity vectors, return the local deformation (strain, drift, etc.) and its velocity.

get_force_and_stiffness(u_global, v_global, dt)

Compute the element resisting force and tangent stiffness. :returns: float or 1D array (force in local sense, or global contribution)

ke : float or 2D array (element tangent stiffness in local coords)

Return type:

fe

For a 1‑D element (e.g., story shear spring), fe is a scalar (force) and ke is a scalar (tangent stiffness). For a 2‑D or 3‑D element, you would return a vector/matrix, but we start simple.

class structdyn.mdf.mdf_helpers.element_models.ShearStoryElement(material_model, dof_indices)

Bases: Element

Element representing a story in a shear‑frame building. If one DOF is given, it is a base story (ground to floor). If two DOFs are given, it is an interior story between two floors.

compute_deformation(u_global, v_global)

Given global displacement and velocity vectors, return the local deformation (strain, drift, etc.) and its velocity.

Helper functions

structdyn.utils.helpers.elcentro_chopra(header=0)

Loads the El Centro ground motion data from Chopra’s book.

This function reads a CSV file containing the ground motion record for the 1940 El Centro earthquake, as provided in Chopra’s “Dynamics of Structures”.

Parameters:

header (int, list of int, None, default 0) – Row number(s) to use as the column names, and the start of the data. Passed directly to pandas.read_csv.

Returns:

A DataFrame containing the ground motion data.

Return type:

pandas.DataFrame

structdyn.utils.helpers.plot_displacement(time_steps, displacement, text=None)

Plots the displacement time history.

Parameters:

• time_steps (array-like) – The time vector.

• displacement (array-like) – The displacement time history.

• text (str, optional) – The title of the plot, by default None.