stem package

Subpackages

• stem.IO package
  • Submodules
  • stem.IO.io_utils module
    • IOUtils
      • IOUtils.create_value_and_table()
      • IOUtils.create_vector_constraint_table_process_dict()
      • IOUtils.write_json_file()
  • stem.IO.kratos_additional_processes_io module
    • KratosAdditionalProcessesIO
      • KratosAdditionalProcessesIO.create_additional_processes_dict()
  • stem.IO.kratos_boundaries_io module
    • KratosBoundariesIO
      • KratosBoundariesIO.create_boundary_condition_dict()
  • stem.IO.kratos_io module
  • stem.IO.kratos_loads_io module
    • KratosLoadsIO
      • KratosLoadsIO.create_load_dict()
  • stem.IO.kratos_material_io module
    • KratosMaterialIO
      • KratosMaterialIO.create_material_dict()
  • stem.IO.kratos_output_io module
    • KratosOutputsIO
      • KratosOutputsIO.create_output_process_dictionary()
  • stem.IO.kratos_solver_io module
    • KratosSolverIO
      • KratosSolverIO.create_settings_dictionary()
  • stem.IO.kratos_water_processes_io module
    • KratosWaterProcessesIO
      • KratosWaterProcessesIO.create_water_process_dict()
  • Module contents

Submodules

stem.additional_processes module

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:

• AdditionalProcessesParametersABC

Attributes:

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

deactivate_body_model_part: bool

class stem.additional_processes.ParameterFieldParameters(property_name: str, function_type: str, field_file_name: 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_name (str): the name of the (material) property 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_name (Optional[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_name: str | None = None

field_generator: FieldGeneratorABC | None = None

function_type: str

property_name: 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:

• BoundaryParametersABC

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(active: List[bool], is_fixed: List[bool], value: List[float | Table])

Bases: BoundaryParametersABC

Class containing the boundary parameters for displacement constraint

Inheritance:

• BoundaryParametersABC

Attributes:

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

• 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.

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 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(active: List[bool], is_fixed: List[bool], value: List[float | Table])

Bases: BoundaryParametersABC

Class containing the boundary parameters for rotation constraint

Inheritance:

• BoundaryParametersABC

Attributes:

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

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

• value (List[float]): Rotation constraint

• 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.

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 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)

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))

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))

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))

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))

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))

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))

class stem.default_materials.RailTypes(value)

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.structural_material.StructuralMaterial

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[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_field: List[Any] | None

Abstract property of the generated field.

Raises:

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

Returns:

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

class stem.field_generator.RandomFieldGenerator(model_name: str, n_dim: int, 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 funtion 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.

Args:

• 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.

Raises:

• ValueError: if the model dimensions is not 2 or 3.

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

generate(coordinates: ndarray[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_field: List[Any] | None

Returns the value of the generated field.

Raises:

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

Returns:

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

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.

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:

• Geometry: The geometry object.

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.

class stem.geometry.Line(id: int)

Bases: GeometricalObjectABC

A class to represent a line in space.

Inheritance:

• GeometricalObjectABC

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:

• GeometricalObjectABC

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:

• Point: A point object.

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:

• GeometricalObjectABC

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:

• Surface: A surface object.

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:

• GeometricalObjectABC

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:

• Volume: A volume object.

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_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]], 'n_vertices': 4, 'ndim': 3, 'order': 2, 'reversed_order': [1, 0, 2, 3, 4, 6, 5, 9, 8, 7]}, '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, 5, 4, 3]}}

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

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:

• LoadParametersABC

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: List[float], velocity: float | str, origin: List[float], offset: float = 0.0)

Bases: LoadParametersABC

Class containing the load parameters for a moving load.

Inheritance:

• LoadParametersABC

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 (List[int]): Direction of the moving load (-1 or +1 in x, y, z direction) [-].

• 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: 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 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:

• LoadParametersABC

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: ~typing.List[float], velocity: float | str, origin: ~typing.List[float], wheel_configuration: ~typing.List[float], uvec_file: str, uvec_function_name: str, uvec_parameters: ~typing.Dict[str, ~typing.Any] = <factory>, uvec_state_variables: ~typing.Dict[str, ~typing.Any] = <factory>)

Bases: LoadParametersABC

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

Inheritance:

• LoadParametersABC

Attributes:

• direction (List[int]): Direction of the moving load (-1 or +1 in x, y, z direction) [-].

• 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_file (str): Path to the UVEC file.

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

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

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

direction: 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 a UVEC load.

origin: List[float]

uvec_file: str

uvec_function_name: str

uvec_parameters: Dict[str, Any]

uvec_state_variables: Dict[str, Any]

velocity: float | str

wheel_configuration: List[float]

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)

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

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:

• Mesh: mesh object

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 element_order: int

Get the element order.

Returns:

• int: element order

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

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:

• ModelPart

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 (Union[stem.soil_material.SoilMaterial, stem.structural_material.StructuralMaterial]): 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

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[Union[stem.load.LoadParametersABC, stem.boundary.BoundaryParametersABC, stem.additional_processes.AdditionalProcessesParametersABC, stem.water_boundaries.WaterBoundaryParametersABC, stem.output.OutputParametersABC]]): 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

stem.output module

class stem.output.GaussPointOutput(value)

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:

• OutputParametersABC

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:

• OutputParametersABC

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)

Bases: Enum

Enum class for variables at the nodes

ACCELERATION = 9

ACCELERATION_X = 10

ACCELERATION_Y = 11

ACCELERATION_Z = 12

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:

• OutputParametersABC

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

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:

• SoilConstitutiveLawABC

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)

Bases: SoilFormulationParametersABC

Class containing the material parameters for an undrained soil material

Inheritance:

• SoilFormulationParametersABC

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 (float): The Biot coefficient [-].

BIOT_COEFFICIENT: float | None = None

BULK_MODULUS_SOLID: float = 50000000000.0

DENSITY_SOLID: float

IS_DRAINED: bool

POROSITY: float

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:

• RetentionLawABC

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:

• RetentionLawABC

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:

• SoilConstitutiveLawABC

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:

• SoilConstitutiveLawABC

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:

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

• soil_formulation (SoilFormulationParametersABC): The soil formulation parameters.

• constitutive_law (SoilConstitutiveLawABC): The soil constitutive law parameters.

• retention_parameters (RetentionLawABC): The retention law parameters.

• fluid_properties (FluidProperties): The fluid properties.

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

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, 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:

• SoilFormulationParametersABC

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 (float): The Biot coefficient [-].

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

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

• PERMEABILITY_ZZ (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

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:

• RetentionLawABC

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-06, max_iteration: int = 1000)

Bases: LinearSolverSettingsABC

Class containing information about the amgcl linear solver settings

Inheritance:

• LinearSolverSettingsABC

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-6.

• 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 for returns the solver type name of the amgcl linear solver settings

Returns:

• str: solver type name

tolerance: float = 1e-06

class stem.solver.AnalysisType(value)

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:

• StrategyTypeABC

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

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:

• SchemeABC

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.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:

• ConvergenceCriteriaABC

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:

• ConvergenceCriteriaABC

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:

• StrategyTypeABC

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

Returns the strategy type name of the line search 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

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:

• SchemeABC

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:

• StrategyTypeABC

max_iterations: int = 15

min_iterations: int = 6

number_cycles: int = 100

property strategy_type

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:

• ConvergenceCriteriaABC

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)

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)

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, NewmarkSceme or BackwardEulerScheme. Default value is NewmarkSceme.

• linear_solver_settings (LinearSolverSettingsABC): linear solver settings, currently only Amgcl is supported

• 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.

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 the solver settings, and changes settings when needed. If the solution type is quasi-static, the time integration scheme is set to Backward Euler.

Raises:

• ValueError: if the Rayleigh damping parameters are not provided for dynamic analysis

• ValueError: if the K0-procedure is selected for dynamic analysis

class stem.solver.StrategyTypeABC

Bases: ABC

Abstract class for the strategy type

abstract property strategy_type

Abstract property for returning the type of the strategy

Raises:

• Exception: abstract class of strategy type is called

class stem.solver.StressInitialisationType(value)

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:

• ConvergenceCriteriaABC

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

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:

• StructuralParametersABC

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)

Bases: StructuralParametersABC

Class containing the material parameters for beam material

Inheritance:

• StructuralParametersABC

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].

CROSS_AREA: float

DENSITY: float

I22: float | None = None

I33: float

POISSON_RATIO: float

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:

• StructuralParametersABC

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[int | float] | ndarray[Any, dtype[float64 | int64]], times: Sequence[float] | ndarray[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[Union[int,float]], npty.NDArray[Union[np.float64, np.int64]]]): 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.

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

values: Sequence[int | float] | ndarray[Any, dtype[float64 | int64]]

stem.utils module

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 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, b) branching out paths

   o—o o—o o | | o o—-o—-o

   
   

   o

Args:

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

Raises:

• ValueError: when geometry is not provided (is None).

• ValueError: when geometry has no lines.

Returns:

• bool: whether the lines are connected along the path

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

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

Args:

• n_dim (int): number of dimensions

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

• available_combinations (Dict[int, List[int]]): dictionary containing the supported combinations of number of dimensions and number of nodes per element or condition-element

• class_name (str): name of the class to be checked

Raises:

• ValueError: when the number of dimensions is not supported.

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

static create_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[Any, dtype[int64]]

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.int64]: list of ids of the nodes close to the geometry points

static flip_node_order(elements: Sequence[Element])

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

Args:

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

Raises:

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

static get_element_edges(element: Element) → ndarray[Any, dtype[int64]]

Gets the nodal connectivities of the line edges of elements

Args:

• element (stem.mesh.Element): element object

Returns:

• npty.NDArray[np.int64]: 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 = 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

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