ogstools.mesh.create package

ogstools.mesh.create.Gaussian2D(bound2D, amplitude, spread, height_offset, n)

Generate a 2D Gaussian-like surface using the provided parameters.

This method computes a 2D Gaussian-like surface by sampling the given bound and parameters.

Parameters:

• bound2D (tuple) – Tuple of boundary coordinates (x_min, x_max, y_min, y_max).

• amplitude (float) – Amplitude or peak value of the Gaussian curve.

• spread (float) – Scaling factor that controls the spread or width of the Gaussian curve.

• height_offset (float) – Constant offset added to elevate the entire surface.

• n (int) – Number of points in each dimension for sampling.

Returns:

pyvista.PolyData: A PyVista PolyData object representing the generated surface.

Return type:

DataSet

note:

• The larger amplitude, the taller the peak of the surface.

• The larger spread, the wider and flatter the surface.

• height_offset shifts the entire surface vertically.

example:

Generating a 2D Gaussian-like surface: ` bound = (-1.0, 1.0, -1.0, 1.0) amplitude = 1.0 spread = 0.5 height_offset = 0.0 n = 100 surface = MyClass.Gaussian2D(bound, amplitude, spread, height_offset, n) `

class ogstools.mesh.create.Layer

Bases: Boundary

Layer(top: ogstools.mesh.create.boundary_subset.Surface, bottom: ogstools.mesh.create.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.

Parameters:

resolution (float) – The resolution for raster creation.

Returns:

A list of filenames to .asc raster files.

Return type:

list[Path]

dim()

Get the dimension of the boundary.

Returns:

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

Return type:

int

to_simplified_mesh(resolution, rank, bounds)

Convert a geological layer to a simplified mesh.

This function converts a geological layer into a simplified mesh using the specified resolution, rank, and bounding bounds.

Parameters:

• (float) (resolution) – The desired spatial resolution of the mesh in units of the geological structure. Be cautious with very high resolutions, as they may lead to distorted or incomplete meshes, making them unsuitable for further analysis.

• (int) (rank) – he rank of the mesh (2 for 2D, 3 for 3D). The mesh dimensionality must be consistent with the provided bounds.

• (list[float]) (bounds) – A list of bounding values [min_x, max_x, min_y, max_y] for 2D mesh or [min_x, max_x, min_y, max_y, min_z, max_z] for 3D mesh. The bounds define the region of the geological structure that will be meshed.

Returns:

A simplified unstructured grid mesh representing the layer.

Return type:

UnstructuredGrid

raises:

Exception: If the specified rank is not 2 or 3, indicating an invalid mesh dimensionality.

example:

layer = … resolution = 1.5 # Example resolution in geological units rank = 2 # Mesh will be 2D bounds = [0, 10, 0, 10] # Bounding box [min_x, max_x, min_y, max_y] mesh = layer.to_simplified_mesh(layer, resolution, rank, bounds)

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

class ogstools.mesh.create.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).

bounds()

Return type:

list

filenames()

Return type:

list[Path]

classmethod from_pandas(df)

Create a LayerSet from a Pandas DataFrame.

Return type:

LayerSet

create_raster(resolution, margin=0.0)

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) – The resolution for raster creation.

• margin (float) – ratio by which to shrink the raster boundary (0.01 == 1%)

Return type:

tuple[Path, Path]

create_rasters(resolution)

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

Parameters:

resolution (float) – The resolution for raster creation.

Return type:

list[Path]

refine(factor)

Refine the LayerSet by increasing the number of subdivisions.

This function refines the LayerSet by increasing the number of subdivisions in each layer. The factor parameter determines the degree of refinement.

Parameters:

• layerset – The original LayerSet to be refined.

• factor (int) – The refinement factor for the number of subdivisions.

Returns:

A new LayerSet with increased subdivisions for each layer.

Return type:

LayerSet

to_region_prism(resolution, margin=0.0)

Convert a layered geological structure into a RegionSet using prism meshing.

This function takes a boundary_set.LayerSet and converts it into a region.RegionSet object using prism or tetrahedral meshing technique. The function will use prism elements for meshing if possible; otherwise, it will use tetrahedral elements.

Parameters:

• resolution (float) – The desired resolution in [meter] for meshing. It must greater than 0.

• margin (float) – ratio by which to shrink the raster boundary (0.01 == 1%)

Returns:

A boundary_set.LayerSet object containing the meshed representation of the geological structure.

Return type:

RegionSet

raises:

ValueError: If an error occurs during the meshing process.

example:

layer_set = LayerSet(…) resolution = 0.1 region_set = layer_set.to_region_prism(resolution)

to_region_simplified(xy_resolution, rank)

Convert a layered geological structure to a simplified meshed region.

This function converts a layered geological structure represented by a LayerSet into a simplified meshed region using the specified xy_resolution and rank.

Parameters:

• (float) (xy_resolution) – The desired spatial resolution of the mesh in the XY plane.

• (int) (rank) – The rank of the mesh (2 for 2D, 3 for 3D).

Returns:

A RegionSet object containing the simplified meshed representation of the geological structure.

Return type:

RegionSet

raises:

AssertionError: If the length of the bounds retrieved from the layer_set is not 6.

example:

layer_set = LayerSet(…) xy_resolution = 0.1 # Example resolution in XY plane rank = 2 # Mesh will be 2D region_set = layer_set.to_region_simplified(xy_resolution, rank)

to_region_tetrahedron(resolution, margin=0.0)

Convert a layered geological structure to a tetrahedral meshed region.

This function converts a layered geological structure represented by a LayerSet into a tetrahedral meshed region using the specified resolution.

Parameters:

• resolution (int) – The desired resolution for meshing.

• margin (float) – ratio by which to shrink the raster boundary (0.01 == 1%)

Returns:

A RegionSet object containing the tetrahedral meshed representation of the geological structure.

Return type:

RegionSet

raises:

ValueError: If an error occurs during the meshing process.

notes:

• The resolution parameter determines the desired spatial resolution of the mesh.

• The function utilizes tetrahedral meshing using Tetgen software to create the meshed representation.

• The resulting mesh is tetrahedral, and material IDs are assigned to mesh cells based on the geological layers.

example:

layer_set = LayerSet(…) resolution = 1 # Example resolution for meshing region_set = layer_set.to_region_tetrahedron(resolution)

to_region_voxel(resolution)

Convert a layered geological structure to a voxelized mesh.

This function converts a layered geological structure represented by a LayerSet into a voxelized mesh using the specified resolution.

Parameters:

resolution (list) – A list of [x_resolution, y_resolution, z_resolution] for voxelization.

Returns:

A Mesh object containing the voxelized mesh representation of the geological structure.

Return type:

RegionSet

raises:

ValueError: If an error occurs during the voxelization process.

example:

layer_set = LayerSet(…) resolution = [0.1, 0.1, 0.1] # Example voxelization resolutions in x, y, and z dimensions voxel_mesh = layer_set.to_region_voxel(resolution)

class ogstools.mesh.create.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.

Parameters:

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

Returns:

None

Return type:

None

__init__(xmin, xmax, ymin, ymax)

class ogstools.mesh.create.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)

as_vtu(outfilevtu)

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

Parameters:

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

Returns:

The path to the saved VTK unstructured grid representation.

Return type:

Path

class ogstools.mesh.create.RegionSet

Bases: object

A class representing a set of regions composed of subsets, each identified by MaterialID.

The RegionSet class represents a collection of regions, where each region is composed of subsets. Each subset within a region is uniquely identified by “MaterialID”.

__init__(input)

box_boundaries()

Retrieve the boundaries of the mesh in local coordinate system (u, v, w).

This function extracts the boundaries of the mesh along the u, v, and w directions of the local coordinate system. The u-axis corresponds to the x-coordinate, the v-axis corresponds to the y-coordinate, and the w-axis corresponds to the z-coordinate.

Returns:

A tuple (u_min, u_max, v_min, v_max, w_min, w_max) representing the boundaries of the mesh in the local coordinate system.

Return type:

tuple[UnstructuredGrid, …]

notes:

• If the original mesh was created from boundaries, this function returns the original boundaries.

• The returned boundaries adhere to the definition of [Pyvista Box](https://docs.pyvista.org/version/stable/api/utilities/_autosummary/pyvista.Box.html).

example:

mesh = … u_min, u_max, v_min, v_max, w_min, w_max = mesh.box_boundaries()

class ogstools.mesh.create.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.

create_raster_file(resolution)

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

Parameters:

resolution (float) – The resolution for raster creation.

Return type:

Path

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

ogstools.mesh.create.dataframe_from_csv(layer_set_id, layer_sets_csvfile, surfaces)

Create a DataFrame from CSV data for a specific layer set.

This function reads a CSV file containing layer set information and filters it for a specific layer set ID. It then maps layer IDs to surface files and returns a DataFrame with material IDs, surface filenames, and resolutions. The surfaces corresponding to the layer_id must be sorted from top to bottom (high z values to low z values).

Parameters:

• layer_set_id (int) – The layer set ID to filter the CSV data by.

• layer_sets_csvfile (Path | str) – CSV file containing layer set information.

• surfaces (dict[int, Path] | Path | str) – Either a dictionary mapping layer IDs to surface files, or a path to a directory containing surface files. If a directory path is provided, all .vtu files in the directory will be used. In that case, the layer_id in the layer_sets_csvfile has to correspond to the sorted list of .vtu files in the directory.

Returns:

A DataFrame containing columns ‘material_id’, ‘filename’, and ‘resolution’ for the specified layer set.

Raises:

ValueError, If no model is defined with the given layer_set_id.

Return type:

DataFrame

Submodules

• ogstools.mesh.create.boundary module
  • Boundary
    • Boundary.dim()
  • Layer
    • Layer.top
    • Layer.bottom
    • Layer.material_id
    • Layer.num_subdivisions
    • Layer.create_raster()
    • Layer.dim()
    • Layer.to_simplified_mesh()
    • 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.mesh.create.boundary_set module
  • BoundarySet
    • BoundarySet.bounds()
    • BoundarySet.filenames()
  • LayerSet
    • LayerSet.__init__()
    • LayerSet.bounds()
    • LayerSet.filenames()
    • LayerSet.from_pandas()
    • LayerSet.create_raster()
    • LayerSet.create_rasters()
    • LayerSet.refine()
    • LayerSet.to_region_prism()
    • LayerSet.to_region_simplified()
    • LayerSet.to_region_tetrahedron()
    • LayerSet.to_region_voxel()
• ogstools.mesh.create.boundary_subset module
  • Surface
    • Surface.material_id
    • Surface.__init__()
    • Surface.create_raster_file()
  • Gaussian2D()
• ogstools.mesh.create.dataframe module
  • dataframe_from_csv()
• ogstools.mesh.create.region module
  • RegionSet
    • RegionSet.__init__()
    • RegionSet.box_boundaries()
  • to_boundary()