sdynpy.core.sdynpy_system.System

class System(coordinate: CoordinateArray, mass, stiffness, damping=None, transformation=None)

Bases: object

Matrix Equations representing a Structural Dynamics System

__init__(coordinate: CoordinateArray, mass, stiffness, damping=None, transformation=None)

Create a system representation including mass, stiffness, damping, and transformation matrices.

Parameters

• coordinate (CoordinateArray) – Physical degrees of freedom in the system.

• mass (np.ndarray) – 2D array consisting of the mass matrix of the system

• stiffness (np.ndarray) – 2D array consisting of the stiffness matrix of the system

• damping (np.ndarray, optional) – 2D array consisting of the damping matrix of the system. If not specified, the damping will be zero.

• transformation (np.ndarray, optional) – A transformation between internal “state” degrees of freedom and the physical degrees of freedom defined in coordinate. The default transformation is the identity matrix.

Raises

ValueError – If inputs are improperly sized

Return type

None.

Methods

__init__(coordinate, mass, stiffness[, ...])	Create a system representation including mass, stiffness, damping, and transformation matrices.
assign_modal_damping(damping_ratios)	Assigns a damping matrix to the system that results in equivalent modal damping
beam(length, width, height, num_nodes[, E, ...])	Create a beam mass and stiffness matrix
concatenate(systems[, coordinate_node_offset])	Combine multiple systems together
constrain(constraint_matrix[, rcond])	Apply a constraint matrix to the system
copy()	Returns a copy of the system object
eigensolution([num_modes, ...])	Computes the eigensolution of the system
frequency_response(frequencies[, responses, ...])	Computes frequency response functions at the specified frequency lines.
from_exodus_superelement(superelement_nc4[, ...])	Creates a system from a superelement from Sierra/SD
get_indices_by_coordinate(coordinates[, ...])	Gets the indices in the transformation matrix corresponding coordinates
load(filename)	Load a system from a file
reduce(reduction_transformation)	Apply the specified reduction to the model
reduce_craig_bampton(...[, return_shape_matrix])	Computes a craig-bampton substructure model for the system
reduce_dynamic(coordinates, frequency)	Perform Dynamic condensation
reduce_guyan(coordinates)	Perform Guyan reduction on the system
remove_transformation()
save(filename)	Saves the system to a file
set_proportional_damping(mass_fraction, ...)	Sets the damping matrix to a proportion of the mass and stiffness matrices.
simulate_test(bandwidth, frame_length, ...)
spy([subplots_kwargs, spy_kwargs])	Plot the structure of the system's matrices
substructure_by_coordinate(dof_pairs[, ...])	Constrain the system by connecting the specified degree of freedom pairs
substructure_by_position(systems, geometries)	Applies constraints to systems by constraining colocated nodes together
substructure_by_shape(constraint_shapes, ...)	Constrain the system using a set of shapes in a least-squares sense.
time_integrate(forces[, dt, responses, ...])	Integrate a system to produce responses to an excitation
to_state_space([output_displacement, ...])	Compute the state space representation of the system
transformation_matrix_at_coordinates(coordinates)	Return the transformation matrix at the specified coordinates
transformation_shapes([shape_indices])

Attributes

C	Get or set the damping matrix of the system
K	Get or set the stffness matrix of the system
M	Get or set the mass matrix of the system
coordinate	Get or set the degrees of freedom in the system
damping	Get or set the damping matrix of the system
mass	Get or set the mass matrix of the system
ndof	Get the number of internal degrees of freedom of the system
ndof_transformed	Get the number of physical degrees of freedom of the system
stiffness	Get or set the stffness matrix of the system
transformation	Get or set the transformation matrix

property C

Get or set the damping matrix of the system

property K

Get or set the stffness matrix of the system

property M

Get or set the mass matrix of the system

assign_modal_damping(damping_ratios)

Assigns a damping matrix to the system that results in equivalent modal damping

Parameters

damping_ratios (ndarray) – An array of damping values to assign to the system

Return type

None.

classmethod beam(length, width, height, num_nodes, E=None, rho=None, nu=None, material=None)

Create a beam mass and stiffness matrix

Parameters

• length (float) – Lenghth of the beam

• width (float) – Width of the beam

• height (float) – Height of the beam

• num_nodes (int) – Number of nodes in the beam.

• E (float, optional) – Young’s modulus of the beam. If not specified, a material must be specified instead

• rho (float, optional) – Density of the beam. If not specified, a material must be specified instead

• nu (float, optional) – Poisson’s ratio of the beam. If not specified, a material must be specified instead

• material (str, optional) – A specific material can be specified instead of E, rho, and nu. Should be a string ‘steel’ or ‘aluminum’. If not specified, then options E, rho, and nu must be specified instead.

Raises

ValueError – If improper materials are defined.

Returns

• system (System) – A system object consisting of the beam mass and stiffness matrices.

• geometry (Geometry) – A Geometry consisting of the beam geometry.

classmethod concatenate(systems, coordinate_node_offset=0)

Combine multiple systems together

Parameters

• systems (iterable of System objects) – Iterable of Systems that will be concatenated. Matrices will be assembled in block diagonal format

• coordinate_node_offset (int, optional) – Offset applied to the coordinates so the nodes do not overlap. The default is 0.

Returns

A system consisting of the combintation of the provided systems.

Return type

System

constrain(constraint_matrix, rcond=None)

Apply a constraint matrix to the system

Parameters

• constraint_matrix (np.ndarray) – A matrix of constraints to apply to the structure (B matrix in substructuring literature)

• rcond (float, optional) – Condition tolerance for computing the nullspace. The default is None.

Returns

Constrained system.

Return type

System

property coordinate

Get or set the degrees of freedom in the system

copy()

Returns a copy of the system object

Returns

A copy of the system object

Return type

System

property damping

Get or set the damping matrix of the system

eigensolution(num_modes=None, maximum_frequency=None, complex_modes=False, return_shape=True)

Computes the eigensolution of the system

Parameters

• num_modes (int, optional) – The number of modes of the system to compute. The default is to compute all the modes.

• maximum_frequency (float, optional) – The maximum frequency to which modes will be computed. The default is to compute all the modes.

• complex_modes (bool, optional) – Whether or not complex modes are computed. The default is False.

• return_shape (bool, optional) – Specifies whether or not to return a ShapeArray (True) or a reduced System (False). The default is True.

Raises

NotImplementedError – Raised if complex modes are specified.

Returns

If return_shape is True, the a ShapeArray will be returned. If return_shape is False, a reduced system will be returned.

Return type

System or ShapeArray

frequency_response(frequencies, responses=None, references=None, displacement_derivative=0)

Computes frequency response functions at the specified frequency lines.

Parameters

• frequencies (ndarray) – A 1D array of frequencies.

• responses (CoordinateArray, optional) – A set of coordinates to compute responses. The default is to create responses at all coordinates.

• references (CoordinateArray, optional) – A set of coordinates to use as inputs. The default is to use all coordinates as inputs.

• displacement_derivative (int, optional) – The number of derivatives to apply to the response. The default is 0, which corresponds to displacement. 1 would be the first derivative, velocity, and 2 would be the second derivative, acceleration.

Returns

frf – A TransferFunctionArray containing the frequency response function for the system at the specified input and output degrees of freedom.

Return type

TransferFunctionArray

classmethod from_exodus_superelement(superelement_nc4, transformation_exodus_file=None, x_disp='DispX', y_disp='DispY', z_disp='DispZ', x_rot=None, y_rot=None, z_rot=None, reduce_to_external_surfaces=False)

Creates a system from a superelement from Sierra/SD

Parameters

• superelement_nc4 (netCDF4.Dataset or string) – Dataset from which the superelement data will be loaded

• transformation_exodus_file (Exodus, ExodusInMemory, or str, optional) – Exodus data containing the transformation between the reduced superelement state and the physical space. If not specified, no transformation will be created.

• x_disp (str, optional) – Variable name to read for x-displacements in the transformation Exodus file. The default is ‘DispX’.

• y_disp (str, optional) – Variable name to read for y-displacements in the transformation Exodus file. The default is ‘DispY’.

• z_disp (str, optional) – Variable name to read for z-displacements in the transformation Exodus file. The default is ‘DispZ’.

• x_rot (str, optional) – Variable name to read for x-rotations in the transformation Exodus file. The default is to not read rotations.

• y_rot (str, optional) – Variable name to read for y-rotations in the transformation Exodus file. The default is to not read rotations.

• z_rot (str, optional) – Variable name to read for z-rotations in the transformation Exodus file. The default is to not read rotations.

• reduce_to_external_surfaces (bool, optional) – If True, exodus results will be reduced to external surfaces

Raises

ValueError – raised if bad data types are passed to the arguments.

Returns

• system (System) – System containing the superelement representation

• geometry (Geometry) – Geometry that can be used to plot the system

• boundary_dofs (CoordinateArray) – Degrees of freedom that can be used to constrain the test article.

get_indices_by_coordinate(coordinates, ignore_sign=False)

Gets the indices in the transformation matrix corresponding coordinates

Parameters

• coordinates (CoordinateArray) – Coordinates to extract transformation indices

• ignore_sign (bool, optional) – Specify whether or not to ignore signs on the coordinates. If True, then ‘101X+’ would match ‘101X+’ or ‘101X-’. The default is False.

Raises

ValueError – Raised if duplicate coordinates or coordinates not in the system are requested

Returns

Array of indices.

Return type

np.ndarray

classmethod load(filename)

Load a system from a file

Parameters

filename (str) – Name of the file from which the system will be loaded.

Returns

A system consisting of the mass, stiffness, damping, and transformation in the file

Return type

System

property mass

Get or set the mass matrix of the system

property ndof

Get the number of internal degrees of freedom of the system

property ndof_transformed

Get the number of physical degrees of freedom of the system

reduce(reduction_transformation)

Apply the specified reduction to the model

Parameters

reduction_transformation (np.ndarray) – Matrix to use in the reduction

Returns

Reduced system.

Return type

System

reduce_craig_bampton(connection_degrees_of_freedom: CoordinateArray, num_fixed_base_modes: int, return_shape_matrix: bool = False)

Computes a craig-bampton substructure model for the system

Parameters

• connection_degrees_of_freedom (CoordinateArray) – Degrees of freedom to keep at the interface.

• num_fixed_base_modes (int) – Number of fixed-base modes to use in the reduction

• return_shape_matrix (bool, optional) – If true, return a set of shapes that represents the transformation in addition to the reduced system. The default is False.

Raises

ValueError – Raised if coordinate arrays are specified when there is already a transformation.

Returns

• System – Reduced system in craig-bampton form

• ShapeArray – Shapes representing the craig-bampton transformation

reduce_dynamic(coordinates, frequency)

Perform Dynamic condensation

Parameters

• coordinates (CoordinateArray) – A list of coordinates to keep in the reduced system.

• frequency (float) – The frequency to preserve in the dynamic reduction.

Raises

ValueError – Raised if the transformation is not identity matrix.

Returns

Reduced system.

Return type

System

reduce_guyan(coordinates)

Perform Guyan reduction on the system

Parameters

coordinates (CoordinateArray) – A list of coordinates to keep in the reduced system.

Raises

ValueError – Raised the transformation matrix is not identity matrix.

Returns

Reduced system.

Return type

System

remove_transformation()

save(filename)

Saves the system to a file

Parameters

filename (str) – Name of the file in which the system will be saved.

Return type

None.

set_proportional_damping(mass_fraction, stiffness_fraction)

Sets the damping matrix to a proportion of the mass and stiffness matrices.

The damping matrix will be set to mass_fraction*self.mass + stiffness_fraction*self.stiffness

Parameters

• mass_fraction (float) – Fraction of the mass matrix

• stiffness_fraction (TYPE) – Fraction of the stiffness matrix

Return type

None.

simulate_test(bandwidth, frame_length, num_averages, excitation, references, responses=None, excitation_level=1.0, excitation_noise_level=0.0, response_noise_level=0.0, steady_state_time=0.0, excitation_min_frequency=None, excitation_max_frequency=None, signal_fraction=0.5, extra_time_between_frames=0.0, integration_oversample=10, displacement_derivative=2, antialias_filter_cutoff_factor=3, antialias_filter_order=4, **generator_kwargs)

spy(subplots_kwargs={'figsize': (10, 3)}, spy_kwargs={})

Plot the structure of the system’s matrices

Parameters

• subplots_kwargs (dict, optional) – Default arguments passed to matplotlib.pyplot’s subplots function. The default is {‘figsize’:(10,3)}.

• spy_kwargs (dict, optional) – Default arguments passed to matplotlib.pyplot’s ‘spy’ function. The default is {}.

Returns

ax – Axes on which the subplots are defined.

Return type

Axes

property stiffness

Get or set the stffness matrix of the system

substructure_by_coordinate(dof_pairs, rcond=None, return_constrained_system=True)

Constrain the system by connecting the specified degree of freedom pairs

Parameters

• dof_pairs (iterable of CoordinateArray) – Pairs of coordinates to be connected. None can be passed instead of a second degree of freedom to constrain to ground

• rcond (float, optional) – Condition threshold to use for the nullspace calculation on the constraint matrix. The default is None.

• return_constrained_system (bool, optional) – If true, apply the constraint matrix and return the constrained system, otherwise simply return the constraint matrix. The default is True.

Returns

Returns a System object with the constraints applied if return_constrained_system is True, otherwise just return the constraint matrix.

Return type

np.ndarray or System

classmethod substructure_by_position(systems, geometries, distance_threshold=1e-08, rcond=None)

Applies constraints to systems by constraining colocated nodes together

Parameters

• systems (iterable of System objects) – A set of systems that will be combined and constrained together

• geometries (iterable of Geometry objects) – A set of geometries that will be combined together

• distance_threshold (float, optional) – The distance between nodes that are considered colocated. The default is 1e-8.

• rcond (float, optional) – Condition number to use in the nullspace calculation on the constraint matrix. The default is None.

Returns

• combined_system (System) – System consisting of constraining the input systems together.

• combined_geometry (Geometry) – Combined geometry of the new system

substructure_by_shape(constraint_shapes, connection_dofs_0, connection_dofs_1=None, rcond=None, return_constrained_system=True)

Constrain the system using a set of shapes in a least-squares sense.

Parameters

• constraint_shapes (ShapeArray) – An array of shapes to use as the basis for the constraints

• connection_dofs_0 (CoordinateArray) – Array of coordinates to use in the constraints

• connection_dofs_1 (CoordinateArray, optional) – Array of coordinates to constrain to the coordinates in connection_dofs_0. If not specified, the connection_dofs_0 degrees of freedom will be constrained to ground.

• rcond (float, optional) – Condition threshold on the nullspace calculation. The default is None.

• return_constrained_system (bool, optional) – If true, apply the constraint matrix and return the constrained system, otherwise simply return the constraint matrix. The default is True.

Returns

Returns a System object with the constraints applied if return_constrained_system is True, otherwise just return the constraint matrix.

Return type

np.ndarray or System

time_integrate(forces, dt=None, responses=None, references=None, displacement_derivative=2, initial_state=None, integration_oversample=1)

Integrate a system to produce responses to an excitation

Parameters

• forces (np.ndarray or TimeHistoryArray) – The forces applied to the system, which should be a signal with time-step dt. If a TimeHistoryArray is passed, then dt and references will be taken from the TimeHistoryArray, and the arguments will be ignored.

• dt (float, optional) – The timestep used for the integration. Must be specified if forces is a ndarray. If forces is a TimeHistoryArray, then this argument is ignored.

• responses (CoordinateArray, optional) – Coordinates at which responses are desired. The default is all responses.

• references (CoordinateArray, optional) – Coordinates at which responses are input. The default is all references. Must be the same size as the number of rows in the forces array. If forces is a TimeHistoryArray, then this argument is ignored.

• displacement_derivative (int, optional) – The derivative of the displacement that the output will be represented as. A derivative of 0 means displacements will be returned, a derivative of 1 will mean velocities will be returned, and a derivative of 2 will mean accelerations will be returned. The default is 2, which returns accelerations.

• initial_state (np.ndarray, optional) – The initial conditions of the integration. The default is zero displacement and zero velocity.

• integration_oversample (int) – The amount of oversampling that will be applied to the force by zero-padding the fft

Returns

• response_array (TimeHistoryArray) – The responses of the system to the forces applied

• reference_array (TimeHistoryArray) – The forces applied to the system as a TimeHistoryArray

to_state_space(output_displacement=True, output_velocity=True, output_acceleration=True, output_force=True, response_coordinates=None, input_coordinates=None)

Compute the state space representation of the system

Parameters

• output_displacement (bool, optional) – Provide rows in the output and feedforward matrices corresponding to displacement outputs. The default is True.

• output_velocity (bool, optional) – Provide rows in the output and feedforward matrices corresponding to velocity outputs. The default is True.

• output_acceleration (bool, optional) – Provide rows in the output and feedforward matrices corresponding to acceleration outputs. The default is True.

• output_force (bool, optional) – Provide rows in the output and feedforward matrices corresponding to force outputs. The default is True.

Returns

• A_state (np.ndarray) – The state matrix

• B_state (np.ndarray) – The input matrix

• C_state (np.ndarray) – The output matrix.

• D_state (np.ndarray) – The feedforward matrix.

property transformation

Get or set the transformation matrix

transformation_matrix_at_coordinates(coordinates)

Return the transformation matrix at the specified coordinates

Parameters

coordinates (CoordinateArray) – coordinates at which the transformation matrix will be computed.

Raises

ValueError – Raised if duplicate coordinates are requested, or if coordinates that do not exist in the system are requested.

Returns

return_value – Portion of the transformation matrix corresponding to the coordinates input to the function.

Return type

np.ndarray

transformation_shapes(shape_indices=None)