Python scripting

The input file has now been made scriptable by permitting blocks of Python code to be specified between #python and #end_python commands. The code is executed when the input file is read by gprMax. You don’t need any external tools, such as MATLAB, to generate larger, more complex input files for building intricate models. Python scripting means that gprMax now includes libraries of more complex objects, such as antennas, that can be easily inserted into a model. You can also access a number of built-in constants from your Python code.

Constants/variables

You can access the following built-in constants from your Python code:

  • c which is the speed of light in vacuum \(c=2.9979245 \times 10^8\) m/s
  • e0 which is the permittivity of free space \(\epsilon_0=8.854187 \times 10^{-12}\) F/m
  • m0 which is the permeability of free space \(\mu_0=1.256637 \times 10^{-6}\) H/m
  • z0 which is the impedance of free space \(z_0=376.7303134\) Ohms

You can access the following built-in variables from your Python code:

  • current_model_run which is the current run number of the model that is been executed.
  • number_model_runs which is the total number of runs specified when the model was initially executed, i.e. from python -m gprMax my_input_file -n number_of_model_runs

Antenna models

You can also access a user library of antenna models. This library currently features models of antennas similar to:

These antenna models can be accessed from within a block of Python code in your simulation. For example, to use Python to include an antenna model similar to a GSSI 1.5 GHz antenna at a location 0.125m, 0.094m, 0.100m (x,y,z) using a 1mm spatial resolution:

#python:
from user_libs.antennas import antenna_like_GSSI_1500
antenna_like_GSSI_1500(0.125, 0.094, 0.100, 0.001)
#end_python:

Functions for input commands

To make it easier to create commands within a block of Python code, there is a built-in module which contains some of the most commonly used input commands in functional form. For example, to use Python to generate a series of cylinders in a model:

#python:
from gprMax.input_cmd_funcs import *
domain = domain(0.2 0.2 0.2)
for x in range(0, 8)
    cylinder(0.02 + x * 0.02, 0.05, 0, 0.020 + x * 0.02, 0.05, domain[2], 0.005, 'pec’)
#end_python:

The domain function will print the #domain command to the input file and return a variable with the extent of the domain that can be used elsewhere in a Python code block, e.g. in this case with the cylinder function. The cylinder function is just a functional version of the #cylinder command which prints it to the input file.

input_cmd_funcs.py

This module contains functional forms of some of the most commonly used gprMax commands. It can be useful to use these within Python scripting in an input file.

gprMax.input_cmd_funcs.domain(x, y, z)

Prints the gprMax #domain command.

Parameters:x, y, z (float) – Extent of the domain in the x, y, and z directions.
Returns:domain – Tuple of the extent of the domain.
Return type:float
gprMax.input_cmd_funcs.dx_dy_dz(x, y, z)

Prints the gprMax #dx_dy_dz command.

Parameters:x, y, z (float) – Spatial resolution in the x, y, and z directions.
Returns:dx_dy_dz – Tuple of the spatial resolutions.
Return type:float
gprMax.input_cmd_funcs.time_window(time_window)

Prints the gprMax #time_window command.

Parameters:time_window (float) – Duration of simulation.
Returns:time_window – Duration of simulation.
Return type:float
gprMax.input_cmd_funcs.material(permittivity, conductivity, permeability, magconductivity, name)

Prints the gprMax #material command.

Parameters:
  • permittivity (float) – Relative permittivity of the material.
  • conductivity (float) – Conductivity of the material.
  • permeability (float) – Relative permeability of the material.
  • magconductivity (float) – Magnetic loss of the material.
  • name (str) – Material identifier.
gprMax.input_cmd_funcs.geometry_view(xs, ys, zs, xf, yf, zf, dx, dy, dz, filename, type='n')

Prints the gprMax #geometry_view command.

Parameters:
  • xs, ys, zs, xf, yf, zf (float) – Start and finish coordinates.
  • dx, dy, dz (float) – Spatial discretisation of geometry view.
  • filename (str) – Filename where geometry file information will be stored.
  • type (str) – Can be either n (normal) or f (fine) which specifies whether to output the geometry information on a per-cell basis (n) or a per-cell-edge basis (f).
gprMax.input_cmd_funcs.snapshot(xs, ys, zs, xf, yf, zf, dx, dy, dz, time, filename)

Prints the gprMax #snapshot command.

Parameters:
  • xs, ys, zs, xf, yf, zf (float) – Start and finish coordinates.
  • dx, dy, dz (float) – Spatial discretisation of geometry view.
  • time (float) – Time in seconds (float) or the iteration number (integer) which denote the point in time at which the snapshot will be taken.
  • filename (str) – Filename where geometry file information will be stored.
gprMax.input_cmd_funcs.edge(xs, ys, zs, xf, yf, zf, material)

Prints the gprMax #edge command.

Parameters:
  • xs, ys, zs, xf, yf, zf (float) – Start and finish coordinates.
  • material (str) – Material identifier.
gprMax.input_cmd_funcs.plate(xs, ys, zs, xf, yf, zf, material)

Prints the gprMax #plate command.

Parameters:
  • xs, ys, zs, xf, yf, zf (float) – Start and finish coordinates.
  • material (str) – Material identifier(s).
gprMax.input_cmd_funcs.triangle(x1, y1, z1, x2, y2, z2, x3, y3, z3, thickness, material)

Prints the gprMax #triangle command.

Parameters:
  • x1, y1, z1, x2, y2, z2, x3, y3, z3 (float) – Coordinates of the vertices.
  • thickness (float) – Thickness for a triangular prism, or zero for a triangular patch.
  • material (str) – Material identifier(s).
gprMax.input_cmd_funcs.box(xs, ys, zs, xf, yf, zf, material, averaging='')

Prints the gprMax #box command.

Parameters:
  • xs, ys, zs, xf, yf, zf (float) – Start and finish coordinates.
  • material (str) – Material identifier(s).
  • averaging (str) – Turn averaging on or off.
gprMax.input_cmd_funcs.sphere(x, y, z, radius, material, averaging='')

Prints the gprMax #sphere command.

Parameters:
  • x, y, z (float) – Coordinates of the centre of the sphere.
  • radius (float) – Radius.
  • material (str) – Material identifier(s).
  • averaging (str) – Turn averaging on or off.
gprMax.input_cmd_funcs.cylinder(x1, y1, z1, x2, y2, z2, radius, material, averaging='')

Prints the gprMax #cylinder command.

Parameters:
  • x1, y1, z1, x2, y2, z2 (float) – Coordinates of the centres of the two faces of the cylinder.
  • radius (float) – Radius.
  • material (str) – Material identifier(s).
  • averaging (str) – Turn averaging on or off.
gprMax.input_cmd_funcs.cylindrical_sector(axis, ctr1, ctr2, t1, t2, radius, startingangle, sweptangle, material, averaging='')

Prints the gprMax #cylindrical_sector command.

Parameters:
  • axis (str) – Axis of the cylinder from which the sector is defined and can be x, y, or z.
  • ctr1, ctr2 (float) – Coordinates of the centre of the cylindrical sector.
  • t1, t2 (float) – Lower and higher coordinates of the axis of the cylinder from which the sector is defined (in effect they specify the thickness of the sector).
  • radius (float) – Radius.
  • startingangle (float) – Starting angle (in degrees) for the cylindrical sector (with zero degrees defined on the positive first axis of the plane of the cylindrical sector).
  • sweptangle (float) – Angle (in degrees) swept by the cylindrical sector (the finishing angle of the sector is always anti-clockwise from the starting angle).
  • material (str) – Material identifier(s).
  • averaging (str) – Turn averaging on or off.