User Guide V2

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 78

Download
Open PDF In Browser	View PDF

GprMax2D/3D

User’s Manual

Version 2.0

Many of the designations used by manufacturers and sellers to distinguish their products are
claimed as trademarks. Where those designations appear in this manual, and the author was
aware of a trademark claim, the designations have been printed in initial caps or small caps.
The procedures and applications presented in this manual have been included for their
instructional value. They have been tested with care but are not guaranteed for any particular
purpose. The author does not offer any warranties or representations, nor does it accept any
liabilities with respect to the programmes or applications.

Typeset in Concrete Roman with LATEX 2ε
Copyright  2005 by Antonis Giannopoulos

All rights reserved. Permission is granted to reproduce and use this manual and GprMax
software for academic or commercial purposes.

LICENCE:
GprMax2D V 2.0 (Electromagnetic simulator for Ground Probing Radar)
GprMax3D V 2.0 (Electromagnetic simulator for Ground Probing Radar)
AUTHOR: Antonis Giannopoulos
COPYRIGHT: Antonis Giannopoulos, 2005
TERMS AND CONDITIONS
This Licence applies to the GprMax2D and GprMax3D executable forms, object codes and to
every file which is part of the GprMax2D and GprMax3D source codes. The “Programmes”,
below, refers to the executable images of GprMax2D and GprMax3D and to all the files which
constitute the source codes for GprMax2D and GprMax3D. The licensee is addressed as
“you”. Any modification of the Programmes and their source code including translation to other
programming languages is referred to as “modification”.
1. You are licenced to copy and distribute only verbatim copies of the Programmes in any
medium. You must keep intact all the notices that refer to their Licence and all copyright
notices included in the Programmes.
Activities other than executing, copying, distribution and modification are not covered by
this Licence; they are outside its scope.
2.

(a) You may modify your copy or copies of the Programmes or any portions of them for
your own personal use only.
(b) You may not modify your copy or copies of the Programmes or any portions of them,
thus forming a work based on the Programmes for any other use different from the
one stated in a) above.

NO WARRANTY
THERE IS NO WARRANTY FOR THE PROGRAMMES, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDER PROVIDES THE PROGRAMMES “AS IS” WITHOUT ANY WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
PROGRAMMES IS WITH YOU. SHOULD THE PROGRAMMES PROVE DEFECTIVE, YOU
ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL THE COPYRIGHT HOLDER BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF
THE USE OR INABILITY TO USE THE PROGRAMMES (INCLUDING BUT NOT LIMITED TO
LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAMMES TO OPERATE WITH ANY
OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
THE POSSIBILITY OF SUCH DAMAGES.
END OF TERMS AND CONDITIONS

Preface
GprMax2D and GprMax3D are electromagnetic wave simulators for Ground Penetrating Radar
modelling. They are based on the Finite-Difference Time-Domain numerical method. This User’s
Manual describes the installation of GprMax2D/3D and the various commands which are
available for the construction of 2D and 3D GPR models. Some simple examples of GPR models are provided to illustrate the procedures that should be followed in order to obtain useful
models using GprMax2D/3D. Please do report any errors or omissions to the author.
If you require further information about GprMax2D and GprMax3D or you have any suggestions for improvements to the software or to this User’s Manual please contact the author:

Dr Antonis Giannopoulos
University of Edinburgh
School of Engineering and Electronics
Institute for Infrastructure and Environment
AGB Building, The King’s Buildings,
Edinburgh, EH9 3JN, Scotland
E-mail: A.Giannopoulos@ed.ac.uk

Preface to Version 2.0
The GprMax2D/3D codes have been around for some time since their initial development in
1996. At that time, 32Mb of RAM and processor speeds of 100 MHz were considered top of the
range in computer technology! Clearly things have moved on. As computer power increases
we are able to realistically model more complex GPR scenarios and even attempt models of GPR
transducers. Version 2.0 of GprMax mainly brings the 2D model in a par with the 3D in terms of
development of the underlying numerical modelling technique.
New with Version 2.0 are:
• Perfectly Matched Layer (PML) boundaries for both1 GprMax2D and GprMax3D

• User specified excitation functions for both GprMax2D and GprMax3D

• Huygens’s Surface in GprMax3D

• Plane Wave excitation in GprMax3D for free space simulations which will be extended for
half space simulations in future.
• Simulation of thin-wires in GprMax3D.

• Voltage sources in GprMax3D along with 1D transmission lines for feeding models of GPR
antennas.
• New excitation structure which makes GprMax2D/3D more general in use and allows for
multiple sources and receivers at the same time.
• New geometry primitive in GprMax3D to create cylinders of any orientation in the model
space.
• Both codes have been parallelised using OpenMP 2

• The cryptic error codes of GprMax2D have been replaced by error messages as in GprMax3D.

I hope to continue developing GprMax in the future so it will become more versatile than what
it is at the moment. If you need to work with the source code you could request it in writing. You
should state that you will not redistribute the code to anyone either verbatim or in any modified
version of it. Finally you should put in a few words about the reasons for needing it.
For any ideas or bugs or collaboration please do not hesitate to contact me!

Antonis Giannopoulos, 2005
1 PML

2 The

boundaries were introduced for GprMax3D with Version 1.5
executables are serial versions due to licensing of OpenMP compilers. Contact me for more information.

Acknowledgements
I would like to thank the Building Research Establishment (BRE) UK, for providing me with the
financial support to develop GprMax2D/3D after completing my D.Phil thesis on GPR modelling at the University of York. Without their support which helped to develop the core of the
GprMax programmes this current release today would not have been possible.

Contents
1 Installation and Getting Started

1

1.1

Contents of the CD-ROM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1

1.2

Downloading from the Website . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1

1.3

Running GprMax2D/3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2

1.4

General structure of the input file . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2

2 Ground Penetrating Radar modelling with GprMax2D/3D

4

2.1

Basic concepts of GPR modelling . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4

2.2

Assumptions for the modelling of GPR in two and three dimensions . . . . . . . .

6

2.3

Capabilities and limitations of GprMax2D/3D . . . . . . . . . . . . . . . . . . . .

7

2.4

GprMax2D coordinate system and conventions . . . . . . . . . . . . . . . . . . . .

7

2.5

GprMax3D coordinate system and conventions . . . . . . . . . . . . . . . . . . . .

8

2.6

Hints and tips for GPR modelling with GprMax2D/3D . . . . . . . . . . . . . . .

8

3 GprMax2D input file commands

11

3.1

General notes on GprMax2D commands . . . . . . . . . . . . . . . . . . . . . . . .

11

3.2

List of all available commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

12

3.3

GprMax2D command parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13

3.3.1

General commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13

3.3.2

ABC related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

17

3.3.3

Media and Object construction commands . . . . . . . . . . . . . . . . . . .

19

3.3.4

Excitation and output commands . . . . . . . . . . . . . . . . . . . . . . . .

22

4 GprMax3D input file commands

27

4.1

General notes on GprMax3D commands . . . . . . . . . . . . . . . . . . . . . . . .

27

4.2

List of all available commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

27

4.3

GprMax3D command parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . .

29

4.3.1

General commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

29

4.3.2

ABC related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

30

i

4.3.3

Media and Object construction commands . . . . . . . . . . . . . . . . . . .

31

4.3.4

Excitation and output commands . . . . . . . . . . . . . . . . . . . . . . . .

36

5 GprMax2D/3D modelling examples

43

5.1

Single rebar in concrete. – 2D model . . . . . . . . . . . . . . . . . . . . . . . . . . .

43

5.2

Other 2D examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

46

5.2.1

BRE example #2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

47

5.2.2

BRE example #4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

49

5.3

Snapshots of the electric field of a horizontal dipole over a dielectric half-space. –
3D model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

50

5.4

GPR response of a small void. – 3D model . . . . . . . . . . . . . . . . . . . . . . . .

51

6 GprMax2D/3D Output File formats

55

6.1

GprMax2D/3D Binary format file header . . . . . . . . . . . . . . . . . . . . . . .

55

6.2

GprMax2D BINARY file formats . . . . . . . . . . . . . . . . . . . . . . . . . . . .

56

6.3

GprMax2D ASCII file formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

59

6.4

GprMax3D BINARY file formats . . . . . . . . . . . . . . . . . . . . . . . . . . . .

59

6.5

GprMax3D ASCII file formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

63

A GprMax2D/3D Media file

64

B GprMax2D/3D Constants and excitation functions

66

GprMax2D/3D Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

66

Excitation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

67

C MATLAB functions for GprMax2D/3D

68

Bibliography

69

ii

Figures
2.1

The 3D FDTD Yee cell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5

2.2

The 2D GPR forward problem and its GprMax2D domain bounded by ABCs . . .

6

2.3

Schematic of the GprMax2D coordinate system and conventions (see text). The
components included in the oval shaped area are the ones which correspond to
space coordinate 3 (∆x = ∆y = 1 metre). . . . . . . . . . . . . . . . . . . . . . . . .

8

Schematic of the GprMax3D coordinate system and conventions. The depicted
field components are the ones which correspond to space coordinate 1. (∆x =
∆y = ∆z = 1 metre) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

9

5.1

Schematic drawing of the rebar in concrete problem. . . . . . . . . . . . . . . . . . .

44

5.2

Normalized power spectrum and time waveform of the ricker excitation function. The centre frequency is 900 MHz. . . . . . . . . . . . . . . . . . . . . . . . . . .

45

5.3

Simulated GPR scan by GprMax2D (left) and image representation of the geometry of the model (right). Note that the vertical scale is exaggerated. . . . . . . . . .

47

5.4

Schematic drawing of the BRE examples 1 and 2 . . . . . . . . . . . . . . . . . . . .

48

5.5

Schematic drawing of the BRE examples 3 and 4 . . . . . . . . . . . . . . . . . . . .

49

5.6

Image produced using the information in the geometry file of the BRE examples 1
and 2 (Note vertical scale is exaggerated). . . . . . . . . . . . . . . . . . . . . . . . .

50

5.7

Image produced using the information in the geometry file of the BRE examples 3
and 4 (Note vertical scale is exaggerated). . . . . . . . . . . . . . . . . . . . . . . . .

51

5.8

Simulated GPR scan of the BRE second example. . . . . . . . . . . . . . . . . . . . .

52

5.9

Simulated GPR scan of the BRE fourth example. . . . . . . . . . . . . . . . . . . . .

53

5.10 Three slices through a volume of data. The amplitude of the Ex field component is
represented as a gray scale image. The figure was created in MATLAB from the
GprMax3D data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

53

5.11 Schematic drawing of the 3D model of a small void (after [1]) . . . . . . . . . . . .

54

5.12 GprMax3D simulated GPR scan over a small void . . . . . . . . . . . . . . . . . .

54

2.4

6.1

Representation in pseudo-code of the procedure used in GprMax2D in order to
store the values of field components in a snapshot . . . . . . . . . . . . . . . . . . .

58

6.2

Representation in pseudo-code of the procedure used in GprMax3D in order to
store the values of field components in a snapshot . . . . . . . . . . . . . . . . . . .

62

iii

Chapter 1

Installation and Getting Started
This chapter describes the installation procedure for GprMax2D/3D.

1.1

Contents of the CD-ROM

If you have obtained a CD-ROM distribution of GprMax then in order to install the right executable for your computer locate the directory which describes your operating system and copy
the file(s) into a suitable directory in your machine.
Linux users should copy the binaries GprMax2D and GprMax3D found in the Linux directory of
the CD-ROM into a suitable directory on their system - preferably one in your path - For example
at: /usr/local/bin1. The GprMax executable should work on all recent Linux distributions
but it has only been tested on RedHat Enterprise 4
MS Windows 9x/2000/NT/XP users should copy the three files GprMax2D.exe, GprMax3D.exe
and cygwin1.dll found under the Windows directory into a suitable directory on the system’s
hard disk (e.g. GprMax). The latter file is required since GprMax has been compiled using Cygwin for the MS Windows platform. Alternatively you can copy the cygwin1.dll file into your
Windows system directory.
Mac Os X users should copy the files found in the MacOs directory to an appropriate location
on their system. GprMax2D/3D binaries for macs have not been tested as I do not have access
to a mac!
In the directory manual there is a copy of this manual in Adobe PDF format. If you do not have
the free Adobe Acrobat Reader you can download it from www.adobe.com
In the directory examples some input files used as examples in this manual have been included.
The directory media contain a sample media file and in the directory tools there are some MATLAB functions that can be used to import GprMax2D/3D modelled data, stored in binary format, in MATLAB.

1.2

Downloading from the Website

If you have downloaded the compressed .zip archive from the GprMax website at www.gprmax.org
or www.gprforum.org or from my web page at www.see.ed.ac.uk/˜agianno follow the
same procedures as described above for the CD-ROM distribution after uncompressing it to a
directory of your preference.
1 That will require root privileges. If you do not known the root password then you can run the program from a
directory in your home space.

1

1.3

Running GprMax2D/3D

To run a 2D or 3D GPR model using GprMax2D/3D you have to create an input file in which
the parameters of the model are specified. This input file is a plain ASCII text file and should
have a valid filename of your preference. The structure of this input file is explained in detail in
subsequent chapters.
To run the programs in an MS Windows environment open a system (DOS) command window.
In recent MS Windows OS versions you can open a command window by clicking on the Run..
option and typing cmd. At the command window then type at the prompt:
GprMax2D your_path\your_input_file
The your_path can be the absolute path where the input file is located or the relative path where
the input file is located with respect to the directory you are currently in. For example, assume
your executable image of GprMax2D is located in the directory C:\GprMax\Bin and assume
that your input file is in the directory C:\GPRModels\Inputs and is called Model1.in . If your
current directory is C:\GprMax you can issue the commands:
Bin\GprMax2D C:\GPRModels\Inputs\Model1.in
or
Bin\GprMAx2D ..\GPRModels\Inputs\Model1.in
in case you have included in your PATH the directory C:\GprMax\Bin then you can type:
GprMax2D C:\GPRModels\Inputs\Model1.in
or
GprMax2D ..\GPRModels\Inputs\Model1.in
To run the programs in a Linux environment follow the same procedure as for an MS-Windows
system2 .

1.4

General structure of the input file

The input file which has to be supplied to GprMax2D/3D contains all the necessary information
to run a GPR model. Detailed description of the various commands available that can be used in
GprMax2D/3D input files are described later in this manual. However, the general structure of
an input file is the same in both programs.
The input file is a plain ASCII text file which can be prepared with any editor or word-processing
program. In the input file the hash character (#) is reserved and is used to denote the beginning of a command which should be passed to the programs. The general syntax of all available
commands is:
#command_name: parameter1 parameter2 parameter3 ...
For example, in GprMax2D the size of the computational domain is specified with a command
2 Directory

names are separated by a / on a Linux system and device names like (C:) are not used.

2

#domain: 1.0 1.0
A command with its parameters should occupy a single line of the input file and only one command per line is allowed. Hence the first character of a line containing a command must be the
hash character (#). If the line starts with any other character it is ignored by the program. Therefore, user comments or descriptions can be included in the input file. If a line starts with a hash
character (#) the program will expect a valid command. In case the command is not spelt correctly
the program will abandon execution issuing an error message. When a command requires more
than one parameter then these are separated using a white space character.
The order of introducing commands into the input file is not important with the exception of
model building commands and execution (i.e. analysis) group commands which will be described
in the relevant Chapter (3). Moreover, as will be explained later, introducing particular commands
before others will facilitate the creation of any desired GPR model.

3

Chapter 2

Ground Penetrating Radar modelling
with GprMax2D/3D
This chapters discusses some basic concepts of GPR modelling using GprMax2D/3D. To accomplish such a task GprMax2D/3D solve Maxwell’s equations using the finite-difference time-domain
method (FDTD). Detailed information about the use of FDTD for GPR modelling can be found in
[1] and general information on the FDTD method in [2] and [3].

2.1

Basic concepts of GPR modelling

All electromagnetic phenomena, on a macroscopic scale, are described by the well known Maxwell’s
equations . These are first order partial differential equations which express the relations between
the fundamental electromagnetic field quantities and their dependence on their sources.
(2.1)
(2.2)
(2.3)
(2.4)

∂B
∂t
∂D
+ Jc + Js
∇×H=
∂t
∇·B=0
∇×E=−

∇ · D = qv

where t is time (seconds) and qv is the volume electric charge density (coulombs/ cubic meter).
In Maxwell’s equations, the field vectors are assumed to be single-valued, bounded, continuous
functions of position and time. In order to simulate the GPR response from a particular target or
set of targets the above equations have to be solved subject to the geometry of the problem and
the initial conditions.
The nature of the GPR forward problem classifies it as an initial value – open boundary problem.
This means that in order to obtain a solution one has to define an initial condition (i.e. excitation
of the GPR transmitting antenna) and allow for the resulting fields to propagate through space
reaching a zero value at infinity since, there is no specific boundary which limits the problem’s
geometry and where the electromagnetic fields can take a predetermined value. Although the
first part is easy to accommodate (i.e. specification of the source), the second part can not be
easily tackled using a finite computational space.
The FDTD approach to the numerical solution of Maxwell’s equations is to discretize both the
space and time continua. Thus the discretization spatial ∆x, ∆y and ∆z and temporal ∆t steps
play a very significant role – since the smaller they are the closer the FDTD model is to a real
representation of the problem. However, the values of the discretization steps always have to be
4

Ex

(i,j+1,k-1)

(i+1,j+1,k-1)

Hy

Ez

Ez

Ex

(i,j+1,k)

Hz

Ey
Hx

Ey

Ey
Hx

Hz

Ey
(i+1,j,k-1)

Ex

Hy

Ez

y

Ez
x

(i,j,k)

(i+1,j,k)

Ex

z

Figure 2.1: The 3D FDTD Yee cell

finite, since computers have a limited amount of storage and finite processing speed. Hence, the
FDTD model represents a discretized version of the real problem and of limited size. The building
block of this discretized FDTD grid is the Yee cell [4] named after Kane Yee who pioneered the
FDTD method. This is illustrated for the 3D case in Figure 2.1. The 2D FDTD cell is a simplification
of the 3D one and is depicted in Figure 2.3.
By assigning appropriate constitutive parameters to the locations of the electromagnetic field components complex shaped targets can be included easily in the models. However, objects with
curved boundaries are represented using a staircase approximation.
The numerical solution is obtained directly in the time domain by using a discretized version
of Maxwell’s curl equations which are applied in each FDTD cell . Since these equations are
discretized in both space and time the solution is obtained in an iterative fashion. In each iteration
the electromagnetic fields advance (propagate) in the FDTD grid and each iteration corresponds
to an elapsed simulated time of one ∆t. Hence by specifying the number of iterations one can
instruct the FDTD solver to simulate the fields for a given time window.
The price one has to pay of obtaining a solution directly in the time domain using the FDTD
method is that the values of ∆x, ∆y, ∆z and ∆t can not be assigned independently. FDTD is
a conditionally stable numerical process. The stability condition is known as the CFL condition
after the initials of Courant, Freidrichs and Lewy and is
(2.5)

∆t ≤ q
1
c (∆x)
2 +

1
1
(∆y)2

+

1
(∆z)2

where c is the speed of light. Hence ∆t is bounded by the values of ∆x, ∆y and ∆z. The stability
condition for the 2D case is easily obtained by letting ∆z −→ ∞.

One of the most challenging issues in modelling open boundary problems as the GPR one is the
truncation of the computational domain at a finite distance from sources and targets where the
values of the electromagnetic fields can not be calculated directly by the numerical method applied inside the model. Hence, an approximate condition known as absorbing boundary condition
(ABC) is applied at a sufficient distance from the source to truncate and therefore limit the computational space. The role of this ABC is to absorb any waves impinging on it, hence simulating
an unbounded space. The computational space (i.e the model) limited by the ABCs should contain all important features of the model such as sources and output points and targets. Figure 2.2
5

  
ABC





antenna
Air

target

Figure 2.2: The 2D GPR forward problem and its GprMax2D domain bounded by ABCs

illustrates this basic difference between the problem to be modelled and the actual FDTD modelled space. In Figure 2.2 it is assumed that the half-space which contains the target(s) is of infinite
extent. Therefore, the only reflected waves will be the ones originating from the target. In cases
where the host medium is not of infinite extent (e.g. a finite concrete slab) the assumption of infinite extent can be made as far as the actual reflections from the slab termination are not of interest
or its actual size is large enough that any reflected waves which will originate at its termination
will not affect the solution for the required time window. In general, any objects that span the
size of the computational domain (i.e. model) are assumed to extend to infinity. The only reflections which will originate from their termination at the truncation boundaries of the model are
due to imperfections of the ABCs and in general are of a very small amplitude compared with the
reflections from target(s) inside the model.
All other boundary conditions which apply at interfaces between different media in the FDTD
model are automatically enforced in GprMax2D/3D.

2.2

Assumptions for the modelling of GPR in two and three dimensions

In constructing a GPR model in two and three dimensions, some assumptions are necessary.
These mainly result from the need to keep the amount of computational resources, required by
the model, to a manageable level and to facilitate the study of the important features of the GPR
response to a target, without cluttering the solution with details which will obscure the fundamental response. However, GprMax2D/3D can easily handle more “complicated” GPR modelling
scenarios if required. The assumptions made for both GprMax2D and GprMax3D models are:
• all media are considered to be linear and isotropic.

• In GprMax3D if the physical structure of the GPR antenna is not included in the model
then the antenna is modelled as an ideal Hertz dipole (i.e. a small current source) . In
GprMax2D the transmitting antenna is modelled as a line source. Using a Hertz dipole in
GprMax3D results in reducing the computational resources required to run a 3D model in
reasonable time, whereas in the GprMax2D case the use of a line source is a consequence
of the assumption of the invariance of the problem in one direction.
• the constitutive parameters are, in most cases, assumed not to vary with frequency. This
assumption simplifies a time domain model. However, a formulation able to handle a Drude
(i.e. Debye plus a constant conductivity) relaxation model for the complex permittivity is
included in both GprMax2D and GprMax3D.

6

Therefore, for the 2D case the governing equations reduce to the ones describing the propagation
of T M mode electromagnetic waves (relative to the invariance direction (z) of the model).

2.3

Capabilities and limitations of GprMax2D/3D

In general, GprMax2D/3D solve numerically Maxwell’s equations in two (T Mz case) and three
dimensions. Any linear, isotropic media with constant constitutive parameters can be included
in the model. In addition they can model dielectrics with frequency depended permittivity described by the Debye formula
(2.6)

 = ∞ +

s −  ∞
1 + ωτ

where ∞ is the permittivity at light frequencies, s is the DC permittivity and ω is the angular
frequency. The computational domain of both GprMax2D/3D could be truncated either using a third order Higdon local absorbing boundary condition (ABC) or by introducing Perfectly
Matched Layers (PML) in the model. The default is the Higdon ABC however the performance of
the PML is superior especially if more than six (6) layers are used. The parameters of the Higdon
ABC can be altered if required using simple commands. In the case of PML only the number of
layers of the PML is adjustable by the user.
Excitation of a model in GprMax2D is achieved by specifying the current of a line source. In
GprMax3D - when a Hertzian dipole is used - excitation is achieved by specifying the current
and polarisation of the small Hertzian dipole. More than one sources can be active at a given
time thus making simulation of GPR arrays simple. There is a choice of excitation waveforms for
GprMax2D/3D. In addition the user can specify its own excitation function.
The discretization of the GprMax2D/3D models can be different in the direction of each coordinate axis but can not vary along this direction. The smallest element in GprMax2D which can be
allocated with user defined characteristics is an area of ∆x × ∆y and in GprMax3D a volume of
∆x × ∆y × ∆z. For a list of the technical characteristics of GprMax2D/3D see Appendix B.

2.4

GprMax2D coordinate system and conventions

The GprMax2D FDTD algorithm is implemented in the (x-y) plane. The origin of the coordinate
system is the lower left corner at (0,0). The smallest space that can be allocated to represent a
specific medium is a 2D cell (∆x × ∆y). The reference point of the 2D cell is its centre. However,
the space coordinates range from the left edge of the first cell to the right edge of the last one. In
Figure 2.3 the coordinate system of GprMax2D is schematically presented. Only one row of cells
in the x direction is depicted. Assuming that ∆x = 1 metre, if one wants to allocate a rectangle
with its x dimension equal to 3 metres and 1 as its lower x coordinate the x range is [1..4]. The 2D
cells allocated by GprMax2D are [1..3]. When source or output positions are specified in space
coordinates they correspond directly to cell coordinates. It is important to remember that for a
given set of space coordinates (x,y) the actual position of the electromagnetic field components
are:
• (x +

• (x +

∆x
2 ,y

+

∆x
2 ,y)

• (x,y +

∆y
2 )

∆y
2 )

for Ez

for Hx
for Hy

due to the staggered arrangement of field components in the FDTD algorithm. Therefore, the
interface between two cells of different constitutive parameters is located on the positions of the
magnetic field components. Further, it is important to remember that all sources are actually
located at the positions of the Ez field component.
7

Allocated Cells
0

0

1

2

1

2

3

3

4

4

5

5

6

6

7

7

8

8

Range for space coordinates

9

9

Cell coordinates

10

Space coordinats

Hy

Hx

Ez

z
x
Figure 2.3: Schematic of the GprMax2D coordinate system and conventions (see text). The components
included in the oval shaped area are the ones which correspond to space coordinate 3 (∆x =
∆y = 1 metre).

2.5

GprMax3D coordinate system and conventions

The coordinate system used in GprMax3D is a right-handed Cartesian. The origin of space
coordinates is (0,0,0) and the analogy between space coordinates and 3D FDTD cells is very similar
to the one in GprMax2D explained above. The difference in GprMax3D is that the 3D FDTD cell
is rather more complicated than in the 2D case and there are no field components located at the
centre of the cell. At interfaces between cells the electric field components are tangential to them
and the magnetic field components are normal to them. Source and output points defined in space
coordinates are directly converted to cell coordinates and the corresponding field components are
depicted in Figure 2.4. The actual position of field components for a given set of space coordinates
(x,y,z) are:
• (x +

∆x
2 ,y,z)

for Ex

• (x,y +

∆y
2 ,z)

for Ey

∆z
2 )

for Ez

• (x,y +

∆y
2 ,z

+

∆z
2 )

for Hx

∆x
2 ,y,z

+

∆z
2 )

for Hy

∆y
2 ,z)

for Hz

• (x,y,z +

• (x +

• (x +

∆x
2 ,y

+

It should be noted that Hertzian dipole sources as well as other electric field excitations (i.e. voltage sources, transmission lines) are actually located at the corresponding electric field components.

2.6

Hints and tips for GPR modelling with GprMax2D/3D

In order to make the most of GprMax2D/3D in modelling GPR responses ultimately one should
be familiar with the FDTD method on which these programs are based. There is a very large
amount of information available in the relevant literature. Good starting points are [2] and [3]
where as the specific application of FDTD to the GPR forward problem is described in [1].
8

Allocated Cells

1

0

1

2

3

4

Cell coordinates

1
0

1

2

3

4

Range for space coordinates

5

Space coordinates

electric field components

z

magnetic field components
y
x

Figure 2.4: Schematic of the GprMax3D coordinate system and conventions. The depicted field components are the ones which correspond to space coordinate 1. (∆x = ∆y = ∆z = 1 metre)

This manual, can not serve as an in depth tutorial and a review of the FDTD method. However,
some useful hints and tips are given here in order to cover the most fundamental aspects of using
an FDTD based program and avoid the most common errors.
Discretization
There is no specific guideline for choosing the right discretization for a given problem. In general,
it depends on the required accuracy, the frequency content of the source’s pulse and the size of
the targets. Obviously, all targets present in a model must be adequately resolved. This means,
for example, that a cylinder with radius equal to one or two spatial steps does not really look like
a cylinder!
An other important factor which influences the discretization is the errors associated with numerical induced dispersion. This means that contrary to the real world where electromagnetic
waves propagate with the same velocity irrespectively of their direction and frequency (assuming
no dispersive media and far-field conditions) in the discrete one this is not the case. This error
(details can be found in [1] and [2]) can be kept in a minimum if the following rule of thumb is
satisfied:
the discretization step should be at least ten times smaller than the smallest wavelength of the propagating electromagnetic fields.
Note that in general low-loss media wavelengths are much smaller compared to free space. The
above rule is described by the equation:
(2.7)

∆l =

λ
10

Absorbing boundary conditions
The ABCs employed in GprMax2D/3D will, in general, perform well (i.e. without introducing
significant artificial reflections) if all sources and targets are kept at least 15 cells away from them.
The formulation of the type of ABCs employed in GprMax2D/3D does not take into account
any near-field effects which dominate close to radiation centres (i.e. sources and targets).
9

Form Version 2.0 Perfectly Matched Layer (PML) absorbing boundaries could be used in GprMax2D
as well as in GprMax3D. These layers which have a user adjustable thickness absorb very efficiently most waves that propagate in them. Although, source and output points can be specified
inside these layers it is wrong to do so from the point of view of correct modelling. The fields
inside these layers are not of interest to GPR modelling. Placing sources inside these layers could
have effects that have not been studied and will certainly provide erroneous results from a GPR
modeller’s point of view.
The above requirements have to be taken into account when the size of the model is to be decided.
Further, for the same reason, free space (i.e. air) should be always included above a source for at
least 15 to 20 cells in both GprMax2D and GprMax3D GPR models.
Obviously, the more cells there are between observation points, sources, targets and the absorbing
boundaries the better the results will be.

10

Chapter 3

GprMax2D input file commands
3.1

General notes on GprMax2D commands

In order to describe the GprMax2D commands and their parameters the following conventions
are used:
• f means a real number which can be entered using either a [.] separating the integral from
the decimal part (e.g. 1.5) or in scientific notation as 15e-1 or 0.15e1
• i means an integer number

• c means a single character (e.g. y)

• str means a string of characters with no white spaces in between (e.g sand)
• file means a filename to be supplied by the user

☞ All parameters associated with simulated space (i.e. size of model, spatial increments, e.t.c.)
should be specified in metres.
☞ All parameters associated with time (i.e. total simulation time, time instants, e.t.c) should
be specified in seconds.
☞ All parameters denoting frequency should be specified in Hertz.
☞ All parameters associated with spatial coordinates in the model should be specified in metres. The origin of the coordinate system (0,0) is at the lower left corner of the model.
It is important to note that GprMax2D converts spatial and temporal parameters given in metres and seconds respectively to integer values corresponding to FDTD cell coordinates and iteration number. Therefore, rounding to the nearest integer number of the user defined values is
performed.
There are no optional parameters within a command. Even if some parameters will not be affecting the model’s values they have to be supplied.
The order which the commands appear in the input file is not significant with the single exception of the #analysis: and #end_analysis: commands which since Version 2.0 specify the
excitation and outputs of the model.
The fundamental spatial and temporal discretization steps are denoted as ∆x , ∆y and ∆t respectively.
11

3.2

List of all available commands

In order to construct a 2D GPR model using GprMax2D a set of commands are available which
can be used to give the necessary instructions to the program.
The are 32 commands available in Version 2.0 of GprMax2D :
#title:
#domain:
#dx_dy:
#time_step_stability_factor:
#time_window:
#messages:
#number_of_media:
#nips_number:
#media_file:
#geometry_file:
#medium:
#abc_type:
#abc_order:
#abc_stability_factors:
#abc_optimization_angles:
#abc_mixing_parameters:
#pml_layers:
#box:
#cylinder:
#x_segment:
#y_segment:
#triangle:
#analysis:
#end_analysis:
#tx:
#rx:
#rx_box:
#snapshot:
#tx_steps:
#rx_steps:
#line_source:
#excitation_file:
the parameters that each command requires is explained in the following section.
There are some GprMax commands that have been retired from Version 2.0 onwards and will not
function anymore in GprMax2D. Their functionality has been replaced by new more enhanced
structures and commands. The commands that have been “retired” and are not functioning
anymore are:
#scan:
12

#csg:
#extra_tx:
In addition some of the old commands have changed in terms of the number of parameters they
take. These are:
#tx:
#snapshot:

3.3

GprMax2D command parameters

To aid the presentation of GprMax2D commands they have been grouped in four categories:
➀ General commands which include the ones used to specify the size and discretization of the
model.
➁ ABC related commands which allow the customisation and optimisation of the absorbing
boundary conditions.
➂ Media and Object construction commands which are used to introduce different media in the
model and construct simple geometric shapes with different constitutive parameters.
➃ Excitation and Output commands which are used to place source and output points in the
model.
Most of the commands are optional with the exception of the ones which are necessary in order to
construct the simplest model possible. For example, none of the commands of the Media and Object
construction section are necessary to run a model. However, without specifying any objects in the
model GprMax2D simulates a free space (air) region not of particular use for GPR modelling.
If you have not specified a command which is essential in order to run a model, for example the
size of the model, GprMax2D will terminate execution issuing an appropriate error message.
☞ The essential commands which represent the minimum set of commands required to run
GprMax2D are:
• #domain:
• #dx_dy:

• #time_window:

• At least one #analysis: with the corresponding #end_analysis: commands enclosing at least one #tx: and one #rx: and/or #rx_box: commands
• In order for the #tx: command to function properly a new #line_source: command is required as well.

3.3.1

General commands

#title:
With the command #title you can include a title for your model. This title is saved in the output
file(s). The syntax of the command is:
#title: str
The parameter str here can contain white space characters to separate individual words. The
title has to be contained in a single line.
13

#domain:
The command #domain: should be used to specify the size in metres of the model. Its syntax is:
#domain: f1 f2
The parameters f1 and f2 are the size in metres of your model in the x and y direction respectively. For example:
#domain: 1.0 1.5
will set the size of the model to be 1.0 × 1.5 metres.
#dx dy:
The command #dx_dy is used to specify the discretization of space in the x and y directions
respectively (i.e. ∆x and ∆y). The syntax of this command is:
#dx_dy: f1 f2
where f1 is the spatial step in the x direction (∆x) and f2 is the spatial step in the y direction
(∆y). Hence a command as
#dx_dy: 0.1 0.1
will set the discretization steps ∆x and ∆y to 10 centimetres in each direction. The choice of
the discretization steps ∆x and ∆y is very important in constructing a model. This command
combined with the #domain command determines the number of cells which are going to be
used in the model and consequently the greatest part of the requirements for computer memory
for the model. For example using the commands:
#domain: 1.0 1.5
#dx_dy: 0.1 0.1
The number of cells in the model will be 10 × 15. Changing the above to
#domain: 1.0 1.5
#dx_dy: 0.01 0.01
the number of cells in the model will increase to 100 × 150. Further, the spatial discretization
controls the maximum permissible time step ∆t with which the solution advances in time to
reach the required simulated time window. The relation between ∆t and ∆x,∆y is
(3.1)

1
∆t ≤ q
1
c (∆x)2 +

1
(∆y)2

where c is the speed of light. In GprMax2D the equality is used in 3.1 to determine ∆t from ∆x
and ∆y. As is evident from 3.1 small values of ∆x and ∆y result in small values for ∆t which
means more iterations in order to reach a given simulated time. However, it is important to note
that the smaller the values of ∆x, ∆y and ∆t are the more accurate your model will be.

14

#time step stability factor:
With the command time_step_stability_factor: you can alter the value of the time step
∆t calculated by GprMax2D. However, the new value should be within the allowable range for
stability determined by equation 3.1. As it was mentioned above, GprMax2D uses the equality
in equation 3.1 hence the maximum permissible time step. If a smaller time step is required then
the command
#time_step_stability_factor: f1
allows you to accomplish this. The parameter f1 can take values 0  Higher) {
For all the Y coordinates (Lower -> Higher) {
WRITE value
}
}
Figure 6.1: Representation in pseudo-code of the procedure used in GprMax2D in order to store the values
of field components in a snapshot

• The lower left y coordinate of the snapshot area expressed in cell coordinates in an int

• The upper right x coordinate of the snapshot area expressed in cell coordinates in an int

• The upper right y coordinate of the snapshot area expressed in cell coordinates in an int
• The sampling interval in the x direction, normalized by ∆x, stored in an int
• The sampling interval in the y direction, normalized by ∆y, stored in an int

• The time instant when the snapshot has been taken, normalized by ∆t (i.e. iteration number), stored in a float
• The number of samples in the x direction in an int

• The number of samples in the y direction in an int

• The values of the Ez electromagnetic field component each stored in a float at every x, y
sampling point. Figure 6.1 illustrates in pseudo-code the procedure used to store the values
of the field component.
• The values of the Hx electromagnetic field component each stored in a float at every x, y
sampling point. Figure 6.1 illustrates in pseudo-code the procedure used to store the values
of the field component.
• The values of the Hy electromagnetic field component each stored in a float at every x, y
sampling point. Figure 6.1 illustrates in pseudo-code the procedure used to store the values
of the field component.

Geometry output file
The geometry file is always stored in binary format. After the header, information is stored as
follows:
• The title of the model in a string of TITLELENGTH bytes

• The number of iterations (NI) which have been performed in an float
• The spatial step ∆x in a float
• The spatial step ∆y in a float

• The time step ∆t in a float

• The number of cells (NX)4 in the x direction in an int

4 Note that the number of cells reported in the geometry file ranges from [1..NX]. Internally GprMax2D uses the range
[0..NX-1] according to the coordinate system.

58

• The number of cells (NY) in the y direction in an int

• The number of different media (PMEDIA) present in the model in an int

• A list PMEDIA long of medium identifiers. Its medium identifier is stored in a string of
MEDIALENGTH characters (bytes).

• A cell ID stored in int (2 bytes) for every cell in the model. The loop structure shown in
Figure 6.1 is used to store these values. Each cell ID corresponds to an entry ([1..PMEDIA])
in the list of different media.

6.3

GprMax2D ASCII file formats

The ASCII output files can be edited with any text editor or word processing software and the
information stored in them is in general self-explanatory.

6.4

GprMax3D BINARY file formats

The file formats of GprMax3D differ from GprMax2D since information for the polarisation of
the source has to be included in addition to the need to store all six components of the electromagnetic fields. The basic structure of the files however, is very similar.
#analysis: BINARY output file
After the header, information is stored as follows:
• The title of the model in a string of TITLELENGTH bytes

• The number of iterations (NI) which have been performed in an float
• The spatial step ∆x in a float
• The spatial step ∆y in a float

• The spatial step ∆z in a float

• The time step ∆t in a float

• The number of steps in the #analysis: command (NSTEPS) in an int

• The step in the x direction with which the source point moves for each trace, normalized by
∆x, stored in an int
• The step in the y direction with which the source point moves for each trace, normalized by
∆y, stored in an int
• The step in the z direction with which the source point moves for each trace, normalized by
∆z, stored in an int
• The step in the x direction with which the output point (receiver) moves for each trace,
normalized by ∆x, stored in an int
• The step in the y direction with which the output point (receiver) moves for each trace,
normalized by ∆y, stored in an int
• The step in the z direction with which the output point (receiver) moves for each trace,
normalized by ∆z, stored in an int
• The number of transmitters specified with #tx: commands (NTX) in an int
59

• The number of receivers specified with #rx: commands (NRX) in an int

• The number of receiver box volume regions specified with #rx_box: commands (NRXBOX)
in an int
• For each one of the Transmitters (sources) #tx: in the analysis
– The polarization of the source x, y or z in a char

– The x coordinate of the source expressed in cell coordinates in an int
– The y coordinate of the source expressed in cell coordinates in an int
– The z coordinate of the source expressed in cell coordinates in an int
– The source type (i.e. the source ID) in a string of SOURCELENGTH bytes
– The initial source time delay as float
– The time of source removal as float
• For each one of the number of Receivers #rx in the analysis

– The x coordinate of the receiver expressed in cell coordinates in an int

– The y coordinate of the receiver expressed in cell coordinates in an int
– The z coordinate of the receiver expressed in cell coordinates in an int
• For each one of the number of Receiver Box regions #rx_box in the analysis

– The total number of output points for this box output region (NRXBOXOUT) in an int

– The x coordinate of each receiver in this box expressed in cell coordinates in an int
– The y coordinate of each receiver in this box expressed in cell coordinates in an int
– The z coordinate of each receiver in this box expressed in cell coordinates in an int
• All six components of the electromagnetic fields Ex , Ey , Ez , Hx , Hy and HZ as well as the
currents Ix , Iy and Iz calculated as (∇ × H)x (∇ × H)y , (∇ × H)z respectively at electric field
component locations and each stored in a float in that order, for every output point (NRX)
and then for every output point defined in each #rx_box: (NRXBOXOUT), at every time
step, for a total of (NI) time steps and a total of (NSTEPS) runs in the analyis.
#snapshot: BINARY output file
After the header, information is stored as follows:
• The title of the model in a string of TITLELENGTH bytes

• The number of iterations (NI) which have been performed in an float
• The spatial step ∆x in a float
• The spatial step ∆y in a float

• The spatial step ∆z in a float

• The time step ∆t in a float

• The global source position number of the snapshot in an int

• The lower left x coordinate of the snapshot area expressed in cell coordinates in an int

• The lower left y coordinate of the snapshot area expressed in cell coordinates in an int
60

• The lower left z coordinate of the snapshot area expressed in cell coordinates in an int

• The upper right x coordinate of the snapshot area expressed in cell coordinates in an int

• The upper right y coordinate of the snapshot area expressed in cell coordinates in an int
• The upper right z coordinate of the snapshot area expressed in cell coordinates in an int
• The sampling interval in the x direction, normalized by ∆x, stored in an int
• The sampling interval in the y direction, normalized by ∆y, stored in an int

• The sampling interval in the z direction, normalized by ∆z, stored in an int

• The time instant when the snapshot has been taken, normalized by ∆t (i.e. iteration number), stored in a float
• The number of samples in the x direction in an int

• The number of samples in the y direction in an int
• The number of samples in the z direction in an int

• The values of the Ex electromagnetic field component each stored in a float at every x, y, z
sampling point. Figure 6.2 illustrates in pseudo-code the procedure used to store the values
of the field component.
• The values of the Ey electromagnetic field component each stored in a float at every x, y, z
sampling point. Figure 6.2 illustrates in pseudo-code the procedure used to store the values
of the field component.
• The values of the Ez electromagnetic field component each stored in a float at every x, y, z
sampling point. Figure 6.2 illustrates in pseudo-code the procedure used to store the values
of the field component.
• The values of the Hx electromagnetic field component each stored in a float at every x, y, z
sampling point. Figure 6.2 illustrates in pseudo-code the procedure used to store the values
of the field component.
• The values of the Hy electromagnetic field component each stored in a float at every x, y, z
sampling point. Figure 6.2 illustrates in pseudo-code the procedure used to store the values
of the field component.
• The values of the Hz electromagnetic field component each stored in a float at every x, y, z
sampling point. Figure 6.2 illustrates in pseudo-code the procedure used to store the values
of the field component.
• The values of the Ix current calculated at an electric field component location as (∇ × H)x
each stored in a float at every x, y, z sampling point. Figure 6.2 illustrates in pseudo-code
the procedure used to store the values of the current component.
• The values of the Iy current calculated at an electric field component location as (∇ × H)y
each stored in a float at every x, y, z sampling point. Figure 6.2 illustrates in pseudo-code
the procedure used to store the values of the current component.
• The values of the Iz current calculated at an electric field component location as (∇ × H)z
each stored in a float at every x, y, z sampling point. Figure 6.2 illustrates in pseudo-code
the procedure used to store the values of the current component.

61

For all the X coordinates (Lower -> Higher) {
For all the Y coordinates (Lower -> Higher) {
For all the Z coordinates (Lower -> Higher) {
WRITE value
}
}
}
Figure 6.2: Representation in pseudo-code of the procedure used in GprMax3D in order to store the values
of field components in a snapshot

Geometry output file
The geometry file is always stored in binary format. After the header, information is stored as
follows:
• The title of the model in a string of TITLELENGTH bytes

• The number of iterations (NI) which have been performed in an float
• The spatial step ∆x in a float
• The spatial step ∆y in a float

• The spatial step ∆z in a float

• The time step ∆t in a float

• The number of cells (NX)5 in the x direction in an int

• The number of cells (NY) in the y direction in an int

• The number of cells (NZ) in the z direction in an int

• The number of different media (PMEDIA) present in the model in an int

• A list PMEDIA long of medium identifiers. Its medium identifier is stored in a string of
MEDIALENGTH characters (bytes).

• A cell ID stored in int (2 bytes) for every cell in the model. The loop structure shown in
Figure 6.2 is used to store these values. Each cell ID corresponds to an entry ([1..PMEDIA])
in the list of different media.
• A component ID stored in int (2 bytes) for the Ex field component. This ID can be used
to determine the extend of surfaces objects in GprMax3D. The ID corresponds to an entry
([1..PMEDIA]) in the list of different media. The range of this ID is [0..NX-1,0..NY,0..NZ]
• A component ID stored in int (2 bytes) for the Ey field component. This ID can be used
to determine the extend of surfaces objects in GprMax3D. The ID corresponds to an entry
([1..PMEDIA]) in the list of different media. The range of this ID is [0..NX,0..NY-1,0..NZ]
• A component ID stored in int (2 bytes) for the Ez field component. This ID can be used
to determine the extend of surfaces objects in GprMax3D. The ID corresponds to an entry
([1..PMEDIA]) in the list of different media. The range of this ID is [0..NX,0..NY,0..NZ-1]
5 Note that the number of cells reported in the geometry file ranges from [1..NX]. Internally GprMax3D uses the range
[0..NX-1] according to the coordinate system.

62

6.5

GprMax3D ASCII file formats

The ASCII output files can be edited with any text editor or word processing software and the
information stored in them is in general self-explanatory.

63

Appendix A

GprMax2D/3D Media file
The media file has the role of a simple database of frequently used materials. Media files can be
used in the same way in both GprMax2D and GprMax3D. The structure of media files is very
simple. Similarly to an input file, the hash character # is reserved.
Each definition of a medium parameters should occupy a single line in the media file. This line
must start with the hash # character. The parameters of the medium follow in the same order
which is required by a #medium: command (see Chapter 3). Hence, a general entry in a media
file looks like
# f1 f2 f3 f4 f5 f6 str1
the parameters are:
• f1 the DC (static) relative permittivity of the medium rs

• f2 the relative permittivity at theoretically infinite frequency r∞
• f3 the relaxation time of the medium τ (seconds)

• f4 the DC (static) conductivity of the medium σ (Siemens/metre)
• f5 the relative permeability of the medium µr

• f6 the magnetic conductivity of the medium σ ∗

• str1 a string characterizing the medium

The maximum length of the identifier str1 is determined by a constant (MEDIALENGTH) and
has been set to 30 characters. No white spaces are allowed in the identifier. Further, every identifier must be unique within a media file.
As an example, a media file constructed for some common materials according to tabulated values
[1] of their constitutive parameters at a frequency of 100 MHz is
#
#
#
#
#
#
#

80.0 0.0 0.0 0.01 1.0 0.0 distilled_water
80.0 0.0 0.0 0.5 1.0 0.0 fresh_water
80.0 0.0 0.0 3e4 1.0 0.0 sea_water
3.0 0.0 0.0 0.01 1.0 0.0 dry_sand_min
5.0 0.0 0.0 0.01 1.0 0.0 dry_sand_max
20.0 0.0 0.0 0.1 1.0 0.0 saturated_sand
7.0 0.0 0.0 0.5 1.0 0.0 limestone
64

Since GprMax2D/3D can model Debye media you can use the definition
# 82.3 5.5 10.9e-12 0.0 1.0 0.0 water
for water in 15◦ C. This will take into account the polarization relaxation phenomena associated
with water which are described by the Debye equation 2.6 (see Chapter 2).

65

Appendix B

GprMax2D/3D Constants and
excitation functions
GprMax2D/3D Constants
In GprMax2D/3D there are some fundamental constants defined which can not be altered unless
the source code is edited. This is however not wise if you are not familiar with both C programming and the FDTD method.
These constants are:
• Physical

– Speed of light c defined as 2.9979245 × 108 (metre/second)

– Permittivity of free space 0 defined as 8.854187 × 10−12 (Farads/metre)

– Permeability of free space µ0 defined as 1.256637 × 10−6 (Henrys/metre)
– Characteristic impedance of free space Z0 defined as 376.7303134 Ohms

• Program related

– The maximum length of media identifiers (MEDIALENGTH) is 30 characters.
– The maximum length of filenames (FILELENGTH) is 255 characters.
– The maximum length of source types (SOURCELENGTH) is 30 characters.
– The maximum length of title (TITLELENGTH) is 250 characters.
– The maximum number of different media in a model is 32768.
– The maximum number of cells which can be allocated depends solely on the amount
of available computer memory.
– The precision of integer numbers is 2 bytes.
– The precision of floating point numbers is 4 bytes.
– The minimum number of cells which can be allocated in any direction is 9
– The maximum number of iterations is 2147483648 which is by far more than will be
required. Take note that the number of iterations in binary output files and the iteration
counter for binary stored snapshots is converted and stored as a float

66

Excitation functions
The definitions of the source functions which can be used in GprMax2D are:
• The cont_sine excitation function is defined as:
I = R sin(2πf t)
and
R=

(

tRc f

if R ≤ 1,

if R > 1.

1

where I is the current, Rc is set to 0.25, t is time and f is the frequency.
• The sine excitation function is defined as:
I = R sin(2πf t)
and
R=

(

1 if tf ≤ 1,

0 if tf > 1.

• The gaussian excitation function is defined as:
I = e−ζ(t−χ)
where ζ = 2π 2 f 2 and χ =

2

1
f

• The ricker excitation function is defined as:
p
2
I = −2ζ e1/(2ζ) e−ζ(t−χ) (t − χ)

which is the first derivative of the gaussian function normalized to unity. The parameters
ζ and χ are as defined for the gaussian function

67

Appendix C

MATLAB functions for
GprMax2D/3D
In the tools subdirectory there are simple MATLAB functions which can be used to import
modeled data created by GprMax2D/3D using the binary format option into MATLAB for
further processing and visualization.

NOTICE: These functions are not guaranteed for any particular purpose. The
author does not offer any warranties or representations, nor does it accept any
liabilities with respect to their function or application. You are free to redistribute these functions but the copyright remains with the author.
In each function there is a small header which explains its purpose, arguments and return values.

68

Bibliography
[1] Giannopoulos A., (1997) “The investigation of Transmission-Line Matrix and Finite-Difference
Time-Domain Methods for the Forward Problem of Ground Probing Radar”, D.Phil thesis, Department of Electronics, University of York, UK.
[2] Kunz K. S. and Luebbers R. J., (1993) “The Finite Difference Time Domain Method for Electromagnetics”, CRC Press
[3] Taflove A., (1995) “Computational Electrodynamics: The Finite-Difference Time-Domain Method”,
Artech House
[4] Yee K. S., (1966),“Numerical Solution of Initial Boundary Value Problems Involving Maxwell’s
Equations in Isotropic Media”, IEEE Transactions on Antennas and Propagation, Vol. 14, pp. 302-307

69



---

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.2
Linearized                      : No
Page Count                      : 78
Has XFA                         : No
Producer                        : GNU Ghostscript 7.07
Modify Date                     : 2015:12:08 18:20:28-03:00

EXIF Metadata provided by EXIF.tools