Skip to content

API Reference

This page summarizes the main public classes and functions used by typical GPRMax UI workflows. The package re-exports GprMaxModel from gprmaxui and the command models from gprmaxui.commands.

The current documented package version is 1.0.3.

Model

GprMaxModel represents one gprMax simulation setup.

Common methods:

  • register_materials(*materials): Add Material commands to the model.
  • add_geometry(*geometry): Add geometry commands such as boxes, spheres, and cylinders.
  • set_source(source): Attach a TxRxPair source and receiver workflow.
  • run(...): Write sim.in, call the gprMax API, and merge output files.
  • data(rx=1): Return receiver component arrays and the simulation time step.
  • plot_data(...): Plot receiver components as B-scans.
  • plot_geometry(...): Render the generated geometry file.
  • plot_snapshot(...): Render a snapshot and B-scan progress view.
  • save_video(...): Render an MP4 from snapshots and receiver data.
  • to_json(path=None, indent=2): Serialize the model configuration to a JSON string or file.
  • from_json(data): Reconstruct a model from a JSON string, file path, or parsed dictionary.

Run Options

run(*args, **kwargs) writes sim.in, calls gprMax.gprMax.api, and returns the same GprMaxModel instance. Common keyword arguments include:

  • n: Trace count. Use "auto" to infer traces from the receiver position and x-step.
  • geometry: Whether to emit geometry output commands.
  • snapshots: Whether to emit snapshot output commands.
  • snapshot_stride: Positive integer interval between snapshot outputs.
  • num_threads: Positive integer for the generated #num_threads command.
  • mpi: gprMax MPI option. Use "auto" for a conservative task count.
  • gpu: GPU selector forwarded to gprMax.
  • geometry_fixed: Forwarded to gprMax for fixed-geometry runs.
  • clear_output_folder: Clears the output folder before running. Defaults to True.
  • geometry_only: Runs geometry output without requiring merged receiver data.

Plotting and Video

Install gprmaxui[viz] for plotting and geometry rendering. Install gprmaxui[video] when using save_video(...).

  • plot_data(rx=1, n_cols=2, return_image=False): Plot receiver components, or return a PIL image when return_image=True.
  • plot_geometry(return_image=False): Generate geometry output and render it with PyVista.
  • plot_snapshot(rx=1, trace_idx=None, iteration_idx=None, rx_component="Ez", cmap="jet", return_image=False): Render one snapshot and the corresponding partial B-scan.
  • save_video(output_file="model.mp4", fps=180, rx=1, rx_component="Ez", cmap="jet", figsize=(10, 10), frame_step=10, workers="auto", temp_dir=None): Render a video from snapshot files and receiver data.

Domain Commands

  • DomainSize: Defines the physical size of the simulation domain.
  • DomainResolution: Defines dx, dy, and dz cell spacing.
  • TimeWindow: Defines the simulation time window.
  • NumThreads: Writes a gprMax #num_threads command.

Materials and Geometry

  • Material: Defines electromagnetic material properties.
  • DomainBox: Defines a rectangular solid. Includes convenience methods for area, volume, containment checks, center-point calculation, and construction from a center point plus size.
  • DomainSphere: Defines a sphere.
  • DomainCylinder: Defines a cylinder.
  • GeometryObjectsRead: References a geometry-object HDF5 file and material mapping file.

Geometry Object Files

Use GeometryObjectsRead when geometry has already been prepared as a gprMax geometry-object HDF5 file:

1
2
3
4
5
6
7
8
9
model.add_geometry(
    GeometryObjectsRead(
        filename="root_images/root1.h5",
        materials_filename="root_images/root1.txt",
        x=0.1,
        y=0.02,
        z=0.0,
    )
)

Sources and Receivers

  • Waveform: Defines the source waveform family, amplitude, and frequency.
  • HertzianDipole: Defines an electric current density source.
  • MagneticDipole: Defines a magnetic dipole source.
  • VoltageSource: Defines a voltage source.
  • Rx: Defines a receiver location.
  • Tx: Binds a waveform to a source command.
  • TxRxPair: Combines transmitter, receiver, source steps, and receiver steps for a model.

Utility Functions

  • get_output_data(filename, rxnumber, rxcomponent): Reads one receiver component from a gprMax output file.
  • merge_model_files(output_folder, output_file, gprMax_version=None): Merges per-trace .out files into output_merged.out.
  • make_images_grid(images_list, num_cols, resample=None): Combines returned plot images into a grid.
  • png2geometry(imagefile, dxdydz, physical_size=None, scale=1.0, zcells=1): Converts visible pixels from an image into a geometry-object HDF5 file.