Installation#

PyHydroGeophysX requires Python 3.10 or higher.

Installation video#

Follow the manual installation walkthrough, using the commands below for the current package. For guided setup, see Install with an AI agent.

Watch on YouTube.

Install from PyPI#

pip install pyhydrogeophysx

What the pip package includes#

The pip package contains the library and the Qt desktop studio (see Desktop App (Qt Studio)). The example scripts and notebooks, their data in examples/data, and the Streamlit web apps in examples/ come with the source repository, not the pip package. To run them, clone the repository as shown in Install from Source, or use the hosted web app at https://pyhydrogeophysx.streamlit.app/. The launchers pyhydrogeophysx-gui and python -m PyHydroGeophysX.gui_mesh3d take an app’s path as their first argument; after a pip install they print where the apps are.

ADERT speed comparison#

Watch the speed comparison, then see the ADTLERT backend setup below. Runtime depends on the hardware, dataset and solver settings. Yang et al. (2026) measured the CUDA engine against pyGIMLi and report an approximately 51-fold speedup under their tested configuration, with forward responses, gradients and recovered resistivity models in close agreement. The engine is aimed at larger lines and time-lapse windows.

Watch on YouTube.

Install the optional ADTLERT ERT backend#

ADTLERT provides a differentiable ERT engine for the existing run_ert_manager_inversion pipeline: 2.5D on a profile mesh, 3D on a tetrahedral mesh passed as mesh_file (Gmsh, E4D or pyGIMLi). It requires Python 3.11 or newer and is intentionally separate from the general geophysics extra because it also installs PyTorch.

pip install "pyhydrogeophysx[adtlert]"

Select it explicitly; the default ERT engine remains unchanged.

from PyHydroGeophysX.inversion.ert_inversion import run_ert_manager_inversion

result = run_ert_manager_inversion(
    "survey.dat",
    "output",
    engine="adtlert",
)

The extra installs ADTLERT with cuDSS and NVRTC (CUDA 12 wheels for Linux and Windows); its sensitivity kernel is compiled by NVRTC, so no compiler toolchain is needed. Both platforms use CUDA-enabled Torch, Torch GPU CGLS and the cuDSS GPU forward solver. Linux remains the recommended, most thoroughly tested platform. When Torch, cuDSS or NVRTC is unavailable, the Python API can fall back to the original PyHydro ERT engine. Studio requires a passing GPU check before starting a GPU mode and offers manual selection of PyHydro CPU on failure. Remote electrodes (negative ABMN indices: pole-dipole, pole-pole) run on ADTLERT on flat and topographic 2D profiles and 3D meshes. Measurements with either receiver polarity (positive or negative geometric factor) are used as recorded.

On Windows, install the CUDA-enabled Torch wheel before the extra, for example:

python -m pip install torch --index-url https://download.pytorch.org/whl/cu128
python -m pip install "pyhydrogeophysx[adtlert]"

For long monitoring sequences, select ADTLERT together with windowed time-lapse inversion. The backend reuses one forward operator and Jacobian cache across overlapping windows. Every timestep must have the same electrode positions and ABMN ordering; process-level window parallelism is disabled for ADTLERT to avoid duplicating GPU memory. The default cgls method selects Torch GPU CGLS on the CUDA-backed ADTLERT path.

from PyHydroGeophysX.inversion.time_lapse import run_timelapse_ert

result = run_timelapse_ert(
    ["survey_0.dat", "survey_1.dat", "survey_2.dat"],
    [0.0, 1.0, 2.0],
    {"engine": "adtlert", "windowed": True, "window_size": 3},
    "output",
)

Measurements are aligned by their ABMN union; missing rows receive 100% relative error and an apparent-resistivity placeholder from the available timesteps. This reduces their weight; it does not exclude them from fitting. Native PyHydro time-lapse keeps each survey’s own measurement count and ordering.

Install from Source#

git clone https://github.com/geohang/PyHydroGeophysX.git
cd PyHydroGeophysX
pip install -e .

The checkout also holds the examples, their data and the Streamlit apps.

Core Dependencies#

pip install numpy scipy matplotlib tqdm

Optional Dependencies#

  • PyGIMLi for ERT/SRT forward and inversion

  • ADTLERT for differentiable 2.5D and 3D ERT inversion

  • SimPEG for TDEM/FDEM workflows

  • RESIPY for field ERT data processing

  • CuPy for GPU acceleration

  • joblib for parallel CPU workflows

pip install pygimli simpeg resipy joblib
pip install "cupy-cuda12x[ctk]"

TetGen builds the 3-D meshes from E4D mesh configurations. It is AGPL-licensed, so it is not installed with the package; without it, Gmsh stands in:

pip install tetgen

E4D, R2 and R3t are external inversion programs, not Python packages; see E4D and R2 and R3t for where they run and how PyHydroGeophysX reaches them.

Desktop App (Qt Studio)#

Prebuilt Windows and macOS bundles are published on GitHub Releases and need no Python environment. To run the studio from a Python install instead:

pip install "pyhydrogeophysx[desktop]"
pyhydrogeophysx-studio

See Desktop Studio (Qt) for the full usage guide.

Verification#

import PyHydroGeophysX as phg
print("PyHydroGeophysX version:", phg.__version__)

Verify GPU time-lapse compatibility#

Use the same Python interpreter as Studio:

python -m PyHydroGeophysX.inversion.adtlert_diagnostics --report gpu-check.json

The command checks CUDA runtime availability, a single-survey GPU inversion, and a two-iteration windowed GPU inversion in separate processes. The normal line-search configuration remains enabled. Each stage has a 120-second timeout; use --timeout to change it. Exit code 0 means all three passed. Inspect the JSON report for individual results, commands, complete logs, exit codes, package versions and interpreter/source paths. A small synthetic test does not establish convergence for every field survey.

Studio runs these checks when ADTLERT is selected and displays single-survey and time-lapse availability separately. A GPU mode waits for its own successful check; switch to PyHydro for CPU operation or reselect ADTLERT to rerun checks. Neither GPU detection nor the Studio UI self-test proves time-lapse compatibility.

Conflicting OpenMP runtimes on Windows#

Dependencies may initialize both libomp.dll and libiomp5md.dll. This is a software-runtime issue, not specific to Intel CPUs. Keep the diagnostic report and verify the CPU path separately if the GPU time-lapse check fails. Do not set KMP_DUPLICATE_LIB_OK, remove DLLs, or disable line search to turn a failing installation check into a pass. A process-isolation or numerical compatibility patch requires its own review and validation.

After all required checks pass, save python -m pip freeze and, when using Conda, conda env export. Record the GPU/driver and package source commit as well. Recheck after dependency changes. The repository’s environment.yml is a starting configuration, not a universal validated GPU lockfile.

For editable installs, the source checkout and environment’s launcher normally live in different directories. Verify the actual imported checkout before updating; do not create another checkout merely because these paths differ:

python -c "import sys, PyHydroGeophysX; print(sys.executable); print(PyHydroGeophysX.__file__)"