stem package

Subpackages

Submodules

stem.additional_processes module

class stem.additional_processes.AdditionalProcessPart(parameters: AdditionalProcessesParametersABC, model_part_name: str = '')

Bases: object

Class containing the parameters for an additional process to be applied to an existing model part. If the model_part_name is left empty, the additional process will be applied to the whole model.

Attributes:

  • parameters (AdditionalProcessesParametersABC): The parameters of the additional process

  • model_part_name (str): The name of the model part to which the additional process will be applied. Default is

    an empty string, meaning the whole model.

model_part_name: str = ''
parameters: AdditionalProcessesParametersABC
class stem.additional_processes.AdditionalProcessesParametersABC

Bases: ABC

Abstract base class to describe the parameters required for additional processes (e.g. excavations and parameter fields)

class stem.additional_processes.Excavation(deactivate_body_model_part: bool)

Bases: AdditionalProcessesParametersABC

Class containing the parameters for an excavation process

Inheritance:
Attributes:

  • deactivate_body_model_part (bool): Deactivate or not the body model part

deactivate_body_model_part: bool
class stem.additional_processes.ExtrapolateIntegrationPointToNodesParameters(list_of_variables: List[str])

Bases: AdditionalProcessesParametersABC

Class containing the parameters for extrapolating integration point values to nodes

Inheritance:
Attributes:

  • list_of_variables (List[str]): list of variable names to be extrapolated from integration points to nodes

list_of_variables: List[str]
class stem.additional_processes.HingeParameters(ROTATIONAL_STIFFNESS_AXIS_2: float, ROTATIONAL_STIFFNESS_AXIS_3: float)

Bases: AdditionalProcessesParametersABC

Class containing the parameters for a hinge process

Inheritance:
Attributes:

  • ROTATIONAL_STIFFNESS_AXIS_2 (float): Rotational stiffness ratio local axis 2

  • ROTATIONAL_STIFFNESS_AXIS_3 (float): Rotational stiffness ratio local axis 3

ROTATIONAL_STIFFNESS_AXIS_2: float
ROTATIONAL_STIFFNESS_AXIS_3: float
class stem.additional_processes.ParameterFieldParameters(property_names: List[str], function_type: str, field_file_names: List[str] | None = None, field_generator: FieldGeneratorABC | None = None, tiny_expr_function: str | None = None)

Bases: AdditionalProcessesParametersABC

For the changing a parameter field, 3 options are available to se the parameter field:

  • json: an additional json file should be provided that contains a values field. The number length of the values must match with the number of elements of the part to be updated.

  • input: In this case, the function is explicitly defined as function of coordinates (x, y and z) and time (t).

  • python: A python script needs to be provided for the purpose. This is currently not supported in STEM.

Attributes:
  • property_names (List[str]): the names of the (material) properties that needs to be changed

    (e.g. [YOUNG_MODULUS])

  • function_type (str): the type of function to be provided. It can be either json_file or input,

    as provided in the function documentation.

  • field_file_names (Optional[List[str]]): Name for the json file where the field parameters will be stored.

    This is optional for json function_type.

  • field_generator (Optional[stem.field_generator.FieldGeneratorABC]): the field generator to produce

    the values in the json file. Currently only random fields is supported but will be in the future implemented as custom functions that take in input X, Y, Z coordinates. Not required for python and input function types. This is optional for json function_type.

  • tiny_expr_function (Optional[str]): is a tiny expression string with dependency on coordinates (x, y, z)

    and time (e.g. x + y^2 + 2*cos(t)). For more info check tinyexpr on GitHub. This is optional for input function_type.

field_file_names: List[str] | None = None
field_generator: FieldGeneratorABC | None = None
function_type: str
property_names: List[str]
tiny_expr_function: str | None = None

stem.boundary module

class stem.boundary.AbsorbingBoundary(absorbing_factors: List[float], virtual_thickness: float)

Bases: BoundaryParametersABC

Class containing the boundary parameters for a point boundary

Inheritance:
Attributes:

  • absorbing_factors (List[float]): Indicated how much of the P-wave and S-wave should be damped from the boundaries and is comprised between 0 (no damping) and 1 (full damping).

  • virtual_thickness (float): Entity of the virtual thickness [m].

absorbing_factors: List[float]
static get_element_name(n_dim_model: int, n_nodes_element: int, analysis_type: AnalysisType) → str | None

Static method to get the element name for an absorbing boundary.

Args:

  • n_dim_model (int): The number of dimensions of the model (2 or 3)

  • n_nodes_element (int): The number of nodes per element

  • analysis_type (stem.solver.AnalysisType): The analysis type.

Raises:

  • ValueError: Absorbing boundary conditions can only be applied in mechanical or mechanical groundwater flow analysis

Returns:

  • Optional[str]: The element name

property is_constraint: bool

Property which indicates if boundary condition is a constraint. False for AbsorbingBoundary.

Returns:

  • bool

virtual_thickness: float
class stem.boundary.BoundaryParametersABC

Bases: ABC

Abstract base class for boundary parameters

abstract static get_element_name(n_dim_model: int, n_nodes_element: int, analysis_type: AnalysisType) → str | None

Abstract static method to get the element name for a boundary condition.

Args:

  • n_dim_model (int): The number of dimensions of the model

  • n_nodes_element (int): The number of nodes per element

  • analysis_type (stem.solver.AnalysisType): The analysis type.

Raises:

  • Exception: abstract method is called

abstract property is_constraint: bool

Property which indicates if boundary condition is a constraint.

Raises:

  • Exception: abstract method is called

class stem.boundary.DisplacementConstraint(is_fixed: List[bool], value: List[float | Table])

Bases: BoundaryParametersABC

Class containing the boundary parameters for displacement constraint

Inheritance:
Attributes:

  • is_fixed (List[bool]): Specify if constraint is fixed for each direction.

  • value (List[Union[float, stem.table.Table]]): Displacement value for direction [m]. It should be a list of either float or table for each displacement. If a float is specified, the displacement is time-independent, otherwise the table specifies the amplitude of the amplitude of the displacement [m] over time [s] for each direction.

static get_element_name(n_dim_model: int, n_nodes_element: int, analysis_type: AnalysisType) → str | None

Static method to get the element name for a displacement constraint. Displacement constraint does not have a name.

Args:

  • n_dim_model (int): The number of dimensions of the model (2 or 3)

  • n_nodes_element (int): The number of nodes per element

  • analysis_type (stem.solver.AnalysisType): The analysis type.

Raises:

  • ValueError: Displacement constraint can only be applied in mechanical or mechanical groundwater flow

Returns:

  • None: Displacement constraint does not have a name

property is_constraint: bool

Property which indicates if boundary condition is a constraint. True for DisplacementConstraint.

Returns:

  • bool

is_fixed: List[bool]
value: List[float | Table]
class stem.boundary.RotationConstraint(is_fixed: List[bool], value: List[float | Table])

Bases: BoundaryParametersABC

Class containing the boundary parameters for rotation constraint

Inheritance:
Attributes:

  • is_fixed (List[bool]): Specify if constraint is fixed around each axis.

  • value (List[Union[float, stem.table.Table]]): Rotation value around x, y and z axis [Rad]. It should be a list of either float or table for each direction. If a float is specified, the rotation is time-independent, otherwise the table specifies the amplitude of the rotation [Rad] over time [s] around each axis.

static get_element_name(n_dim_model: int, n_nodes_element: int, analysis_type: AnalysisType) → str | None

Static method to get the element name for a rotation constraint. Rotation constraint does not have a name.

Args:

  • n_dim_model (int): The number of dimensions of the model

  • n_nodes_element (int): The number of nodes per element

  • analysis_type (stem.solver.AnalysisType): The analysis type.

Raises:

  • ValueError: Rotation constraint can only be applied in mechanical or mechanical groundwater flow

Returns:

  • None: Rotation constraint does not have a name

property is_constraint: bool

Property which indicates if boundary condition is a constraint. True for RotationConstraint.

Returns:

  • bool

is_fixed: List[bool]
value: List[float | Table]

stem.default_materials module

class stem.default_materials.DefaultMaterial(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enumeration class to retrieve default soil materials to help the user in making the model.

Rail_46E3_2D = StructuralMaterial(name='default_elastic_rail_46E3_2D', material_parameters=EulerBeam(ndim=2, YOUNG_MODULUS=210000000000.0, POISSON_RATIO=0.3, DENSITY=7850, CROSS_AREA=0.005944, I33=1.606e-05, I22=None, TORSIONAL_INERTIA=None, RAYLEIGH_M=None, RAYLEIGH_K=None))
Rail_46E3_3D = StructuralMaterial(name='default_elastic_rail_46E3_3D', material_parameters=EulerBeam(ndim=3, YOUNG_MODULUS=210000000000.0, POISSON_RATIO=0.3, DENSITY=7850, CROSS_AREA=0.005944, I33=1.606e-05, I22=3.075e-06, TORSIONAL_INERTIA=1.9135e-05, RAYLEIGH_M=None, RAYLEIGH_K=None))
Rail_54E1_2D = StructuralMaterial(name='default_elastic_rail_54E1_2D', material_parameters=EulerBeam(ndim=2, YOUNG_MODULUS=210000000000.0, POISSON_RATIO=0.3, DENSITY=7850, CROSS_AREA=0.006977, I33=2.3372e-05, I22=None, TORSIONAL_INERTIA=None, RAYLEIGH_M=None, RAYLEIGH_K=None))
Rail_54E1_3D = StructuralMaterial(name='default_elastic_rail_54E1_3D', material_parameters=EulerBeam(ndim=3, YOUNG_MODULUS=210000000000.0, POISSON_RATIO=0.3, DENSITY=7850, CROSS_AREA=0.006977, I33=2.3372e-05, I22=2.787e-06, TORSIONAL_INERTIA=2.616e-05, RAYLEIGH_M=None, RAYLEIGH_K=None))
Rail_60E1_2D = StructuralMaterial(name='default_elastic_rail_60E1_2D', material_parameters=EulerBeam(ndim=2, YOUNG_MODULUS=210000000000.0, POISSON_RATIO=0.3, DENSITY=7850, CROSS_AREA=0.00767, I33=3.038e-05, I22=None, TORSIONAL_INERTIA=None, RAYLEIGH_M=None, RAYLEIGH_K=None))
Rail_60E1_3D = StructuralMaterial(name='default_elastic_rail_60E1_3D', material_parameters=EulerBeam(ndim=3, YOUNG_MODULUS=210000000000.0, POISSON_RATIO=0.3, DENSITY=7850, CROSS_AREA=0.00767, I33=3.038e-05, I22=5.123e-06, TORSIONAL_INERTIA=3.55e-05, RAYLEIGH_M=None, RAYLEIGH_K=None))
class stem.default_materials.RailTypes(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enumeration of rail types

rail_46E3 = 1
rail_54E1 = 2
rail_60E1 = 3
stem.default_materials.set_default_steel_rail_material(ndim: int, rail_type: RailTypes) → StructuralMaterial

Function to define the default elastic material for a steel beam of the given geometry. Currently, the most common rails adopted in the Netherlands are implemented (46E3, 54E1 and 60E1).

Args:

  • ndim (int): number of dimensions of the problem (either 2 or 3)

  • rail_type (RailTypes): instance of the enumeration to describe the rail type

Raises:

  • ValueError: if the rail type is not implemented

Returns:

stem.field_generator module

class stem.field_generator.FieldGeneratorABC

Bases: ABC

Abstract class to generate fields as function of points coordinates (x, y and z). The function should implement a generate method to initialise the field and the values property to retrieve the generated field.

abstract generate(coordinates: ndarray[tuple[Any, ...], dtype[float64]])

Abstract method to generate the fields for the required coordinates. It has to set the generated_field attribute.

Args:

  • coordinates (numpy.typing.NDArray[np.float64]): Sequence of points where the field needs to be generated.

Raises:

  • Exception: abstract class of generate is called

abstract property generated_fields: List[List[Any]] | None

Abstract property of the generated field.

Raises:

  • ValueError: if field is not generated using the generate() method

Returns:

  • Optional[List[List[Any]]]: the list of generated values for the fields.

class stem.field_generator.RandomFieldGenerator(model_name: str, cov: float, v_scale_fluctuation: float, anisotropy: float | List[float], angle: float | List[float], mean_value: int | float | None = None, seed: int = 14)

Bases: FieldGeneratorABC

Class to generate random fields for a material property in the model as function of the coordinates of the centroid of the elements (x, y and z).

Inheritance:

  • FieldGeneratorABC: abstract class to generate fields as function of points coordinates (x, y and z).

Attributes:

  • __generated_field (Optional[List[float]]): The generated field values. Defaults to None.

  • model_name (str): Name of the model to be used. Options are: “Gaussian”, “Exponential”, “Matern”, “Linear”

  • n_dim (int): number of dimensions of the model (2 or 3).

  • cov (float): The coefficient of variation of the random field.

  • v_scale_fluctuation (float): The vertical scale of fluctuation of the random field.

  • anisotropy (list): The anisotropy of the random field in the other directions (per dimension).

  • angle (list): The angle of the random field (per dimension).

  • mean_value (Optional[float]): mean value of the random field. Defaults to None. In that case it should be set otherwise before running the generate method.

  • seed (int): The seed number for the random number generator.

Initialise a random generator field. The mean value is optional because it can be set at another moment. In that case it should be set before running the generate method.

Anisotropy and angle can be given as scalar, 1-D and 2-D lists. In case the model is 3D but a 1-D or scalar is provided, it is assumed the same angle and anisotropy along both horizontal direction. Because the models in STEM always have coordinates in three dimensions (x, y, and z), random fields always have a dimension (n_dim) equal to 3.

Args:

  • model_name (str): Name of the model to be used. Options are: “Gaussian”, “Exponential”, “Matern”, “Linear”

  • cov (float): The coefficient of variation of the random field.

  • v_scale_fluctuation (float): The vertical scale of fluctuation of the random field.

  • anisotropy (Union[float, List[float]]): The anisotropy of the random field in the other directions (per dimension). Either a float, or a list of float containing 1 or 2 elements is accepted.

  • angle (Union[float, List[float]]): The angle of the random field (per dimension). Either a float, or a list of float containing 1 or 2 elements is accepted.

  • mean_value (Optional[float]): mean value of the random field. Defaults to None. In that case it should be set otherwise before running the generate method.

  • seed (int): The seed number for the random number generator.

Raises:

  • ValueError: if the model_name is not a valid or implemented model.

  • ValueError: if the anisotropy has more than 2 elements.

  • ValueError: if the angle has more than 2 elements.

generate(coordinates: ndarray[tuple[Any, ...], dtype[float64]])

Generate the random field parameters at the coordinates specified. The generated values are stored in generated_field attribute.

Args:

  • coordinates (numpy.typing.NDArray[np.float64]): Sequence of points where the random field needs to be

generated.

Raises:

  • ValueError: if the mean value of the random field is undefined.

property generated_fields: List[Any] | None

Returns the value of the generated field.

Raises:

  • ValueError: if field is not generated using the generate() method

Returns:

  • Optional[List[List[Any]]]: the list of generated values for the fields.

stem.geometry module

class stem.geometry.GeometricalObjectABC

Bases: ABC

An abstract base class for all geometrical objects.

abstract property id: int

Abstract property for returning the id of the object.

Raises:

  • Exception: cannot call abstract method.

class stem.geometry.Geometry(points: Dict[int, Point] = {}, lines: Dict[int, Line] = {}, surfaces: Dict[int, Surface] = {}, volumes: Dict[int, Volume] = {})

Bases: object

A class to represent a collection of geometric objects in a zero-, one-, two- or three-dimensional space.

Attributes:

  • points (Dict[int, Point]): An dictionary of Point objects representing the points in the geometry.

  • lines (Dict[int, Line]): A dictionary of Line objects representing the lines in the geometry.

  • surfaces (Dict[int, Surface]): A dictionary of Surface objects representing the surfaces in the geometry.

  • volumes (Dict[int, Volume]): A dictionary of Volume objects representing the volumes in the geometry.

calculate_area_surface(surface_id: int) → float

Calculate the area of a convex or concave surface in a 3D space using the shoelace algorithm.

Args:

  • surface_id (int): The id of the surface.

Returns:

  • float: The area of the surface.

calculate_centre_of_mass_surface(surface_id: int) → ndarray[tuple[Any, ...], dtype[float64]]

Calculate the centre of mass of a surface. Where mass is given to the length of the lines that make up the surface. The centre of mass is then given by the ‘O’ in the following diagram:

x—x—x—x—x | | x O x | | x—————x

Args:

  • surface_id (int): The id of the surface.

Returns:

  • npty.NDArray[np.float64]: The coordinates of the centre of mass of the surface.

calculate_centre_of_mass_volume(volume_id: int) → ndarray[tuple[Any, ...], dtype[float64]]

Calculate the centre of mass of a volume. Where mass is given to the area of the surfaces that make up the volume.

Args:

  • volume_id (int): The id of the volume.

Returns:

  • npty.NDArray[np.float64]: The coordinates of the centre of mass of the volume.

calculate_centroid_of_line(line_id: int) → ndarray[tuple[Any, ...], dtype[float64]]

Calculate the centroid of a line.

Args:

  • line_id (int): The id of the line.

Returns:

  • npty.NDArray[np.float64]: The coordinates of the centroid of the line.

calculate_centroid_of_surface(surface_id: int) → ndarray[tuple[Any, ...], dtype[float64]]

Calculate the centroid of a surface.

Args:

  • surface_id (int): The id of the surface.

Returns:

  • npty.NDArray[np.float64]: The coordinates of the centroid of the surface.

calculate_length_line(line_id: int) → float

Calculate the length of a line.

Args:

  • line_id (int): The id of the line.

Returns:

  • float: The length of the line.

classmethod create_geometry_from_geo_data(geo_data: Dict[str, Any])

Creates the geometry from gmsh geo_data

Args:

  • geo_data (Dict[str, Any]): A dictionary containing the geometry data as provided by gmsh_utils.

Returns:
classmethod create_geometry_from_gmsh_group(geo_data: Dict[str, Any], group_name: str)

Initialises the geometry by parsing the geometry data from the geo_data dictionary.

Args:

  • geo_data (Dict[str, Any]): A dictionary containing the geometry data as provided by gmsh_utils.

  • group_name (str): The name of the group to create the geometry from.

Returns:

  • Geometry: A Geometry object containing the geometric objects in the group.

get_ordered_points_from_surface(surface_id: int) → List[Point]

Returns the points that make up the surface in the correct order, i.e. the order in which the points are connected by the lines that make up the surface.

Args:

  • surface_id (int): The id of the surface.

Returns:

  • List[Point]: A sequence of points that make up the surface in the correct order.

to_dict() → Dict[str, Any]

Serializes the geometry object to a dictionary.

Returns:

  • Dict[str, Any]: A dictionary representation of the geometry object.

class stem.geometry.Line(id: int)

Bases: GeometricalObjectABC

A class to represent a line in space.

Inheritance:
Attributes:

  • id (int): A unique identifier for the line.

  • point_ids (Sequence[int]): A sequence of two integers representing the ids of the points that make up the line.

Constructor for the line class.

Args:

id (int): The id of the line.

classmethod create(point_ids: Sequence[int], id: int) → Line

Creates a line object from a list of point ids and a line id.

Args:

  • point_ids (Sequence[int]): A sequence of two integers representing the ids of the points that make up the line.

  • id (int): The id of the line.

Returns:

  • Line: A line object.

property id: int

Getter for the id of the line.

Returns:

  • int: The id of the line.

class stem.geometry.Point(id: int)

Bases: GeometricalObjectABC

A class to represent a point in space.

Inheritance:
Attributes:

  • __id (int): A unique identifier for the point.

  • coordinates (Sequence[float]): A sequence of floats representing the x, y and z coordinates of the point.

Constructor for the point class.

Args:

  • id (int): The id of the point.

classmethod create(coordinates: Sequence[float], id: int) → Point

Creates a point object from a list of coordinates and a point id.

Args:

  • coordinates (Sequence[float]): An iterable of floats representing the x, y and z coordinates of the point.

  • id (int): The id of the point.

Returns:
property id: int

Getter for the id of the point.

Returns:

  • int: The id of the point.

class stem.geometry.Surface(id: int)

Bases: GeometricalObjectABC

A class to represent a surface in space.

Inheritance:
Attributes:

  • __id (int): A unique identifier for the surface.

  • line_ids (Sequence[int]): A sequence of three or more integers representing the ids of the lines that make up the surface.

classmethod create(line_ids: Sequence[int], id: int) → Surface

Creates a surface object from a list of line ids and a surface id.

Args:

  • line_ids (Sequence[int]): A sequence of three or more integers representing the ids of the lines that make up the surface.

  • id (int): The id of the surface.

Returns:
property id: int

Getter for the id of the surface.

Returns:

  • int: The id of the surface.

class stem.geometry.Volume(id: int)

Bases: GeometricalObjectABC

A class to represent a volume in a three-dimensional space.

Inheritance:
Attributes:

  • __id (int): A unique identifier for the volume.

  • surface_ids (Sequence[int]): A sequence of four or more integers representing the ids of the surfaces that make up the volume.

classmethod create(surface_ids: Sequence[int], id: int) → Volume

Creates a volume object from a list of surface ids and a volume id.

Args:

  • surface_ids (Sequence[int]): A sequence of four or more integers representing the ids of the surfaces that make up the volume.

  • id (int): The id of the volume.

Returns:
property id: int

Getter for the id of the volume.

Returns:

  • int: The id of the volume.

stem.globals module

This module contains global variables used in the stem package.

stem.globals.ELEMENT_DATA: Dict[str, Any] = {'HEXAHEDRON_20N': {'edges': [[0, 1, 8], [1, 2, 9], [2, 3, 10], [3, 0, 11], [4, 5, 16], [5, 6, 17], [6, 7, 18], [7, 4, 19], [0, 4, 12], [1, 5, 13], [2, 6, 14], [3, 7, 15]], 'gmsh_to_kratos_order': [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 13, 9, 10, 12, 14, 15, 16, 18, 19, 17], 'n_vertices': 8, 'ndim': 3, 'order': 2, 'reversed_order': [1, 0, 3, 2, 5, 4, 7, 6, 8, 11, 10, 9, 13, 12, 15, 14, 16, 19, 18, 17]}, 'HEXAHEDRON_8N': {'edges': [[0, 1], [1, 2], [2, 3], [3, 0], [4, 5], [5, 6], [6, 7], [7, 4], [0, 4], [1, 5], [2, 6], [3, 7]], 'n_vertices': 8, 'ndim': 3, 'order': 1, 'reversed_order': [1, 0, 3, 2, 5, 4, 7, 6]}, 'LINE_2N': {'edges': [[0, 1]], 'n_vertices': 2, 'ndim': 1, 'order': 1, 'reversed_order': [1, 0]}, 'LINE_3N': {'edges': [[0, 1, 2]], 'n_vertices': 2, 'ndim': 1, 'order': 2, 'reversed_order': [1, 0, 2]}, 'POINT_1N': {'edges': [], 'n_vertices': 1, 'ndim': 0, 'order': 1, 'reversed_order': [0]}, 'QUADRANGLE_4N': {'edges': [[0, 1], [1, 2], [2, 3], [3, 0]], 'n_vertices': 4, 'ndim': 2, 'order': 1, 'reversed_order': [1, 0, 3, 2]}, 'QUADRANGLE_8N': {'edges': [[0, 1, 4], [1, 2, 5], [2, 3, 6], [3, 0, 7]], 'n_vertices': 4, 'ndim': 2, 'order': 2, 'reversed_order': [1, 0, 3, 2, 4, 7, 6, 5]}, 'TETRAHEDRON_10N': {'edges': [[0, 1, 4], [1, 2, 5], [2, 0, 6], [0, 3, 7], [1, 3, 8], [2, 3, 9]], 'gmsh_to_kratos_order': [0, 1, 2, 3, 4, 5, 6, 7, 9, 8], 'n_vertices': 4, 'ndim': 3, 'order': 2, 'reversed_order': [1, 0, 2, 3, 4, 6, 5, 8, 7, 9]}, 'TETRAHEDRON_4N': {'edges': [[0, 1], [1, 2], [2, 0], [0, 3], [1, 3], [2, 3]], 'n_vertices': 4, 'ndim': 3, 'order': 1, 'reversed_order': [1, 0, 2, 3]}, 'TRIANGLE_3N': {'edges': [[1, 2], [2, 0], [0, 1]], 'n_vertices': 3, 'ndim': 2, 'order': 1, 'reversed_order': [2, 1, 0]}, 'TRIANGLE_6N': {'edges': [[1, 2, 3], [1, 2, 4], [2, 0, 5]], 'n_vertices': 3, 'ndim': 2, 'order': 2, 'reversed_order': [2, 1, 0, 4, 3, 5]}}

Element data for supported element types in STEM. The data contains the following information: - ndim (int): number of dimensions - order (int): element order - n_vertices (int): number of vertices - reversed_order (List[int]): reversed connectivity order of the element - edges (List[List[int]]): edges of the element, line edges of each element

class stem.globals.GlobalSettings(gravity_value: float = -9.81, time_step_precision: float = 1e-08, geometry_precision: float = 1e-08)

Bases: object

Class containing global settings for the stem package. These settings can be modified by the user to adjust the behavior of the package.

Attributes:

  • gravity_value (float): The gravitational acceleration value in m/s². Default is -9.81 m/s².

  • time_step_precision (float): The precision for time step calculations in seconds. Default is 1e-08 s.

  • geometry_precision (float): The precision for geometry calculations in meters. Default is 1e-08 m.

geometry_precision: float = 1e-08
gravity_value: float = -9.81
time_step_precision: float = 1e-08

stem.load module

class stem.load.GravityLoad(active: ~typing.List[bool] = <factory>, value: ~typing.List[float] = <factory>)

Bases: LoadParametersABC

Class containing the load parameters for a gravity load.

Inheritance:
Attributes:

  • active (List[bool]): Activate/deactivate load for each direction. Input True only in the vertical direction.

  • value (List[float]): Entity of the gravity acceleration in the 3 directions [m/s^2]. Should be -9.81 only in the vertical direction

active: List[bool]
static get_element_name(n_dim_model, n_nodes_element, analysis_type) → str | None

Static method to get the element name for a gravity load.

Args:

  • n_dim_model (int): The number of dimensions of the model

  • n_nodes_element (int): The number of nodes per element

  • analysis_type (stem.solver.AnalysisType): The analysis type

Raises:

  • ValueError: If the analysis type is not mechanical or mechanical groundwater flow

Returns:

  • None: Gravity load does not have a name

value: List[float]
class stem.load.LineLoad(active: List[bool], value: List[float | Table])

Bases: LoadParametersABC

Class containing the load parameters for a line load

Attributes:

  • active (List[bool]): Activate/deactivate load for each direction.

  • value (List[Union[float, stem.table.Table]]): Entity of the load in the 3 directions [N/m]. It should be a list of either float or table for each load. If a float is specified, the load is time-independent, otherwise the table specifies the amplitude of the load [N/m] over time [s] for each direction.

active: List[bool]
static get_element_name(n_dim_model: int, n_nodes_element: int, analysis_type: AnalysisType) → str | None

Static method to get the element name for a line load.

Args:

  • n_dim_model (int): The number of dimensions of the model (2 or 3)

  • n_nodes_element (int): The number of nodes per condition-element (2, 3)

  • analysis_type (stem.solver.AnalysisType): The analysis type

Raises:

  • ValueError: If the analysis type is not mechanical or mechanical groundwater flow

Returns:

  • Optional[str]: The element name for a line load

value: List[float | Table]
class stem.load.LoadParametersABC

Bases: ABC

Abstract base class for load parameters

abstract static get_element_name(n_dim_model: int, n_nodes_element: int, analysis_type: AnalysisType) → str | None

Abstract static method to get the element name for a load.

Args:

  • n_dim_model (int): The number of dimensions of the model

  • n_nodes_element (int): The number of nodes per condition-element

  • analysis_type (stem.solver.AnalysisType): The analysis type.

Raises:

  • Exception: abstract method is called

class stem.load.MovingLoad(load: List[float] | List[str], direction_signs: List[int], velocity: float | str, origin: List[float], offset: float = 0.0)

Bases: LoadParametersABC

Class containing the load parameters for a moving load.

Inheritance:
Attributes:

  • load (Union[List[float], List[str]]): Entity of the load [N] in the 3 directions. Can be defined as strings (when function of time) or as float. Mixed types are not accepted.

  • direction_signs (List[int]): Sign of motion along each axis (+1 or -1 for x, y, z).

    The actual direction is defined by the existing load path geometry.

  • velocity (Union[float, str]): Velocity of the moving load [m/s].

  • origin (List[float]): Starting coordinates of the moving load [m].

  • offset (float): Offset of the moving load [m].

direction_signs: List[int]
static get_element_name(n_dim_model: int, n_nodes_element: int, analysis_type: AnalysisType) → str | None

Static method to get the element name for a moving load.

Args:

  • n_dim_model (int): The number of dimensions of the model (2 or 3)

  • n_nodes_element (int): The number of nodes per condition-element (2, 3)

  • analysis_type (stem.solver.AnalysisType): The analysis type

Raises:

  • ValueError: If the analysis type is not mechanical or mechanical groundwater flow

Returns:

  • Optional[str]: The element name for a moving load

load: List[float] | List[str]
offset: float = 0.0
origin: List[float]
velocity: float | str
class stem.load.PointLoad(active: List[bool], value: List[float | Table])

Bases: LoadParametersABC

Class containing the load parameters for a point load

Inheritance:
Attributes:

  • active (List[bool]): Activate/deactivate load for each direction.

  • value (List[Union[float, stem.table.Table]]): Entity of the load in the 3 directions [N]. It should be a list of either float or table for each load. If a float is specified, the load is time-independent, otherwise the table specifies the amplitude of the load [N] over time [s] for each direction.

active: List[bool]
static get_element_name(n_dim_model: int, n_nodes_element: int, analysis_type: AnalysisType) → str | None

Static method to get the element name for a point load. Point load does not have a name.

Args:

  • n_dim_model (int): The number of dimensions of the model (2 or 3)

  • n_nodes_element (int): The number of nodes per condition-element (1)

  • analysis_type (stem.solver.AnalysisType): The analysis type

Raises:

  • ValueError: If the analysis type is not mechanical or mechanical groundwater flow

Returns:

  • Optional[str]: The element name for a point load

value: List[float | Table]
class stem.load.SurfaceLoad(active: List[bool], value: List[float] | List[Table])

Bases: LoadParametersABC

Class containing the load parameters for a surface load

Attributes:

  • active (List[bool]): Activate/deactivate load for each direction.

  • value (List[Union[float, stem.table.Table]]): Entity of the load in the 3 directions [Pa]. It should be a list of either float or table for each load. If a float is specified, the load is time-independent, otherwise the table specifies the amplitude of the load [Pa] over time [s] for each direction.

active: List[bool]
static get_element_name(n_dim_model: int, n_nodes_element: int, analysis_type: AnalysisType) → str | None

Static method to get the element name for a surface load.

Args:

  • n_dim_model (int): The number of dimensions of the model (3)

  • n_nodes_element (int): The number of nodes per condition-element

  • analysis_type (stem.solver.AnalysisType): The analysis type

Raises:

  • ValueError: If the analysis type is not mechanical or mechanical groundwater flow

Returns:

  • Optional[str]: The element name for a surface load

value: List[float] | List[Table]
class stem.load.UvecLoad(direction_signs: ~typing.List[int], velocity: float | str, origin: ~typing.List[float], wheel_configuration: ~typing.List[float], uvec_parameters: ~typing.Dict[str, ~typing.Any] = <factory>, uvec_state_variables: ~typing.Dict[str, ~typing.Any] = <factory>, uvec_model: ~types.ModuleType | ~typing.Any = None, uvec_file: str = '', uvec_function_name: str = '')

Bases: LoadParametersABC

Class containing the load parameters for a UVEC (User-defined VEhiCle) load.

Inheritance:
Attributes:
  • direction_signs (List[int]): Sign of motion along each axis (+1 or -1 for x, y, z).

    The actual direction is defined by the existing load path geometry.

  • velocity (Union[float, str]): Velocity of the moving load [m/s].

  • origin (List[float]): Starting coordinates of the first wheel [m].

  • wheel_configuration (List[float]): Wheel configuration, i.e. distances from the origin of each wheel [m].

  • uvec_parameters (Dict[str, Any]): Parameters of the UVEC function.

  • uvec_state_variables (Dict[str, Any]): State variables of the UVEC function.

  • uvec_model (ModuleType): UVEC model.

  • uvec_file (str): Path to the UVEC file.

  • uvec_function_name (str): Name of the UVEC function.

direction_signs: List[int]
static get_element_name(n_dim_model: int, n_nodes_element: int, analysis_type: AnalysisType) → str | None

Static method to get the element name for a UVEC load.

origin: List[float]
uvec_file: str = ''
uvec_function_name: str = ''
uvec_model: ModuleType | Any = None
uvec_parameters: Dict[str, Any]
uvec_state_variables: Dict[str, Any]
velocity: float | str
wheel_configuration: List[float]
class stem.load.UvecSupportedModels(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum class containing the supported UVEC models.

Inheritance:

  • Enum

Attributes:

  • TEN_DOF (str): 10 degrees of freedom UVEC model.

  • TWO_DOF (str): 2 degrees of freedom UVEC model.

TEN_DOF = 'UVEC.uvec_ten_dof_vehicle_2D'
TWO_DOF = 'UVEC.uvec_two_dof_vehicle_2D'

stem.logger module

stem.logger.enable_writing_to_log_file(log_path: Path | str)

Redirects all stdout/stderr to a log file

Args:

  • log_path (Union[Path, str]): Path to the log file

stem.mesh module

class stem.mesh.Element(id: int, element_type: str, node_ids: List[int])

Bases: object

Class containing information about an element

Attributes:

  • id (int): element id

  • element_type (str): Gmsh element type

  • node_ids (Sequence[int]): node ids

Initialize the element.

Args:

  • id (int): Element id

  • element_type (str): Gmsh-element type

  • node_ids (List[int]): Node connectivities

class stem.mesh.ElementShape(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum class for the element shape. TRIANGLE for triangular elements and tetrahedral elements, QUADRILATERAL for quadrilateral elements and hexahedral elements.

QUADRILATERAL = 'quadrilateral'
TRIANGLE = 'triangle'
class stem.mesh.Mesh(ndim: int)

Bases: object

Class containing information about the mesh

Args:

  • ndim (int): number of dimensions of the mesh

Attributes:

  • ndim (int): number of dimensions of the mesh

  • nodes (Dict[int, Node]): dictionary of node ids followed by the node object

  • elements (Dict[int, Element]): dictionary of element ids followed by the element object

Initialize the mesh.

Args:

  • ndim (int): number of dimensions of the mesh

calculate_centroids() → ndarray[tuple[Any, ...], dtype[float64]]

Calculate the centroids of all elements

Returns:

  • npty.NDArray[np.float64]: centroids of all elements

classmethod create_mesh_from_gmsh_group(mesh_data: Dict[str, Any], group_name: str) → Mesh

Creates a mesh object from gmsh group

Args:

  • mesh_data (Dict[str, Any]): dictionary of mesh data

  • group_name (str): name of the group

Raises:

  • ValueError: If the group name is not found in the mesh data

Returns:
find_elements_connected_to_nodes() → Dict[int, List[int]]

Creates a dictionary of node ids as keys and a list of element ids which are connected to the node as values.

Returns:

  • Dict[int, List[int]]: dictionary containing node ids as keys and a list of element ids which are

connected to the node as values.

class stem.mesh.MeshSettings(element_size: float = -1, element_order: int = 1, element_shape: ElementShape = ElementShape.TRIANGLE)

Bases: object

A class to represent the mesh settings.

Attributes:

  • element_size (float): The element size (default -1, which means that gmsh determines the size).

  • element_shape (ElementShape): The element shape. TRIANGLE for triangular elements and tetrahedral elements, QUADRILATERAL for quadrilateral elements and hexahedral elements. (default TRIANGLE)

  • __element_order (int): The element order. 1 for linear elements, 2 for quadratic elements. (default 1)

Initialize the mesh settings.

Args:

  • element_size (float): The element size (default -1, which means that gmsh determines the size).

  • element_order (int): The element order. 1 for linear elements, 2 for quadratic elements. (default 1)

  • element_shape (ElementShape): The element shape. TRIANGLE for triangular elements and tetrahedral elements, QUADRILATERAL for quadrilateral elements and hexahedral elements. (default TRIANGLE)

property constraints: Dict[str, Any]

Get the constraints.

Returns:

  • Dict[str, Any]: The constraints.

property element_order: int

Get the element order.

Returns:

  • int: element order

set_structured_mesh_constraint_line(line_id: int, n_points: int)

Set the structured mesh constraint for a line.

Args:

  • line_id (int): The line id.

  • n_points (int): The number of points.

set_structured_mesh_constraint_surface(surface_id: int, n_points: List[int])

Set the structured mesh constraint for a surface.

Args:

  • surface_id (int): The surface id.

  • n_points (List[int]): The number of points in x,y,z direction.

set_structured_mesh_constraint_volume(volume_id: int, n_points: List[int])

Set the structured mesh constraint for a volume.

Args:

  • volume_id (int): The volume id.

  • n_points (int): The number of points in x,y,z direction.

class stem.mesh.Node(id: int, coordinates: Sequence[float])

Bases: object

Class containing information about a node

Attributes:

  • id (int): node id

  • coordinates (Sequence[float]): node coordinates

Initialize the node.

Args:

  • id (int): Node id

  • coordinates (Sequence[float]): Node coordinates

stem.model module

class stem.model.Model(ndim: int)

Bases: object

A class to represent the main model.

Attributes:

  • ndim (int): Number of dimensions of the model

  • project_parameters (:class:`stem.solver.Problem): Object containing the problem data and solver settings.

  • geometry (Optional[stem.geometry.Geometry]) The geometry of the whole model.

  • body_model_parts (List[stem.model_part.BodyModelPart]): A list containing the body model parts.

  • process_model_parts (List[stem.model_part.ModelPart]): A list containing the process model parts.

  • additional_process_parts (List[stem.additional_processes.AdditionalProcessPart]): A list containing

    the additional process model parts.

  • output_settings (List[stem.output.Output]): A list containing the output settings.

  • extrusion_length (Optional[float]): The extrusion length in the out of plane direction.

  • groups (Dict[str, Any]): A dictionary containing shared information among sets of model parts.

Constructor of the Model class.

Args:

  • ndim (int): Number of dimensions of the model

add_all_layers_from_geo_file(geo_file_name: str, body_names: Sequence[str])

Add all physical groups from a geo file to the model. The physical groups with the names in body_names are added as body model parts, the other physical groups are added as process model parts.

Args:

  • geo_file_name (str): name of the geo file

  • body_names (Sequence[str]): names of the physical groups which should be added as body model parts

add_boundary_condition_by_geometry_ids(ndim_boundary: int, geometry_ids: Sequence[int], boundary_parameters: BoundaryParametersABC, name: str)

Add a boundary condition to the model by giving the geometry ids of the boundary condition.

Args:

  • ndim_boundary (int): dimension of the boundary condition

  • geometry_ids (Sequence[int]): geometry ids of the boundary condition

  • boundary_condition (stem.boundary_condition.BoundaryCondition): boundary condition object

  • name (str): name of the boundary condition

add_boundary_condition_on_plane(plane_vertices: Sequence[Sequence[float]], boundary_parameters: BoundaryParametersABC, name: str)

Adds a boundary condition to the model by giving a sequence of 3D coordinates. The boundary condition is added to all the surfaces which fall within the plane.

Args:

  • plane_vertices (Sequence[Sequence[float]]): Minimum 3 vertices of the plane.

  • boundary_parameters (stem.boundary.BoundaryParametersABC): The parameters of the boundary

    condition.

  • name (str): The name of the boundary condition.

Raises:

  • ValueError: if the plane has less than 3 vertices.

add_boundary_condition_on_polygon(polygon_coordinates: Sequence[Sequence[float]], boundary_parameters: BoundaryParametersABC, name: str)

Adds a boundary condition to the model by giving a sequence of 3D coordinates. The boundary condition is added to all the surfaces which fall within the polygon. A surface is considered to be within the polygon if all its points are within the polygon.

Args:

  • polygon_coordinates (Sequence[Sequence[float]]): The coordinates of the polygon.

  • boundary_parameters (stem.boundary.BoundaryParametersABC): The parameters of the boundary

    condition.

  • name (str): The name of the boundary condition.

add_field(part_name: str, field_parameters: ParameterFieldParameters)

Add a parameter field to a given model part (specified by the part_name input). if the mean_value attribute of the field generator is None, the corresponding material property is used as mean.

Args:
Raises:

  • ValueError: if the part name is not a body model part.

  • ValueError: if the body model part has no material.

  • ValueError: if the mean value of the material property is a boolean.

add_group_for_extrusion(group_name: str, reference_depth: float, extrusion_length: float)

Adds a group for extrusion which consists of a starting coordinate in the out of plane direction a name and the the length for the extrusion. The group must be always unique while extrusion length can also be negative.

Args:

  • group_name (str): The name of the group. Must be unique.

  • reference_depth (float): The reference (starting) depth for the extrusion in the out of plane direction.

  • extrusion_length (float): The length of the group used for the extrusion. It can also be negative

Raises:

  • ValueError: if the section_name matches an already an existing 3D section.

add_hinge_on_beam(beam_model_part_name: str, hinge_coordinates: Sequence[Sequence[float]], hinge_parameters: HingeParameters, hinge_model_part_name: str)

Adds a hinge to the model by giving the name of the beam model part where the hinge has to be applied.

Args:

  • beam_model_part_name (str): name of the beam model part where the hinge needs to be applied.

  • hinge_coordinates (Sequence[Sequence[float]]): coordinates of the hinge.

  • hinge_parameters (stem.hinge.HingeParametersABC): hinge parameters to define the hinge object.

  • hinge_model_part_name (str): name of the hinge.

Raises:

  • ValueError: if the hinge model part does not have a geometry.

  • ValueError: if the beam model part is not found.

  • ValueError: if the beam model part does not have a geometry.

  • ValueError: if the beam model part does not have a beam material.

  • NotImplementedError: if the hinge is applied in a 2D model.

  • ValueError: if the hinge points are not part of the beam model part.

add_load_by_coordinates(coordinates: Sequence[Sequence[float]], load_parameters: LoadParametersABC, name: str)

Adds a load to the model by giving a sequence of 3D coordinates. For a 2D model, the third coordinate is ignored. The coordinates need to follow clockwise or anti-clockwise order.

Args:

  • coordinates (Sequence[Sequence[float]]): The coordinates of the load.

  • load_parameters (stem.load.LoadParametersABC): The parameters of the load.

  • name (str): The name of the load part.

Raises:
  • ValueError: if load_parameters is not of one of the classes PointLoad, MovingLoad, LineLoad

    or SurfaceLoad.

add_load_by_geometry_ids(geometry_ids: Sequence[int], load_parameters: LoadParametersABC, name: str)

Add a load to the model by giving the geometry ids of the geometry where the load has to be applied. The geometry dimension of the entity where the load needs to be applied is determined based on the load_parameters (0=point load, 1=line load, 2=surface load, 3=volume).

Args:

  • geometry_ids (Sequence[int]): geometry ids of the entities where the load needs to be applied.

  • load_parameters (stem.load.LoadParametersABC): load parameters to define the load object.

  • name (str): name of the load.

Raises:

  • NotImplementedError: when the load parameter provided is not one of point, line, moving, UVEC

or surface loads.

add_load_on_line_model_part(model_part_name: str, load_parameters: LoadParametersABC, load_name: str)

Adds a load to the model by giving the name of the line model part where the load has to be applied. It only works with LineLoad, MovingLoad and UvecLoad.

Args:

  • model_part_name (str): name of the line model part where the load needs to be applied.

  • load_parameters (stem.load.LoadParametersABC): load parameters to define the load object.

  • load_name (str): name of the load.

Raises:

  • ValueError: if the model part name is not found.

  • ValueError: if the model part is not a line model part.

  • ValueError: if the load parameters are not of type LineLoad or MovingLoad or UvecLoad.

add_model_part_to_group(group_name: str, part_name: str)

Adds a model part name to a pre-existing group for extrusion.

Args:

  • group_name (str): The name of the group.

  • part_name (str): The name of the model part to be added to the group.

Raises:

  • ValueError: if the group doesn’t exist.

  • ValueError: if the model part doesn’t exist.

add_output_settings(output_parameters: OutputParametersABC, part_name: str | None = None, output_dir: str = './', output_name: str | None = None)

Adds an output to the model, including the output folder, the name of the output file (if applicable) and the part of interest to output.

If no part is specified, the whole model is considered as output.

Args:

  • output_parameters (OutputParametersABC): class containing the output parameters

  • part_name (Optional[str]): name of the submodelpart to be given in output. If None, all the model is

    provided in output.

  • output_dir (str): output directory for the relative or absolute path to the output file. The path will be created if it does not exist yet.

    example1=’test1’ results in the test1 output folder relative to current folder as ‘./test1’ example2=’path1/path2/test2’ saves the outputs in ‘./path1/path2/test2’ example3=’C:/Documents/yourproject/test3’ saves the outputs in ‘C:/Documents/yourproject/test3’.

    if output_dir is None, then the current directory is assumed.

    [NOTE]: for VTK file type, the content of the target directory will be deleted. Therefore a subfolder is always appended to the specified output directory to avoid erasing important memory content. The appended folder is defined based on the submodelpart name specified.

  • output_name (Optional[str]): Name for the output file. This parameter is used by GiD and JSON outputs while is ignored in VTK. If the name is not given, the part_name is used instead.

Raises:

  • ValueError: if the model part for which output needs to be requested doesn’t exist.

add_output_settings_by_coordinates(coordinates: Sequence[Sequence[float]], output_parameters: OutputParametersABC, part_name: str, output_dir: str = './', output_name: str | None = None)

Sets coordinates where the output is to be defined. The coordinates have to be laying on an existing geometry surface. Both the first- and end-point has to lie on one of the edges of the surface. A new process model part is created, to specify the list of nodes of interest.

Current limitations:

  • The nodes have to be laying on an existing geometry surface.

  • The first and endpoint have to lie on one of the edges of the surface.

  • A single point cannot be provided, but is always a sequence of lines.

Args:
  • coordinates (Optional[Sequence[Sequence[float]]]): A list of nodes that are of interest for the

    outputs.

  • output_parameters (OutputParametersABC): class containing the output parameters

  • part_name (str): name of the submodelpart name for the output. Must be different from

    existing parts.

  • output_dir (Optional[str]): output directory for the relative or absolute path to the output file. The path will be created if it does not exist yet.

    example1=’test1’ results in the test1 output folder relative to current folder as ‘./test1’ example2=’path1/path2/test2’ saves the outputs in ‘./path1/path2/test2’ example3=’C:/Documents/yourproject/test3’ saves the outputs in ‘C:/Documents/yourproject/test3’.

    if output_dir is None, then the current directory is assumed.

    [NOTE]: for VTK file type, the content of the target directory will be deleted. Therefore, a subfolder is always appended to the specified output directory to avoid erasing important memory content. The appended folder is defined based on the submodelpart name specified.

  • output_name (Optional[str]): Name for the output file. This parameter is used by GiD and JSON outputs while is ignored in VTK. If the name is not

add_soil_layer_by_coordinates(coordinates: Sequence[Sequence[float]], material_parameters: SoilMaterial | StructuralMaterial, name: str, group_name: str | None = None)

Adds a soil layer to the model by giving a sequence of 3D coordinates. The coordinates have to belong to the same plane. In a 3D model, the 2D geometry is extruded in the direction of the extrusion group. If no extrusion group is provided, the geometry is extruded in the out of plane direction. The coordinates need to follow clockwise or anti-clockwise order.

Args:
Raises:

  • ValueError: if the polygon of the soil layer is not planar.

  • ValueError: if the model is 3D and the specified group_name doesn’t exist.

  • ValueError: if the model is 3D but no group_name nor model.extrusion_length are specified.

  • ValueError: if the model is 3D, a valid group is specified, but the reference point of the group is not in the same plane of the polygon of the soil layer.

property all_model_parts: List[ModelPart]

Get all model parts.

Returns:
apply_additional_process(process_parameters: AdditionalProcessesParametersABC, part_name: str = '')

Apply a process on an existing model part.

Args:
Raises:

  • ValueError: if the part name does not exist.

finalise(input_folder: str)

Finalise the model run: * adjust json output for nodal output coordinates so the order matches the desired one.

Args:

  • input_folder (str): input folder for the written files.

generate_extended_straight_track(sleeper_distance: float, n_sleepers: int, rail_parameters: EulerBeam, sleeper_parameters: SoilMaterial | NodalConcentrated, rail_pad_parameters: ElasticSpringDamper, rail_pad_thickness: float, origin_point: Sequence[float], soil_equivalent_parameters: ElasticSpringDamper, length_soil_equivalent_element: float, direction_vector: Sequence[float], name: str, sleeper_dimensions: Sequence[float] | None = None, distance_middle_sleeper_to_rail: float | None = None)

Generates a track geometry. With rail, rail-pads and sleepers. Sleepers are placed at the bottom of the track with a distance of sleeper_distance between them. The sleepers are connected to the rail with rail-pads with a thickness of rail_pad_thickness. The track is generated in the direction of the direction_vector starting from the origin_point. The track can only move in the vertical direction. When part of the track is located outside the 2D or 3D soil domain, 1D elements are placed below the sleepers which simulate the behaviour of the soil in vertical direction. The bottom of the 1D elements are fixed in all directions.

Sleepers can be modelled as NodalConcentrated or SoilMaterial, so as points or volume elements. If the sleepers are modelled as SoilMaterial, the dimensions of the sleepers must be provided and the distance between the sleeper centre and the rail pad location in the sleeper length direction. Sleepers outside the soil domain are modelled as NodalConcentrated elements with equivalent mass.

Args:

parameters - length_soil_equivalent_element (float): length of the 1D soil equivalent - direction_vector (Sequence[float]): direction vector of the track - name (str): name of the track - sleeper_dimensions (Optional[Sequence[float]]): dimensions of the sleepers to be modelled

with the format [width, height, length] in 3D and [width, height] in 2D

  • distance_middle_sleeper_to_rail (Optional[float]): distance from centre of sleeper to the rail pad

    location in the sleeper length direction.

Raises:

  • ValueError: if sleeper_parameters is SoilMaterial and sleeper_dimensions is not provided.

  • ValueError: if sleeper_parameters is SoilMaterial and distance_middle_sleeper_to_rail is not provided.

generate_mesh(save_file: bool = False, mesh_output_dir: str = './', mesh_name: str = 'mesh_file', open_gmsh_gui: bool = False)

Generate the mesh for the whole model.

Args:

  • save_file (bool): If True, saves mesh data to gmsh msh file. (default is False)

  • mesh_name (str): Name of gmsh model and mesh output file. (default is working directory)

  • mesh_output_dir (bool): Output directory of mesh file. (default is mesh_file)

  • open_gmsh_gui (bool): User indicates whether to open gmsh interface (default is False)

generate_straight_track(sleeper_distance: float, n_sleepers: int, rail_parameters: EulerBeam, sleeper_parameters: NodalConcentrated | SoilMaterial, rail_pad_parameters: ElasticSpringDamper, rail_pad_thickness: float, origin_point: Sequence[float], direction_vector: Sequence[float], name: str, sleeper_dimensions: Sequence[float] | None = None, distance_middle_sleeper_to_rail: float | None = None)

Generates a track geometry. With rail, rail-pads and sleepers. Sleepers are placed at the bottom of the track with a distance of sleeper_distance between them. The sleepers are connected to the rail with rail-pads with a thickness of rail_pad_thickness. The track is generated in the direction of the direction_vector starting from the origin_point. The track can only move in the vertical direction.

Sleepers can be modelled as NodalConcentrated or SoilMaterial, so as points or volume elements. If the sleepers are modelled as SoilMaterial, the dimensions of the sleepers must be provided and the distance between the sleeper centre and the rail pad location in the sleeper length direction.

In 2D the sleeper dimensions must be provided in the format [width, height], where the length is not required. In 3D The sleeper dimensions must be provided in the format [width, height, length], where the length is defined as half the sleeper length, as symmetry is assumed and only half the sleeper is modelled

Args:

stem.soil_material.SoilMaterial]): sleeper parameters - rail_pad_parameters (stem.structural_material.ElasticSpringDamper): rail pad parameters - rail_pad_thickness (float): thickness of the rail pad - origin_point (Sequence[float]): origin point of the track - direction_vector (Sequence[float]): direction vector of the track - name (str): name of the track - sleeper_dimensions (Optional[Sequence[float]]): dimensions of the sleepers to be modelled

with the format [width, height] in 2D and [width, height, length] in 3D

  • distance_middle_sleeper_to_rail (Optional[float]): distance from centre of sleeper to the rail pad

    location in the sleeper length direction.

get_all_nodes()

Retrieve all the unique nodes in the model mesh.

Raises:

  • ValueError: If the geometry has not been meshed yet.

Returns:

  • node_dict (Dict[int, stem.mesh.Node]): dictionary containing nodes id and nodes objects.

get_bounding_box_soil() → Tuple[List[float], List[float]]

Get the bounding box of the soil model parts.

Raises:

  • ValueError: if the model part has no geometry

Returns:

  • Tuple[List[float], List[float]]: The minimum and maximum coordinates of the bounding box.

get_model_part_by_name(part_name: str) → ModelPart | None

Find the model part matching the given part_name

Args:

  • part_name (str): the name of the part to retrieve.

Returns:
get_points_outside_soil(model_part_name: str) → List[Point]

Get the points of the model part that are outside the soil model parts.

Args:

  • model_part_name (str): The name of the model part to check the points

Raises:

  • ValueError: if the model part is not found.

  • ValueError: if the model part has no geometry.

Returns:

  • List[int]: The ids of the points that are outside the volume of the model part.

  • List[List[float]]: The coordinates of the points that are outside the volume of the model part.

post_setup()
Post setup of the model:

  • Synchronise the geometry.

  • Generate the mesh.

  • Validate the model.

  • Set up the stress initialisation.

set_element_size_of_group(element_size: float, group_name: str)

Set the element size of a group of elements. In multiple groups share the same mesh, the lowest element size is used.

Args:

  • element_size (float): The element size.

  • group_name (str): The name of the group.

Raises:

  • ValueError: If the group name is not found.

set_mesh_size(element_size: float)

Set the element size to dimension [m].

Args:

  • element_size (float): the desired element size [m].

show_geometry(show_volume_ids: bool = False, show_surface_ids: bool = False, show_line_ids: bool = False, show_point_ids: bool = False, file_name: str = 'tmp_geometry_file.html', auto_open: bool = True)

Show the 2D or 3D geometry in a plot.

Args:

  • show_volume_ids (bool): Show the volume ids in the plot. (default False)

  • show_surface_ids (bool): Show the surface ids in the plot. (default False)

  • show_line_ids (bool): Show the line ids in the plot. (default False)

  • show_point_ids (bool): Show the point ids in the plot. (default False)

  • file_name (str): The name of the html file in which the plot is saved. (default “tmp_geometry_file.html”)

  • auto_open (bool): Open the html file automatically. (default True)

Raises:

  • ValueError: If the geometry is not set.

split_model_part(from_model_part_name: str, to_model_part_name: str, geometry_ids: List[int], new_parameters: SoilMaterial | StructuralMaterial | LoadParametersABC | BoundaryParametersABC | AdditionalProcessesParametersABC | WaterProcessParametersABC | OutputParametersABC)

Move the geometry from one model part to another.

Args:

  • from_model_part_name (str): The name of the model part from which the geometry needs to be moved.

  • to_model_part_name (str): The name of the model part to which the geometry needs to be moved.

  • geometry_ids (List[int]): The geometry ids to be moved.

  • new_parameters (Union[stem.model_part.Material, stem.model_part.ProcessParameters]): The new material or process parameters for the model part.

Raises:

  • ValueError: If the model part name is not found.

  • ValueError: If the geometry is not defined in the model part.

  • ValueError: If the new parameters are not of the same type as the existing material or process parameters.

  • ValueError: If the geometry is empty in the model part.

synchronise_geometry()

Synchronise the geometry of all model parts and synchronise the geometry of the whole model. This function recalculates all ids and connectivities of all geometrical entities.

validate()

Validate the model. - Checks if all model parts have a unique name.

stem.model_part module

class stem.model_part.BodyModelPart(name: str)

Bases: ModelPart

This class contains model parts which are part of the body, e.g. a soil layer or track components.

Inheritance:
Attributes:

  • __name (str): name of the model part

  • geometry (Optional[stem.geometry.Geometry]): geometry of the model part

  • mesh (Optional[stem.mesh.Mesh]): mesh of the model part

  • parameters (Dict[str, Any]): dictionary containing the model part parameters

  • material (Material): material of the model part

Initialize the body model part

Args:

  • name (str): name of the body model part

get_element_name(n_dim_model: int, n_nodes_element: int, analysis_type: AnalysisType) → str | None

Get the element name of the elements within the model part

Args:

  • n_dim_model (int): The number of dimensions of the model (2 or 3)

  • n_nodes_element (int): The number of nodes per element

  • analysis_type (stem.solver.AnalysisType): The analysis type of the model

Returns:

  • Optional[str]: element name of the model part

stem.model_part.Material
TypeAlias:

alias of SoilMaterial | StructuralMaterial

class stem.model_part.ModelPart(name: str)

Bases: object

One part of the complete model, this can be a boundary condition, a loading or another special process like excavation.

Attributes:

  • __name (str): name of the model part

  • geometry (Optional[stem.geometry.Geometry]): geometry of the model part

  • parameters (Optional[ProcessParameters]): process parameters containing the model part parameters.

  • mesh (Optional[stem.mesh.Mesh]): mesh of the model part

  • id (Optional[int]): the id of the model part

Initialize the model part

Args:

  • name (str): name of the model part

get_element_name(n_dim_model: int, n_nodes_element: int, analysis_type: AnalysisType) → str | None

Get the element name of the model part. Only loads and boundary conditions currently may have an element name.

Args:

  • n_dim_model (int): The number of dimensions of the model (2 or 3)

  • n_nodes_element (int): The number of nodes per element

  • analysis_type (stem.solver.AnalysisType): The analysis type of the model

Returns:

  • Optional[str]: element name of the model part

get_geometry_from_geo_data(geo_data: Dict[str, Any], name: str)

Get the geometry from the geo_data and set the nodes and elements attributes.

Args:

  • geo_data (Dict[str, Any]): dictionary containing the geometry data as generated by the gmsh_io

property name: str

Get the name of the model part

Returns:

  • str: name of the model part

validate_input()

Validate the input of the model part

Raises:

  • ValueError: if the geometry of the model part is not defined

  • ValueError: if the parameters of the model part is not defined

  • ValueError: if the origin of the moving load is not aligned with the lines of the geometry

  • ValueError: if the lines of the geometry are not aligned on a path, i.e. there are loops or branching points

stem.model_part.MovingLoadTypes = (<class 'stem.load.MovingLoad'>, <class 'stem.load.UvecLoad'>)
TypeAlias:
stem.model_part.ProcessParameters
TypeAlias:

alias of LoadParametersABC | BoundaryParametersABC | AdditionalProcessesParametersABC | WaterProcessParametersABC | OutputParametersABC

stem.output module

class stem.output.GaussPointOutput(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum class for variables at the Gauss Point

BIOT_COEFFICIENT = 20
BULK_MODULUS_FLUID = 26
BULK_MODULUS_SOLID = 19
CAUCHY_STRESS_TENSOR = 9
CAUCHY_STRESS_VECTOR = 8
DENSITY_FLUID = 24
DENSITY_SOLID = 14
DYNAMIC_VISCOSITY = 25
ENGINEERING_STRAIN_TENSOR = 7
ENGINEERING_STRAIN_VECTOR = 6
FLUID_FLUX_VECTOR = 2
FORCE = 28
GREEN_LAGRANGE_STRAIN_TENSOR = 5
GREEN_LAGRANGE_STRAIN_VECTOR = 4
HYDRAULIC_HEAD = 3
MOMENT = 29
PERMEABILITY_XX = 16
PERMEABILITY_XY = 18
PERMEABILITY_YY = 17
PERMEABILITY_YZ = 21
PERMEABILITY_ZX = 22
PERMEABILITY_ZZ = 23
POISSON_RATIO = 13
POROSITY = 15
TOTAL_STRESS_TENSOR = 11
TOTAL_STRESS_VECTOR = 10
UMAT_PARAMETERS = 27
VON_MISES_STRESS = 1
YOUNG_MODULUS = 12
class stem.output.GiDOutputParameters(output_interval: float, output_control_type: str = 'step', file_format: str = 'binary', nodal_results: ~typing.Sequence[~stem.output.NodalOutput | str] = <factory>, gauss_point_results: ~typing.Sequence[~stem.output.GaussPointOutput | str] = <factory>, file_label: str = 'step')

Bases: OutputParametersABC

Class containing the output parameters for GiD output

Inheritance:
Attributes:

  • output_interval (float): frequency of the output, either step interval if output_control_type is step or time interval in seconds if output_control_type is time.

  • output_control_type (str): type of output control, either step or time.

  • file_format (str): format of output (binary,`ascii` or hdf5) for the gid_post_mode flag

  • nodal_results (Sequence[Union[NodalOutput, str]]): list of nodal outputs as defined in NodalOutput.

  • gauss_point_results (Sequence[Union[GaussPointOutput, str]]): list of gauss point outputs as defined in GaussPointOutput.

  • file_label (str): labelling format for the files (step or time)

file_format: str = 'binary'
file_label: str = 'step'
gauss_point_results: Sequence[GaussPointOutput | str]
nodal_results: Sequence[NodalOutput | str]
output_control_type: str = 'step'
output_interval: float
class stem.output.JsonOutputParameters(output_interval: float, nodal_results: ~typing.Sequence[~stem.output.NodalOutput | str] = <factory>, gauss_point_results: ~typing.Sequence[~stem.output.GaussPointOutput | str] = <factory>)

Bases: OutputParametersABC

Class containing the output parameters for JSON output

Inheritance:
Attributes:

  • output_interval (float): time frequency of the output [s].

  • nodal_results (Sequence[Union[NodalOutput, str]]): list of nodal outputs as defined in NodalOutput.

  • gauss_point_results (Sequence[Union[GaussPointOutput, str]]): list of gauss point outputs as defined in GaussPointOutput.

gauss_point_results: Sequence[GaussPointOutput | str]
nodal_results: Sequence[NodalOutput | str]
output_interval: float
class stem.output.NodalOutput(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum class for variables at the nodes

ACCELERATION = 9
ACCELERATION_X = 10
ACCELERATION_Y = 11
ACCELERATION_Z = 12
CAUCHY_STRESS_VECTOR = 22
DISPLACEMENT = 1
DISPLACEMENT_X = 2
DISPLACEMENT_Y = 3
DISPLACEMENT_Z = 4
TOTAL_DISPLACEMENT = 13
TOTAL_DISPLACEMENT_X = 14
TOTAL_DISPLACEMENT_Y = 15
TOTAL_DISPLACEMENT_Z = 16
VELOCITY = 5
VELOCITY_X = 6
VELOCITY_Y = 7
VELOCITY_Z = 8
VOLUME_ACCELERATION = 18
VOLUME_ACCELERATION_X = 19
VOLUME_ACCELERATION_Y = 20
VOLUME_ACCELERATION_Z = 21
WATER_PRESSURE = 17
class stem.output.Output(output_parameters: OutputParametersABC, part_name: str | None = None, output_dir: str = './', output_name: str | None = None)

Bases: object

Class containing output information for postprocessing

Attributes:

  • output_parameters (OutputParametersABC): class containing output parameters

  • part_name (Optional[str]): name of the model part

  • output_dir (str): path to the output files

  • output_name (Optional[str]): name for the output file

Constructor of the output process class

Args:

  • output_parameters (OutputParametersABC): class containing the output parameters

  • part_name (Optional[str]): name of the submodelpart to be given in output. If None, all the model is

    provided in output.

  • output_dir (Optional[str]): output directory for the relative or absolute path to the output file. The path will be created if it does not exist yet.

    example1=’test1’ results in the test1 output folder relative to current folder as ‘./test1’ example2=’path1/path2/test2’ saves the outputs in ‘./path1/path2/test2’ example3=’C:/Documents/yourproject/test3’ saves the outputs in ‘C:/Documents/yourproject/test3’.

    if output_dir is None, then the current directory is assumed.

    [NOTE]: for VTK file type, the content of the target directory will be deleted. Therefore a subfolder is always appended to the specified output directory to avoid erasing important memory content. The appended folder is defined based on the submodelpart name specified.

  • output_name (Optional[str]): Name for the output file. This parameter is used by GiD and JSON outputs while is ignored in VTK. If the name is not given, the part_name is used instead.

class stem.output.OutputParametersABC

Bases: ABC

Abstract class for the definition of user output parameters (GiD, VTK, json).

class stem.output.VtkOutputParameters(output_interval: float, output_control_type: str = 'step', file_format: str = 'binary', nodal_results: ~typing.Sequence[~stem.output.NodalOutput | str] = <factory>, gauss_point_results: ~typing.Sequence[~stem.output.GaussPointOutput | str] = <factory>, output_precision: int = 7)

Bases: OutputParametersABC

Class containing the output parameters for GiD output

Inheritance:
Attributes:

  • output_interval (float): frequency of the output, either step interval if output_control_type is step or time interval in seconds if output_control_type is time.

  • output_control_type (str): type of output control, either step or time.

  • file_format (str): file format for VTK, either binary or ascii are allowed.

  • nodal_results (Sequence[Union[NodalOutput, str]]): list of nodal outputs as defined in NodalOutput.

  • gauss_point_results (Sequence[Union[GaussPointOutput, str]]): list of gauss point outputs as defined in GaussPointOutput. output_precision (int): precision of the output for ascii. Default is 7.

file_format: str = 'binary'
gauss_point_results: Sequence[GaussPointOutput | str]
nodal_results: Sequence[NodalOutput | str]
output_control_type: str = 'step'
output_interval: float
output_precision: int = 7
stem.output.detect_tensor_outputs(requested_outputs: Sequence[GaussPointOutput | str])

Detects whether gauss point outputs are requested for specific gauss point outputs and warns the user if some cause problems. In VTK and JSON output types the vector output are rendered incorrectly.

If such output types are detected the script merely warns the user since the simulation can still run correctly.

Args:

  • requested_outputs (List[GaussPointOutput]): list of requested outputs (gauss point)

stem.output.detect_vector_in_tensor_outputs(requested_outputs: Sequence[GaussPointOutput | str])

Detects whether tensor gauss point outputs are requested as vector output instead and warns the user if some cause problems. In GiD the vector output for tensors is incorrectly rendered. For example, for 2D tensor with 3 components, given the symmetry of the tensor, 6 component are expected when vector output is considered. In GiD, this is rendered with 4 components.

If such output types are detected the script merely warns the user since the simulation can still run correctly.

Args:

  • requested_outputs (Sequence[Union[GaussPointOutput, str]]): list of requested outputs (gauss point)

stem.output.validate_gauss_point_output(gauss_point_results: Sequence[GaussPointOutput | str])

Validates that the specified string requested for gauss point outputs are compatible with the ones defined in the corresponding enumeration.

Args:

  • gauss_point_results (Sequence[Union[GaussPointOutput, str]]): the requested gauss point outputs.

Raises:

  • ValueError: when incorrect outputs are found

stem.output.validate_nodal_point_output(nodal_results: Sequence[NodalOutput | str])

Validates that the specified string requested for nodal outputs are compatible with the ones defined in the corresponding enumeration.

Args:

  • nodal_results (Sequence[Union[NodalOutput, str]]): the requested nodal outputs.

Raises:

  • ValueError: when incorrect outputs are found

stem.plot_utils module

class stem.plot_utils.PlotUtils

Bases: object

Utility class for plotting geometry.

static create_geometry_figure(ndim: int, geometry: Geometry, show_volume_ids: bool = False, show_surface_ids: bool = False, show_line_ids: bool = False, show_point_ids: bool = False) → Figure

Creates the geometry of the model in a plotly graph object figure.

Args:

  • ndim (int): Number of dimensions of the geometry. Either 2 or 3.

  • geometry (stem.geometry.Geometry): Geometry object.

  • show_volume_ids (bool): If True, the volume ids are shown in the plot.

  • show_surface_ids (bool): If True, the surface ids are shown in the plot.

  • show_line_ids (bool): If True, the line ids are shown in the plot.

  • show_point_ids (bool): If True, the point ids are shown in the plot.

Returns:

  • plotly.graph_objects.Figure: graph object figure

stem.soil_material module

class stem.soil_material.FluidProperties(DENSITY_FLUID: float = 1000, DYNAMIC_VISCOSITY: float = 0.0013, BULK_MODULUS_FLUID: float = 2000000000.0)

Bases: object

Class containing the parameters for a fluid. Default values are for water at 12 degrees Celsius.

Attributes:

  • DENSITY_FLUID (float): The density of fluid [kg/m^3].

  • DYNAMIC_VISCOSITY (float): The dynamic viscosity of fluid [Pa s].

  • BULK_MODULUS_FLUID (float): The bulk modulus of fluid [Pa].

BULK_MODULUS_FLUID: float = 2000000000.0
DENSITY_FLUID: float = 1000
DYNAMIC_VISCOSITY: float = 0.0013
class stem.soil_material.LinearElasticSoil(YOUNG_MODULUS: float, POISSON_RATIO: float)

Bases: SoilConstitutiveLawABC

Class containing the material parameters for a 2D linear elastic material

Inheritance:
Attributes:

  • YOUNG_MODULUS (float): The Young’s modulus [Pa].

  • POISSON_RATIO (float): The Poisson’s ratio [-].

POISSON_RATIO: float
YOUNG_MODULUS: float
class stem.soil_material.OnePhaseSoil(ndim: int, IS_DRAINED: bool, DENSITY_SOLID: float, POROSITY: float, BULK_MODULUS_SOLID: float = 50000000000.0, BIOT_COEFFICIENT: float | None = None, RAYLEIGH_M: float | None = None, RAYLEIGH_K: float | None = None)

Bases: SoilFormulationParametersABC

Class containing the material parameters for an undrained soil material

Inheritance:
Attributes:

  • IS_UNDRAINED (bool): Boolean indicating if the soil is undrained.

  • DENSITY_SOLID (float): The density of the solid material [kg/m^3].

  • POROSITY (float): The porosity of the soil [-].

  • BULK_MODULUS_SOLID (float): The bulk modulus of the solid material [Pa].

  • BIOT_COEFFICIENT (Optional[float]): The Biot coefficient [-].

  • RAYLEIGH_M (Optional[float]): Mass proportional Rayleigh damping parameter [-].

  • RAYLEIGH_K (Optional[float]): Stiffness proportional Rayleigh damping parameter [-].

BIOT_COEFFICIENT: float | None = None
BULK_MODULUS_SOLID: float = 50000000000.0
DENSITY_SOLID: float
IS_DRAINED: bool
POROSITY: float
RAYLEIGH_K: float | None = None
RAYLEIGH_M: float | None = None
ndim: int
class stem.soil_material.RetentionLawABC

Bases: ABC

Abstract class containing the parameters for a retention law. This class is created for type checking purposes.

class stem.soil_material.SaturatedBelowPhreaticLevelLaw(SATURATED_SATURATION: float = 1.0, RESIDUAL_SATURATION: float = 1e-10)

Bases: RetentionLawABC

Class containing the parameters for the retention law: saturated below phreatic level

Inheritance:
Attributes:

  • SATURATED_SATURATION (float): The saturation ratio below phreatic level [-].

  • RESIDUAL_SATURATION (float): The residual saturation ratio [-].

RESIDUAL_SATURATION: float = 1e-10
SATURATED_SATURATION: float = 1.0
class stem.soil_material.SaturatedLaw(SATURATED_SATURATION: float = 1.0)

Bases: RetentionLawABC

Class containing the parameters for the retention law: saturated

Inheritance:
Attributes:

  • SATURATED_SATURATION (float): The saturation ratio [-].

SATURATED_SATURATION: float = 1.0
class stem.soil_material.SmallStrainUdsmLaw(UDSM_NAME: str, UDSM_NUMBER: int, IS_FORTRAN_UDSM: bool, UDSM_PARAMETERS: List[Any])

Bases: SoilConstitutiveLawABC

Class containing the material parameters for small strain udsm material

Inheritance:
Attributes:

  • UDSM_NAME (str): The name and location of the udsm .dll or .so file.

  • UDSM_NUMBER (int): The model number within the udsm.

  • IS_FORTRAN_UDSM (bool): A boolean to indicate whether the udsm is written in Fortran.

  • UDSM_PARAMETERS (list): The parameters of the udsm.

IS_FORTRAN_UDSM: bool
UDSM_NAME: str
UDSM_NUMBER: int
UDSM_PARAMETERS: List[Any]
class stem.soil_material.SmallStrainUmatLaw(UMAT_NAME: str, IS_FORTRAN_UMAT: bool, UMAT_PARAMETERS: List[Any], STATE_VARIABLES: List[Any])

Bases: SoilConstitutiveLawABC

Class containing the material parameters for a 2D small strain umat material

Inheritance:
Attributes:

  • UMAT_NAME (str): The name and location of the umat .dll or .so file.

  • IS_FORTRAN_UMAT (bool): A boolean to indicate whether the umat is written in Fortran.

  • UMAT_PARAMETERS (list): The parameters of the umat.

  • STATE_VARIABLES (list): The state variables of the umat.

IS_FORTRAN_UMAT: bool
STATE_VARIABLES: List[Any]
UMAT_NAME: str
UMAT_PARAMETERS: List[Any]
class stem.soil_material.SoilConstitutiveLawABC

Bases: ABC

Abstract base class for soil constitutive laws

class stem.soil_material.SoilFormulationParametersABC(ndim: int)

Bases: ABC

Abstract base class for soil formulation parameters

Attributes:

  • ndim (int): The number of dimensions of the soil formulation (2 or 3)

ndim: int
class stem.soil_material.SoilMaterial(name: str, soil_formulation: ~stem.soil_material.SoilFormulationParametersABC, constitutive_law: ~stem.soil_material.SoilConstitutiveLawABC, retention_parameters: ~stem.soil_material.RetentionLawABC, fluid_properties: ~stem.soil_material.FluidProperties = <factory>)

Bases: object

Class containing the parameters for a soil material

Attributes:
constitutive_law: SoilConstitutiveLawABC
fluid_properties: FluidProperties
static get_element_name(n_dim_model: int, n_nodes_element: int, analysis_type: AnalysisType) → str

Function to get the element name based on the number of dimensions, the number of nodes and the analysis type.

Args:

  • n_dim_model (int): The number of dimensions of the model.

  • n_nodes_element (int): The number of nodes per element.

  • analysis_type (stem.solver.AnalysisType): The analysis type.

Raises:

  • ValueError: If the analysis type is not implemented yet for nodal concentrated elements.

Returns:

  • element_name (str): The name of the element.

get_property_in_material(property_name: str) → Any

Function to retrieve the requested property for the soil material. The function is capital sensitive!

Args:

  • property_name (str): The desired soil property name.

Raises:

  • ValueError: If the property is not in not available in the soil material.

Returns:

  • Any : The value of the soil property.

name: str
retention_parameters: RetentionLawABC
soil_formulation: SoilFormulationParametersABC
to_dict() → Dict[str, Any]

Function to convert the soil material to a dictionary. For serialization purposes.

Returns:

  • Dict[str, Any]: The soil material as a dictionary.

class stem.soil_material.TwoPhaseSoil(ndim: int, DENSITY_SOLID: float, POROSITY: float, PERMEABILITY_XX: float, PERMEABILITY_YY: float, PERMEABILITY_XY: float = 0, BULK_MODULUS_SOLID: float = 50000000000.0, BIOT_COEFFICIENT: float | None = None, RAYLEIGH_M: float | None = None, RAYLEIGH_K: float | None = None, PERMEABILITY_YZ: float | None = 0, PERMEABILITY_ZX: float | None = 0, PERMEABILITY_ZZ: float | None = None)

Bases: SoilFormulationParametersABC

Class containing the material parameters for a two phase soil material

Inheritance:
Attributes:

  • DENSITY_SOLID (float): The density of the solid material [kg/m^3].

  • POROSITY (float): The porosity of the soil [-].

  • PERMEABILITY_XX (float): The permeability in the x-direction [m^2].

  • PERMEABILITY_YY (float): The permeability in the y-direction [m^2].

  • PERMEABILITY_XY (float): The permeability in the xy-direction [m^2].

  • BULK_MODULUS_SOLID (float): The bulk modulus of the solid material [Pa].

  • BIOT_COEFFICIENT (Optional[float]): The Biot coefficient [-].

  • RAYLEIGH_M (Optional[float]): Mass proportional rayleigh damping parameter [-].

  • RAYLEIGH_K (Optional[float]): Stiffness proportional rayleigh damping parameter [-].

  • PERMEABILITY_YZ (Optional[float]): The permeability in the yz-direction [m^2].

  • PERMEABILITY_ZX (Optional[float]): The permeability in the zx-direction [m^2].

  • PERMEABILITY_ZZ (Optional[float]): The permeability in the z-direction [m^2].

BIOT_COEFFICIENT: float | None = None
BULK_MODULUS_SOLID: float = 50000000000.0
DENSITY_SOLID: float
PERMEABILITY_XX: float
PERMEABILITY_XY: float = 0
PERMEABILITY_YY: float
PERMEABILITY_YZ: float | None = 0
PERMEABILITY_ZX: float | None = 0
PERMEABILITY_ZZ: float | None = None
POROSITY: float
RAYLEIGH_K: float | None = None
RAYLEIGH_M: float | None = None
ndim: int
class stem.soil_material.VanGenuchtenLaw(VAN_GENUCHTEN_AIR_ENTRY_PRESSURE: float, VAN_GENUCHTEN_GN: float, VAN_GENUCHTEN_GL: float, SATURATED_SATURATION: float = 1.0, RESIDUAL_SATURATION: float = 1e-10, MINIMUM_RELATIVE_PERMEABILITY: float = 0.0001)

Bases: RetentionLawABC

Class containing the parameters for a retention law

Inheritance:
Attributes:

  • VAN_GENUCHTEN_AIR_ENTRY_PRESSURE (float): The air entry pressure [Pa].

  • VAN_GENUCHTEN_GN (float): The pore size distribution index [-].

  • VAN_GENUCHTEN_GL (float): exponent for calculating relative permeability [-].

  • SATURATED_SATURATION (float): The maximum saturation ratio [-].

  • RESIDUAL_SATURATION (float): The minumum saturation ratio [-].

  • MINIMUM_RELATIVE_PERMEABILITY (float): The minimum relative permeability [-].

MINIMUM_RELATIVE_PERMEABILITY: float = 0.0001
RESIDUAL_SATURATION: float = 1e-10
SATURATED_SATURATION: float = 1.0
VAN_GENUCHTEN_AIR_ENTRY_PRESSURE: float
VAN_GENUCHTEN_GL: float
VAN_GENUCHTEN_GN: float

stem.solver module

class stem.solver.Amgcl(scaling: bool = False, tolerance: float = 1e-12, max_iteration: int = 1000, krylov_type: str = 'cg', smoother_type: str = 'ilu0', preconditioner_type: str = 'amg', coarsening_type: str = 'aggregation')

Bases: LinearSolverSettingsABC

Class containing information about the Algebraic multigrid iterative linear solver settings

Inheritance:
Attributes:

  • scaling (bool): if true, the system matrix will be scaled before solving the linear system of equations. Default value is False.

  • tolerance (float): tolerance for the linear solver convergence criteria. Default value is 1e-12.

  • max_iteration (int): maximum number of iterations for the linear solver. Default value is 1000.

  • krylov_type (str): type of the Krylov solver. Default value is “cg”, other options are “gmres” and “bicgstab”.

  • smoother_type (str): type of the smoother. Default value is “ilu0”, other options are “spai0”, “spai1”, “ilut”, “iluk”, “damped_jacobi”, “gauss_seidel” and “chebyshev”

  • preconditioner_type (str): type of the preconditioner. Default value is “amg”, other options are “relaxation” and “none”

  • coarsening_type (str): type of the coarsening. Default value is “aggregation”, other options are

    “ruge_stuben”,”smoothed_aggregation” and “smoothed_aggr_emin”

coarsening_type: str = 'aggregation'
krylov_type: str = 'cg'
max_iteration: int = 1000
preconditioner_type: str = 'amg'
scaling: bool = False
smoother_type: str = 'ilu0'
property solver_type

Property that returns the solver type name of the amgcl iterative linear solver settings

Returns:

  • str: solver type name

tolerance: float = 1e-12
class stem.solver.AnalysisType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum class containing the analysis type

Attributes:

  • MECHANICAL_GROUNDWATER_FLOW (int): coupled mechanical and groundwater flow analysis

  • MECHANICAL (int): mechanical analysis

  • GROUNDWATER_FLOW (int): groundwater flow analysis

GROUNDWATER_FLOW = 3
MECHANICAL = 2
MECHANICAL_GROUNDWATER_FLOW = 1
class stem.solver.ArcLengthStrategy(max_iterations: int = 15, min_iterations: int = 6, number_cycles: int = 100, desired_iterations: int = 10, max_radius_factor: float = 1.0, min_radius_factor: float = 0.1)

Bases: StrategyTypeABC

Class containing information about the arc length strategy

Inheritance:
Attributes:

  • max_iterations (int): maximum number of iterations allowed, if this number is reached, the time step size is decreased and the algorithm is restarted. Default value is 15.

  • min_iterations (int): minimum number of iterations, below this number, the time step size is increased. Default value is 6.

  • number_cycles (int): number of allowed cycles of decreasing the time step size until the algorithm is stopped. Default value is 100.

  • desired_iterations (int): This is used to calculate the radius of the next step. Default value is 10.

  • max_radius_factor (float): maximum radius factor of the arc. Default value is 1.0.

  • min_radius_factor (float): minimum radius factor of the arc. Default value is 0.1.

desired_iterations: int = 10
max_iterations: int = 15
max_radius_factor: float = 1.0
min_iterations: int = 6
min_radius_factor: float = 0.1
number_cycles: int = 100
property strategy_type: str

Returns the strategy type name of the arc length strategy

Returns:

  • str: strategy type name

class stem.solver.BackwardEulerScheme

Bases: SchemeABC

Class containing information about the backward Euler scheme

Inheritance:
property scheme_type

Property for returning the type of the backward Euler scheme

Returns:

  • str: The type of the backward Euler scheme

class stem.solver.Cg(scaling: bool = False, tolerance: float = 1e-12, max_iteration: int = 1000, preconditioner_type: str = 'diagonal')

Bases: LinearSolverSettingsABC

Class containing information about the conjugate gradient iterative linear solver settings

Inheritance:
Attributes:

  • scaling (bool): if true, the system matrix will be scaled before solving the linear system of equations. Default value is False.

  • tolerance (float): tolerance for the linear solver convergence criteria. Default value is 1e-12.

  • max_iteration (int): maximum number of iterations for the linear solver. Default value is 1000.

  • preconditioner_type (str): type of the preconditioner. Default value is “diagonal”, other options are “ilu0” and “none”.

max_iteration: int = 1000
preconditioner_type: str = 'diagonal'
scaling: bool = False
property solver_type

Property that returns the solver type name of the conjugate gradient iterative linear solver settings

Returns:

  • str: solver type name

tolerance: float = 1e-12
validate_settings()

Validates the cg linear solver settings

Raises:

  • ValueError: if the preconditioner type is not valid

class stem.solver.ConvergenceCriteriaABC

Bases: ABC

Abstract class for the convergence criteria

abstract property convergence_criterion

Abstract property for returning the type of the convergence criterion

Raises:

  • Exception: abstract class of convergence criteria is called

class stem.solver.DisplacementAndWaterPressureConvergenceCriteria(displacement_relative_tolerance: float = 0.0001, displacement_absolute_tolerance: float = 1e-09, water_pressure_relative_tolerance: float = 0.0001, water_pressure_absolute_tolerance: float = 1e-09)

Bases: ConvergenceCriteriaABC

Class containing information about the displacement and water pressure convergence criteria

Inheritance:
Attributes:

  • displacement_relative_tolerance (float): The relative tolerance for the displacement. Default value is 1e-4.

  • displacement_absolute_tolerance (float): The absolute tolerance for the displacement. Default values is 1e-9.

  • water_pressure_relative_tolerance (float): The relative tolerance for the water pressure. Default value is 1e-4.

  • water_pressure_absolute_tolerance (float): The absolute tolerance for the water pressure. Default value is 1e-9.

property convergence_criterion

Property for returning the type of the displacement and water pressure convergence criterion

Returns:

  • str: The type of the displacement and water pressure convergence criterion

displacement_absolute_tolerance: float = 1e-09
displacement_relative_tolerance: float = 0.0001
water_pressure_absolute_tolerance: float = 1e-09
water_pressure_relative_tolerance: float = 0.0001
class stem.solver.DisplacementConvergenceCriteria(displacement_relative_tolerance: float = 0.0001, displacement_absolute_tolerance: float = 1e-09)

Bases: ConvergenceCriteriaABC

Class containing information about the displacement convergence criteria

Inheritance:
Attributes:

  • displacement_relative_tolerance (float): The relative tolerance for the displacement. Default value is 1e-4.

  • displacement_absolute_tolerance (float): The absolute tolerance for the displacement. Default values is 1e-9.

property convergence_criterion

Property for returning the type of the displacement convergence criterion

Returns:

  • str: The type of the displacement convergence criterion

displacement_absolute_tolerance: float = 1e-09
displacement_relative_tolerance: float = 0.0001
class stem.solver.LineSearchStrategy(max_iterations: int = 15, min_iterations: int = 6, number_cycles: int = 100, max_line_search_iterations: int = 10, first_alpha_value: float = 1.0, second_alpha_value: float = 0.5, min_alpha: float = 0.0001, max_alpha: float = 10000.0, line_search_tolerance: float = 0.0001, echo_level: int = 0)

Bases: StrategyTypeABC

Class containing information about the line search strategy

Inheritance:
Attributes:

  • max_iterations (int): maximum number of iterations allowed, if this number is reached, the time step size is decreased and the algorithm is restarted. Default value is 15.

  • min_iterations (int): minimum number of iterations, below this number, the time step size is increased. Default value is 6.

  • number_cycles (int): number of allowed cycles of decreasing the time step size until the algorithm is stopped. Default value is 100.

  • max_line_search_iterations (int): maximum number of line search iterations. Default value is 10.

  • first_alpha_value (float): first alpha guess value used for the first iteration. Default value is 1.0.

  • second_alpha_value (float): second alpha guess value used for the first iteration. Default value is 0.5.

  • min_alpha (float): minimum possible alpha value at the end of the algorithm. Default value is 1e-4.

  • max_alpha (float): maximum possible alpha value at the end of the algorithm. Default value is 1e4.

  • line_search_tolerance (float): Tolerance of the line search algorithm, defined as the ratio between maximum residual*alpha*dx and current iteration residual*alpha*dx. Default value is 1e-4.

  • echo_level (int): echo level. Default value is 0.

echo_level: int = 0
first_alpha_value: float = 1.0
line_search_tolerance: float = 0.0001
max_alpha: float = 10000.0
max_iterations: int = 15
max_line_search_iterations: int = 10
min_alpha: float = 0.0001
min_iterations: int = 6
number_cycles: int = 100
second_alpha_value: float = 0.5
property strategy_type: str

Returns the strategy type name of the line search strategy

Returns:

  • str: strategy type name

class stem.solver.LinearNewtonRaphsonStrategy(max_iterations: int = 15, min_iterations: int = 6, number_cycles: int = 100, initialize_acceleration: bool = False)

Bases: StrategyTypeABC

Class containing information about the Newton-Raphson strategy for linear systems

Attributes:

  • max_iterations (int): maximum number of iterations allowed, if this number is reached, the time step size is decreased and the algorithm is restarted. Default value is 15.

  • min_iterations (int): minimum number of iterations, below this number, the time step size is increased. Default value is 6.

  • number_cycles (int): number of allowed cycles of decreasing the time step size until the algorithm is stopped. Default value is 100.

  • initialize_acceleration (bool): if true, the acceleration is re-calculated at the beginning of the stage. Default value is False. This is important for a changing external force at stage transition in dynamic

    analysis. However, the model needs a displacement constraint in each direction, i.e. absorbing boundaries can not be used for all directions.

Inheritance:
initialize_acceleration: bool = False
max_iterations: int = 15
min_iterations: int = 6
number_cycles: int = 100
property strategy_type: str

Returns the strategy type name of the Linear Newton-Raphson strategy

Returns:

  • str: strategy type name

class stem.solver.LinearSolverSettingsABC

Bases: ABC

Class containing information about the linear solver settings

abstract property solver_type

Abstract property for returning the solver type

Raises:

  • Exception: abstract class of linear solver settings is called

validate_settings()

Validates the linear solver settings, can be overridden in child classes

class stem.solver.Lu(scaling: bool = False)

Bases: LinearSolverSettingsABC

Class containing information about the LU decomposition direct linear solver settings

Inheritance:
Attributes:

  • scaling (bool): if true, the system matrix will be scaled before solving the linear system of equations. Default value is False.

scaling: bool = False
property solver_type

Property that returns the solver type name of the LU decomposition direct linear solver settings

Returns:

  • str: solver type name

class stem.solver.NewmarkScheme(newmark_beta: float = 0.25, newmark_gamma: float = 0.5, newmark_theta: float = 0.5)

Bases: SchemeABC

Class containing information about the Newmark scheme

Inheritance:
Attributes:

  • newmark_beta (float): The beta parameter of the Newmark scheme. Default value is 0.25.

  • newmark_gamma (float): The gamma parameter of the Newmark scheme. Default value is 0.5.

  • newmark_theta (float): The theta parameter of the Newmark scheme, which is used for water pressure. Default value is 0.5.

newmark_beta: float = 0.25
newmark_gamma: float = 0.5
newmark_theta: float = 0.5
property scheme_type

Property for returning the type of the Newmark scheme

Returns:

  • str: The type of the newmark scheme

class stem.solver.NewtonRaphsonStrategy(max_iterations: int = 15, min_iterations: int = 6, number_cycles: int = 100)

Bases: StrategyTypeABC

Class containing information about the Newton-Raphson strategy

Attributes:

  • max_iterations (int): maximum number of iterations allowed, if this number is reached, the time step size is decreased and the algorithm is restarted. Default value is 15.

  • min_iterations (int): minimum number of iterations, below this number, the time step size is increased. Default value is 6.

  • number_cycles (int): number of allowed cycles of decreasing the time step size until the algorithm is stopped. Default value is 100.

Inheritance:
max_iterations: int = 15
min_iterations: int = 6
number_cycles: int = 100
property strategy_type: str

Returns the strategy type name of the Newton-Raphson strategy

Returns:

  • str: strategy type name

class stem.solver.Problem(problem_name: str, number_of_threads: int, settings: SolverSettings)

Bases: object

Class containing information about the problem settings and the solver settings

Attributes:

  • problem_name (str): name of the problem

  • number_of_threads (int): number of threads used for the analysis

  • settings (SolverSettings): dictionary containing the solver settings

number_of_threads: int
problem_name: str
settings: SolverSettings
class stem.solver.ResidualConvergenceCriteria(residual_relative_tolerance: float = 0.0001, residual_absolute_tolerance: float = 1e-09)

Bases: ConvergenceCriteriaABC

Class containing information about the residual convergence criteria

Inheritance:
Attributes:

  • residual_relative_tolerance (float): The relative tolerance for the residual. Default value is 1e-4.

  • residual_absolute_tolerance (float): The absolute tolerance for the residual. Default value is 1e-9.

property convergence_criterion

Property for returning the type of the residual convergence criterion

Returns:

  • str: The type of the residual convergence criterion

residual_absolute_tolerance: float = 1e-09
residual_relative_tolerance: float = 0.0001
class stem.solver.SchemeABC

Bases: ABC

Abstract class for the scheme

abstract property scheme_type

Abstract property for returning the type of the scheme

Raises:

  • Exception: abstract class of scheme is called

class stem.solver.SolutionType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum class containing the solution types

Attributes:

  • QUASI_STATIC (int): quasi-static solution type

  • DYNAMIC (int): dynamic solution type

DYNAMIC = 2
QUASI_STATIC = 1
class stem.solver.SolverSettings(analysis_type: ~stem.solver.AnalysisType, solution_type: ~stem.solver.SolutionType, stress_initialisation_type: ~stem.solver.StressInitialisationType, time_integration: ~stem.solver.TimeIntegration, is_stiffness_matrix_constant: bool, are_mass_and_damping_constant: bool, convergence_criteria: ~stem.solver.ConvergenceCriteriaABC, reset_displacements: bool = False, calculate_stresses_on_nodes: bool = True, strategy_type: ~stem.solver.StrategyTypeABC = <factory>, scheme: ~stem.solver.SchemeABC = <factory>, linear_solver_settings: ~stem.solver.LinearSolverSettingsABC = <factory>, rayleigh_m: float | None = None, rayleigh_k: float | None = None, echo_level: int = 1, _inititalize_acceleration: bool = False)

Bases: object

Class containing information about the time integration, builder, strategy, scheme and linear solver.

Attributes:

  • solution_type (SolutionType): solution type, QUASI_STATIC or DYNAMIC

  • stress_initialisation_type (StressInitialisationType): stress initialisation type, NONE, GRAVITY_LOADING OR K0_PROCEDURE

  • time_integration (TimeIntegration): time integration settings

  • is_stiffness_matrix_constant (bool): if true, the lhs matrix is only built once, else, the lhs matrix is rebuilt at each non-linear iteration

  • are_mass_and_damping_constant (bool): if true, the mass and damping matrices are prebuilt and directly used to calculate the rhs. If false, the mass and damping matrices are built at each non-linear iteration for calculating the rhs and possibly the lhs

  • convergence_criteria (ConvergenceCriteriaABC): convergence criteria, DisplacementConvergenceCriteria, ResidualConvergenceCriteria, WaterPressureConvergenceCriteria or DisplacementAndWaterPressureConvergenceCriteria

  • reset_displacements (bool): if true, the displacements are reset at the beginning of the phase

  • calculate_stresses_on_nodes (bool): if true, the stresses are also calculated on the nodes and not only on the gauss points. Default value is True.

  • strategy_type (StrategyTypeABC): strategy type, NewtonRaphsonStrategy, LineSearchStrategy or ArcLengthStrategy. Default value is NewtonRaphsonStrategy.

  • scheme (SchemeABC): scheme, NewmarkScheme or BackwardEulerScheme. Default value is NewmarkScheme.

  • linear_solver_settings (LinearSolverSettingsABC): linear solver settings, Amgcl Cg, Lu. Default value is Amgcl.

  • rayleigh_m (Optional[float]): mass proportional damping parameter

  • rayleigh_k (Optional[float]): stiffness proportional damping parameter

  • echo_level (int): echo level. Default value is 1. If 0, only time information is printed. If 1, time information and convergence information are printed. If 2, time information, convergence information, intermediate rhs results and linear solver settings are printed.

  • _inititalize_acceleration (bool): if true, the acceleration is initialized at the beginning of the stage, this value should not be changed by the user.

analysis_type: AnalysisType
are_mass_and_damping_constant: bool
calculate_stresses_on_nodes: bool = True
convergence_criteria: ConvergenceCriteriaABC
echo_level: int = 1
is_stiffness_matrix_constant: bool
linear_solver_settings: LinearSolverSettingsABC
rayleigh_k: float | None = None
rayleigh_m: float | None = None
reset_displacements: bool = False
scheme: SchemeABC
solution_type: SolutionType
strategy_type: StrategyTypeABC
stress_initialisation_type: StressInitialisationType
time_integration: TimeIntegration
validate_settings()

Validates all solver settings

class stem.solver.SparseCg(scaling: bool = False, tolerance: float = 1e-12, max_iteration: int = 1000)

Bases: LinearSolverSettingsABC

Class containing information about the Eigen library implementation of conjugate gradient iterative linear solver settings. Compared to the Cg class, this class uses the Eigen library’s conjugate gradient solver, which is optimized for sparse matrices and can be more efficient for large systems.

Inheritance:
Attributes:

  • scaling (bool): if true, the system matrix will be scaled before solving the linear system of equations. Default value is False.

  • tolerance (float): tolerance for the linear solver convergence criteria. Default value is 1e-12.

  • max_iteration (int): maximum number of iterations for the linear solver. Default value is 1000.

max_iteration: int = 1000
scaling: bool = False
property solver_type

Property that returns the solver type name of the Eigen library implementation of conjugate gradient iterative linear solver settings

Returns:

  • str: solver type name

tolerance: float = 1e-12
class stem.solver.StaticScheme

Bases: SchemeABC

Class containing information about the static scheme

Inheritance:
property scheme_type: str

Property for returning the type of the static scheme

Returns:

  • str: The type of the static scheme

class stem.solver.StrategyTypeABC

Bases: ABC

Abstract class for the strategy type

abstract property strategy_type: str

Abstract property for returning the type of the strategy

Raises:

  • Exception: abstract class of strategy type is called

class stem.solver.StressInitialisationType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum class containing the stress initialisation types

Attributes:

  • NONE (int): no stress initialisation

  • GRAVITY_LOADING (int): gravity loading stress initialisation

  • K0_PROCEDURE (int): K0-procedure stress initialisation

GRAVITY_LOADING = 2
K0_PROCEDURE = 3
NONE = 1
class stem.solver.TimeIntegration(start_time: float, end_time: float, delta_time: float, reduction_factor: float, increase_factor: float, max_delta_time_factor: float = 1000)

Bases: object

Class containing information about the time integration

Attributes:

  • start_time (float): start time of the analysis

  • end_time (float): end time of the analysis

  • delta_time (float): initial time step

  • reduction_factor (float): factor used to reduce the time step when the solution diverges

  • increase_factor (float): factor used to increase the time step when the solution converges within the minimum number of iterations

  • max_delta_time_factor (float): maximum time step factor, used to limit the time step increase. Default value is 1000.

delta_time: float
end_time: float
increase_factor: float
max_delta_time_factor: float = 1000
reduction_factor: float
start_time: float
class stem.solver.WaterPressureConvergenceCriteria(water_pressure_relative_tolerance: float = 0.0001, water_pressure_absolute_tolerance: float = 1e-09)

Bases: ConvergenceCriteriaABC

Class containing information about the water pressure convergence criteria

Inheritance:
Attributes:

  • water_pressure_relative_tolerance (float): The relative tolerance for the water pressure. Default value is 1e-4.

  • water_pressure_absolute_tolerance (float): The absolute tolerance for the water pressure. Default value is 1e-9.

property convergence_criterion

Property for returning the type of the water pressure convergence criterion

Returns:

  • str: The type of the water pressure convergence criterion

water_pressure_absolute_tolerance: float = 1e-09
water_pressure_relative_tolerance: float = 0.0001

stem.stem module

class stem.stem.Stem(initial_stage: Model, input_files_dir: str)

Bases: object

Class containing the main calculation.

Attributes:

  • input_files_dir (str): The directory where the input files are to be written.

  • kratos_io (stem.IO.kratos_io.KratosIO): The Kratos IO object.

  • kratos_model (KratosMultiphysics.Model): The Kratos model.

  • __stages (List[stem.model.Model]): The calculation stages.

  • __stage_settings_file_names (Dict[int, str]): The file names of the project parameters files for each stage.

  • __last_ran_stage_number (int): The number of the last ran stage.

  • __last_uvec_data (KratosMultiphysics.Parameters): The uvec data from the last ran stage

Constructor of the main calculation class.

Args:

  • initial_stage (stem.model.Model): The initial stage of the calculation.

  • input_files_dir (str): The directory where the input files are to be written.

add_calculation_stage(stage: Model)

Add a calculation stage to the calculation. The geometry and the mesh of the new stage are regenerated.

Args:
create_new_stage(delta_time: float, stage_duration: float) → Model

Create a new stage based on the last stage in the calculation. Note that the stage is not added to the calculation.

Args:

  • delta_time (float): The time step of the new stage.

  • stage_duration (float): The duration of the new stage.

Returns:
finalise()

Finalise the calculation.

run_calculation()

Run the full calculation.

run_stage(stage_number: int)

Runs a single stage of the calculation.

Args:

  • stage_number (int): The number of the stage to be run.

property stages: List[Model]

The calculation stages.

Returns:
validate_latest_stage()

Validate the latest stage. The validation checks if the number of body and process model parts are the same between the last two stages. And if the mesh is the same in the new stage.

Raises:

  • Exception: If the number of body model parts are not the same between stages.

  • Exception: If the number of process model parts are not the same between stages.

write_all_input_files()

Write all input files for the calculation.

stem.structural_material module

class stem.structural_material.ElasticSpringDamper(NODAL_DISPLACEMENT_STIFFNESS: List[float], NODAL_ROTATIONAL_STIFFNESS: List[float], NODAL_DAMPING_COEFFICIENT: List[float], NODAL_ROTATIONAL_DAMPING_COEFFICIENT: List[float])

Bases: StructuralParametersABC

Class containing the constitutive parameters for an elastic spring-damper

Inheritance:
Attributes:

  • NODAL_DISPLACEMENT_STIFFNESS (List[float]): The stiffness of the spring in x,y,z direction [N/m].

  • NODAL_ROTATIONAL_STIFFNESS (List[float]): The stiffness of the rotational spring around x,y,z axis [Nm/rad].

  • NODAL_DAMPING_COEFFICIENT (List[float]): The damping coefficient of the spring in x,y,z direction [Ns/m].

  • NODAL_ROTATIONAL_DAMPING_COEFFICIENT (List[float]): The damping coefficient of the rotational spring around x,y,z axis [Ns/rad].

NODAL_DAMPING_COEFFICIENT: List[float]
NODAL_DISPLACEMENT_STIFFNESS: List[float]
NODAL_ROTATIONAL_DAMPING_COEFFICIENT: List[float]
NODAL_ROTATIONAL_STIFFNESS: List[float]
static get_element_name(n_dim_model, n_nodes_element, analysis_type) → str | None

Static method to get the element name for an elastic spring damper element.

Args:

  • n_dim_model (int): The number of dimensions of the model

  • n_nodes_element (int): The number of nodes per element

  • analysis_type (stem.solver.AnalysisType): The analysis type.

Raises:

  • ValueError: If the analysis type is not implemented yet for elastic spring damper elements.

Returns:

  • Optional[str]: The element name

class stem.structural_material.EulerBeam(ndim: int, YOUNG_MODULUS: float, POISSON_RATIO: float, DENSITY: float, CROSS_AREA: float, I33: float, I22: float | None = None, TORSIONAL_INERTIA: float | None = None, RAYLEIGH_M: float | None = None, RAYLEIGH_K: float | None = None)

Bases: StructuralParametersABC

Class containing the material parameters for beam material

Inheritance:
Attributes:

  • ndim (int): The number of dimensions of the beam formulation (2 or 3)

  • YOUNG_MODULUS (float): The Young’s modulus [Pa].

  • POISSON_RATIO (float): The Poisson’s ratio [-].

  • DENSITY (float): The density [kg/m3].

  • CROSS_AREA (float): The cross-sectional area [m2].

  • I33 (float): The second moment of area around the z-axis [m4].

  • I22 (float): The second moment of area around the y-axis [m4].

  • TORSIONAL_INERTIA (float): The torsional inertia [m4].

  • RAYLEIGH_M (Optional[float]): Mass proportional rayleigh damping parameter [-].

  • RAYLEIGH_K (Optional[float]): Stiffness proportional rayleigh damping parameter [-].

CROSS_AREA: float
DENSITY: float
I22: float | None = None
I33: float
POISSON_RATIO: float
RAYLEIGH_K: float | None = None
RAYLEIGH_M: float | None = None
TORSIONAL_INERTIA: float | None = None
YOUNG_MODULUS: float
static get_element_name(n_dim_model: int, n_nodes_element: int, analysis_type: AnalysisType) → str | None

Static method to get the element name for an Euler beam element.

Args:

  • n_dim_model (int): The number of dimensions of the model

  • n_nodes_element (int): The number of nodes per element

  • analysis_type (stem.solver.AnalysisType): The analysis type.

Raises:

  • ValueError: If the analysis type is not implemented yet for Euler beam elements.

Returns:

  • Optional[str]: The element name

ndim: int
class stem.structural_material.NodalConcentrated(NODAL_DISPLACEMENT_STIFFNESS: List[float], NODAL_MASS: float, NODAL_DAMPING_COEFFICIENT: List[float])

Bases: StructuralParametersABC

Class containing the material parameters for a nodal concentrated element

Inheritance:
Attributes:

  • NODAL_DISPLACEMENT_STIFFNESS (List[float]): The stiffness of the spring in x,y,z direction [N/m].

  • NODAL_MASS (float): The mass of the concentrated element [kg].

  • NODAL_DAMPING_COEFFICIENT (List[float]): The damping coefficient of the spring in x,y,z direction [Ns/m].

NODAL_DAMPING_COEFFICIENT: List[float]
NODAL_DISPLACEMENT_STIFFNESS: List[float]
NODAL_MASS: float
static get_element_name(n_dim_model: int, n_nodes_element: int, analysis_type: AnalysisType) → str | None

Get the element name for the nodal concentrated element

Args:

  • n_dim_model (int): The number of dimensions of the model (2 or 3)

  • n_nodes_element (int): The number of nodes of the element (1)

  • analysis_type (AnalysisType): The analysis type of the model

Raises:

  • ValueError: If the analysis type is not implemented yet for nodal concentrated elements.

Returns:

  • Optional[str]: The element name

class stem.structural_material.StructuralMaterial(name: str, material_parameters: StructuralParametersABC)

Bases: object

Class containing material information about a body part, e.g. a soil layer or track components

Attributes:

  • name (str): The name to describe the structural material.

  • material_parameters (StructuralParametersABC): class containing material parameters

get_element_name(n_dim_model: int, n_nodes_element: int, analysis_type: AnalysisType) → str | None

Get the element name for the structural material

Args:

  • n_dim_model (int): The dimension of the model.

  • n_nodes_element (int): The number of nodes per element.

  • analysis_type (stem.solver.AnalysisType): The analysis type.

Returns:

  • Optional[str]: The element name.

get_property_in_material(property_name: str) → Any

Function to retrieve the requested property for the structural material. The function is capital sensitive!

Args:

  • property_name (str): The desired structural property name.

Raises:

  • ValueError: If the property is not in not available in the structural material.

Returns:

  • Any : The value of the structural property

material_parameters: StructuralParametersABC
name: str
class stem.structural_material.StructuralParametersABC

Bases: ABC

Abstract base class for structural material parameters

abstract static get_element_name(n_dim_model: int, n_nodes_element: int, analysis_type: AnalysisType) → str | None

Abstract static method to get the element name for a structural material.

Args:

  • n_dim_model (int): The number of dimensions of the model

  • n_nodes_element (int): The number of nodes per element

  • analysis_type (stem.solver.AnalysisType): The analysis type.

Raises:

  • Exception: abstract method is called

stem.table module

class stem.table.Table(values: Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]], times: Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]], _Table__id: int | None = None)

Bases: object

Class to write time-dependent functions for imposed load and constraints. If analysis runs outside the specified time-steps, the function is linearly extrapolated. If load/constraint is required to remain constant, please specify the same load/constraint value for the last two point of the sequence/array.

Attributes:

  • values (Union[Sequence[float], npty.NDArray[np.float64]]): values of the load/constraint.

  • times (Union[Sequence[float], npty.NDArray[np.float64]]): time [s] corresponding to the values specified.

  • __id (Optional[int]): unique identifier for the table.

property id: int | None

Getter for the id of the table.

Returns:

  • Optional[int]: The id of the table.

interpolate_value_at_time(time: float) → float

Interpolates the value at a given time. If the time is < times[0], the value at times[0] is returned. If the time is > times[-1], the value at times[-1] is returned.

Args:

  • time (float): time [s] at which the value is interpolated.

Returns:

  • float: interpolated value at the given time.

times: Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]
values: Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]

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:

  1. disconnected lines,

  2. branching out paths:

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

b) Branching out paths:
    o---o
         |
    o----o----o
         |
         o
Args:
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:
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:
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).

stem.water_processes module

class stem.water_processes.UniformWaterPressure(water_pressure: float, is_fixed: bool = True)

Bases: WaterProcessParametersABC

Class which contains the parameters for a uniform water pressure process.

Inheritance:

  • WaterProcessParametersABC (ABC): Abstract base class which contains the parameters for a water process.

Attributes:

  • water_pressure (float): The water pressure.

  • is_fixed (bool): Whether the water pressure is fixed or not (default: True).

is_fixed: bool = True
water_pressure: float
class stem.water_processes.WaterProcessParametersABC

Bases: ABC

Abstract class which contains the parameters for a water process.

Module contents