Merge remote-tracking branch 'origin/master'

docs/source/benchmarking.rst

@@ -1,8 +1,8 @@
 .. _benchmarking:
 
-************
+************************
-Benchmarking
+Performance benchmarking
-************
+************************
 
 This section provides information and results from performance benchmarking of gprMax.
 

docs/source/comparisons_analytical.rst

@@ -15,7 +15,7 @@ This example is of a Hertzian dipole, i.e. an additive source (electric current
     :language: none
     :linenos:
 
-The function ``hertzian_dipole_fs``, which can be found in the ``analytical solutions`` module in the ``tests`` sub-package, computes the analytical solution.
+The function ``hertzian_dipole_fs``, which can be found in the ``analytical_solutions`` module in the ``tests`` sub-package, computes the analytical solution.
 
 Results
 -------

docs/source/examples_advanced.rst

@@ -1,6 +1,6 @@
-******************
+*****************
-Advanced modelling
+Advanced features
-******************
+*****************
 
 This section provides example models of some of the more advanced features of gprMax. Each example comes with an input file which you can download and run.
 

docs/source/examples_simple_2D.rst

@@ -1,6 +1,6 @@
-****************************
+************************
-Introductory/basic 2D models
+Introductory (2D) models
-****************************
+************************
 
 This section provides some introductory example models in 2D that demonstrate basic features of gprMax. Each example comes with an input file which you can download and run.
 

docs/source/geometry_snapshots.rst

@@ -1,66 +0,0 @@
-***************************
-Geometry and Snapshot files
-***************************
-
-The geometry and snapshot files use the open source Visualization ToolKit (VTK) (http://www.vtk.org) format which can be viewed in many free readers, such as Paraview (http://www.paraview.org). Paraview is an open-source, multi-platform data analysis and visualization application. It is available for Linux, Mac OS X, and Windows.
-
-Geometry files
-==============
-
-The ``#geometry_view:`` command produces either ImageData (.vti) for a per-cell geometry view, or PolygonalData (.vtp) for a per-cell-edge geometry view. The per-cell geometry views also show the location of the PML regions and any sources and receivers in the model. The following are steps to get started with viewing geometry files in Paraview:
-
-.. _pv_toolbar:
-
-.. figure:: images/paraview_toolbar.png
-
-    Paraview toolbar showing ``gprMax_info`` macro button.
-
-#. **Open the file** either from the File menu or toolbar.
-#. Click the **Apply** button in the Properties panel. You should see an outline of the volume of the geometry view.
-#. Install the ``gprMax_info.py`` Python script, that comes with the gprMax source code (in the ``tools/Paraview macros`` directory), as a macro in Paraview. This script makes it quick and easy to view the different materials in a geometry file. To add the script as a macro in Paraview choose the file from the Macros->Add new macro menu. It will then appear as a shortcut button in the toolbar as shown in :numref:`pv_toolbar`. You only need to do this once, the macro will be kept in Paraview for future use.
-#. Click the ``gprMax_info`` shortcut button. All the materials in the model should appear in the Pipeline Browser as Threshold items as shown in :numref:`pv_pipeline`.
-
-.. _pv_pipeline:
-
-.. figure:: images/paraview_pipeline.png
-    :width: 350 px
-
-    Paraview Pipeline Browser showing list of materials in an example model.
-
-.. tip::
-    * You can turn on and off the visibility of materials using the eye icon in the Pipeline Browser. You can select multiple materials using the Shift key, and by shift-clicking the eye icon, turn the visibility of multiple materials on and off.
-
-    * You can set the Color and Opacity of materials from the Properties panel.
-
-
-Snapshot files
-==============
-
-The ``#snapshot:`` command produces an ImageData (.vti) snapshot file for each time instance requested.
-
-.. tip::
-    You can take advantage of Python scripting to easily create a series of snapshots. For example, to create 30 snapshots starting at time 0.1ns until 3ns in intervals of 0.1ns, use the following code snippet in your input file. Replace ``xs, ys, zs, xf, yf, zf, dx, dy, dz`` accordingly.
-
-    .. code-block:: none
-
-        #python:
-        from gprMax.input_cmd_funcs import *
-        for i in range(1, 31):
-            snapshot(xs, ys, zs, xf, yf, zf, dx, dy, dz, (i/10)*1e-9, 'snapshot' + str(i))
-        #end_python:
-
-The following are steps to get started with viewing snapshot files in Paraview:
-
-#. **Open the file** either from the File menu or toolbar. Paraview should recognise the time series based on the file name and load in all the files.
-#. Click the **Apply** button in the Properties panel. You should see an outline of the snapshot volume.
-#. Use the **Coloring** drop down menu to select either **E-field** or **H-field**, and the further drop down menu to select either **Magnitude**, **x**, **y** or **z** component.
-#. From the **Representation** drop down menu select **Surface**.
-#. You can step through or play as an animation the time steps using the **time controls** in the toolbar.
-
-.. tip::
-
-    * Turn on the Animation View (View->Animation View menu) to control the speed and start/stop points of the animation.
-
-    * Use the Color Map Editor to adjust the Color Scaling.
-
-

docs/source/index.rst

@@ -21,7 +21,7 @@ gprMax User Guide
 
 .. toctree::
     :maxdepth: 2
-    :caption: Additional tools
+    :caption: Python tools
 
     plotting
     utils
@@ -32,6 +32,7 @@ gprMax User Guide
 
     python_scripting
     openmp_mpi
+    user_libraries
 
 .. toctree::
     :maxdepth: 2
@@ -50,10 +51,15 @@ gprMax User Guide
 
 .. toctree::
     :maxdepth: 2
-    :caption: Appendices
+    :caption: Accuracy and performance
 
     comparisons_analytical
     comparisons_numerical
     benchmarking
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Appendices
+
     references
 

docs/source/input.rst

@@ -1,8 +1,8 @@
 .. _commands:
 
-*******************
+**************
-Input file commands
+Input commands
-*******************
+**************
 
 An input file has to be supplied to gprMax which should contain all the necessary information to run a GPR model. The input file is an ASCII text file which can be prepared with any text 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 will be passed to gprMax. The general syntax of commands is:
 

docs/source/openmp_mpi.rst

@@ -1,8 +1,8 @@
 .. _openmp-mpi:
 
-************************
+***********
-Parallelism - OpenMP/MPI
+Parallelism
-************************
+***********
 
 OpenMP
 ======

docs/source/output.rst

@@ -1,14 +1,16 @@
 .. _output:
 
 ***********
-Output file
+Output data
 ***********
 
-gprMax produces an output file that has the same name as the input file but with ``.out`` appended. The output file uses the widely-supported HDF5 (https://www.hdfgroup.org/HDF5/) format which was designed to store and organize large amounts of numerical data.
+Field(s) output
+===============
 
+gprMax produces an output file that has the same name as the input file but with ``.out`` appended. The output file uses the widely-supported HDF5 (https://www.hdfgroup.org/HDF5/) format which was designed to store and organize large amounts of numerical data. There are a number of free tools available to read HDF5 files. Also MATLAB has high- and low-level functions for reading and writing HDF5 files, i.e. ``h5info`` and ``h5disp`` are useful for returning information and displaying the contents of HDF5 files respectively. gprMax includes some Python modules (in the ``tools`` package) to help you view output data. These are documented in the :ref:`tools section <plotting>`.
 
 File structure
-==============
+--------------
 
 The output file has the following HDF5 attributes at the root (``/``):
 
@@ -97,9 +99,67 @@ Within each individual ``tl`` group are the following datasets:
 * ``Itotal`` is an array containing the time history (for the model time window) of the values of the total (field) current in the transmission line.
 
 
-Viewing output
+Snapshots
-==============
+---------
+
+Snapshot files use the open source Visualization ToolKit (VTK) (http://www.vtk.org) format which can be viewed in many free readers, such as Paraview (http://www.paraview.org). Paraview is an open-source, multi-platform data analysis and visualization application. It is available for Linux, Mac OS X, and Windows. The ``#snapshot:`` command produces an ImageData (.vti) snapshot file containing electric and magnetic field data and current data for each time instance requested.
+
+.. tip::
+    You can take advantage of Python scripting to easily create a series of snapshots. For example, to create 30 snapshots starting at time 0.1ns until 3ns in intervals of 0.1ns, use the following code snippet in your input file. Replace ``xs, ys, zs, xf, yf, zf, dx, dy, dz`` accordingly.
+
+    .. code-block:: none
+
+        #python:
+        from gprMax.input_cmd_funcs import *
+        for i in range(1, 31):
+            snapshot(xs, ys, zs, xf, yf, zf, dx, dy, dz, (i/10)*1e-9, 'snapshot' + str(i))
+        #end_python:
+
+The following are steps to get started with viewing snapshot files in Paraview:
+
+#. **Open the file** either from the File menu or toolbar. Paraview should recognise the time series based on the file name and load in all the files.
+#. Click the **Apply** button in the Properties panel. You should see an outline of the snapshot volume.
+#. Use the **Coloring** drop down menu to select either **E-field** or **H-field**, and the further drop down menu to select either **Magnitude**, **x**, **y** or **z** component.
+#. From the **Representation** drop down menu select **Surface**.
+#. You can step through or play as an animation the time steps using the **time controls** in the toolbar.
+
+.. tip::
+
+    * Turn on the Animation View (View->Animation View menu) to control the speed and start/stop points of the animation.
+
+    * Use the Color Map Editor to adjust the Color Scaling.
+
+
+Geometry output
+===============
+
+Geometry files use the open source Visualization ToolKit (VTK) (http://www.vtk.org) format which can be viewed in many free readers, such as Paraview (http://www.paraview.org). Paraview is an open-source, multi-platform data analysis and visualization application. It is available for Linux, Mac OS X, and Windows.
+
+The ``#geometry_view:`` command produces either ImageData (.vti) for a per-cell geometry view, or PolygonalData (.vtp) for a per-cell-edge geometry view. The per-cell geometry views also show the location of the PML regions and any sources and receivers in the model. The following are steps to get started with viewing geometry files in Paraview:
+
+.. _pv_toolbar:
+
+.. figure:: images/paraview_toolbar.png
+
+    Paraview toolbar showing ``gprMax_info`` macro button.
+
+#. **Open the file** either from the File menu or toolbar.
+#. Click the **Apply** button in the Properties panel. You should see an outline of the volume of the geometry view.
+#. Install the ``gprMax_info.py`` Python script, that comes with the gprMax source code (in the ``tools/Paraview macros`` directory), as a macro in Paraview. This script makes it quick and easy to view the different materials in a geometry file. To add the script as a macro in Paraview choose the file from the Macros->Add new macro menu. It will then appear as a shortcut button in the toolbar as shown in :numref:`pv_toolbar`. You only need to do this once, the macro will be kept in Paraview for future use.
+#. Click the ``gprMax_info`` shortcut button. All the materials in the model should appear in the Pipeline Browser as Threshold items as shown in :numref:`pv_pipeline`.
+
+.. _pv_pipeline:
+
+.. figure:: images/paraview_pipeline.png
+    :width: 350 px
+
+    Paraview Pipeline Browser showing list of materials in an example model.
+
+.. tip::
+    * You can turn on and off the visibility of materials using the eye icon in the Pipeline Browser. You can select multiple materials using the Shift key, and by shift-clicking the eye icon, turn the visibility of multiple materials on and off.
+
+    * You can set the Color and Opacity of materials from the Properties panel.
+
 
-There are a number of free tools available to read HDF5 files. Also MATLAB has high- and low-level functions for reading and writing HDF5 files, i.e. ``h5info`` and ``h5disp`` are useful for returning information and displaying the contents of HDF5 files respectively. gprMax includes some Python modules (in the ``tools`` package) to help you view output data. These are documented in the :ref:`tools section <plotting>`.
 
 

docs/source/python_scripting.rst

@@ -1,8 +1,8 @@
 .. _python-scripting:
 
-****************
+************************
-Python scripting
+Scripting the input file
-****************
+************************
 
 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 :ref:`libraries of more complex objects, such as antennas <antennas>`, that can be easily inserted into a model. You can also access a number of built-in constants from your Python code.
 
@@ -22,22 +22,6 @@ You can access the following built-in variables from your Python code:
 * ``number_model_runs`` 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``
 * ``inputdirectory`` is the path to the directory where your input file is located.
 
-Antenna models
-==============
-
-You can also access a user library of antenna models. This library currently features models of antennas similar to:
-
-* a Geophysical Survey Systems, Inc. (GSSI) 1.5 GHz (Model 5100) antenna (http://www.geophysical.com)
-* a MALA Geoscience 1.2 GHz antenna (http://www.malags.com/)
-
-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:
-
-.. code-block:: none
-
-    #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
 ============================
@@ -48,7 +32,7 @@ To make it easier to create commands within a block of Python code, there is a b
 
     #python:
     from gprMax.input_cmd_funcs import *
-    domain = domain(0.2 0.2 0.2)
+    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:

docs/source/user_libraries.rst

@@ -0,0 +1,34 @@
+.. _user-libs:
+
+*************
+User libaries
+*************
+
+The user libraries sub-package is where useful modules contributed by users are stored.
+
+antennas.py
+===========
+
+This library currently features models of antennas similar to:
+
+* a Geophysical Survey Systems, Inc. (GSSI) 1.5 GHz (Model 5100) antenna (http://www.geophysical.com)
+* a MALA Geoscience 1.2 GHz antenna (http://www.malags.com/)
+
+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:
+
+.. code-block:: none
+
+    #python:
+    from user_libs.antennas import antenna_like_GSSI_1500
+    antenna_like_GSSI_1500(0.125, 0.094, 0.100, 0.001)
+    #end_python:
+
+.. figure:: images/antenna_like_GSSI_1500.png
+    :width: 600 px
+
+    FDTD geometry mesh showing an antenna model similar to a GSSI 1.5   GHz antenna (skid removed for illustrative purposes).
+
+.. figure:: images/antenna_like_MALA_1200.png
+    :width: 600 px
+
+    FDTD geometry mesh showing an antenna model similar to a MALA 1.2GHz antenna (skid removed for illustrative purposes).