Package: gprMax
Getting StartedWhat is gprMax?gprMaxis open source software that simulates electromagnetic wave propagation. It solves Maxwell’s equations in 3D using the Finite-Difference Time-Domain (FDTD) method. gprMax was designed for modelling Ground Penetrating Radar (GPR) but can also be used to model electromagnetic wave propagation for many other applications.gprMax is currently released under theGNU General Public License v3 or higher.gprMax is principally written inPython3 with performance-critical parts written inCython. It includes a CPU-based solver parallelised usingOpenMP, and a GPU-based solver written using theNVIDIA CUDAprogramming model.Using gprMax? Cite usIf you use gprMax and publish your work we would be grateful if you could cite our work using:Warren, C., Giannopoulos, A., & Giannakis I. (2016). gprMax: Open source software to simulate electromagnetic wave propagation for Ground Penetrating Radar,Computer Physics Communications(http://dx.doi.org/10.1016/j.cpc.2016.08.020)For further information on referencing gprMax visit thePublications section of our website.Package overviewgprMax/conda_env.ymlCONTRIBUTORSdocs/gprMax/gsoc-ideas.mdLICENSEREADME.rstsetup.cfgsetup.pytests/tools/user_libs/user_models/conda_env.ymlis a configuration file for Anaconda (Miniconda) that sets up a Python environment with all the required Python packages for gprMax.CONTRIBUTORScontains a list of names of people who have contributed to the gprMax codebase.docscontains source files for the User Guide. The User Guide is written usingreStructuredTextmarkup, and is built usingSphinxandRead the Docs.gprMaxis the main package. Within this package the main module isgprMax.pygsoc-ideas.mdis a list of potential project ideas forGoogle Summer of CodeprogramLICENSEcontains information on theGNU General Public License v3 or higher.README.rstcontains getting started information on installation, usage, and new features/changes.setup.cfgis used to set preference for code formatting/styling using flake8.setup.pyis used to compile the Cython extension modules.testsis a sub-package which contains test modules and input files.toolsis a sub-package which contains scripts to assist with viewing and post-processing output from models.user_libsis a sub-package where useful modules contributed by users are stored.user_modelsis a sub-package where useful input files contributed by users are stored.InstallationThe following steps provide guidance on how to install gprMax:Install Python, required Python packages, and get the gprMax source code from GitHubInstall a C compiler which supports OpenMPBuild and install gprMaxYou canwatch screencaststhat demonstrate the installation and update processes.1. Install Python, required Python packages, and get gprMax sourceWe recommend using Miniconda to install Python and the required Python packages for gprMax in a self-contained Python environment. Miniconda is a mini version of Anaconda which is a completely free Python distribution (including for commercial use and redistribution). It includes more than 300 of the most popular Python packages for science, math, engineering, and data analysis.Download and install Miniconda. Choose the Python 3.x version for your platform. We recommend choosing the installation options to: install Miniconda only for your user account; add Miniconda to your PATH environment variable; and to register Miniconda Python as your default Python. See theQuick Install pagefor help installing Miniconda.Open a Terminal (Linux/macOS) or Command Prompt (Windows) and run the following commands:$condaupdateconda$condainstallgit$gitclonehttps://github.com/gprMax/gprMax.git$cdgprMax$condaenvcreate-fconda_env.ymlThis will make sure conda is up-to-date, install Git, get the latest gprMax source code from GitHub, and create an environment for gprMax with all the necessary Python packages.If you prefer to install Python and the required Python packages manually, i.e. without using Anaconda/Miniconda, look in theconda_env.ymlfile for a list of the requirements.2. Install a C compiler which supports OpenMPLinuxgccshould be already installed, so no action is required.macOSXcode (the IDE for macOS) comes with the LLVM (clang) compiler, but it does not currently support OpenMP, so you must installgcc. That said, it is still useful to have Xcode (with command line tools) installed. It can be downloaded from the App Store. Once Xcode is installed, download and install theHomebrew package managerand then to install gcc, run:$brewinstallgccMicrosoft WindowsDownload and installMicrosoft Visual C++ 2015 Build Tools(currently you must use the 2015 version, not 2017). Use the custom installation option and deselect everything apart from the Windows SDK for your version of Windows.Alternatively if you are using Windows 10 and feeling adventurous you can install theWindows Subsystem for Linuxand then follow the Linux install instructions for gprMax. Note however that currently WSL does not aim to support GUI desktops or applications, e.g. Gnome, KDE, etc….3. Build and install gprMaxOnce you have installed the aforementioned tools follow these steps to build and install gprMax:Open a Terminal (Linux/macOS) or Command Prompt (Windows), navigate into the top-level gprMax directory, and if it is not already active, activate the gprMax conda environmentconda activate gprMax. Run the following commands:(gprMax)$pythonsetup.pybuild(gprMax)$pythonsetup.pyinstallYou are now ready to proceed to running gprMax.If you have problems with building gprMax on Microsoft Windows, you may need to addC:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\binto your path environment variable.Running gprMaxgprMax is designed as a Python package, i.e. a namespace which can contain multiple packages and modules, much like a directory.Open a Terminal (Linux/macOS) or Command Prompt (Windows), navigate into the top-level gprMax directory, and if it is not already active, activate the gprMax conda environmentconda activate gprMax.Basic usage of gprMax is:(gprMax)$python-mgprMaxpath_to/name_of_input_fileFor example to run one of the test models:(gprMax)$python-mgprMaxuser_models/cylinder_Ascan_2D.inWhen the simulation is complete you can plot the A-scan using:(gprMax)$python-mtools.plot_Ascanuser_models/cylinder_Ascan_2D.outYour results should like those from the A-scan from the metal cylinder example inintroductory/basic 2D models sectionWhen you are finished using gprMax, the conda environment can be deactivated usingconda deactivate.Optional command line argumentsArgument nameTypeDescription-nintegernumber of times to run the input file. This option can be used to run a series of models, e.g. to create a B-scan with 60 traces:(gprMax)$ python-mgprMax user_models/cylinder_Bscan_2D.in-n60-gpuflag/listflag to use NVIDIA GPU or list of NVIDIA GPU device ID(s) for specific GPU card(s).-restartintegermodel number to start/restart simulation from. It would typically be used to restart a series of models from a specific model number, with the-nargument, e.g. to restart from A-scan 45 when creating a B-scan with 60 traces:(gprMax)$ python-mgprMax user_models/cylinder_Bscan_2D.in-n15-restart45-taskintegertask identifier (model number) when running simulation as a job array onOpen Grid Scheduler/Grid Engine. For further details see theparallel performance section of the User Guide-mpiintegernumber of Message Passing Interface (MPI) tasks, i.e. master + workers, for MPI task farm. This option is most usefully combined with-nto allow individual models to be farmed out using a MPI task farm, e.g. to create a B-scan with 60 traces and use MPI to farm out each trace:(gprMax)$ python-mgprMax user_models/cylinder_Bscan_2D.in-n60-mpi61. For further details see theparallel performance section of the User Guide--mpi-no-spawnflaguse MPI task farm without spawn mechanism. For further details see theparallel performance section of the User Guide-benchmarkflagswitch on benchmarking mode. This can be used to benchmark the threading (parallel) performance of gprMax on different hardware. For further details see thebenchmarking section of the User Guide--geometry-onlyflagbuild a model and produce any geometry views but do not run the simulation, e.g. to check the geometry of a model is correct:(gprMax)$ python-mgprMax user_models/heterogeneous_soil.in--geometry-only--geometry-fixedflagrun a series of models where the geometry does not change between models, e.g. a B-scan whereonlythe position of simple sources and receivers, moved using#src_stepsand#rx_steps, changes between models.--opt-taguchiflagrun a series of models using an optimisation process based on Taguchi’s method. For further details see theuser libraries section of the User Guide--write-processedflagwrite another input file after any Python code and include commands in the original input file have been processed. Useful for checking that any Python code is being correctly processed into gprMax commands.-hor--helpflagused to get help on command line options.Updating gprMaxOpen a Terminal (Linux/macOS) or Command Prompt (Windows), navigate into the top-level gprMax directory, and if it is not already active, activate the gprMax conda environmentconda activate gprMax. Run the following commands:(gprMax)$gitpull(gprMax)$pythonsetup.pycleanall(gprMax)$pythonsetup.pybuild(gprMax)$pythonsetup.pyinstallThis will pull the most recent gprMax source code form GitHub, remove/clean previously built modules, and then build and install the latest version of gprMax.Updating conda and Python packagesPeriodically you should update conda and the required Python packages. With the gprMax environment deactivated and from the top-level gprMax directory, run the following commands:$condaupdateconda$condaenvupdate-fconda_env.yml