PyHydroGeophysX.Geophy_modular package#

Submodules#

PyHydroGeophysX.Geophy_modular.ERT_to_WC module#

Geophysics -> hydrology inverse pipeline for the desktop studio.

This is the inverse counterpart to hydro_pipeline.py. It takes an already-inverted (time-lapse) ERT resistivity model on a mesh and converts it to volumetric water content (and, optionally, saturated-zone porosity) with Monte Carlo uncertainty. It is a thin, parameterized re-use of examples/Ex_MC_Hydro.py and the petrophysics in PyHydroGeophysX.petrophysics.resistivity_models. It is deliberately Qt-free so it can run inside a worker thread (or be unit-tested) without a QApplication.

Two layers:

  • extract_model_summary / build_petro_config / extract_point_series – numpy only. These work even when pygimli is not installed, so loading the inverted model bundle, inspecting its layers, exporting the petrophysics configuration, and reading monitoring-point time series never depend on the heavy backend.

  • run_ert_to_wc – the real Monte Carlo run. It imports pygimli lazily to load the mesh and render the section figures; if anything is missing or fails it raises BackendUnavailable so the caller can fall back to config export.

The petrophysical conversion itself (resistivity_to_saturation / resistivity_to_porosity) is pure numpy/scipy and is reused directly from the library rather than re-implemented here.

PyHydroGeophysX.Geophy_modular.ERT_to_WC.DEFAULT_LAYER_DISTRIBUTIONS: Dict[int, Dict[str, Any]] = {2: {'m': {'mean': 1.9, 'std': 0.2}, 'n': {'mean': 1.7, 'std': 0.2}, 'name': 'Bedrock', 'porosity': {'mean': 0.25, 'std': 0.15}, 'rho_fluid': {'mean': 20.0, 'std': 0.0}, 'sigma_sur': {'mean': 0.0, 'std': 0.0}}, 3: {'m': {'mean': 1.3, 'std': 0.1}, 'n': {'mean': 2.1, 'std': 0.1}, 'name': 'Regolith', 'porosity': {'mean': 0.42, 'std': 0.05}, 'rho_fluid': {'mean': 20.0, 'std': 0.0}, 'sigma_sur': {'mean': 0.005, 'std': 0.005}}}#

Fallback per-layer petrophysics distributions, matching the two layers of the bundled Treeline demo in Ex_MC_Hydro.py (marker 3 = regolith, 2 = bedrock).

PyHydroGeophysX.Geophy_modular.ERT_to_WC.MODEL_FILES = {'coverage': 'all_coverage.npy', 'markers': 'index_marker.npy', 'mesh': 'mesh_res.bms', 'resistivity': 'resmodel.npy'}#

The four files of an inverted-model bundle. markers and coverage are optional; everything else is required for a real run.

PyHydroGeophysX.Geophy_modular.ERT_to_WC.build_petro_config(context: Dict[str, Any], params: Dict[str, Any]) → Dict[str, Any][source]#

Build a complete, JSON-serializable petrophysics inversion configuration.

PyHydroGeophysX.Geophy_modular.ERT_to_WC.derive_markers_from_interface(context: ~typing.Dict[str, ~typing.Any], params: ~typing.Dict[str, ~typing.Any], interface_xz: ~typing.Any, top_marker: int = 3, bot_marker: int = 2, log: ~typing.Callable[[str], None] = <function noop>) → Dict[str, Any][source]#

Classify the model mesh into layers using a (seismic) bedrock interface.

Cells whose center elevation is at or above the interface get top_marker (e.g. regolith); cells below get bot_marker (e.g. bedrock). The result is written as index_marker.npy in the model directory so the rest of the Geophysics -> Hydro workflow can use it. Requires pygimli to load the mesh.

PyHydroGeophysX.Geophy_modular.ERT_to_WC.extract_model_summary(context: ~typing.Dict[str, ~typing.Any], params: ~typing.Dict[str, ~typing.Any], log: ~typing.Callable[[str], None] = <function noop>) → Dict[str, Any][source]#

Inspect the inverted-model bundle without loading the mesh.

Returns shapes, the unique layer markers with per-marker cell counts, and a few resistivity statistics. Powers the Data and Layers steps with no pygimli dependency (the inverse analog of hydro_pipeline.extract_profile).

PyHydroGeophysX.Geophy_modular.ERT_to_WC.extract_point_series(cell_centers: ndarray, values: ndarray, positions: Sequence[Sequence[float]]) → Tuple[ndarray, List[int]][source]#

Nearest-cell time series at monitoring (x, y) positions.

Parameters:

  • cell_centers – (n_cells, >=2) mesh cell-center coordinates.

  • values – (n_cells, n_time) per-cell field (e.g. mean water content).

  • positions – list of (x, y) tuples.

Returns:

(series, cell_indices) where series is (n_positions, n_time).

PyHydroGeophysX.Geophy_modular.ERT_to_WC.find_model_files(data_dir: Path) → Dict[str, Path | None][source]#

Return the resolved path for each expected bundle file (or None).

PyHydroGeophysX.Geophy_modular.ERT_to_WC.run_ert_to_wc(context: ~typing.Dict[str, ~typing.Any], params: ~typing.Dict[str, ~typing.Any], log: ~typing.Callable[[str], None] = <function noop>) → Dict[str, Any][source]#

Run the real ERT -> water content / porosity Monte Carlo inversion.

Raises BackendUnavailable if pygimli cannot be imported (needed to load the .bms mesh and render the section figures), and propagates any other exception so the caller can fall back to config export.

PyHydroGeophysX.Geophy_modular.ert_to_wc_model module#

Module for converting Electrical Resistivity Tomography (ERT) resistivity models to volumetric water content, incorporating structural information (geological layers) and quantifying uncertainty using Monte Carlo simulations.

This module provides the ERTtoWC class, which takes ERT resistivity data, a corresponding mesh, cell markers identifying different layers, and optional coverage information. It allows users to define petrophysical parameter distributions (saturated resistivity rhos, saturation exponent n, surface conductivity sigma_sur, and porosity φ) for each layer. The core functionality involves running Monte Carlo simulations to sample these parameters and convert resistivity to water content for each realization, thereby providing a distribution of possible water content values. Statistics (mean, std, percentiles) can then be calculated from these distributions. The module also includes utilities for plotting results and extracting time series.

class PyHydroGeophysX.Geophy_modular.ert_to_wc_model.ERTtoWC(mesh: pg.Mesh, resistivity_values: np.ndarray, cell_markers: np.ndarray, coverage: np.ndarray | None = None)[source]#

Bases: object

Class for converting ERT resistivity models to water content.

extract_time_series(positions: List[Tuple[float, float]]) → Tuple[ndarray, List[int]][source]#

Extract time series at specific positions.

get_statistics() → Dict[str, ndarray][source]#

Calculate statistics across Monte Carlo realizations.

plot_water_content(time_idx: int = 0, ax=None, cmap: str = 'jet', cmin: float = 0.0, cmax: float = 0.32, coverage_threshold: float | None = None)[source]#

Plot water content for a specific time step.

run_monte_carlo(n_realizations: int = 100, progress_bar: bool = True, seed: int = 7) → Tuple[source]#

Run Monte Carlo simulation for uncertainty quantification.

Parameters:

  • n_realizations – Number of Monte Carlo realizations

  • progress_bar – Whether to show progress bar

Returns:

Tuple of (water_content_all, saturation_all, params_used)

save_results(output_dir: str, base_filename: str) → None[source]#

Save Monte Carlo results to files.

setup_layer_distributions(layer_distributions: Dict[int, Dict[str, Dict[str, float]]]) → None[source]#

Set up parameter distributions for different layers.

Parameters:

layer_distributions – Dictionary mapping layer markers to parameter distributions

PyHydroGeophysX.Geophy_modular.ert_to_wc_model.plot_time_series(time_steps: ndarray, time_series_data: ndarray, true_values: ndarray | None = None, labels: List[str] | None = None, colors: List[str] | None = None, output_file: str | None = None) → Any[source]#

Plot time series with uncertainty bands.

PyHydroGeophysX.Geophy_modular.seismic_processor module#

Seismic data processing module for structure identification.

PyHydroGeophysX.Geophy_modular.seismic_processor.extract_velocity_structure(mesh: Any, velocity_data: Any, threshold: Any = 1200, interval: Any = 4.0) → Any[source]#

Extract structure interface from velocity model at the specified threshold.

Parameters:

  • mesh – PyGIMLi mesh

  • velocity_data – Velocity values for each cell

  • threshold – Velocity threshold defining interface (default: 1200)

  • interval – Horizontal sampling interval (default: 4.0)

Returns:

Horizontal coordinates of interface points z_coords: Vertical coordinates of interface points interface_data: Dictionary with interface information

Return type:

x_coords

PyHydroGeophysX.Geophy_modular.seismic_processor.process_seismic_tomography(ttData: Any, mesh: Any = None, **kwargs: Any) → Any[source]#

Process seismic tomography data and perform inversion.

Parameters:

  • ttData – Travel time data container

  • mesh – Mesh for inversion (optional, created if None)

  • **kwargs – Additional parameters including: - lam: Regularization parameter (default: 50) - zWeight: Vertical regularization weight (default: 0.2) - vTop: Top velocity constraint (default: 500) - vBottom: Bottom velocity constraint (default: 5000) - quality: Mesh quality if creating new mesh (default: 31) - paraDepth: Maximum depth for parametric domain (default: 30) - verbose: Verbosity level (default: 1)

Returns:

TravelTimeManager object with inversion results

PyHydroGeophysX.Geophy_modular.seismic_processor.save_velocity_structure(filename: Any, x_coords: Any, z_coords: Any, interface_data: Any = None) → None[source]#

Save velocity structure data to file.

Parameters:

  • filename – Output filename

  • x_coords – X coordinates of interface

  • z_coords – Z coordinates of interface

  • interface_data – Additional data to save (optional)

PyHydroGeophysX.Geophy_modular.seismic_processor.seismic_velocity_classifier(velocity_data: Any, mesh: Any, threshold: Any = 1200) → Any[source]#

Classify mesh cells based on velocity threshold.

Parameters:

  • velocity_data – Velocity values for each cell

  • mesh – PyGIMLi mesh

  • threshold – Velocity threshold for classification (default: 1200)

Returns:

below threshold, 2: above threshold)

Return type:

Array of cell markers (1

PyHydroGeophysX.Geophy_modular.structure_integration module#

Seismic -> 3D subsurface model pipeline for the desktop studio.

Takes one or more 2D seismic velocity sections (each an inverted velocity model on a pyGIMLi mesh, positioned in map coordinates) and builds a 3D subsurface model: a kriged/interpolated velocity volume and a bedrock-interface surface across the survey area. It is a thin, parameterized re-use of PyHydroGeophysX.Geophy_modular.seismic_processor.extract_velocity_structure (2D velocity -> interface) and PyHydroGeophysX.core.kriging_3d (3D structured grid + optional ordinary kriging). It is deliberately Qt-free so it can run inside a worker thread (or be unit-tested) without a QApplication.

Two layers:

  • build_seismic3d_config – numpy only. Serializes the line list + grid settings so a configuration can be exported without any heavy backend.

  • build_3d_model – the real run. It imports pygimli lazily to load the section meshes. PyVista is optional and adds VTK export plus a rendered 3D preview; the NumPy arrays and Matplotlib results are still built without it. 3D velocity interpolation uses scipy griddata by default and gstools ordinary kriging when that package is installed and requested.

PyHydroGeophysX.Geophy_modular.structure_integration.DEFAULT_KRIGING = {'len_scale_x': 100.0, 'len_scale_y': 100.0, 'len_scale_z': 10.0, 'model': 'Exponential', 'nugget': 0.0, 'var': 0.5}#

horizontal range 100 m, vertical 10 m.

Type:

Default 3D variogram (anisotropic)

PyHydroGeophysX.Geophy_modular.structure_integration.VARIOGRAM_MODELS = ('Exponential', 'Gaussian', 'Spherical', 'Matern')#

Supported gstools variogram models (name -> gstools class attribute name).

PyHydroGeophysX.Geophy_modular.structure_integration.VELOCITY_FILES = {'mesh': 'velmesh.bms', 'velocity': 'Vinvmodel.npy'}#

a folder with these two files.

Type:

Per-line velocity-model bundle

PyHydroGeophysX.Geophy_modular.structure_integration.build_3d_model(context: ~typing.Dict[str, ~typing.Any], params: ~typing.Dict[str, ~typing.Any], log: ~typing.Callable[[str], None] = <function noop>) → Dict[str, Any][source]#

Build the 3D subsurface model from the configured seismic lines.

Raises BackendUnavailable if pygimli or Matplotlib cannot be imported, and propagates other exceptions so the caller can fall back to config export.

PyHydroGeophysX.Geophy_modular.structure_integration.build_seismic3d_config(context: Dict[str, Any], params: Dict[str, Any]) → Dict[str, Any][source]#

Build a complete, JSON-serializable 3D-model configuration.

PyHydroGeophysX.Geophy_modular.structure_integration.extract_line_structure(line: ~typing.Dict[str, ~typing.Any], threshold: float, interval: float, log: ~typing.Callable[[str], None] = <function noop>) → Dict[str, Any][source]#

Load one velocity section and extract its surface, interface and velocity points.

Returns dict with surface_pts (n,3), interface_pts (m,3), vel_pts (k,4) [x,y,z,vel] mapped into map coordinates, and the raw 2D interface.

PyHydroGeophysX.Geophy_modular.structure_integration.find_velocity_files(data_dir: Path) → Dict[str, Path | None][source]#

Return the resolved path for each expected velocity-bundle file (or None).

PyHydroGeophysX.Geophy_modular.structure_integration.summarize_line(line: Dict[str, Any]) → Dict[str, Any][source]#

Light per-line summary (cell count, velocity range, x-extent). Needs pygimli.

Module contents#

Cross-modal geophysics-to-hydrology and structure integration APIs.

class PyHydroGeophysX.Geophy_modular.ERTtoWC(mesh: pg.Mesh, resistivity_values: np.ndarray, cell_markers: np.ndarray, coverage: np.ndarray | None = None)[source]#

Bases: object

Class for converting ERT resistivity models to water content.

extract_time_series(positions: List[Tuple[float, float]]) → Tuple[ndarray, List[int]][source]#

Extract time series at specific positions.

get_statistics() → Dict[str, ndarray][source]#

Calculate statistics across Monte Carlo realizations.

plot_water_content(time_idx: int = 0, ax=None, cmap: str = 'jet', cmin: float = 0.0, cmax: float = 0.32, coverage_threshold: float | None = None)[source]#

Plot water content for a specific time step.

run_monte_carlo(n_realizations: int = 100, progress_bar: bool = True, seed: int = 7) → Tuple[source]#

Run Monte Carlo simulation for uncertainty quantification.

Parameters:

  • n_realizations – Number of Monte Carlo realizations

  • progress_bar – Whether to show progress bar

Returns:

Tuple of (water_content_all, saturation_all, params_used)

save_results(output_dir: str, base_filename: str) → None[source]#

Save Monte Carlo results to files.

setup_layer_distributions(layer_distributions: Dict[int, Dict[str, Dict[str, float]]]) → None[source]#

Set up parameter distributions for different layers.

Parameters:

layer_distributions – Dictionary mapping layer markers to parameter distributions

PyHydroGeophysX.Geophy_modular.extract_velocity_structure(mesh: Any, velocity_data: Any, threshold: Any = 1200, interval: Any = 4.0) → Any[source]#

Extract structure interface from velocity model at the specified threshold.

Parameters:

  • mesh – PyGIMLi mesh

  • velocity_data – Velocity values for each cell

  • threshold – Velocity threshold defining interface (default: 1200)

  • interval – Horizontal sampling interval (default: 4.0)

Returns:

Horizontal coordinates of interface points z_coords: Vertical coordinates of interface points interface_data: Dictionary with interface information

Return type:

x_coords

PyHydroGeophysX.Geophy_modular.plot_time_series(time_steps: ndarray, time_series_data: ndarray, true_values: ndarray | None = None, labels: List[str] | None = None, colors: List[str] | None = None, output_file: str | None = None) → Any[source]#

Plot time series with uncertainty bands.

PyHydroGeophysX.Geophy_modular.process_seismic_tomography(ttData: Any, mesh: Any = None, **kwargs: Any) → Any[source]#

Process seismic tomography data and perform inversion.

Parameters:

  • ttData – Travel time data container

  • mesh – Mesh for inversion (optional, created if None)

  • **kwargs – Additional parameters including: - lam: Regularization parameter (default: 50) - zWeight: Vertical regularization weight (default: 0.2) - vTop: Top velocity constraint (default: 500) - vBottom: Bottom velocity constraint (default: 5000) - quality: Mesh quality if creating new mesh (default: 31) - paraDepth: Maximum depth for parametric domain (default: 30) - verbose: Verbosity level (default: 1)

Returns:

TravelTimeManager object with inversion results

PyHydroGeophysX.Geophy_modular.run_ert_to_wc(context: ~typing.Dict[str, ~typing.Any], params: ~typing.Dict[str, ~typing.Any], log: ~typing.Callable[[str], None] = <function noop>) → Dict[str, Any][source]#

Run the real ERT -> water content / porosity Monte Carlo inversion.

Raises BackendUnavailable if pygimli cannot be imported (needed to load the .bms mesh and render the section figures), and propagates any other exception so the caller can fall back to config export.

PyHydroGeophysX.Geophy_modular.seismic_velocity_classifier(velocity_data: Any, mesh: Any, threshold: Any = 1200) → Any[source]#

Classify mesh cells based on velocity threshold.

Parameters:

  • velocity_data – Velocity values for each cell

  • mesh – PyGIMLi mesh

  • threshold – Velocity threshold for classification (default: 1200)

Returns:

below threshold, 2: above threshold)

Return type:

Array of cell markers (1