sdynpy.core.sdynpy_shape.ShapeArray

class ShapeArray(shape, ndof, shape_type='real', buffer=None, offset=0, strides=None, order=None)

Bases: SdynpyArray

Shape information specifying displacements at nodes.

Use the shape_array helper function to create the array.

__init__()

Methods

complex_data_dtype(ndof)	Data type of the underlying numpy structured array for complex shapes
compute_frf(frequencies[, responses, ...])	Computes FRFs from shape data
concatenate_dofs(shape_arrays)	Combines the degrees of freedom from multiple shapes into one set of shapes
edit_comments([geometry])	Opens up a table where the shape comments can be edited
expand(initial_geometry, expansion_geometry, ...)	Perform SEREP expansion on shape data
from_exodus(exo[, x_disp, y_disp, z_disp, ...])	Reads shape data from displacements in an Exodus file
from_imat_struct(imat_shp_struct)	Constructs a ShapeArray from an imat_shp class saved to a Matlab structure
from_uff(unv_data_dict[, combine])	Load ShapeArrays from universal file data from read_unv
from_unv(unv_data_dict[, combine])	Load ShapeArrays from universal file data from read_unv
is_complex()	Returns true if the shape is a complex shape, False if shape is real
mode_table([table_format, frequency_format, ...])	Generates a table of modal information including frequency and damping
normalize(system_or_matrix[, ...])	Computes A-normalized or mass-normalized shapes
optimize_degrees_of_freedom(sensors_to_keep)	Creates a reduced set of shapes using optimal degrees of freedom
overlay_shapes(geometries, shapes[, ...])	Combines several shapes and geometries for comparitive visualization
plot_frequency(interp_abscissa, interp_ordinate)	Plots the frequencies of the shapes on curves of a 2D plot
real_data_dtype(ndof)	Data type of the underlying numpy structured array for real shapes
reduce(nodelist_or_coordinate_array)	Reduces the shape to the degrees of freedom specified
reduce_for_comparison(comparison_shape[, ...])
repack(coefficients)	Creates new shapes by linearly combining existing shapes
shape_alignment(shape_1, shape_2[, node_id_map])	Computes if the shapes are aligned, or if one needs to be flipped
system()	Create system matrices from the shapes
time_integrate(forces, dt[, responses, ...])	Integrate equations of motion created from shapes
to_complex()	Creates complex shapes from real shapes
to_real([force_angle])	Creates real shapes from complex shapes by collapsing the complexity
transform_coordinate_system(...[, ...])	Performs coordinate system transformations on the shape
write_to_unv(filename[, specific_data_type, ...])	Writes shape data to a unverisal file

Attributes

modeshape	The mode shape matrix with degrees of freedom as second to last axis
ndof	The number of degrees of freedom in the shape

static complex_data_dtype(ndof)

Data type of the underlying numpy structured array for complex shapes

Parameters

ndof (int) – Number of degrees of freedom in the shape array

Returns

Numpy dtype that can be passed into any of the numpy array constructors

Return type

list

compute_frf(frequencies, responses=None, references=None, displacement_derivative=2)

Computes FRFs from shape data

Parameters

• frequencies (iterable) – A list of frequencies to compute the FRF at.

• responses (CoordinateArray, optional) – Degrees of freedom to use as responses. The default is to compute FRFs at all degrees of freedom in the shape.

• references (CoordinateArray, optional) – Degrees of freedom to use as references. The default is to compute FRFs using the response degrees of freedom also as references.

• displacement_derivative (int, optional) – The derivative to use when computing the FRFs. 0 corresponds to displacement FRFs, 1 corresponds to velocity, and 2 corresponds to acceleration. The default is 2.

Returns

output_data – A transfer function array containing the specified references and responses.

Return type

TransferFunctionArray

static concatenate_dofs(shape_arrays)

Combines the degrees of freedom from multiple shapes into one set of shapes

Parameters

shape_arrays (list of ShapeArray) – List of ShapeArray objects to combine in to one set of shapes

Returns

ShapeArray object containing degrees of freedom from all input shapes

Return type

ShapeArray

edit_comments(geometry=None)

Opens up a table where the shape comments can be edited

If a geometry is also passed, it will also open up a mode shape plotter window where you can visualize the modes you are looking at.

Edited comments will be stored back into the ShapeArray object when the OK button is pressed. Comments will not be stored if the Cancel button is pressed.

Parameters

geometry (Geometry, optional) – A geometry on which the shapes will be plotted. If not specified, a table will just open up.

Returns

A ShapeCommentTable displaying the modal information where comments can be edited.

Return type

ShapeCommentTable

Notes

Due to how Python handles garbage collection, the table may be immediately closed if not assigned to a variable, as Python things it is no longer in use.

expand(initial_geometry, expansion_geometry, expansion_shapes, node_id_map=None, expansion_coordinates=None, return_coefficients=False)

Perform SEREP expansion on shape data

Parameters

• initial_geometry (Geometry) – The initial or “Test” Geometry, corresponding to the initial shapes (self)

• expansion_geometry (Geometry) – The expanded or “FEM” Geometry, corresponding to the shapes that will be expanded

• expansion_shapes (ShapeArray) – Shapes defined on the expanded geometry, which will be used to expand the initial shapes

• node_id_map (id_map, optional) – If the initial and expanded geometry or shapes do not have common node ids, an id_map can be specified to map the finite element node ids to test node ids. The default is None, which means no mapping will occur, and the shapes have common id numbers.

• expansion_coordinates (CoordinateArray, optional) – Degrees of freedom in the test shapes to use in the expansion. The default is None, which results in all degrees of freedom being used for expansion

• return_coefficients (bool, optional) – If True, the coefficients used in the expansion will be returned along with the expanded shapes. The default is False.

Returns

• ShapeArray – The original shapes expanded to the expansion_geometry

• np.ndarray – The coefficients used to perform the expansion, only returned if return_coefficients is True

classmethod from_exodus(exo, x_disp='DispX', y_disp='DispY', z_disp='DispZ', x_rot=None, y_rot=None, z_rot=None, timesteps=None)

Reads shape data from displacements in an Exodus file

Parameters

• exo (Exodus or ExodusInMemory) – The exodus data from which geometry will be created.

• x_disp (str, optional) – String denoting the nodal variable in the exodus file from which the X-direction displacement should be read. The default is ‘DispX’. Specify None if no x_disp is to be read.

• y_disp (str, optional) – String denoting the nodal variable in the exodus file from which the Y-direction displacement should be read. The default is ‘DispY’. Specify None if no y_disp is to be read.

• z_disp (str, optional) – String denoting the nodal variable in the exodus file from which the Z-direction displacement should be read. The default is ‘DispZ’. Specify None if no z_disp is to be read.

• x_rot (str, optional) – String denoting the nodal variable in the exodus file from which the X-direction rotation should be read. The default is None which results in the X-direction rotation not being read. Typically this would be set to ‘RotX’ if rotational values are desired.

• y_rot (str, optional) – String denoting the nodal variable in the exodus file from which the Y-direction rotation should be read. The default is None which results in the Y-direction rotation not being read. Typically this would be set to ‘RotY’ if rotational values are desired.

• z_rot (str, optional) – String denoting the nodal variable in the exodus file from which the Z-direction rotation should be read. The default is None which results in the Z-direction rotation not being read. Typically this would be set to ‘RotZ’ if rotational values are desired.

• timesteps (iterable, optional) – A list of timesteps from which data should be read. The default is None, which reads all timesteps.

Returns

Shape data from the exodus file

Return type

ShapeArray

classmethod from_imat_struct(imat_shp_struct)

Constructs a ShapeArray from an imat_shp class saved to a Matlab structure

In IMAT, a structure can be created from an imat_shp by using the get() function. This can then be saved to a .mat file and loaded using scipy.io.loadmat. The output from loadmat can be passed into this function

Parameters

imat_fem_struct (np.ndarray) – structure from loadmat containing data from an imat_shp

Returns

ShapeArray constructed from the data in the imat structure

Return type

ShapeArray

static from_uff(unv_data_dict, combine=True)

Load ShapeArrays from universal file data from read_unv

Parameters

• unv_data_dict (dict) – Dictionary containing data from read_unv

• combine (bool, optional) – If True, return as a single ShapeArray

Raises

ValueError – Raised if an unknown data characteristic is provided

Returns

output_arrays – Shapes read from unv

Return type

ShapeArray

static from_unv(unv_data_dict, combine=True)

Load ShapeArrays from universal file data from read_unv

Parameters

• unv_data_dict (dict) – Dictionary containing data from read_unv

• combine (bool, optional) – If True, return as a single ShapeArray

Raises

ValueError – Raised if an unknown data characteristic is provided

Returns

output_arrays – Shapes read from unv

Return type

ShapeArray

is_complex()

Returns true if the shape is a complex shape, False if shape is real

Returns

True if the shape is complex

Return type

bool

mode_table(table_format='csv', frequency_format='{:0.2f}', damping_format='{:0.2f}%')

Generates a table of modal information including frequency and damping

Parameters

• table_format (str, optional) – The type of table to generate. Can be ‘csv’, ‘rst’, ‘markdown’, ‘latex’, or ‘ascii’. The default is ‘csv’.

• frequency_format (str, optional) – Format specifier for frequency. The default is ‘{:0.2f}’.

• damping_format (str, optional) – Format specifier for damping percent. The default is ‘{:0.2f}%’.

Raises

ValueError – Raised if a invalid table_format is specified

Returns

table – String representation of the mode table

Return type

str

property modeshape

The mode shape matrix with degrees of freedom as second to last axis

property ndof

The number of degrees of freedom in the shape

normalize(system_or_matrix, return_modal_matrix=False)

Computes A-normalized or mass-normalized shapes

Parameters

• system_or_matrix (System or np.ndarray) – A System object or a mass matrix for real modes or A-matrix for complex modes.

• return_modal_matrix (bool, optional) – If true, it will return the modal mass or modal-A matrix computed from the normalized mode shapes. The default is False.

Returns

A copy of the original shape array with normalized shape coefficients

Return type

ShapeArray

optimize_degrees_of_freedom(sensors_to_keep, group_by_node=False, method='ei')

Creates a reduced set of shapes using optimal degrees of freedom

Parameters

• sensors_to_keep (int) – Number of sensors to keep

• group_by_node (bool, optional) – If True, group shape degrees of freedom a the same node as one sensor, like a triaxial accelerometer. The default is False.

• method (str, optional) – ‘ei’ for effective independence or ‘cond’ for condition number. The default is ‘ei’.

Returns

The set of shapes with a reduced set of degrees of freedom that are optimally chosen.

Return type

ShapeArray

static overlay_shapes(geometries, shapes, color_override=None)

Combines several shapes and geometries for comparitive visualization

Parameters

• geometries (Iterable of Geometry) – A list of Geometry objects that will be combined into a single Geometry

• shapes (Iterable of ShapeArray) – A list of ShapeArray objects that will be combined into a single ShapeArray

• color_override (iterable, optional) – An iterble of integers specifying colors, which will override the existing geometry colors. This should have the same length as the geometries input. The default is None, which keeps the original geometry colors.

Returns

• new_geometry (Geometry) – A geometry consisting of a combination of the specified geometries

• new_shape (ShapeArray) – A ShapeArray consisting of a combination of the specified ShapeArrays

plot_frequency(interp_abscissa, interp_ordinate, ax=None, plot_kwargs={'color': 'k', 'linestyle': 'None', 'marker': 'x'})

Plots the frequencies of the shapes on curves of a 2D plot

Parameters

• interp_abscissa (np.ndarray) – The abscissa used to interpolate the Y-position of the frequency mark

• interp_ordinate (np.ndarray) – The ordinate used to interpolate the Y-postiion of the frequency mark

• ax (matplotlib axes, optional) – Axes on which to plot the frequency marks. The default is None, which creates a new window

• plot_kwargs (dict, optional) – Additional arguments to pass to the matplotlib plot command. The default is {‘color’:’k’,’marker’:’x’,’linestyle’:”None”}.

Returns

ax – Axes on which the frequency marks were plotted

Return type

matplotlib axes, optional

static real_data_dtype(ndof)

Data type of the underlying numpy structured array for real shapes

Parameters

ndof (int) – Number of degrees of freedom in the shape array

Returns

Numpy dtype that can be passed into any of the numpy array constructors

Return type

list

reduce(nodelist_or_coordinate_array)

Reduces the shape to the degrees of freedom specified

Parameters

nodelist_or_coordinate_array (iterable or CoordinateArray) – Consists of either a list of node ids or a CoordinateArray. The ShapeArray will be reduced to only the degrees of freedom specified

Returns

A reduced ShapeArray

Return type

ShapeArray

reduce_for_comparison(comparison_shape, node_id_map=None)

repack(coefficients)

Creates new shapes by linearly combining existing shapes

Parameters

coefficients (np.ndarray) – coefficient matrix that will be multiplied by the shapes. This should have number of rows equal to the number of shapes that are going to be combined. The number of columns will specify the number of shapes that will result

Returns

ShapeArray consisting of linear combinations of the original ShapeArray

Return type

ShapeArray

static shape_alignment(shape_1, shape_2, node_id_map=None)

Computes if the shapes are aligned, or if one needs to be flipped

Parameters

• shape_1 (ShapeArray) – Shape to compare.

• shape_2 (ShapeArray) – Shape to compare.

Returns

An array denoting if one of the shapes need to be flipped (-1) to be equivalent to the other, or if they are already aligned (1)

Return type

np.ndarray

system()

Create system matrices from the shapes

This will create a System object with modal mass, stiffness, and damping matrices, with the mode shape matrix as the transformation to physical coordinates

Raises

NotImplementedError – Raised if complex modes are used

Returns

A System object containing modal mass, stiffness, and damping matrices, with the mode shape matrix as the transformation to physical coordinates

Return type

System

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

Integrate equations of motion created from shapes

Parameters

• forces (np.ndarray) – Input force provided to the shapes, with number of rows equal to the number of references, and number of columns equal to the number of time steps in the simulation.

• dt (float) – Time increment for the integration. For accuracy, this is generally about 10x higher than the bandwidth of interest

• responses (CoordinateArray, optional) – Degrees of freedom to get response measurements. The default is None, which returns modal responses.

• references (CoordinateArray, optional) – Degrees of freedom at which to apply forces. The default is None, which means the input forces are treated as modal forces

• displacement_derivative (int, optional) – The derivative to use for the responses. 0 corresponds to displacement, 1 corresponds to velocity, and 2 corresponds to acceleration. The default is 2.

Raises

NotImplementedError – Complex shapes are not currently implemented

Returns

• response_array (TimeHistoryArray) – Responses assembled into a TimeHistoryArray.

• reference_array (TimeHistoryArray) – Input forces assembled into a TimeHistoryArray.

to_complex()

Creates complex shapes from real shapes

Returns

Complex shapes compute from the real shape coefficients

Return type

ShapeArray

to_real(force_angle=-0.7853981633974483, **kwargs)

Creates real shapes from complex shapes by collapsing the complexity

Parameters

• force_angle (float) – Angle to force the complex collapsing to real, by default it is -pi/4 (-45 degrees). To allow other angles, use None for this argument.

• **kwargs (various) – Extra arguments to pass to collapse_complex_to_real

Returns

Real shapes created from the original complex shapes

Return type

ShapeArray

transform_coordinate_system(original_geometry, new_geometry, node_id_map=None, rotations=False, missing_dofs_are_zero=False)

Performs coordinate system transformations on the shape

Parameters

• original_geometry (Geometry) – The Geometry in which the shapes are currently defined

• new_geometry (Geometry) – The Geometry in which the shapes are desired to be defined

• node_id_map (id_map, optional) – If the original and new geometries do not have common node ids, an id_map can be specified to map the original geometry node ids to new geometry node ids. The default is None, which means no mapping will occur, and the geometries have common id numbers.

• rotations (bool, optional) – If True, also transform rotational degrees of freedom. The default is False.

• missing_dofs_are_zero (bool, optional) – If False, any degree of freedom required for the transformation that is not provided will result in a ValueError. If True, these missing degrees of freedom will simply be appended to the original shape matrix as zeros. Default is False.

Returns

A ShapeArray that can now be plotted with the new geometry

Return type

ShapeArray

write_to_unv(filename, specific_data_type=12, load_case_number=0)

Writes shape data to a unverisal file

Parameters

• filename (str) – Filename to which the geometry will be written. If None, unv data will be returned instead, similar to that obtained from the readunv function in sdynpy

• specific_data_type (int, optional) – Integer specifying the type of data in the shape. The default is 12, which denotes acceleration shapes.

• load_case_number (int, optional) – The load case number. The default is 0.

Raises

NotImplementedError – Raised if complex numbers are used as they are not implemented yet

Returns

shape_unv – A list of Sdynpy_UFF_Dataset_55 objects, only if filename is None

Return type

List