Skip to content

Parallel Runs and Video

Large B-scans can produce many trace files, geometry files, and snapshots. GPRMax UI exposes options for controlling gprMax parallel execution and for rendering videos without keeping every frame in memory.

Run with Parallel Options

GprMaxModel.run() forwards most keyword arguments to gprMax.gprMax.api. It also handles a few convenience options before calling the API.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
model.run(
    n="auto",
    geometry=True,
    snapshots=True,
    snapshot_stride=10,
    num_threads=8,
    mpi="auto",
    gpu=[0, 1],
    geometry_fixed=True,
)

Key options:

  • snapshot_stride: Writes snapshots every nth iteration.
  • num_threads: Emits a #num_threads command in the generated input file.
  • mpi="auto": Chooses a conservative MPI task count from the trace count, detected CPU cores, and requested GPUs.
  • gpu: Passed through to the gprMax API.
  • geometry_fixed: Passed through to the gprMax API for fixed-geometry runs.
  • clear_output_folder: Clears the output folder before the run by default.
  • geometry_only: Generates geometry output without requiring merged receiver data.

Tip

The automatic trace count assumes the transmitter-receiver pair moves along the x axis using the configured receiver step.

Save a Simulation Video

save_video() reads the merged output data and combines B-scan progress with snapshot geometry frames.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
model.save_video(
    "model.mp4",
    fps=25,
    rx=1,
    rx_component="Ez",
    cmap="jet",
    figsize=(6, 10),
    frame_step=10,
    workers="auto",
)

The frame_step should match snapshot files that exist on disk. If snapshots were written with snapshot_stride=10, use frame_step=10 for video rendering.

workers="auto" chooses a conservative number of worker processes. Use workers=1 for serial rendering when debugging or when process startup overhead is larger than the frame-rendering work.

Use a Temporary Frame Directory

By default, rendered PNG frames are written to a temporary directory and cleaned after the video writer completes. To place temporary frames under a known parent directory:

1
2
3
4
5
6
model.save_video(
    "model.mp4",
    frame_step=10,
    workers=4,
    temp_dir="frame_cache",
)

Common Failure Modes

  • Missing snapshot files: rerun with snapshots=True and a compatible snapshot_stride.
  • Missing geometry files: rerun with geometry=True.
  • Empty videos: check that receiver data exists and that frame_step is not larger than the number of iterations.