Installation#

PyHydroGeophysX requires Python 3.8 or higher.

Install from PyPI#

pip install pyhydrogeophysx

Install the optional ADTLERT ERT backend#

ADTLERT provides a differentiable 2.5D ERT engine for the existing run_ert_manager_inversion pipeline. 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 CuPy CUDA 12 and cuDSS on both Linux and Windows. Both platforms use CUDA-enabled Torch, CuPy GPU CGLS and the cuDSS GPU forward solver. The slower SciPy forward solver is intentionally disabled so ADTLERT is never reported while running an unaccelerated forward path. Linux remains the recommended, most thoroughly tested and generally fastest platform. When Torch, CuPy CUDA 12 or cuDSS is unavailable, selecting ADTLERT automatically uses the original PyHydro ERT engine instead. ADTLERT 0.1 also cannot represent remote electrodes encoded as negative ABMN indices; those surveys safely use the original engine without changing data.

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 CuPy CGLS on the CUDA-backed ADTLERT path.

The adtlert and gpu extras share cupy-cuda12x. Do not install a second CuPy package such as cupy-cuda11x in the same environment.

Install from Source#

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

Core Dependencies#

pip install numpy scipy matplotlib tqdm

Optional Dependencies#

  • PyGIMLi for ERT/SRT forward and inversion

  • ADTLERT for differentiable 2.5D 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]"

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__)