Documentation Status

gprMax

Getting Started

What is gprMax?

gprMax is open-source computational electromagnetics software that solves Maxwell’s equations using the finite-difference time-domain (FDTD) method. It supports two- and three-dimensional models through both a Python API and a text-based input-file interface.

The software originated in research on the forward problem of ground-penetrating radar in the 1990s. Antonis Giannopoulos created the original gprMax code and established its numerical foundations; this work is documented in his 1997 D.Phil. thesis. Ground Penetrating Radar (GPR) remains an important application and gives gprMax its name.

Craig Warren led the creation of the open-source Python and Cython codebase that became gprMax version 3, building on his doctoral research. Iraklis Giannakis contributed major original developments in dispersive-material modelling, fractal media and realistic GPR models through his doctoral research on realistic GPR modelling. Together with Antonis Giannopoulos, they described this generation in the 2016 Computer Physics Communications paper.

The subgridding lineage of gprMax includes the early ADI-FDTD research of Nectaria Diamanti. This work influenced the subsequent doctoral research of John Hartley, through which version 4 was initiated and the current FDTD subgridding and dispersive-interface averaging capabilities were developed. Nathan Mannall subsequently carried out a major architectural refactoring and developed the MPI domain-decomposition solver. Qifeng Shen developed the FDFD eigenmode solver, wave-port and impedance-boundary capabilities, and has led the expansion of antenna and RF modelling. Accelerator backends, testing infrastructure, geometry importers, toolboxes, antenna models and documentation also reflect substantial work by the wider gprMax community and Google Summer of Code contributors. The full authors and contributors record describes these contributions in more detail.

After nearly three decades of development, the current version 4 codebase extends substantially beyond the capabilities described in the 2016 paper. Although GPR remains a core application, gprMax is now a general-purpose research platform for time-domain computational electromagnetics. Applications also include antenna and microwave modelling, electromagnetic scattering and radar cross section, bioelectromagnetics and dosimetry, and radiometry. A range of established and recent methods from the published literature complement gprMax’s original formulations and existing core functionality. Some of the key features include:

  • geometrical modelling with dielectric smoothing, semantic object tags, imported voxel geometries, fractal media and locally refined subgrids;

  • conductive, anisotropic, magnetic and multipole dispersive materials, with reusable material databases and dispersive interface averaging;

  • dipole, voltage, transmission-line, magnetic-frill, plane-wave, rational network and FDFD eigenmode-port excitation;

  • port quantities and multi-case studies, S-parameters, impedance, antenna gain and directivity, radar cross section, near- and far-field transforms, SAR and radiometric absorbed-power outputs; and

  • shared-memory CPU execution, NVIDIA CUDA, OpenCL, Apple Metal and MPI domain decomposition, with common model-building and output interfaces.

gprMax is currently released under the GNU General Public License v3 or higher.

gprMax is principally written in Python 3 with performance-critical parts written in Cython. It includes accelerators for CPU using OpenMP, CPU/GPU using OpenCL, GPU using NVIDIA CUDA, and GPU using Apple Metal on macOS with M-series chips. Additionally, MPI support (using mpi4py) enables larger scale (multi-node) simulations. There is more information about the different acceleration approaches in the performance section of the documentation.

Using gprMax? Cite us

If you use gprMax and publish your work we would be grateful if you could cite our work using:

  • Warren, C., Giannopoulos, A., & Giannakis I. (2016). gprMax: Open source software to simulate electromagnetic wave propagation for Ground Penetrating Radar, Computer Physics Communications (http://dx.doi.org/10.1016/j.cpc.2016.08.020)

For further information on referencing gprMax visit the Publications section of our website.

Repository overview

gprMax/
    .github/
    docs/
    examples/
    gprMax/
        toolboxes/
    images_shared/
    packaging/
    reframe_tests/
    testing/
    tests/
    CITATION.cff
    CODE_OF_CONDUCT.md
    conda_env.yml
    CONTRIBUTING.md
    AUTHORS.rst
    LICENSE
    MANIFEST.in
    pyproject.toml
    README.rst
    requirements.txt
    build_config.py
    packaging_config.py
    setup.py

  • .github/ contains the continuous-integration workflows that test the supported operating systems, build binary wheels and source distributions, and run the automated test suites.

  • docs/ contains the source for the HTML and PDF versions of the User Guide. It uses reStructuredText and Sphinx, and is published by Read the Docs.

  • examples/ contains user-facing input files and Python API models grouped by application. These examples are also distributed as package resources so they remain available to users who install a binary wheel.

  • gprMax/ is the main Python package. It contains model construction, material and source definitions, CPU and accelerator solvers, MPI domain decomposition, subgridding, FDFD eigenmode ports, near-to-far-field transforms, antenna and port processing, SAR and radiometry outputs, and the compiled Cython kernels used by performance-critical operations.

  • images_shared/ stores figures shared by the README and User Guide.

  • packaging/ contains platform-specific helpers used to produce portable binary distributions, including the macOS OpenMP build support.

  • reframe_tests/ contains whole-model and HPC regression tests built with ReFrame. The supplied machine configuration and numerical references currently target ARCHER2; other systems can provide their own configuration and reference data.

  • testing/ is the manually run scientific evidence archive. It separates analytical validation, comparisons with other numerical codes, backend consistency studies, larger regression campaigns, experimental work, and performance benchmarks.

  • tests/ is the automated pytest suite, containing focused unit tests, compact integration tests, platform tests and tests that require real accelerator hardware.

  • gprMax/toolboxes/ contains user-facing processing, conversion, visualisation, antenna-model and waveform-modelling tools. Toolboxes and their compact examples are included in source and binary distributions.

  • CITATION.cff is a plain text file with human- and machine-readable citation information for gprMax.

  • conda_env.yml defines the recommended Conda development environment. MPI runtimes and accelerator bindings remain optional and are installed for the hardware and workflow being used.

  • CONTRIBUTING.md is a guide to contributing to gprMax.

  • AUTHORS.rst records the people and organisations that have created, developed, contributed to, and supported gprMax.

  • LICENSE contains information on the GNU General Public License v3 or higher.

  • MANIFEST.in consists of commands, one per line, instructing setuptools to add or remove files from the source distribution.

  • pyproject.toml contains build-system requirements and configuration for pytest, source formatting, and cross-platform binary-wheel builds.

  • README.rst contains getting started information on installation, usage, and new features/changes.

  • requirements.txt lists the common source-development and test dependencies that can be installed with pip. Optional MPI and accelerator dependencies are selected through package extras.

  • build_config.py provides the portable compiler and OpenMP configuration used for local source builds and binary wheels.

  • packaging_config.py defines which packages, examples, toolboxes and data files are included in installed distributions.

  • setup.py defines the setuptools package metadata and Cython extension modules, using the shared build and packaging configuration above.

Installation

PyPI installation (recommended for running models)

For ordinary modelling and use of the toolboxes, install a released package from the Python Package Index (PyPI). You do not need a source checkout or the development environment. With a supported Python selected, the installation command is:

$ python -m pip install gprMax

These PyPI commands apply after the v4 release is published. To install an unpublished development version, use Installing from source instead.

Python 3.11–3.13 is supported, with Python 3.12 recommended. Release wheels target 64-bit Linux x86-64, Windows x86-64, and Intel and Apple Silicon macOS. A matching binary wheel contains the compiled CPU extensions: you do not need a C compiler, OpenMP development headers, Git or Conda to install it. pip installs the declared Python dependencies as well. If no compatible wheel is available, pip may attempt a source build, which needs the build tools described under Installing from source. An optional accelerator binding can also require its own compiler or runtime even when gprMax uses a wheel.

A virtual environment is recommended but not required. Choose one of the two routes below. Use a new environment if you want to retain a v3 installation.

Which Python does pip use?

Install a supported Python with pip first, for example using the Python downloads or your platform’s Python provider. Installing gprMax with pip does not install Python itself.

python -m pip installs into the Python selected by python; it does not install gprMax into every Python on the computer. A terminal with an activated Conda environment uses that environment’s Python, even though the installer is pip. python may be called python3 or python3.12 on your system; on Windows, py -3.12 can select an installed Python 3.12. Use the same interpreter for installation and execution.

If you are unsure which interpreter is selected, check it before installing:

$ python -c "import sys; print(sys.executable); print(sys.version)"
$ python -m pip --version

These are setup/troubleshooting checks, not commands required before each simulation. See the pip user guide for how interpreter selection works.

Option A: use a virtual environment

A venv keeps gprMax and its dependencies separate from other Python projects. With a separately installed Python 3.12, create a new working folder and environment. Do not create it inside your old v3 checkout.

Linux/macOS (bash or zsh):

$ mkdir gprmax-work
$ cd gprmax-work
$ python3.12 -m venv .venv
$ source .venv/bin/activate
$ python -m pip install gprMax
$ python -m gprMax --help

Windows (PowerShell):

mkdir gprmax-work
cd gprmax-work
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install gprMax
python -m gprMax --help

In a later terminal, return to gprmax-work and activate the existing environment again; do not recreate or reinstall it for each simulation. Alternatively, activation is optional if you call its Python explicitly:

$ .venv/bin/python -m gprMax model.in

On Windows, the equivalent is .\.venv\Scripts\python.exe -m gprMax model.in. This also avoids changing PowerShell execution policy if activation scripts are blocked. Use deactivate when finished with an activated venv. See the Python venv documentation for other shells. If Conda is already active and you want a non-Conda setup, deactivate it and select your separately installed Python explicitly.

Option B: install without a virtual environment

On a user-managed Python installation that permits pip package installation, you can install and run directly, with no activation step:

$ python -m pip install gprMax
$ python -m gprMax model.in

Here model.in is your input file. This route shares dependencies with other packages in that Python installation. Updates may affect those projects, and v3 and v4 are not independently selectable installations in the same environment. If that Python already contains v3, use a separate environment to preserve it rather than installing over it.

If pip reports externally-managed-environment, the OS or another package manager owns that Python. Use Option A or a separate user-managed Python. Do not use sudo pip or --break-system-packages as a routine workaround: overriding those safeguards can interfere with software managed by the OS. --user is not an isolation mechanism and may also be blocked. See the externally managed environments guidance.

If installation fails because the destination is not writable, create a venv in a writable directory rather than elevating permissions.

Working directories and installed files

Run models and plotting commands from your own working directory. Neither a wheel installation nor its toolboxes require you to enter site-packages. Keep inputs, scripts and outputs outside the installed package so that an upgrade does not overwrite your work. See Running gprMax for a complete example and Using the installed toolboxes for toolbox commands and assets.

There is no single installation path: it depends on the selected Python. For the Linux/macOS environment above it is normally gprmax-work/.venv/lib/python3.12/site-packages/gprMax/; on Windows it is gprmax-work\.venv\Lib\site-packages\gprMax\. Locate the actual installation with:

$ python -c "import gprMax; print(gprMax.__file__)"

Do not run v4 from a directory containing an old v3 gprMax package, or add the old checkout to PYTHONPATH. A local package can shadow the installed one, even after changing environments. Select the same environment in your IDE or notebook kernel as in the terminal.

Optional features

Install only the optional features you need, into the same selected Python:

$ python -m pip install "gprMax[mpi]"
$ python -m pip install "gprMax[cuda]"
$ python -m pip install "gprMax[opencl]"
$ python -m pip install "gprMax[metal]"

These extras install Python bindings only. MPI, CUDA, OpenCL, and Metal still require compatible system runtimes and hardware as described below and in the accelerator documentation.

Conda environments and coexistence with v3

Conda is useful for source development, testing and managing native libraries, but it is not a gprMax requirement. It can also provide an isolated environment for an ordinary PyPI installation. Choose Conda instead of the venv route; there is no need to nest them for normal use.

To run a released v4 with Conda, create a new environment:

$ conda create --name gprMax-v4 python=3.12 pip
$ conda activate gprMax-v4
$ python -m pip install gprMax
$ python -m gprMax --help

This uses Conda for Python and pip for gprMax; it does not need the repository’s larger development environment. In a new terminal, activate gprMax-v4 before running models. Alternatively, select the environment for one command:

$ conda run --no-capture-output -n gprMax-v4 python -m gprMax model.in

Use conda deactivate when finished with an activated Conda environment. See Conda environment management and conda run.

gprMax-v4 is the default environment name for both released-package and source installations: it identifies the major version, not a Git branch. Choose one installation route; do not run both environment-creation commands for the same name. If you need a wheel installation and an editable checkout side by side, give the second environment a distinct name with --name (for example, gprMax-v4-source) and activate that name instead.

Keeping v3 and v4 side by side

Keep the old environment and, for an editable installation, its source checkout. Do not rename, delete or update that checkout to v4: the v3 environment may import directly from it. Use a separate checkout for v4 development and separate working/output directories for comparisons.

If the original v3 environment is named gprMax, select versions with:

$ conda activate gprMax-v4
$ python -m gprMax model_v4.in
$ conda activate gprMax
$ python -m gprMax model_v3.in

Replace gprMax with the actual old environment name. There is no machine-wide “default gprMax” that permanently wins: the selected interpreter and its import paths determine the version. Both versions use the package name gprMax. Do not install v4 or apply the v4 conda_env.yml to the old environment if you want v3 to remain available; avoid using Conda’s base environment for either project.

For a one-time coexistence check, run this outside both source checkouts:

$ python -c "import sys, gprMax; print(sys.executable); print(gprMax.__version__); print(gprMax.__file__)"

Installing v4 does not itself convert v3 inputs or results. Read the v3-to-v4 migration guide before comparing them.

Installing from source

Build from source when developing gprMax, modifying its Cython extensions, or using a platform for which no wheel is published. The supplied conda_env.yml is development-focused: it includes notebooks, tests and optional geometry/visualisation packages such as pythonocc-core and PyVista. It is larger than the dependencies of a core PyPI installation and is not needed merely to run a released wheel. On HPC systems, use your site’s compiler/MPI modules and consult the HPC guide.

Use a separate source checkout and environment, as below. The source-build steps are:

  1. Install a C compiler which supports OpenMP

  2. [Optional] Install MPI

  3. Install Python, required Python packages, and get the gprMax source code from GitHub

  4. [Optional] Build h5py against Parallel HDF5

  5. [Optional] Install mpi4py_fft

  6. Build and install gprMax

1. Install a C compiler which supports OpenMP

Linux

  • Install GCC and the corresponding development tools using your distribution’s package manager, or load the compiler module on an HPC system. They may already be available; check gcc --version.

macOS

  • Install the Xcode command-line tools, which provide Apple Clang, and install the OpenMP runtime using Homebrew:

  $ xcode-select --install
  $ brew install libomp

gprMax detects ``libomp`` from Homebrew, the active Python environment, or
``GPRMAX_LIBOMP_PREFIX``. The previous Homebrew GCC requirement is no longer
necessary.
Microsoft Windows

  • Download and install Microsoft Build Tools for Visual Studio 2022 (direct link). You can also find it on the Microsoft Visual Studio downloads page by scrolling down to the ‘All Downloads’ section, clicking the disclosure triangle by ‘Tools for Visual Studio 2022’, then clicking the download button next to ‘Build Tools for Visual Studio 2022’. When installing, choose the ‘Desktop development with C++’ Workload and select only ‘MSVC v143’ and ‘Windows 10 SDK’ or ‘Windows 11 SDK options.

  • Use an x64 Native Tools Command Prompt for Visual Studio, then activate the chosen Python environment there. The compiler needs its headers and libraries as well as its executable; adding a guessed compiler directory to PATH is not sufficient. See the Microsoft compiler-environment instructions.

Alternatively, use the Windows Subsystem for Linux and follow the Linux instructions. That is a separate Linux Python installation, not the Windows one.

2. [Optional] Install MPI

MPI is required only for domain decomposition and task farming. Ordinary serial, OpenMP, CUDA, OpenCL, and Metal simulations do not require an MPI runtime or the mpi4py Python package. The mpi4py binding is installed through the gprMax mpi extra in step 6.

If you plan to use MPI and are running gprMax on an HPC system, a suitable MPI implementation will likely be installed already. Otherwise you will need to install one yourself.

Linux/macOS

  • It is recommended to use OpenMPI.

Microsoft Windows

  • It is recommended to use Microsoft MPI. Download and install both the .exe and .msi files.

3. Install Python, the required Python packages, and get the gprMax source

Install Conda if it is not already available, and install Git. There is no need to replace an existing Conda installation or make its Python the system-wide default. The Python in Conda’s base environment can differ from Python 3.12 in the development environment.

The following commands select the devel branch for v4 development, not a pinned release. To build a published release instead, check out that release’s tag in the new checkout before creating its environment. Use a new directory and environment name; do not reuse your v3 checkout or environment:

$ git clone --branch devel https://github.com/gprMax/gprMax.git gprMax-v4-src
$ cd gprMax-v4-src
$ conda env create -f conda_env.yml
$ conda activate gprMax-v4

The YAML file defaults to gprMax-v4. This step installs development dependencies, not gprMax itself; step 6 builds and installs the checkout. MPI and accelerator bindings remain optional. If gprMax-v4 already exists, keep it and choose a different name with --name rather than overwriting it.

For a non-Conda source environment, create and activate a venv using the earlier instructions, then run python -m pip install -r requirements.txt from the checkout for the common development/test dependencies. Optional CAD, MPI and accelerator libraries still need their own installation instructions. For a minimal source installation, step 6 installs the declared package dependencies and isolated build requirements without that development list.

4. [Optional] Build h5py against Parallel HDF5

If you plan to use parallel HDF5 output with the MPI domain decomposition functionality available in gprMax, h5py must be built with MPI support.

Install with conda

h5py can be installed with MPI support in a conda environment with:

$ conda install -c conda-forge "h5py>=2.9=mpi*"
Install with pip

For a pip-managed environment on Linux/macOS, install a compatible parallel HDF5 library and h5py’s dependencies first, then build with mpicc and HDF5_MPI. If serial h5py is already installed, an ordinary pip install can report it as already satisfied instead of rebuilding it:

$ CC=mpicc HDF5_MPI=ON python -m pip install --force-reinstall --no-deps --no-cache-dir --no-binary=h5py h5py

--no-deps leaves the already prepared runtime dependencies unchanged. For a Conda-managed h5py installation, prefer the Conda route above rather than replacing its files with pip. Verify MPI support in the selected Python:

$ python -c "import h5py; print(h5py.get_config().mpi)"

Further guidance on building h5py against a parallel build of HDF5 is available in the h5py documentation.

5. [Optional] Install mpi4py_fft

If you plan to use the MPI domain decomposition functionality with fractal user objects, you need to install mpi4py_fft.

Python 3.12 is recommended for this optional configuration. mpi4py_fft contains Python-version-specific compiled extensions and also requires a compatible MPI implementation and FFTW installation, so it is more sensitive to the local software stack than the core gprMax package.

Install FFTW

FFTW is a required dependency of mpi4py_fft, however, if you are running gprMax on a HPC system, FFTW may be available already - consult your site’s documentation. Otherwise you will need to install it yourself.

Linux

  • It is possible binaries are available via your package manager. E.g. libfftw3-dev on Ubuntu.

  • Otherwise you can find the latest source code on the fftw downloads page. There are instructions to build from source in the fftw docs.

macOS
$ brew install fftw
Microsoft Windows

  • While FFTW can be installed on Windows (guidance here), it is not possible to build mpi4py_fft using the MSVC compiler.

  • Therefore, we recommend using Windows Subsystem for Linux and then following the Linux install instructions for gprMax.

Install with conda

mpi4py_fft can be installed in a conda environment with:

$ conda install -c conda-forge mpi4py_fft
Install with pip

mpi4py_fft can be installed using pip with:

$ python -m pip install mpi4py_fft

6. Build and install gprMax

Stay in the top-level gprMax-v4-src checkout (the directory containing setup.py and pyproject.toml), with gprMax-v4 or your chosen source-build environment active:

$ python -m pip install -e .

The . means this checkout, and -e makes the installation editable. Python changes are read from these files; changes to compiled Cython code require rebuilding with the same command. Do not delete or move the checkout while using its editable installation. For a non-editable source install, use python -m pip install . instead.

Release and ordinary source builds use portable instruction sets. Developers making a private build for the current host can opt into machine-specific optimisation on Linux or macOS:

$ GPRMAX_BUILD_NATIVE=1 python -m pip install -e .

Do not redistribute a native build: it may contain instructions unavailable on another processor. Published binary wheels never enable this option. Two extension modules are compiled concurrently by default; constrained systems can set GPRMAX_BUILD_JOBS=1, while release builders may select a larger positive value.

For MPI domain decomposition or task farming, install the MPI extra instead:

$ python -m pip install -e ".[mpi]"

For distributed fractal generation, use the combined extra:

$ python -m pip install -e ".[mpi-fractals]"

The mpi-fractals extra includes both mpi4py and mpi4py-fft. If a core source installation is already built, MPI support can be added without recompiling gprMax by installing the system MPI runtime and then running python -m pip install mpi4py (plus mpi4py-fft for distributed fractals). A compatible system MPI runtime is still required; the Python extra does not install or configure that runtime.

Accelerator bindings are also optional and can be installed independently:

$ python -m pip install -e ".[cuda]"       # NVIDIA CUDA; Linux/Windows
$ python -m pip install -e ".[opencl]"     # OpenCL
$ python -m pip install -e ".[metal]"      # Apple Metal; macOS

These editable targets refer to the current checkout. In contrast, python -m pip install "gprMax[cuda]" selects the published distribution; do not substitute that command when you mean to use your edited source.

Several extras can be requested together, for example .[cuda,opencl]. The .[accelerators] convenience extra requests every accelerator binding applicable to the current operating system. It is not the default because package installers cannot detect whether a compatible device, driver, CUDA toolkit, or OpenCL runtime is present, and building an unavailable binding can prevent installation. The backend-specific system software described in the accelerator documentation is still required.

The interactive Marimo dashboards have their own optional dependencies:

$ python -m pip install -e ".[marimo]"

See the Marimo toolbox documentation for the available A-scan, B-scan, progress, and introductory processing dashboards.

You are now ready to proceed to running gprMax.

Running gprMax

gprMax is designed as a Python package, i.e. a namespace which can contain multiple packages and modules, much like a directory.

Open a terminal and select the Python where gprMax is installed. If using an environment, activate it or explicitly select its interpreter; a direct installation into a user-managed Python needs no activation. Run models from your own working directory; a wheel installation does not require a repository checkout. Source users can also work from the repository root for the version they intend to run. The $ below represents a shell prompt, not a required environment name; do not type it.

Using the installed toolboxes

Toolboxes are included under the gprMax.toolboxes namespace, so they do not compete with an unrelated Python package called toolboxes. Run a toolbox from your working directory, for example:

python -m gprMax.toolboxes.Plotting.plot_Ascan model.h5
python -m gprMax.toolboxes.Plotting.plot_port model.h5 --list-ports

Python model scripts import the same namespace:

from gprMax.toolboxes.GPRAntennaModels.GSSI import antenna_like_GSSI_1500

To locate toolbox-specific examples, MATLAB utilities or other bundled files:

python -c "from importlib.resources import files; print(files('gprMax.toolboxes'))"

Copy files you want to edit into your own workspace; do not modify the installed package. The example-copy command below copies the main model examples, not all toolbox folders. Some specialist toolboxes need additional optional dependencies, and large reference datasets may remain in the source repository; consult the selected toolbox’s documentation.

Existing scripts must change toolboxes.<name> to gprMax.toolboxes.<name> in imports and python -m commands. No top-level toolboxes compatibility package is installed, because that would retain the naming conflict. An isolated environment is recommended when upgrading an older development installation that installed the former namespace.

Examples from a wheel installation

Binary wheel installations also contain the examples that match the installed gprMax version. Copy them from the installed package into a writable workspace with:

$ python -m gprMax.examples list
$ python -m gprMax.examples copy ~/gprMax-v4-examples
$ cd ~/gprMax-v4-examples

The destination contains the normal examples/ hierarchy, so the same commands work for wheel and source installations. An existing example tree is not overwritten unless --force is supplied.

Basic usage of gprMax is:

$ python -m gprMax path_to/name_of_input_file

For example to run one of the test models:

$ python -m gprMax examples/gpr/basic/cylinder_Ascan_2D.in

To use Apple Metal GPU acceleration on macOS:

$ python -m gprMax examples/gpr/basic/cylinder_Ascan_2D.in -metal

When the simulation is complete you can plot the A-scan using:

$ python -m gprMax.toolboxes.Plotting.plot_Ascan examples/gpr/basic/cylinder_Ascan_2D.h5

Your results should be like those from the A-scan from the metal cylinder example in introductory/basic 2D models section

When finished, use deactivate for an activated venv or conda deactivate for Conda. No deactivation is needed when you selected the interpreter directly without activating an environment.

Optional command line arguments

Argument name

Type

Description

-o or -outputfile

string

File path to save the output data.

-n

integer

Number of required simulation runs. This option can be used to run a series of models, e.g. to create a B-scan with 60 traces: $ python -m gprMax examples/gpr/basic/cylinder_Bscan_2D.in -n 60

-i

integer

Model number to start/restart the simulation from. It would typically be used to restart a series of models from a specific model number, with the n argument, e.g. to restart from A-scan 45 when creating a B-scan with 60 traces.

-t or --taskfarm

flag

Flag to use Message Passing Interface (MPI) taskfarm. This option is most usefully combined with -n to allow individual models to be farmed out using a MPI taskfarm, e.g. to create a B-scan with 60 traces and use MPI to farm out each trace: $ python -m gprMax examples/gpr/basic/cylinder_Bscan_2D.in -n 60 --taskfarm. For further details see the MPI task-farm section of the User Guide

--mpi

list

Flag to use Message Passing Interface (MPI) to divide the model between MPI ranks. Three integers should be provided to define the number of MPI processes (min 1) in the x, y, and z dimensions.

-gpu

list/bool

Flag to use NVIDIA GPU or list of NVIDIA GPU device ID(s) for specific GPU card(s), e.g. -gpu 0 1

-opencl

list/bool

Flag to use OpenCL or list of OpenCL device ID(s) for specific compute device(s).

-metal

list/bool

Flag to use Apple Metal GPU or list of Metal device ID(s) for specific compute device(s) (macOS with M-series chips).

-cpu_precision

string

Precision for the CPU solver: single (default) or double. This option is ignored when a GPU solver is used. Sub-gridding always uses double precision regardless of this setting.

-gpu_precision

string

Precision for the CUDA, OpenCL, or Metal solver: single (default) or double. Apple Metal currently supports single precision only. This option is ignored when the CPU solver or sub-gridding is used.

--geometry-only

flag

Build a model and produce any geometry views but do not run the simulation, e.g. to check the geometry of a model is correct: $ python -m gprMax examples/gpr/materials/heterogeneous_soil.in --geometry-only

--geometry-fixed

flag

Run a series of models where the geometry does not change between models, e.g. a B-scan where only the position of simple sources and receivers, moved using #src_steps and #rx_steps, changes between models.

--write-processed

flag

Write another input file after any Python blocks and include commands in the original input file have been processed. Useful for checking that any Python blocks are being correctly processed into gprMax commands.

--show-progress-bars

flag

Forces progress bars to be displayed - by default, progress bars are displayed when the log level is info (20) or less.

--hide-progress-bars

flag

Forces progress bars to be hidden - by default, progress bars are hidden when the log level is greater than info (20).

--log-level

integer

Level of logging to use, see the Python logging module.

--log-file

flag

Write logging information to file.

--log-all-ranks

flag

Write logging information from all MPI ranks. Default behaviour only provides log output from rank 0. When used with --log-file, each rank will write to an individual file.

-h or --help

flag

Used to get help on command line options.

Updating gprMax

Updating a released v4 installation

Select the environment you intend to update, then use pip. No Git checkout or manual uninstallation is needed:

$ python -m pip install --upgrade "gprMax>=4,<5"

The version range keeps an existing v4 project on the v4 release series. An unversioned pip install gprMax may report an existing installation as already satisfied; it is not an explicit upgrade request. For reproducible work, record or pin the exact version and retain representative reference outputs before updating. This command updates the selected environment, not every installation on the machine.

For v3-to-v4 migration, create a separate environment first as described in Keeping v3 and v4 side by side. Do not use this upgrade command inside the old v3 environment if you want to retain that installation.

Updating a source-development installation

Preserve or commit your local edits before switching branches/tags or pulling changes. In the separate v4 checkout, select the desired revision, activate its development environment, then rebuild with python -m pip install -e .. Do not use a PyPI upgrade command to update an editable checkout.

If the revision changes dependencies, recreate a development environment from its YAML file under a new name, for example:

$ conda env create --name gprMax-v4-next --file conda_env.yml
$ conda activate gprMax-v4-next
$ python -m pip install -e .

Reinstall any selected optional bindings. Install Conda-managed dependencies before the final pip installation; repeated Conda/pip changes in place can leave inconsistent dependency sets. Do not apply this YAML file to a v3 environment or to Conda’s base. The environment name is only a selector: an editable install still follows the source files in its checkout.

Thanks to our contributors

The complete and current contributor history is available in the GitHub contributor graph.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

Owner

PyPI data
Data sourced directly from PyPI's database.

Credits

Author: Craig Warren, Antonis Giannopoulos, and John Hartley

License

GNU General Public License v3 or later (GPLv3+) (GPLv3+)

Requires

Python <3.14, >=3.11

Provides Extra

cuda opencl metal accelerators mpi mpi-fractals marimo

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gprmax-4.0.0.tar.gz (16.0 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

gprmax-4.0.0-cp313-cp313-win_amd64.whl (12.8 MB view details)

Uploaded CPython 3.13Windows x86-64

gprmax-4.0.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (34.9 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

gprmax-4.0.0-cp313-cp313-macosx_11_0_x86_64.whl (14.3 MB view details)

Uploaded CPython 3.13macOS 11.0+ x86-64

gprmax-4.0.0-cp313-cp313-macosx_11_0_arm64.whl (14.0 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

gprmax-4.0.0-cp312-cp312-win_amd64.whl (12.8 MB view details)

Uploaded CPython 3.12Windows x86-64

gprmax-4.0.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (35.0 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

gprmax-4.0.0-cp312-cp312-macosx_11_0_x86_64.whl (14.0 MB view details)

Uploaded CPython 3.12macOS 11.0+ x86-64

gprmax-4.0.0-cp312-cp312-macosx_11_0_arm64.whl (13.9 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

gprmax-4.0.0-cp311-cp311-win_amd64.whl (12.8 MB view details)

Uploaded CPython 3.11Windows x86-64

gprmax-4.0.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (34.5 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

gprmax-4.0.0-cp311-cp311-macosx_11_0_x86_64.whl (14.2 MB view details)

Uploaded CPython 3.11macOS 11.0+ x86-64

gprmax-4.0.0-cp311-cp311-macosx_11_0_arm64.whl (14.0 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

File details

Details for the file gprmax-4.0.0.tar.gz.

File metadata

  • Download URL: gprmax-4.0.0.tar.gz
  • Upload date:
  • Size: 16.0 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for gprmax-4.0.0.tar.gz
Algorithm Hash digest
SHA256 f27e3795dc4e6e1a53fa9bd069bf0225c42917ae41f62b348ae151a80052c4f7
MD5 94b28b52d1d7d966e9c5830bbad41199
BLAKE2b-256 5d97e3b56b7a81127fa0b1b49a3e438621b533090eb11015d5b73c64e9e0c714

See more details on using hashes here.

Provenance

The following attestation bundles were made for gprmax-4.0.0.tar.gz:

Publisher: release.yml on gprMax/gprMax

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gprmax-4.0.0-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: gprmax-4.0.0-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 12.8 MB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for gprmax-4.0.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 ecf12b10bf5a5cdf4d34c9eb220692fc878e8f365dee3d3a4f8f6c68cc976148
MD5 26cd6badea332c25b7e65036e17d7d63
BLAKE2b-256 24f72ee6f54808e58bd4541e602bdd4a86705d1193f987c2d1a46461b59a5691

See more details on using hashes here.

Provenance

The following attestation bundles were made for gprmax-4.0.0-cp313-cp313-win_amd64.whl:

Publisher: release.yml on gprMax/gprMax

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gprmax-4.0.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for gprmax-4.0.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 97bad9afaf866038a583034665a518f748a6776f9920333f5a02f180433420de
MD5 f0ceb74997642c5cb4314f5333049640
BLAKE2b-256 d8f3f620891d201f95259535277674095be068f9969407dd669575a85a2e3b6f

See more details on using hashes here.

Provenance

The following attestation bundles were made for gprmax-4.0.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on gprMax/gprMax

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gprmax-4.0.0-cp313-cp313-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for gprmax-4.0.0-cp313-cp313-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 8891676a8d5c512a8cf0327aec307cd4a51f1675e8d33e9423de01fa84f607ad
MD5 f351db9fea8534d93d7c88b62b9ad975
BLAKE2b-256 f88e1ee3484bef977ceae6f9553682cf3c578caa96d29e24c7352e3d9e204003

See more details on using hashes here.

Provenance

The following attestation bundles were made for gprmax-4.0.0-cp313-cp313-macosx_11_0_x86_64.whl:

Publisher: release.yml on gprMax/gprMax

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gprmax-4.0.0-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for gprmax-4.0.0-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 6331570496ae5200a8c08e2cb8d128a922bc2cbe0e43a82c60aadaa635b506c5
MD5 06bf37a6beb9f34124683f2786b183a0
BLAKE2b-256 d0b16241a2f6258fa3ab6f02b00ffe88dd41a066cf71ce0424c65e5c524573e1

See more details on using hashes here.

Provenance

The following attestation bundles were made for gprmax-4.0.0-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: release.yml on gprMax/gprMax

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gprmax-4.0.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: gprmax-4.0.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 12.8 MB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for gprmax-4.0.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 0768424b35405345f6affb668610fd99a8b67219c2e76692918ece528729a395
MD5 33e8533021da93bd09facec66dd35ff1
BLAKE2b-256 d9ddf1e1019cc2f41d834ad63381d79f59c71071378b8c9db37e60ca761717c6

See more details on using hashes here.

Provenance

The following attestation bundles were made for gprmax-4.0.0-cp312-cp312-win_amd64.whl:

Publisher: release.yml on gprMax/gprMax

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gprmax-4.0.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for gprmax-4.0.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 5dafb976d2a0ceee65fdffbb0231136c2bf5a3280da11ba38ec542f5514b526b
MD5 00c14792a1b8d19ec641be2d1d8acfab
BLAKE2b-256 e1f393e9bcd0315a9310f68c09f0e7bbb2cdf9cf92c5ee61097ccae85dcf7cd4

See more details on using hashes here.

Provenance

The following attestation bundles were made for gprmax-4.0.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on gprMax/gprMax

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gprmax-4.0.0-cp312-cp312-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for gprmax-4.0.0-cp312-cp312-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 9ae7542b778bfa6b9e6484e1f805fddef74a4a60d427154557ac5d5b24eae11e
MD5 8a963413d850f527db80f011ccf26cf0
BLAKE2b-256 de1b2afb9fcbcd5989fcc3e3304b22ef3891ce675cee583f2ebf8a82bf6b53fe

See more details on using hashes here.

Provenance

The following attestation bundles were made for gprmax-4.0.0-cp312-cp312-macosx_11_0_x86_64.whl:

Publisher: release.yml on gprMax/gprMax

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gprmax-4.0.0-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for gprmax-4.0.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 c2f0a1ee6d1db29ba7e18fb667a23aa50ca5036ad2a5201ce3d703d02fabed65
MD5 ef96066c711d203a0377a6fc8457e552
BLAKE2b-256 3a1921df95bbb3413de117756e682b989a7ba353215c6d3b9e2bbfb46c0d237b

See more details on using hashes here.

Provenance

The following attestation bundles were made for gprmax-4.0.0-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: release.yml on gprMax/gprMax

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gprmax-4.0.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: gprmax-4.0.0-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 12.8 MB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for gprmax-4.0.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 a089f1572d2efc841c8b3b86be66d57c08fe4af96b5420e8392b9c5bb0dac2f6
MD5 cb0355663ba3d40d086368bf52474055
BLAKE2b-256 4f0ececd38b7d35c36b80783afc6b1985c229103b28949fa4e8223e52d076275

See more details on using hashes here.

Provenance

The following attestation bundles were made for gprmax-4.0.0-cp311-cp311-win_amd64.whl:

Publisher: release.yml on gprMax/gprMax

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gprmax-4.0.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for gprmax-4.0.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 fdae459b811d4aae81428a9ce33eac53ba8dbfdae9f8d7d209d3648b3b6a9dfa
MD5 ad78273078a0cd4489dcaf4e19668bd3
BLAKE2b-256 ad19d254b52805889cb32db2f84166213f4d6d483bc4b336e1cc7f6cfa5e047a

See more details on using hashes here.

Provenance

The following attestation bundles were made for gprmax-4.0.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on gprMax/gprMax

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gprmax-4.0.0-cp311-cp311-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for gprmax-4.0.0-cp311-cp311-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 db5d31d3f1be5a68b75874d0337f9164e336435571a6497b5ddc5326fe2dc98d
MD5 63543f3a7c29946f9084b1bffc40a830
BLAKE2b-256 5e51990a9cd67e5c5a49ecf4444fb3035aa48307b41b4d3d64124978e765e433

See more details on using hashes here.

Provenance

The following attestation bundles were made for gprmax-4.0.0-cp311-cp311-macosx_11_0_x86_64.whl:

Publisher: release.yml on gprMax/gprMax

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gprmax-4.0.0-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for gprmax-4.0.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 70af4628721a068af0cc2f4e132f08332dc1db4a8b122cc5949cdd1791d9520b
MD5 70a74104568572ba6b46620f86d5fd2a
BLAKE2b-256 ba61de5b15589f3e62177def827198150c4fe6ba7501b5a543e51a174b2e5083

See more details on using hashes here.

Provenance

The following attestation bundles were made for gprmax-4.0.0-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: release.yml on gprMax/gprMax

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

4.0.0 This release

13 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page