Workflow functions

Read coordinates

Pymeshit.headless.read_points(path)[source]

Read a text, CSV, or VTK point file into an (N, 3) array.

Parameters:
pathpath-like

Input file. .vtu, .vtk, and .vtp are read with PyVista. Other files are treated as UTF-8 text with whitespace, comma, semicolon, or tab separators. Blank lines and lines beginning with # are ignored.

Returns:
numpy.ndarray

Floating-point coordinates with shape (N, 3). Two-column text data receives z=0 and extra columns are ignored.

Raises:
FileNotFoundError

If path does not exist.

ValueError

If no usable coordinates are found or the loaded array has fewer than two coordinate columns.

Parameters:

path (str | PathLike)

Return type:

numpy.ndarray

Notes

Text lines that cannot be parsed as numeric coordinates are skipped. A line beginning with Bounds: is expanded into the corners encoded by its X[...], Y[...], and optional Z[...] ranges.

Run a complete case

Pymeshit.headless.run_mesh_case(mesh_case, *, output_path=None, custom_block_names=None, custom_sideset_names=None, custom_well_names=None, well_export_type='Node Sets')[source]

Run the complete headless PyMeshIt workflow for one case.

Parameters:
mesh_caseMeshCase

Surfaces, wells, materials, and meshing options.

output_pathpath-like, optional

Optional path where the generated tetrahedral mesh should be saved. The GUI exporter is used when available, so EXODUS/NetCDF outputs include material blocks, sidesets, and well node sets. It is used only when mesh_case.options.generate_volume is True.

custom_block_namesdict of int to str, optional

Map material attributes to Exodus element-block names.

custom_sideset_namesdict of int to str, optional

Map surface markers to Exodus sideset names.

custom_well_namesdict of int to str, optional

Map well markers to Exodus node-set or BAR2 block names.

well_export_type{“Node Sets”, “Element Blocks”}, default=”Node Sets”

Select the Exodus representation for wells.

Returns:
MeshResult

Contains the intermediate datasets, conforming surface meshes, and the final PyVista/TetGen volume mesh when generate_volume is enabled.

Raises:
ValueError

If there are no surfaces, the global target size is non-positive, a constraint mode or surface role is invalid, or point data is malformed.

RuntimeError

If volume generation is requested but no conforming surface mesh can be generated. Lower-level geometry errors may also propagate from hull or initial triangulation stages.

Parameters:

  • mesh_case (MeshCase)

  • output_path (str | PathLike | None)

  • custom_block_names (Dict[int, str] | None)

  • custom_sideset_names (Dict[int, str] | None)

  • custom_well_names (Dict[int, str] | None)

  • well_export_type (str)

Return type:

MeshResult

Notes

Conforming triangulation errors for individual surfaces are recorded in MeshResult.failures so other surfaces can still be inspected. A TetGen failure is also recorded and returns tetra_mesh=None.

Run TetGen from conforming surfaces

Pymeshit.headless.generate_tetrahedral_mesh_from_surfaces(surface_meshes, *, datasets=None, selected_surfaces=None, border_surface_indices=None, unit_surface_indices=None, fault_surface_indices=None, materials=None, tetgen_switches='pq1.414aAY')[source]

Run only the final TetGen stage from already conforming surface meshes.

This is useful when geometry is generated externally and users only need PyMeshIt’s PLC assembly and TetGen/material handling.

Parameters:
surface_meshesdict of int to dict

Surface-indexed conforming meshes. Each entry must provide vertices and triangles; facet_markers and name should be supplied when boundary identification matters.

datasetslist of dict, optional

Dataset metadata aligned with the integer surface indices. Minimal placeholder names are generated when omitted.

selected_surfacesiterable of int, optional

Surface indices included in the PLC. All supplied surfaces are selected by default.

border_surface_indicesiterable of int, optional

Selected indices treated as external boundaries. Defaults to all selected surfaces.

unit_surface_indicesiterable of int, optional

Selected internal stratigraphic surface indices.

fault_surface_indicesiterable of int, optional

Selected internal fault surface indices.

materialssequence of MaterialSpec or dict, optional

Formation/fault material metadata and region seeds.

tetgen_switchesstr, default=”pq1.414aAY”

Switch string forwarded to TetGen.

Returns:
object or None

A PyVista UnstructuredGrid when TetGen succeeds, otherwise None.

Raises:
ValueError

If surface_meshes is empty.

Parameters:

  • surface_meshes (Dict[int, Dict[str, Any]])

  • datasets (List[Dict[str, Any]] | None)

  • selected_surfaces (Iterable[int] | None)

  • border_surface_indices (Iterable[int] | None)

  • unit_surface_indices (Iterable[int] | None)

  • fault_surface_indices (Iterable[int] | None)

  • materials (Sequence[MaterialSpec | Dict[str, Any]] | None)

  • tetgen_switches (str)