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.