stem.utils module

stem.utils.NUMBER_TYPES = (<class 'int'>, <class 'float'>, <class 'numpy.int64'>, <class 'numpy.float64'>)

TypeAlias:

NUMBER_TYPES: Tuple[int, float, np.int64, np.float64]

class stem.utils.Utils

Bases: object

Class containing utility methods.

static are_2d_coordinates_clockwise(coordinates: Sequence[Sequence[float]]) → bool

Checks if the 2D coordinates are given in clockwise order. If the signed area is positive, the coordinates are given in clockwise order.

Args:

coordinates (Sequence[Sequence[float]]): coordinates of the points of a surface

Returns:

bool: True if the coordinates are given in clockwise order, False otherwise.

static calculate_normal_unit_vector_to_line_on_xy_plane(line_points: Sequence[Sequence[float]]) → ndarray[tuple[Any, ...], dtype[float64]]

Calculates the normal unit vector to a line defined by two points.

Args:

line_points (Sequence[Sequence[float]]): two points defining the line.

Raises:

ValueError: if less than two points are provided.
ValueError: if the points are identical.

Returns:

npty.NDArray[np.float64]: normal unit vector to the line.

static calculated_normal_unit_vector_to_plane(plane_points: Sequence[Sequence[float]]) → ndarray[tuple[Any, ...], dtype[float64]]

Calculates the normal unit vector to a plane defined by three points.

Args:

plane_points (Sequence[Sequence[float]]): three points defining the plane.

Raises:

ValueError: if less than three points are provided.
ValueError: if the points are collinear.

Returns:

npty.NDArray[np.float64]: normal unit vector to the plane.

static chain_sequence(sequences: Sequence[Sequence[Any]]) → Generator[Sequence[Any], Sequence[Any], None]

Chains sequences together

Args:

sequences (Sequence[Sequence[Any]]): sequences to chain

Returns:

Generator[Sequence[Any], Sequence[Any], None]: generator for chaining sequences

static check_dimensions(points: Sequence[Sequence[float]]) → None

Check if points have the same dimensions (2D or 3D).

Args:

points: (Sequence[Sequence[float]]): points to be tested

Raises:

ValueError: when the points have different dimensions.
ValueError: when the dimension is not either 2 or 3D.

Returns:

None

static check_lines_geometry_are_path(geometry: Geometry | None) → bool

Checks if lines are connected forming a path without:

disconnected lines,

branching out paths:

a) Disconnected lines:
    o---o
    |
    o

b) Branching out paths:
    o---o
         |
    o----o----o
         |
         o

Args:

geometry (stem.geometry.Geometry): geometry to be checked.

Raises:

ValueError: when geometry is not provided (is None).
ValueError: when geometry has no lines.

Returns:

bool: whether the lines are connected along the path

static check_ndim_nnodes_combinations(n_dim: int, n_nodes_element: int | None, available_combinations: Dict[int, List[Any]], class_name: str)

Check if the combination of number of global dimensions and number of nodes per element is supported.

Args:

n_dim (int): number of dimensions
n_nodes_element (int): number of nodes per element or condition-element
available_combinations (Dict[int, List[int]]): dictionary containing the supported combinations of number of dimensions and number of nodes per element or condition-element
class_name (str): name of the class to be checked

Raises:

ValueError: when the number of dimensions is not supported.
ValueError: when the combination of number of dimensions and number of nodes per element is not supported.

static create_box_tiny_expr(transition_parameter: float, start_peak: float, end_peak: float, peak_value: float, base_value: float, variable: str = 'x') → str

Creates a tiny expression for a hyperbolic approximation of the box function. For more information on tiny expressions, see: https://github.com/codeplea/tinyexpr

Args:

transition_parameter (float): parameter to control the transition of the box function, the higher the value, the steeper the transition
start_peak (float): start of the peak of the box function
end_peak (float): end of the peak of the box function
peak_value (float): value of the peak of the box function
base_value (float): value of the base of the box function
variable (str): variable within the box function tinyexpr, default is “x”, other options are “y”, “z”, “t”

Raises:

ValueError: when start peak is larger or equal to end peak
ValueError: when variable is not “x”, “y”, “z” or “t”

Returns:

str: tiny expression of the box function

static create_sigmoid_tiny_expr(start_time: float, dt_slope: float, initial_value: float, final_value: float, is_half_function: bool) → str

Creates a tiny expression with variable time for a sigmoid function. For more information on tiny expressions, see: https://github.com/codeplea/tinyexpr

Args:

start_time (float): start time of the sigmoid function
dt_slope (float): delta time on where the slope is present in the sigmoid function
initial_value (float): initial value of the sigmoid function
final_value (float): final value of the sigmoid function
is_half_function (bool): whether to return half the sigmoid function or the full sigmoid function

Returns:

str: tiny expression of the sigmoid time function

static find_first_three_non_collinear_points(points: Sequence[Sequence[float]], a_tol: float = 1e-06) → Sequence[Sequence[float]] | None

Find the first 3 non-collinear points in sequence of points. If all are collinear, the function returns None.

Args:

points (Sequence[Sequence[float]]): points from which the non-collinear points should be searched for.
a_tol (float): absolute tolerance to check collinearity (default 1e-6)

Raises:

ValueError: if less than three points are provided.

Returns:

Optional[List[Sequence[float]]]: list of the first three points that are not collinear. If all are

collinear, None is returned.

static find_node_ids_close_to_geometry_nodes(mesh: Mesh, geometry: Geometry, eps: float = 1e-06) → ndarray[tuple[Any, ...], dtype[uint64]]

Searches the nodes in the mesh close to the point of a given geometry.

Args:

mesh (stem.mesh.Mesh): mesh object for which the node ids are required to be computed.
geometry (stem.geometry.Geometry): geometry containing the points of interest.
eps (float): tolerance for searching close nodes.

Returns:

npty.NDArray[np.uint64]: list of ids of the nodes close to the geometry points

static flip_node_order(elements: Sequence[Element])

Flips the node order of the elements, where all elements should be of the same type.

Args:

elements (List[stem.mesh.Element]): list of elements

Raises:

ValueError: when the elements are not of the same type.

static get_element_edges(element: Element) → List[List[int]]

Gets the nodal connectivities of the line edges of elements

Args:

element (stem.mesh.Element): element object

Returns:

List[List[int]]: nodal connectivities of the line edges of the element

static get_unique_objects(input_sequence: Sequence[Any]) → List[Any]

Get the unique objects, i.e., the objects that share the same memory location.

Args:

input_sequence (Sequence[Any]): full list of possible duplicate objects

Returns:

List[Any]: list of unique objects

static is_collinear(point: Sequence[float], start_point: Sequence[float], end_point: Sequence[float], a_tol: float = 1e-06) → bool

Check if point is aligned with the other two on a line. Points must have the same dimension (2D or 3D)

Args:

point (Sequence[float]): point coordinates to be tested
start_point (Sequence[float]): coordinates of first point of a line
end_point (Sequence[float]): coordinates of second point of a line
a_tol (float): absolute tolerance to check collinearity (default 1e-6)

Raises:

ValueError: when there is a dimension mismatch in the point dimensions.

Returns:

bool: whether the point is aligned or not

static is_non_str_sequence(seq: object) → bool

check whether object is a sequence but also not a string

Returns:

bool: whether the sequence but also not a string

static is_point_aligned_and_between_any_of_points(coordinates: Sequence[Sequence[Sequence[float]]], origin: Sequence[float]) → bool

Checks that the point (origin) provided aligns with at least one of the lines, expressed as list of pairs of coordinates representing the edges of the line.

Args:

coordinates (Sequence[Sequence[Sequence[float]]]): Pair-wise sets of coordinates representing the line on which the origin should lie.
origin (Sequence[float]): the coordinates of the point to be checked for alignment.

Returns:

bool: whether the considered point in at least one of the given lines (i.e. within the sequence of pair-wise points).

static is_point_between_points(point: Sequence[float], start_point: Sequence[float], end_point: Sequence[float]) → bool

Check if point is between the other two. Points must have the same dimension (2D or 3D).

Args:

point (Sequence[float]): point coordinates to be tested
start_point (Sequence[float]): first extreme coordinates of the line
end_point (Sequence[float]): second extreme coordinates of the line

Raises:

ValueError: when there is a dimension mismatch in the point dimensions.

Returns:

bool: whether the point is between the other two or not

static is_point_coplanar_to_polygon(point: Sequence[float], polygon_points: Sequence[Sequence[float]], a_tol: float = 1e-06) → bool

Checks whether a point is coplanar to a list of points defining a polygon

Args:

point (Sequence[float]): point to be checked.
polygon_points (Sequence[Sequence[float]]): points belonging to the polygon.
a_tol (float): absolute tolerance to check planarity (default 1e-6)

Raises:

ValueError: if the polygon itself is not planar.
ValueError: if all the points in the polygon are collinear.

Returns:

bool: whether the point is coplanar with the polygon.

static is_polygon_planar(polygon_points: Sequence[Sequence[float]], a_tol: float = 1e-06) → bool

Checks whether a polygon is planar, i.e. all its point lie on the same plane.

Args:

polygon_points (Sequence[Sequence[float]]): points belonging to the polygon.
a_tol (float): absolute tolerance to check planarity (default 1e-6)

Raises:

ValueError: if less than three points are provided.
ValueError: if all the points in the polygon are collinear.

Returns:

bool: whether the polygon is planar.

static is_volume_edge_defined_outwards(edge_element: Element, body_element: Element, nodes: Dict[int, Sequence[float]]) → bool

Checks if the normal vector of the edge element is pointing outwards of the body element.

Args:

edge_element (stem.mesh.Element): 2D edge surface element
body_element (stem.mesh.Element): 3D body volume element
nodes (Dict[int, Sequence[float]]): dictionary of node ids and coordinates

Raises:

ValueError: when the edge element is not a 2D element.
ValueError: when the body element is not a 3D element.
ValueError: when not all nodes of the edge element are part of the body element.

Returns:

bool: True if the normal vector of the edge element is pointing outwards of the body element,
False otherwise.

static merge(a: Dict[Any, Any], b: Dict[Any, Any], path: List[str] | Any = None) → Dict[Any, Any]

merges dictionary b into dictionary a. if existing keywords conflict it assumes they are concatenated in a list

Args:

a (Dict[Any,Any]): first dictionary
b (Dict[Any,Any]): second dictionary
path (List[str]): object to help navigate the deeper layers of the dictionary. Initially this has to be None

Returns:

a (Dict[Any,Any]): updated dictionary with the additional dictionary b

static replace_extensions(filename: str, new_extension: str) → str

Adjust the extension of a file. Can remove multiple extensions (e.g. .tar.gz.tmp) with a new extension (e.g. json). If no extensions are given, the new extension is added directly.

Args:

filename (str): name or path to the filename for which the extension needs to be changed
new_extension (str): the new extension for the file

Returns:

str: name or path to the filename with the desired extension

static validate_coordinates(coordinates: Sequence[Sequence[float]] | ndarray[tuple[Any, ...], dtype[float64]])

Validates the coordinates in input.

Args:

coordinates (Union[Sequence[Sequence[float]], npty.NDArray[np.float64]]): The coordinates of the load.

Raises:

ValueError: if coordinates is not a 2D array
ValueError: if the coordinates are not 3D.
ValueError: if the coordinates are not real numbers (i.e. contain NaN or inf).