core package

Submodules

PyHydroGeophysX.core.interpolation module

Interpolation utilities for geophysical data processing.

class PyHydroGeophysX.core.interpolation.ProfileInterpolator(point1: List[int], point2: List[int], surface_data: ndarray, origin_x: float = 0.0, origin_y: float = 0.0, pixel_width: float = 1.0, pixel_height: float = -1.0, num_points: int = 200)

Bases: object

Class for handling interpolation of data to/from profiles.

interpolate_3d_data(data: ndarray) → ndarray

Interpolate 3D data (n_layers, ny, nx) to profile.

Parameters:

data – 3D array of values

Returns:

Array of interpolated values (n_layers, n_profile_points)

interpolate_layer_data(layer_data: List[ndarray]) → ndarray

Interpolate multiple layer data to profile.

Parameters:

layer_data – List of 2D arrays for each layer

Returns:

Array of interpolated values (n_layers, n_profile_points)

interpolate_to_mesh(property_values: ndarray, depth_values: ndarray, mesh_x: ndarray, mesh_y: ndarray, mesh_markers: ndarray, ID: ndarray, layer_markers: list = [3, 0, 2]) → ndarray

Interpolate property values from profile to mesh with layer-specific handling.

Parameters:

• property_values – Property values array (n_layers, n_points), any number of layers

• depth_values – Vertical coordinates, at least one row per property row, in the same datum/units as mesh_y; see the module-level interpolate_to_mesh.

• mesh_x – Coordinates of mesh cells

• mesh_y – Coordinates of mesh cells

• mesh_markers – One layer marker per mesh cell. Cells outside

• output. (layer_markers retain zero in the)

ID: Source layer labels shaped like property_values.

layer_markers: List of marker values for each layer

Returns:

Interpolated values for mesh cells

PyHydroGeophysX.core.interpolation.create_surface_lines(L_profile: ndarray, structure: ndarray, top_idx: int = 0, mid_idx: int = 4, bot_idx: int = 12) → Tuple[ndarray, ndarray, ndarray]

Create surface and boundary lines from structure data

Parameters:

• L_profile – Distance along profile

• structure – Interpolated structure data

• top_idx – Index for top surface

• mid_idx – Index for middle boundary

• bot_idx – Index for bottom boundary

Returns:

Surface coordinates line1: First boundary coordinates line2: Second boundary coordinates

Return type:

surface

PyHydroGeophysX.core.interpolation.interpolate_structure_to_profile(structure_data: List[ndarray], X_grid: ndarray, Y_grid: ndarray, X_pro: ndarray, Y_pro: ndarray) → ndarray

Interpolate multiple structure layers onto profile

Parameters:

• structure_data – List of 2D arrays for each layer

• X_grid – X coordinates of original grid

• Y_grid – Y coordinates of original grid

• X_pro – X coordinates of profile points

• Y_pro – Y coordinates of profile points

Returns:

Array of interpolated values with shape (n_layers, n_points)

PyHydroGeophysX.core.interpolation.interpolate_to_mesh(property_values: ndarray, profile_distance: ndarray, depth_values: ndarray, mesh_x: ndarray, mesh_y: ndarray, mesh_markers: ndarray, ID: Any, layer_markers: list = [3, 0, 2]) → ndarray

Interpolate property values from profile to mesh with layer-specific handling.

Parameters:

• property_values – Array shaped (layers, profile points), any number of layers.

• profile_distance – Distance along profile (n_points)

• depth_values – Vertical coordinates (at least as many rows as property_values, profile points), in the same datum/units as mesh_y. Row i locates property row i, so with the usual layer surfaces (top plus one bottom per layer) each layer is placed at its top; rows beyond property_values’ are not used.

• mesh_x – X coordinates of mesh cells

• mesh_y – Y coordinates of mesh cells

• mesh_markers – One layer marker per mesh cell. Cells outside layer_markers retain zero in the output.

• ID – Source layer labels shaped like property_values.

• layer_markers – List of marker values for each layer

Returns:

Interpolated values for mesh cells

Raises:

ValueError – depth_values has fewer rows, or a different number of profile points, than property_values.

PyHydroGeophysX.core.interpolation.interpolate_to_profile(data: ndarray, X_grid: ndarray, Y_grid: ndarray, X_pro: ndarray, Y_pro: ndarray, method: str = 'linear') → ndarray

Interpolate 2D data onto a profile line

Parameters:

• data – 2D array of values to interpolate

• X_grid – X coordinates of original grid (meshgrid)

• Y_grid – Y coordinates of original grid (meshgrid)

• X_pro – X coordinates of profile points

• Y_pro – Y coordinates of profile points

• method – Interpolation method (‘linear’ or ‘nearest’)

Returns:

Interpolated values along profile

PyHydroGeophysX.core.interpolation.prepare_2D_profile_data(data: ndarray, XX: ndarray, YY: ndarray, X_pro: ndarray, Y_pro: ndarray) → ndarray

Interpolate multiple 2D gridded data layers onto a profile line.

Parameters:

• data – 3D array of gridded data (n_layers, ny, nx)

• XX – Coordinate grids from meshgrid

• YY – Coordinate grids from meshgrid

• X_pro – Profile line coordinates

• Y_pro – Profile line coordinates

Returns:

Interpolated values along profile (n_layers, n_profile_points)

PyHydroGeophysX.core.interpolation.setup_profile_coordinates(point1: List[int], point2: List[int], surface_data: ndarray, origin_x: float = 0.0, origin_y: float = 0.0, pixel_width: float = 1.0, pixel_height: float = -1.0, num_points: int = 200) → Tuple[ndarray, ndarray, ndarray, ndarray, ndarray]

Set up profile coordinates based on surface elevation data between two points

The profile starts at point2 (distance zero) and runs toward point1, stopping one step short of it: num_points - 1 samples, spaced distance / (num_points - 1) apart. The examples, and the data bundled with them (TL_measurements, Seismic), were built on this layout, and create_mesh_from_layers places each layer’s region marker from the first node of the profile, so a profile run the other way puts the regolith and bedrock markers in each other’s layers.

Parameters:

• point1 – End point indices [col, row]; the profile stops one step before it

• point2 – Start point indices [col, row]; distance zero

• surface_data – 2D array of surface elevation data

• origin_x – X coordinate of origin

• origin_y – Y coordinate of origin

• pixel_width – Width of each pixel

• pixel_height – Height of each pixel (negative for top-down)

• num_points – Size of the spacing along the profile (an integer >= 2); the profile holds num_points - 1 of its points

Returns:

X coordinates along profile Y_pro: Y coordinates along profile L_profile: Distances along profile XX: X coordinate grid YY: Y coordinate grid

Return type:

X_pro

Raises:

ValueError – num_points is not an integer >= 2, or the endpoints are the same location.

PyHydroGeophysX.core.mesh_utils module

Mesh utilities for geophysical modeling and inversion.

class PyHydroGeophysX.core.mesh_utils.MeshCreator(quality: float = 28, area: float = 40)

Bases: object

Class for creating and managing meshes for geophysical inversion.

create_from_ert_data(data, max_depth: float = 30.0, quality: float = 34)

Create a mesh suitable for ERT inversion from ERT data.

Parameters:

• data – PyGIMLI ERT data object

• max_depth – Positive parameter-domain depth forwarded as paraDepth.

• quality – Mesh quality parameter

Returns:

PyGIMLI mesh for ERT inversion

create_from_layers(surface: ndarray, layers: List[ndarray], bottom_depth: float | None = None, markers: List[int] = None, *, bottom_elevation: float | None = None) → Tuple[pygimli.Mesh, pygimli.Mesh]

Create a mesh from surface and layer boundaries.

Parameters:

• surface – Surface coordinates [[x,z],…]

• layers – Exactly two arrays of layer-boundary coordinates, in the same (x, elevation) coordinate system as surface.

• bottom_depth – Legacy alias for bottom_elevation; retains elevation semantics.

• bottom_elevation – Absolute bottom elevation, default 30.0. Supply only one of bottom_depth and bottom_elevation.

• markers – Three integer region markers, top to bottom (default [2, 3, 2]).

Returns:

Tuple of (PyGIMLi mesh, geometry).

PyHydroGeophysX.core.mesh_utils.add_velocity_interface(ertData: Any, smooth_x: Any, smooth_z: Any, paraBoundary: Any = 2, boundary: Any = 1, paraDepth: Any = 30.0, paraDX: Any = None, paraMaxCellSize: Any = 30) → Any

Add a velocity interface line to the geometry and create a mesh with different markers: - Outside survey area: marker = 1 - Inside survey area, above velocity line: marker = 2 - Inside survey area, below velocity line: marker = 3

Parameters:

• ertData – ERT data with sensor positions

• smooth_x – Arrays with x and z coordinates of the velocity interface

• smooth_z – Arrays with x and z coordinates of the velocity interface

• paraBoundary – Parameter boundary size (default: 2)

• boundary – Boundary marker (default: 1)

• paraDepth – Depth of parameter domain (default: 30.0)

• paraDX – Horizontal mesh refinement (default: None)

• paraMaxCellSize – Maximum cell size in parameter domain (default: 30)

Returns:

Array with cell markers meshafter: The created mesh with updated markers

Return type:

markers

PyHydroGeophysX.core.mesh_utils.createTriangles(mesh: Any) → Any

Generate triangle objects for later drawing.

Creates triangle for each 2D triangle cell or 3D boundary. Quads will be split into two triangles. Result will be cached into mesh._triData.

Parameters:

mesh (GIMLI::Mesh) – 2D mesh or 3D mesh

Returns:

• x (numpy array) – x position of nodes

• y (numpy array) – x position of nodes

• triangles (numpy array Cx3) – cell indices for each triangle, quad or boundary face

• z (numpy array) – z position for given indices

• dataIdx (list of int) – List of indices for a data array

PyHydroGeophysX.core.mesh_utils.create_mesh_from_layers(surface: ndarray, line1: ndarray, line2: ndarray, bottom_depth: float | None = None, quality: float = 28, area: float = 40, *, bottom_elevation: float | None = None, markers: List[int] | None = None) → Tuple[pygimli.Mesh, ndarray, ndarray, pygimli.Mesh]

Create mesh from layer boundaries and get cell centers and markers.

Parameters:

• surface – Surface coordinates [[x,z],…]

• line1 – First layer boundary coordinates

• line2 – Second layer boundary coordinates

• bottom_depth – Legacy alias for bottom_elevation. Supply only one of them.

• bottom_elevation – Absolute bottom elevation in the input datum (default 30.0 when neither argument is supplied), below both interfaces.

• markers – Three integer region markers, from top to bottom (default [2, 3, 2]).

• quality – Mesh quality parameter

• area – Maximum cell area

Returns:

(mesh, mesh_centers, markers, geom):

• mesh: PyGIMLI mesh

• mesh_centers: Array of cell center coordinates

• markers: Array of cell markers

• geom: Geometry used to generate the mesh

Return type:

tuple

PyHydroGeophysX.core.mesh_utils.extract_velocity_interface(mesh: Any, velocity_data: Any, threshold: Any = 1200, interval: Any = 4.0, x_min: Any = None, x_max: Any = None) → Any

Extract the interface where velocity equals the threshold value.

Parameters: mesh - The PyGIMLi mesh velocity_data - The velocity values threshold - The velocity value defining the interface (default: 1200) interval - The binning interval for extracting the interface (default: 4.0) x_min - Optional: minimum x-coordinate for the range (default: None, uses mesh data) x_max - Optional: maximum x-coordinate for the range (default: None, uses mesh data)

Returns: x_dense, z_dense - Arrays with x and z coordinates of the smooth interface

PyHydroGeophysX.core.mesh_utils.fill_holes_2d(pos: Any, cov: Any, grid_resolution: Any = 100) → Any

Fill holes (0 values) surrounded by 1 values in 2D scattered data.

Parameters:

posndarray of shape (n, 3)

Position array where first two columns are x,y coordinates

covndarray of shape (n,)

Coverage values at each point (0 or 1)

grid_resolutionint

Resolution of the grid for interpolation

Returns:

filled_covndarray of shape (n,)

Updated coverage values with holes filled

Module contents

Core utilities for geophysical modeling and inversion.

Names are loaded from their submodules on first use, as the package root does: importing one core module - the 3-D mesh builder a workflow process runs, say - no longer loads SciPy’s signal and image tools, pandas and the kriging stack for the others, which took a second before any work began. The availability flags and the None stand-ins for an optional module that is not installed are as they were.

class PyHydroGeophysX.core.MeshCreator(quality: float = 28, area: float = 40)

Bases: object

Class for creating and managing meshes for geophysical inversion.

create_from_ert_data(data, max_depth: float = 30.0, quality: float = 34)

Create a mesh suitable for ERT inversion from ERT data.

Parameters:

• data – PyGIMLI ERT data object

• max_depth – Positive parameter-domain depth forwarded as paraDepth.

• quality – Mesh quality parameter

Returns:

PyGIMLI mesh for ERT inversion

create_from_layers(surface: ndarray, layers: List[ndarray], bottom_depth: float | None = None, markers: List[int] = None, *, bottom_elevation: float | None = None) → Tuple[pygimli.Mesh, pygimli.Mesh]

Create a mesh from surface and layer boundaries.

Parameters:

• surface – Surface coordinates [[x,z],…]

• layers – Exactly two arrays of layer-boundary coordinates, in the same (x, elevation) coordinate system as surface.

• bottom_depth – Legacy alias for bottom_elevation; retains elevation semantics.

• bottom_elevation – Absolute bottom elevation, default 30.0. Supply only one of bottom_depth and bottom_elevation.

• markers – Three integer region markers, top to bottom (default [2, 3, 2]).

Returns:

Tuple of (PyGIMLi mesh, geometry).

class PyHydroGeophysX.core.ProfileInterpolator(point1: List[int], point2: List[int], surface_data: ndarray, origin_x: float = 0.0, origin_y: float = 0.0, pixel_width: float = 1.0, pixel_height: float = -1.0, num_points: int = 200)

Bases: object

Class for handling interpolation of data to/from profiles.

interpolate_3d_data(data: ndarray) → ndarray

Interpolate 3D data (n_layers, ny, nx) to profile.

Parameters:

data – 3D array of values

Returns:

Array of interpolated values (n_layers, n_profile_points)

interpolate_layer_data(layer_data: List[ndarray]) → ndarray

Interpolate multiple layer data to profile.

Parameters:

layer_data – List of 2D arrays for each layer

Returns:

Array of interpolated values (n_layers, n_profile_points)

interpolate_to_mesh(property_values: ndarray, depth_values: ndarray, mesh_x: ndarray, mesh_y: ndarray, mesh_markers: ndarray, ID: ndarray, layer_markers: list = [3, 0, 2]) → ndarray

Interpolate property values from profile to mesh with layer-specific handling.

Parameters:

• property_values – Property values array (n_layers, n_points), any number of layers

• depth_values – Vertical coordinates, at least one row per property row, in the same datum/units as mesh_y; see the module-level interpolate_to_mesh.

• mesh_x – Coordinates of mesh cells

• mesh_y – Coordinates of mesh cells

• mesh_markers – One layer marker per mesh cell. Cells outside

• output. (layer_markers retain zero in the)

ID: Source layer labels shaped like property_values.

layer_markers: List of marker values for each layer

Returns:

Interpolated values for mesh cells

PyHydroGeophysX.core.add_velocity_interface(ertData: Any, smooth_x: Any, smooth_z: Any, paraBoundary: Any = 2, boundary: Any = 1, paraDepth: Any = 30.0, paraDX: Any = None, paraMaxCellSize: Any = 30) → Any

Add a velocity interface line to the geometry and create a mesh with different markers: - Outside survey area: marker = 1 - Inside survey area, above velocity line: marker = 2 - Inside survey area, below velocity line: marker = 3

Parameters:

• ertData – ERT data with sensor positions

• smooth_x – Arrays with x and z coordinates of the velocity interface

• smooth_z – Arrays with x and z coordinates of the velocity interface

• paraBoundary – Parameter boundary size (default: 2)

• boundary – Boundary marker (default: 1)

• paraDepth – Depth of parameter domain (default: 30.0)

• paraDX – Horizontal mesh refinement (default: None)

• paraMaxCellSize – Maximum cell size in parameter domain (default: 30)

Returns:

Array with cell markers meshafter: The created mesh with updated markers

Return type:

markers

PyHydroGeophysX.core.create_mesh_from_layers(surface: ndarray, line1: ndarray, line2: ndarray, bottom_depth: float | None = None, quality: float = 28, area: float = 40, *, bottom_elevation: float | None = None, markers: List[int] | None = None) → Tuple[pygimli.Mesh, ndarray, ndarray, pygimli.Mesh]

Create mesh from layer boundaries and get cell centers and markers.

Parameters:

• surface – Surface coordinates [[x,z],…]

• line1 – First layer boundary coordinates

• line2 – Second layer boundary coordinates

• bottom_depth – Legacy alias for bottom_elevation. Supply only one of them.

• bottom_elevation – Absolute bottom elevation in the input datum (default 30.0 when neither argument is supplied), below both interfaces.

• markers – Three integer region markers, from top to bottom (default [2, 3, 2]).

• quality – Mesh quality parameter

• area – Maximum cell area

Returns:

(mesh, mesh_centers, markers, geom):

• mesh: PyGIMLI mesh

• mesh_centers: Array of cell center coordinates

• markers: Array of cell markers

• geom: Geometry used to generate the mesh

Return type:

tuple

PyHydroGeophysX.core.create_surface_lines(L_profile: ndarray, structure: ndarray, top_idx: int = 0, mid_idx: int = 4, bot_idx: int = 12) → Tuple[ndarray, ndarray, ndarray]

Create surface and boundary lines from structure data

Parameters:

• L_profile – Distance along profile

• structure – Interpolated structure data

• top_idx – Index for top surface

• mid_idx – Index for middle boundary

• bot_idx – Index for bottom boundary

Returns:

Surface coordinates line1: First boundary coordinates line2: Second boundary coordinates

Return type:

surface

PyHydroGeophysX.core.extract_velocity_interface(mesh: Any, velocity_data: Any, threshold: Any = 1200, interval: Any = 4.0, x_min: Any = None, x_max: Any = None) → Any

Extract the interface where velocity equals the threshold value.

Parameters: mesh - The PyGIMLi mesh velocity_data - The velocity values threshold - The velocity value defining the interface (default: 1200) interval - The binning interval for extracting the interface (default: 4.0) x_min - Optional: minimum x-coordinate for the range (default: None, uses mesh data) x_max - Optional: maximum x-coordinate for the range (default: None, uses mesh data)

Returns: x_dense, z_dense - Arrays with x and z coordinates of the smooth interface

PyHydroGeophysX.core.interpolate_structure_to_profile(structure_data: List[ndarray], X_grid: ndarray, Y_grid: ndarray, X_pro: ndarray, Y_pro: ndarray) → ndarray

Interpolate multiple structure layers onto profile

Parameters:

• structure_data – List of 2D arrays for each layer

• X_grid – X coordinates of original grid

• Y_grid – Y coordinates of original grid

• X_pro – X coordinates of profile points

• Y_pro – Y coordinates of profile points

Returns:

Array of interpolated values with shape (n_layers, n_points)

PyHydroGeophysX.core.interpolate_to_mesh(property_values: ndarray, profile_distance: ndarray, depth_values: ndarray, mesh_x: ndarray, mesh_y: ndarray, mesh_markers: ndarray, ID: Any, layer_markers: list = [3, 0, 2]) → ndarray

Interpolate property values from profile to mesh with layer-specific handling.

Parameters:

• property_values – Array shaped (layers, profile points), any number of layers.

• profile_distance – Distance along profile (n_points)

• depth_values – Vertical coordinates (at least as many rows as property_values, profile points), in the same datum/units as mesh_y. Row i locates property row i, so with the usual layer surfaces (top plus one bottom per layer) each layer is placed at its top; rows beyond property_values’ are not used.

• mesh_x – X coordinates of mesh cells

• mesh_y – Y coordinates of mesh cells

• mesh_markers – One layer marker per mesh cell. Cells outside layer_markers retain zero in the output.

• ID – Source layer labels shaped like property_values.

• layer_markers – List of marker values for each layer

Returns:

Interpolated values for mesh cells

Raises:

ValueError – depth_values has fewer rows, or a different number of profile points, than property_values.

PyHydroGeophysX.core.interpolate_to_profile(data: ndarray, X_grid: ndarray, Y_grid: ndarray, X_pro: ndarray, Y_pro: ndarray, method: str = 'linear') → ndarray

Interpolate 2D data onto a profile line

Parameters:

• data – 2D array of values to interpolate

• X_grid – X coordinates of original grid (meshgrid)

• Y_grid – Y coordinates of original grid (meshgrid)

• X_pro – X coordinates of profile points

• Y_pro – Y coordinates of profile points

• method – Interpolation method (‘linear’ or ‘nearest’)

Returns:

Interpolated values along profile

PyHydroGeophysX.core.prepare_2D_profile_data(data: ndarray, XX: ndarray, YY: ndarray, X_pro: ndarray, Y_pro: ndarray) → ndarray

Interpolate multiple 2D gridded data layers onto a profile line.

Parameters:

• data – 3D array of gridded data (n_layers, ny, nx)

• XX – Coordinate grids from meshgrid

• YY – Coordinate grids from meshgrid

• X_pro – Profile line coordinates

• Y_pro – Profile line coordinates

Returns:

Interpolated values along profile (n_layers, n_profile_points)

PyHydroGeophysX.core.setup_profile_coordinates(point1: List[int], point2: List[int], surface_data: ndarray, origin_x: float = 0.0, origin_y: float = 0.0, pixel_width: float = 1.0, pixel_height: float = -1.0, num_points: int = 200) → Tuple[ndarray, ndarray, ndarray, ndarray, ndarray]

Set up profile coordinates based on surface elevation data between two points

The profile starts at point2 (distance zero) and runs toward point1, stopping one step short of it: num_points - 1 samples, spaced distance / (num_points - 1) apart. The examples, and the data bundled with them (TL_measurements, Seismic), were built on this layout, and create_mesh_from_layers places each layer’s region marker from the first node of the profile, so a profile run the other way puts the regolith and bedrock markers in each other’s layers.

Parameters:

• point1 – End point indices [col, row]; the profile stops one step before it

• point2 – Start point indices [col, row]; distance zero

• surface_data – 2D array of surface elevation data

• origin_x – X coordinate of origin

• origin_y – Y coordinate of origin

• pixel_width – Width of each pixel

• pixel_height – Height of each pixel (negative for top-down)

• num_points – Size of the spacing along the profile (an integer >= 2); the profile holds num_points - 1 of its points

Returns:

X coordinates along profile Y_pro: Y coordinates along profile L_profile: Distances along profile XX: X coordinate grid YY: Y coordinate grid

Return type:

X_pro

Raises:

ValueError – num_points is not an integer >= 2, or the endpoints are the same location.