Skip to content

GPRMax UI

GPRMax UI is a Python interface for building, running, and inspecting gprMax electromagnetic simulations. It wraps the gprMax input-command format with typed Python objects, manages common simulation output workflows, and provides plotting helpers for B-scans, geometry, snapshots, and rendered videos.

Library Logo

Current Version

The current package version is 1.0.3. The documented API reflects the live package in this repository, including:

  • GeometryObjectsRead support for gprMax geometry-object files.
  • GprMaxModel.to_json() and GprMaxModel.from_json() for model configuration reuse.
  • snapshot_stride, num_threads, mpi, gpu, and geometry_fixed run options.
  • Parallel video-frame rendering through save_video(..., workers=...).
  • Optional viz and video extras for plotting, PyVista rendering, and MP4 export.

What It Provides

  • Python objects for domains, materials, geometry, sources, receivers, and output commands.
  • A GprMaxModel workflow for writing input files and calling the gprMax API.
  • Helpers for merging output files and reading receiver components.
  • Visualization routines for model geometry, receiver data, snapshots, and videos.
  • Parallel execution options for gprMax runs and video-frame rendering.
  • JSON export and import for repeatable model definitions.

Minimal Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
from pathlib import Path

from gprmaxui import GprMaxModel
from gprmaxui.commands import (
    DomainBox,
    DomainResolution,
    DomainSize,
    HertzianDipole,
    Material,
    Rx,
    RxSteps,
    SrcSteps,
    TimeWindow,
    Tx,
    TxRxPair,
    Waveform,
)

model = GprMaxModel(
    title="B-scan from a dielectric half-space",
    output_folder=Path("output"),
    domain_size=DomainSize(x=0.2, y=0.2, z=0.002),
    domain_resolution=DomainResolution(dx=0.002, dy=0.002, dz=0.002),
    time_window=TimeWindow(twt=3e-9),
)

model.register_materials(
    Material(id="half_space", permittivity=6, conductivity=0, permeability=1)
)

model.add_geometry(
    DomainBox(
        x_min=0.0,
        y_min=0.0,
        z_min=0.0,
        x_max=0.2,
        y_max=0.145,
        z_max=0.002,
        material="half_space",
    )
)

tx = Tx(
    waveform=Waveform(wave_family="ricker", amplitude=1.0, frequency=1.5e9),
    source=HertzianDipole(polarization="z", x=0.03, y=0.15, z=0.0),
)
rx = Rx(x=0.05, y=0.15, z=0.0)

model.set_source(
    TxRxPair(
        tx=tx,
        rx=rx,
        src_steps=SrcSteps(dx=0.002, dy=0.0, dz=0.0),
        rx_steps=RxSteps(dx=0.002, dy=0.0, dz=0.0),
    )
)

model.run(n="auto", geometry=True, snapshots=True)
model.plot_data()

Next Steps