simtools.py

This module contains helper functions that are useful for inspecting and manipulating simulation data.

print_dataclass_fields(in_data)

Diagnostic function to print all fields of a dataclass.

Parameters:

in_data (Any) – A data class to print the type and fields for as well as the type of each of the fields.

print_sim_data(sim_data)

Diagnostic function for inspecting a sim data object to work out shapes of time, coordinates, connectivity tables, node vars, elem vars as well as the associated keys in the dicttionaries for the connectivity, node/elem/glob vars.

Parameters:

sim_data (mh.SimData) – SimData to print shapes of numpy arrays.

print_dimensions(sim_data)

Diagnostic function for quickly finding the coordinate limits for from a given simulation.

Parameters:

sim_data (mh.SimData) – Simulation data object containing the nodal coordinates.

get_sim_dims(sim_data)

Diagnostic function for extracting the dimensional limits in space and time from a SimData object. Useful for finding the spatial dimensions over which simulated sensors can be placed as well as the times over which they can sampled the underlying field.

Parameters:

sim_data (mh.SimData) – Simulation data object containing the coordinates and time steps.

Returns:

dict[str,tuple[float,float]] – Dictionary of space and time coordinate limits keyed as ‘x’,’y’,’z’ for the spatial dimensions and ‘t’ for time. The dictionary will return a tuple with the (min,max) of the given dimension.

centre_mesh_nodes(nodes, spat_dim)

A method to centre the nodes of a mesh around the origin.

Parameters:

• nodes (np.ndarray) – An array containing the node locations of the mesh.

• spat_dim (int) – The spatial dimension of the mesh.

Returns:

np.ndarray – An array containing the mesh node locations, but centred around the origin.

get_deformed_nodes(timestep, render_mesh)

A method to obtain the deformed locations of all the nodes at a given

timestep.

Parameters:

• timestep (int) – The timestep at which to find the deformed nodes.

• render_mesh (RenderMeshData) – A dataclass containing the skinned mesh and simulation results.

Returns:

np.ndarray | None – An array containing the deformed values of all the components at each node location. Returns None if there are no deformation values.

scale_length_units(scale, sim_data, disp_keys=None)

Used to scale the length units of a simulation. Commonly used to convert SI units to mm for use with visualisation tools and rendering algorithms.

Parameters:

• scale (float) – Scale multiplier used to scale the coordinates and displacement fields if specified.

• sim_data (mh.SimData) – Simulation dataclass that will be scaled.

• disp_keys (tuple[str,...] | None, optional) – Tuple of string keys for the displacement keys to be scaled, by default None. If None then the displacements are not scaled.

Returns:

mh.SimData – Simulation dataclass with scaled length units.

coords_to_2D(coords_3d)

Collapses and input coordinate array with 3 spatial dimensions to have only 2 spatial dimensions. Useful for removing the axis that is zero for Delaunay triangulation.

Parameters:

coords_3d (np.ndarray) – Array of coordinates with shape=(num_points,coord[X,Y,Z]). Note that this is the same format as in a SimData object

Returns:

np.ndarray – A coordinate array for the 2D simulation with the zero axis removed. The array has shape (num_points,2) where the second axis represents the 2D coords.

Raises:

Collapse2Dto3DError – Problem is either 3D or 1D, coordinates must have exactly one axis which is all zeros.

get_sim_zero_axs(coords_3d)

Helper function to extract which (if any) axis is all zeros in a coordinate array.

Parameters:

coords_3d (np.ndarray) – Array of coordinates with shape=(num_points,coord[X,Y,Z]). Note that this is the same format as in a SimData object

Returns:

np.ndarray – A 3 element array with ‘1’ where the axis is zero and ‘0’ everywhere else. The elements of the array nominally represent (X,Y,Z).

is_sim_2D(coords_3d)

Helper function that inspects a numpy array of coordinates and determines if one of the spatial axes is all zero to infer that the simulation is 2D.

Parameters:

coords_3d (np.ndarray) – Array of coordinates with shape=(num_points,coord[X,Y,Z]). Note that this is the same format as in a SimData object

Returns:

bool – True if the simulation has exactly one coordinate axis as all zero and False otherwise.