ogstools.meshlib package

class ogstools.meshlib.Surface

Bases: object

A surface is a sub group of a polygon mesh (2D). A surface is not closed and therefore does not represent a volume. (Geological) layers (stratigraphic units) can be defined by an upper and lower surface. By convention, properties (material_id and resolution ), actually associated to the stratigraphic unit layer, are given together with the lower boundary (class Surface) of a stratigraphic unit (class Layer).

Initialize a surface mesh. Either from pyvista or from a file.

property material_id: int

__init__(input, material_id)

Initialize a surface mesh. Either from pyvista or from a file.

Parameters:

• input (Path | DataObject)

• material_id (int)

create_raster_file(resolution)

Creates a raster file specific to resolution. If outfile is not specified, the extension is replaced by .asc

:returns the path and filename of the created file (.asc)

Parameters:

resolution (float)

Return type:

Path

class ogstools.meshlib.Layer

Bases: Boundary

Layer(top: ogstools.meshlib.boundary_subset.Surface, bottom: ogstools.meshlib.boundary_subset.Surface, material_id: int = 0, num_subdivisions: int = 0)

top: Surface

bottom: Surface

material_id: int = 0

num_subdivisions: int = 0

Class representing a geological layer with top and bottom surfaces.

A geological layer is a distinct unit of rock or sediment that has unique properties and characteristics, associated by the material_id. It is often bounded by two surfaces: the top surface and the bottom surface. These surfaces delineate the spatial extent of the layer in the GIS system.

create_raster(resolution)

Create raster representations for the layer.

For each surface, including intermediate surfaces (num_of_subdivisions > 0), this method generates .asc files.

Args:

resolution (float): The resolution for raster creation.

Returns:

list[Path]: A list of filenames to .asc raster files.

Parameters:

resolution (float)

Return type:

list[Path]

dim()

Get the dimension of the boundary.

Returns:

int: The dimension of the boundary. For example, the dimension of a boundary of a cube (3D) is 2.

Return type:

int

__init__(top, bottom, material_id=0, num_subdivisions=0)

Parameters:

• top (Surface)

• bottom (Surface)

• material_id (int)

• num_subdivisions (int)

Return type:

None

class ogstools.meshlib.Raster

Bases: object

Class representing a raster representation of a location frame.

This class provides methods to create and save a raster representation based on a specified location frame and resolution.

frame: LocationFrame

resolution: float

__init__(frame, resolution)

Parameters:

• frame (LocationFrame)

• resolution (float)

Return type:

None

as_vtu(outfilevtu)

Create and save a raster representation as a VTK unstructured grid.

Args:

outfilevtu (Path): The path to save the VTK unstructured grid representation.

Returns:

Path: The path to the saved VTK unstructured grid representation.

Parameters:

outfilevtu (Path)

Return type:

Path

class ogstools.meshlib.LocationFrame

Bases: object

LocationFrame(xmin: float, xmax: float, ymin: float, ymax: float)

xmin: float

xmax: float

ymin: float

ymax: float

as_gml(filename)

Generate GML representation of the location frame.

Args:

filename (Path): The filename to save the GML representation to.

Returns:

None

Parameters:

filename (Path)

Return type:

None

__init__(xmin, xmax, ymin, ymax)

Parameters:

• xmin (float)

• xmax (float)

• ymin (float)

• ymax (float)

Return type:

None

class ogstools.meshlib.Boundary

Bases: ABC

Abstract base class representing a boundary within a mesh.

A boundary refers to the set of edges or faces that defines the delineation between the interior region and exterior regions of a mesh. In a 2D mesh, it is formed by a closed collection of line segments (1D). In a 3D mesh, it is formed by a closed collection of faces (2D).

abstract dim()

Get the dimension of the boundary.

Returns:

int: The dimension of the boundary. For example, the dimension of a boundary of a cube (3D) is 2.

Return type:

int

class ogstools.meshlib.MeshSeries

Bases: object

A wrapper around pyvista and meshio for reading of pvd and xdmf timeseries.

Will be replaced by own module in ogstools with similar interface.

Initialize a MeshSeries object

param filepath:

Path to the PVD or XDMF file.

param time_unit:

Data unit of the timevalues.

returns:

A MeshSeries object

__init__(filepath, time_unit='s')

Initialize a MeshSeries object

param filepath:

Path to the PVD or XDMF file.

param time_unit:

Data unit of the timevalues.

returns:

A MeshSeries object

Parameters:

• filepath (str | Path)

• time_unit (str | None)

Return type:

None

property hdf5: File

read(timestep, lazy_eval=True)

Lazy read function.

Parameters:

• timestep (int)

• lazy_eval (bool)

Return type:

UnstructuredGrid

clear()

Return type:

None

property timesteps: range

Return the timesteps of the timeseries data.

property timevalues: ndarray

Return the timevalues of the timeseries data.

closest_timestep(timevalue)

Return the corresponding timestep from a timevalue.

Parameters:

timevalue (float)

Return type:

int

closest_timevalue(timevalue)

Return the closest timevalue to a timevalue.

Parameters:

timevalue (float)

Return type:

float

read_closest(timevalue)

Return the closest timestep in the data for a given timevalue.

Parameters:

timevalue (float)

Return type:

UnstructuredGrid

read_interp(timevalue, lazy_eval=True)

Return the temporal interpolated mesh for a given timevalue.

Parameters:

• timevalue (float)

• lazy_eval (bool)

Return type:

UnstructuredGrid

values(data_name)

Get the data in the MeshSeries for all timesteps.

Parameters:

data_name (str) – Name of the data in the MeshSeries.

Returns:

A numpy array of the requested data for all timesteps

Return type:

ndarray

aggregate(mesh_property, func)

Aggregate data over all timesteps using a specified function.

Parameters:

• mesh_property (Property | str) – The mesh property to be aggregated. If given as type Property, the transform() function will be applied on each timestep and aggregation afterwards.

• func (Literal['min', 'max', 'mean', 'median', 'sum', 'std', 'var']) – The aggregation function to apply. It must be one of “min”, “max”, “mean”, “median”, “sum”, “std”, “var”, where the equally named numpy function will be used to aggregate over all timesteps or “min_time” or “max_time”, which return the timevalue when the limit occurs.

Returns:

A mesh with aggregated data according to the given function.

Return type:

UnstructuredGrid

probe(points, data_name, interp_method=None, interp_backend_pvd=None)

Probe the MeshSeries at observation points.

Parameters:

• points (ndarray) – The points to sample at.

• data_name (str) – Name of the data to sample.

• interp_method (Literal['nearest', 'linear', 'probefilter'] | None) – Choose the interpolation method, defaults to linear for xdmf MeshSeries and probefilter for pvd MeshSeries.

• interp_backend – Interpolation backend for PVD MeshSeries.

• interp_backend_pvd (Literal['vtk', 'scipy'] | None)

Returns:

numpy array of interpolated data at observation points.

Return type:

ndarray

class ogstools.meshlib.LayerSet

Bases: BoundarySet

Collection of geological layers stacked to represent subsurface arrangements.

In a geological information system, multiple layers can be stacked vertically to represent the subsurface arrangement. This class provides methods to manage and work with layered geological data.

Initializes a LayerSet. It checks if the list of provided layers are given in a top to bottom order. In neighboring layers, layers share the same surface (upper bottom == low top).

__init__(layers)

Initializes a LayerSet. It checks if the list of provided layers are given in a top to bottom order. In neighboring layers, layers share the same surface (upper bottom == low top).

Parameters:

layers (list[Layer])

bounds()

Return type:

list

filenames()

Return type:

list[Path]

classmethod from_pandas(df)

Create a LayerSet from a Pandas DataFrame.

Parameters:

df (DataFrame)

Return type:

LayerSet

create_raster(resolution)

Create raster representations for the LayerSet.

This method generates raster files at a specified resolution for each layer’s top and bottom boundaries and returns paths to the raster files.

Parameters:

resolution (float)

Return type:

tuple[Path, Path]

create_rasters(resolution)

For each surface a (temporary) raster file with given resolution is created.

Parameters:

resolution (float)

Return type:

list[Path]

ogstools.meshlib.difference(mesh1, mesh2, mesh_property=None)

Compute the difference of properties between two meshes.

Parameters:

• mesh1 (UnstructuredGrid) – The first mesh to be subtracted from.

• mesh2 (UnstructuredGrid) – The second mesh whose data is subtracted from the first mesh.

• mesh_property (Property | str | None) – The property of interest. If not given, all point and cell_data will be processed raw.

Returns:

A new mesh containing the difference of mesh_property or all datasets between mesh1 and mesh2.

Return type:

UnstructuredGrid

ogstools.meshlib.difference_pairwise(meshes_1, meshes_2, mesh_property=None)

Compute pairwise difference between meshes from two lists/arrays (they have to be of the same length).

Parameters:

• meshes_1 (list | ndarray) – The first list/array of meshes to be subtracted from.

• meshes_2 (list | ndarray) – The second list/array of meshes whose data is subtracted from the first list/array of meshes - meshes_1.

• mesh_property (Property | str | None) – The property of interest. If not given, all point and cell_data will be processed raw.

Returns:

An array of meshes containing the differences of mesh_property or all datasets between meshes_1 and meshes_2.

Return type:

ndarray

ogstools.meshlib.difference_matrix(meshes_1, meshes_2=None, mesh_property=None)

Compute the difference between all combinations of two meshes from one or two arrays based on a specified property.

Parameters:

• meshes_1 (list | ndarray) – The first list/array of meshes to be subtracted from.

• meshes_2 (list | ndarray | None) – The second list/array of meshes, it is subtracted from the first list/array of meshes - meshes_1 (optional).

• mesh_property (Property | str | None) – The property of interest. If not given, all point and cell_data will be processed raw.

Returns:

An array of meshes containing the differences of mesh_property or all datasets between meshes_1 and meshes_2 for all possible combinations.

Return type:

ndarray

ogstools.meshlib.interp_points(points, resolution=100)

Provides lists of points on every segment at a line profile between arbitrary number of points pairs.

Parameters:

• points (ndarray) – Numpy array of N points to sample between. Has to be of shape (N, 3).

• resolution (int) – Resolution of the sampled profile. Total number of points within all profile segments.

Returns:

Numpy array of shape (N, 3), without duplicated nodal points.

Return type:

ndarray

ogstools.meshlib.distance_in_profile(points)

Parameters:

points (ndarray) – 2D array of N points (profile nodes) of shape (N, 3)

Returns:

1D array of distances of each point to the beginning of the profile (first row in points), shape of (N,)

Return type:

ndarray

ogstools.meshlib.distance_in_segments(profile_nodes, profile)

Calculate the distance within segments of a polyline profile.

Parameters:

• profile_nodes (ndarray) – 2D array of N points (profile nodes) of shape (N, 3)

• profile (ndarray) – output from interp_points function. 2D array of N points (profile nodes) of shape (N, 3)

Returns:

1D array of distances in each segment to its starting point of shape (N, 3), where N is the number of points in profile

Return type:

ndarray

ogstools.meshlib.sample_polyline(mesh, properties, profile_nodes, resolution=100)

Sample one or more properties along a polyline. Profiles created by user can be passed as profile_nodes parameter. In this case user should also set resolution to None in order to avoid further interpolation between the points.

Parameters:

• mesh (UnstructuredGrid) – Mesh from which properties will be sampled.

• properties (str | Property | list) – Name or list of names of properties to sample. :param profile_nodes: 2D array of N points (profile nodes) of shape (N, 3)

• resolution (int | None) – Total number of sampling points.

• profile_nodes (ndarray)

Returns:

tuple containing DataFrame with results of the profile sampling and Numpy array of distances from the beginning of the profile at points defined in profile_points.

Return type:

tuple[DataFrame, array]

ogstools.meshlib.rect(lengths=1.0, n_edge_cells=1, structured_grid=True, order=1, out_name=Path('unit_square.msh'), msh_version=None)

Parameters:

• lengths (float | list[float])

• n_edge_cells (int | list[int])

• structured_grid (bool)

• order (int)

• out_name (Path)

• msh_version (float | None)

Return type:

None

ogstools.meshlib.cuboid(lengths=1.0, n_edge_cells=1, structured_grid=True, order=1, out_name=Path('unit_cube.msh'), msh_version=None)

Parameters:

• lengths (float | list[float])

• n_edge_cells (int | list[int])

• structured_grid (bool)

• order (int)

• out_name (Path)

• msh_version (float | None)

Return type:

None

Subpackages

• ogstools.meshlib.region package
  • to_region_prism()
  • to_region_simplified()
  • to_region_tetraeder()
  • to_region_voxel()
  • RegionSet
    • RegionSet.__init__()
    • RegionSet.box_boundaries()
  • to_boundary()
  • Submodules
    • ogstools.meshlib.region.region module
      • RegionSet
      • to_boundary()
      • to_region_prism()
      • layer_to_simplified_mesh()
      • to_region_simplified()
      • to_region_tetraeder()
      • to_region_voxel()

Submodules

• ogstools.meshlib.boundary module
  • Boundary
    • Boundary.dim()
  • Layer
    • Layer.top
    • Layer.bottom
    • Layer.material_id
    • Layer.num_subdivisions
    • Layer.create_raster()
    • Layer.dim()
    • Layer.__init__()
  • LocationFrame
    • LocationFrame.xmin
    • LocationFrame.xmax
    • LocationFrame.ymin
    • LocationFrame.ymax
    • LocationFrame.as_gml()
    • LocationFrame.__init__()
  • Raster
    • Raster.frame
    • Raster.resolution
    • Raster.__init__()
    • Raster.as_vtu()
• ogstools.meshlib.boundary_set module
  • BoundarySet
    • BoundarySet.bounds()
    • BoundarySet.filenames()
  • LayerSet
    • LayerSet.__init__()
    • LayerSet.bounds()
    • LayerSet.filenames()
    • LayerSet.from_pandas()
    • LayerSet.create_raster()
    • LayerSet.create_rasters()
• ogstools.meshlib.boundary_subset module
  • Surface
    • Surface.material_id
    • Surface.__init__()
    • Surface.create_raster_file()
  • Gaussian2D()
• ogstools.meshlib.data_processing module
  • difference()
  • difference_pairwise()
  • difference_matrix()
  • interp_points()
  • distance_in_segments()
  • distance_in_profile()
  • sample_polyline()
• ogstools.meshlib.gmsh_meshing module
  • rect()
  • cuboid()
  • Groundwater
    • Groundwater.begin
    • Groundwater.isolation_layer_id
    • Groundwater.flow_direction
    • Groundwater.__init__()
  • BHE
    • BHE.x
    • BHE.y
    • BHE.__init__()
    • BHE.z_begin
    • BHE.z_end
    • BHE.borehole_radius
  • gen_bhe_mesh_gmsh()
  • gen_bhe_mesh()
• ogstools.meshlib.mesh_series module
  • MeshSeries
    • MeshSeries.__init__()
    • MeshSeries.hdf5
    • MeshSeries.read()
    • MeshSeries.clear()
    • MeshSeries.timesteps
    • MeshSeries.timevalues
    • MeshSeries.closest_timestep()
    • MeshSeries.closest_timevalue()
    • MeshSeries.read_closest()
    • MeshSeries.read_interp()
    • MeshSeries.values()
    • MeshSeries.aggregate()
    • MeshSeries.probe()
• ogstools.meshlib.refine_mesh module
  • refine()
• ogstools.meshlib.xdmf_reader module
  • XDMFReader
    • XDMFReader.__init__()
    • XDMFReader.read_data()