Merge branch 'master' of https://github.com/gprMax/gprMax

default voxel and optional edge writing

.gitignore

@@ -10,11 +10,16 @@
 # Mac OS X
 .DS_Store
 
-# Build directory
+# build, dist and egg-info directories
 build/
+dist/
+*.egg-info/
 
 # Backup files
 *~
 
 # Hidden files
 .*
+
+# Jupyter notebook checkpoints
+.ipynb_checkpoints/

docs/source/conf.py

@@ -13,15 +13,15 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import os, sys
+import os
+import re
+import sys
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('../..'))
 
-import gprMax
-
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -72,7 +72,9 @@ author = 'Craig Warren and Antonis Giannopoulos'
 # built documents.
 #
 # The short X.Y version.
-version = gprMax.__version__
+with open('../../gprMax/_version.py', 'r') as fd:
+    version = re.search(r'^__version__\s*=\s*[\'"]([^\'"]*)[\'"]',
+                        fd.read(), re.MULTILINE).group(1)
 # The full version, including alpha/beta/rc tags.
 release = version
 

docs/source/readme_install_devs.rst

@@ -10,7 +10,7 @@ Those that are interested in developing or contributing to gprMax should use the
 1. Get the code
 2. Install Python and required Python packages
 3. Install a C compiler which supports OpenMP
-4. Compile the Cython extensions
+4. Compile the Cython extensions and install packages
 
 1. Get the code
 ---------------
@@ -22,15 +22,15 @@ Those that are interested in developing or contributing to gprMax should use the
 
 We 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.
 
-* Install the Python 3.5 version of Miniconda for your platform (http://conda.pydata.org/miniconda.html).  Follow the instructions (http://conda.pydata.org/docs/install/quick.html) if you are having any trouble.
+* Install the Python 3.5 version of Miniconda for your platform from http://conda.pydata.org/miniconda.html (You can get help with installing Miniconda from http://conda.pydata.org/docs/install/quick.html)
 * Open a Terminal (Linux/Mac OS X) or Command Prompt (Windows) and navigate into the top-level gprMax directory.
 * Update conda :code:`conda update conda`
-* Create an environment (using the supplied environment file) for gprMax with all the necessary Python packages :code:`conda env create -f conda_env.yml`
-* Activate the new environment (Linux/Mac OS X) :code:`source activate gprMax` or (Windows) :code:`activate gprMax`.
+* Create an environment (using the supplied ``conda_env.yml`` environment file) for gprMax with all the necessary Python packages :code:`conda env create -f conda_env.yml`
+* Activate the new environment :code:`source activate gprMax` (Linux/Mac OS X) or :code:`activate gprMax` (Windows).
 
 .. note::
-
-    When you are finished using gprMax the Miniconda environment can be deactivated using (Linux/Mac OS X) :code:`source deactivate` or (Windows) :code:`deactivate`
+    * When you are finished using gprMax the Miniconda environment can be deactivated using :code:`source deactivate` (Linux/Mac OS X)  or :code:`deactivate` (Windows).
+    * If you want to install Python and the required Python packages manually, i.e. without using Anaconda/Miniconda, look in the ``conda_env.yml`` file for a list of the requirements.
 
 
 3. Install a C compiler which supports OpenMP
@@ -63,13 +63,13 @@ Microsoft Windows
     Screenshot of Microsoft Visual Studio 2015 Community custom install settings.
 
 
-4. Compile the Cython extensions
---------------------------------
+4. Compile the Cython extensions and install packages
+-----------------------------------------------------
 
 Once you have installed the aforementioned tools follow these steps to build the Cython extension modules for gprMax:
 
 a) Open a Terminal (Linux/Mac OS X) or Command Prompt (Windows) and navigate into the top-level gprMax directory.
-b) Compile the Cython extension modules using: :code:`python setup.py build_ext --inplace`. You should see a set of :code:`.c` source files and a set of :code:`.so` (Linux/Mac OS X) or :code:`.pyd` (Windows) compiled module files inside the gprMax directory.
+b) Compile the Cython extension modules and install using: :code:`python setup.py install`. You should see a set of :code:`.c` source files and a set of :code:`.so` (Linux/Mac OS X) or :code:`.pyd` (Windows) compiled module files inside the gprMax directory.
 
 .. note::
 

gprMax/fields_update.pyx

@@ -19,6 +19,7 @@
 import numpy as np
 cimport numpy as np
 from cython.parallel import prange
+
 from gprMax.constants cimport floattype_t, complextype_t
 
 

gprMax/geometry_primitives.pyx

@@ -19,6 +19,7 @@
 import numpy as np
 cimport numpy as np
 np.seterr(divide='raise')
+
 from gprMax.utilities import round_value
 from gprMax.yee_cell_setget_rigid cimport set_rigid_Ex, set_rigid_Ey, set_rigid_Ez, set_rigid_Hx, set_rigid_Hy, set_rigid_Hz, set_rigid_E, unset_rigid_E, set_rigid_H, unset_rigid_H
 

gprMax/geometry_views.py

@@ -16,12 +16,14 @@
 # You should have received a copy of the GNU General Public License
 # along with gprMax.  If not, see <http://www.gnu.org/licenses/>.
 
-import os, sys
+import os
+import sys
+
 import numpy as np
 from struct import pack
-from gprMax.xdmf import write_output_file
 
 from gprMax.utilities import round_value
+from gprMax.xdmf import write_output_file
 
 
 class GeometryView(object):

gprMax/gprMax.py

@@ -67,7 +67,8 @@ def main():
 
 
 def api(inputfile, n=1, mpi=False, benchmark=False, geometry_only=False, geometry_fixed=False, write_processed=False, opt_taguchi=False):
-    """If you have installed gprMax as a module this is the entry point"""
+    """If installed as a module this is the entry point."""
+    
     class ImportArguments:
         pass
 
@@ -86,6 +87,11 @@ def api(inputfile, n=1, mpi=False, benchmark=False, geometry_only=False, geometr
 
 
 def run_main(args):
+    """Top-level function that controls what mode of simulation (standard/optimsation/benchmark etc...) is run.
+        
+    Args:
+        args (dict): Namespace with input arguments from command line or api.
+    """
         
     numbermodelruns = args.n
     inputdirectory = os.path.dirname(os.path.abspath(args.inputfile))
@@ -415,7 +421,7 @@ def run_model(args, modelrun, numbermodelruns, inputfile, usernamespace):
         tgeostart = perf_counter()
         for geometryview in G.geometryviews:
             geometryview.write_vtk(modelrun, numbermodelruns, G)
-            geometryview.write_xdmf(modelrun, numbermodelruns, G)
+        #geometryview.write_xdmf(modelrun, numbermodelruns, G)
         tgeoend = perf_counter()
         print('\nGeometry file(s) written in [HH:MM:SS]: {}'.format(datetime.timedelta(seconds=int(tgeoend - tgeostart))))
 

gprMax/grid.py

@@ -17,13 +17,13 @@
 # along with gprMax.  If not, see <http://www.gnu.org/licenses/>.
 
 import numpy as np
-import matplotlib.pyplot as plt
 
 from gprMax.constants import c, floattype, complextype
 from gprMax.materials import Material
 
 
-class Grid():
+class Grid(object):
+    """Generic grid/mesh."""
     
     def __init__(self, grid):
         self.nx = grid.shape[0]

gprMax/input_cmds_file.py

@@ -16,7 +16,8 @@
 # You should have received a copy of the GNU General Public License
 # along with gprMax.  If not, see <http://www.gnu.org/licenses/>.
 
-import os, sys
+import os
+import sys
 
 from gprMax.exceptions import CmdInputError
 from gprMax.utilities import ListStream

gprMax/input_cmds_geometry.py

@@ -17,6 +17,7 @@
 # along with gprMax.  If not, see <http://www.gnu.org/licenses/>.
 
 import os
+
 import h5py
 import numpy as np
 

gprMax/input_cmds_singleuse.py

@@ -16,8 +16,10 @@
 # You should have received a copy of the GNU General Public License
 # along with gprMax.  If not, see <http://www.gnu.org/licenses/>.
 
-import os, psutil
+import os
+import psutil
 import decimal as d
+
 import numpy as np
 
 from gprMax.constants import c, floattype

gprMax/optimisation_taguchi.py

@@ -16,7 +16,9 @@
 # You should have received a copy of the GNU General Public License
 # along with gprMax.  If not, see <http://www.gnu.org/licenses/>.
 
-import importlib, os, pickle
+import importlib
+import os
+import pickle
 from collections import OrderedDict
 
 import numpy as np

gprMax/pml_1order_update.pyx

@@ -19,6 +19,7 @@
 import numpy as np
 cimport numpy as np
 from cython.parallel import prange
+
 from gprMax.constants cimport floattype_t, complextype_t
 
 

gprMax/pml_2order_update.pyx

@@ -19,6 +19,7 @@
 import numpy as np
 cimport numpy as np
 from cython.parallel import prange
+
 from gprMax.constants cimport floattype_t, complextype_t
 
 

gprMax/snapshots.py

@@ -16,10 +16,12 @@
 # You should have received a copy of the GNU General Public License
 # along with gprMax.  If not, see <http://www.gnu.org/licenses/>.
 
-import os, sys
-import numpy as np
+import os
+import sys
 from struct import pack
 
+import numpy as np
+
 from gprMax.constants import floattype
 from gprMax.grid import Ix, Iy, Iz
 from gprMax.utilities import round_value

gprMax/sources.py

@@ -17,6 +17,7 @@
 # along with gprMax.  If not, see <http://www.gnu.org/licenses/>.
 
 from copy import deepcopy
+
 import numpy as np
 
 from gprMax.constants import c, floattype

gprMax/utilities.py

@@ -18,6 +18,7 @@
 
 import sys
 import decimal as d
+
 from pyfiglet import Figlet
 
 

gprMax/writer_hdf5.py

@@ -18,7 +18,7 @@
 
 import h5py
 
-from ._version import __version__
+from gprMax._version import __version__
 from gprMax.constants import floattype
 from gprMax.grid import Ix, Iy, Iz
 

gprMax/xdmf.py

@@ -1,8 +1,11 @@
-import numpy as np
+import copy
+
 import h5py
 from lxml import etree
+import numpy as np
+
 from gprMax.grid import Grid
-import copy
+
 
 
 class Edges:

gprMax/yee_cell_build.pyx

@@ -18,6 +18,7 @@
 
 import numpy as np
 cimport numpy as np
+
 from gprMax.materials import Material
 from gprMax.yee_cell_setget_rigid cimport get_rigid_Ex, get_rigid_Ey, get_rigid_Ez, get_rigid_Hx, get_rigid_Hy, get_rigid_Hz
 

setup.py

@@ -29,23 +29,22 @@ except ImportError:
 
 import glob
 import os
+import re
 import shutil
 import sys
-import re
 
 # Importing _version__.py before building can cause issues.
 with open('gprMax/_version.py', 'r') as fd:
     version = re.search(r'^__version__\s*=\s*[\'"]([^\'"]*)[\'"]',
         fd.read(), re.MULTILINE).group(1)
 
-"""
-  Parse package name from init file. Importing __init__.py / gprMax will
-  break as gprMax depends on compiled .pyx files.
-"""
+# Parse package name from init file. Importing __init__.py / gprMax will break as gprMax depends on compiled .pyx files.
 with open('gprMax/__init__.py', 'r') as fd:
     packagename = re.search(r'^__name__\s*=\s*[\'"]([^\'"]*)[\'"]',
         fd.read(), re.MULTILINE).group(1)
 
+packages = [packagename, 'tests', 'tools', 'user_libs']
+
 # Python version
 if sys.version_info[:2] < (3, 4):
     print('gprMax requires Python 3.4 or newer')
@@ -178,5 +177,5 @@ setup(name=packagename,
                    'Topic :: Scientific/Engineering'
                    ],
       ext_modules=extensions,
-      packages=['gprMax'],
+      packages=packages,
       include_dirs=[np.get_include()])

tools/plot_Ascan.py

@@ -26,13 +26,16 @@ from gprMax.exceptions import CmdInputError
 from gprMax.receivers import Rx
 
 
-def make_plot(filename, outputs=Rx.availableoutputs, fft=False):
+def mpl_plot(filename, outputs=Rx.availableoutputs, fft=False):
     """Plots electric and magnetic fields and currents from all receiver points in the given output file. Each receiver point is plotted in a new figure window.
             
     Args:
         filename (string): Filename (including path) of output file.
         outputs (list): List of field/current components to plot.
         fft (boolean): Plot FFT switch.
+        
+    Returns:
+        plt (object): matplotlib plot object.
     """
     
     # Open output file and read some attributes
@@ -210,7 +213,7 @@ def make_plot(filename, outputs=Rx.availableoutputs, fft=False):
         #fig.savefig(os.path.splitext(os.path.abspath(file))[0] + '_rx' + str(rx) + '.pdf', dpi=None, format='pdf', bbox_inches='tight', pad_inches=0.1)
         #fig.savefig(os.path.splitext(os.path.abspath(file))[0] + '_rx' + str(rx) + '.png', dpi=150, format='png', bbox_inches='tight', pad_inches=0.1)
 
-    plt.show()
+    return plt
 
 
 if __name__ == "__main__":
@@ -222,4 +225,6 @@ if __name__ == "__main__":
     parser.add_argument('-fft', action='store_true', help='plot FFT (single output must be specified)', default=False)
     args = parser.parse_args()
 
-    make_plot(args.outputfile, args.outputs, fft=args.fft)
+    plt = mpl_plot(args.outputfile, args.outputs, fft=args.fft)
+    plt.show()
+

tools/plot_Bscan.py

@@ -62,6 +62,7 @@ def get_output_data(filename, rxnumber, rxcomponent):
 
     return outputdata, dt
 
+
 def mpl_plot(outputdata, dt, rxnumber, rxcomponent):
     """Creates a plot (with matplotlib) of the B-scan.
         
@@ -117,3 +118,4 @@ if __name__ == "__main__":
         plt = mpl_plot(outputdata, dt, rx, args.rx_component)
 
     plt.show()
+

tools/plot_antenna_params.py

@@ -25,14 +25,17 @@ import matplotlib.gridspec as gridspec
 from gprMax.exceptions import CmdInputError
 
 
-def plot_antenna_params(filename, tlnumber=1, rxnumber=None, rxcomponent=None):
-    """Calculates and plots antenna parameters - s11, (s21) and input impedance.
+def calculate_antenna_params(filename, tlnumber=1, rxnumber=None, rxcomponent=None):
+    """Calculates antenna parameters - incident, reflected and total volatges and currents; s11, (s21) and input impedance.
             
     Args:
         filename (string): Filename (including path) of output file.
         tlnumber (int): Transmitting antenna - transmission line number
         rxnumber (int): Receiver antenna - output number
         rxcomponent (str): Receiver antenna - output electric field component
+        
+    Returns:
+        antennaparams (dict): Antenna parameters.
     """
 
     # Open output file and read some attributes
@@ -90,7 +93,7 @@ def plot_antenna_params(filename, tlnumber=1, rxnumber=None, rxcomponent=None):
     # Delay correction - current lags voltage, so delay voltage to match current timestep
     delaycorrection = np.exp(-1j * 2 * np.pi * freqs * (dt / 2))
 
-    # Calculate s11
+    # Calculate s11 and (optionally) s21
     s11 = np.abs(np.fft.fft(Vref) * delaycorrection) / np.abs(np.fft.fft(Vinc) * delaycorrection)
     if rxnumber:
         s21 = np.abs(np.fft.fft(Vrec)) / np.abs(np.fft.fft(Vinc) * delaycorrection)
@@ -109,8 +112,34 @@ def plot_antenna_params(filename, tlnumber=1, rxnumber=None, rxcomponent=None):
     Vtotalp = 20 * np.log10(np.abs((np.fft.fft(Vtotal) * delaycorrection)))
     Itotalp = 20 * np.log10(np.abs(np.fft.fft(Itotal)))
     s11 = 20 * np.log10(s11)
+    
+    # Create dictionary of antenna parameters
+    antennaparams = {'time': time, 'freqs': freqs, 'Vinc': Vinc, 'Vincp': Vincp, 'Iinc': Iinc, 'Iincp': Iincp,
+                    'Vref': Vref, 'Vrefp': Vrefp, 'Iref': Iref, 'Irefp': Irefp,
+                    'Vtotal': Vtotal, 'Vtotalp': Vtotalp, 'Itotal': Itotal, 'Itotalp': Itotalp,
+                    's11': s11, 'zin': zin, 'yin': yin}
     if rxnumber:
         s21 = 20 * np.log10(s21)
+        antennaparams['s21'] = s21
+
+    return antennaparams
+
+
+def mpl_plot(time, freqs, Vinc, Vincp, Iinc, Iincp, Vref, Vrefp, Iref, Irefp, Vtotal, Vtotalp, Itotal, Itotalp, s11, zin, yin, s21=None):
+    """Plots antenna parameters - incident, reflected and total volatges and currents; s11, (s21) and input impedance.
+            
+    Args:
+        time (array): Simulation time.
+        freq (array): Frequencies for FFTs.
+        Vinc, Vincp, Iinc, Iincp (array): Time and frequency domain representations of incident voltage and current.
+        Vref, Vrefp, Iref, Irefp (array): Time and frequency domain representations of reflected voltage and current.
+        Vtotal, Vtotalp, Itotal, Itotalp (array): Time and frequency domain representations of total voltage and current.
+        s11, s21 (array): s11 and, optionally, s21 parameters.
+        zin, yin (array): Input impedance and input admittance parameters.
+        
+    Returns:
+        plt (object): matplotlib plot object.
+    """
     
     # Set plotting range
     pltrangemin = 1
@@ -260,7 +289,7 @@ def plot_antenna_params(filename, tlnumber=1, rxnumber=None, rxcomponent=None):
     # Figure 2
     # Plot frequency spectra of s11
     fig2, ax = plt.subplots(num='Antenna parameters', figsize=(20, 12), facecolor='w', edgecolor='w')
-    gs2 = gridspec.GridSpec(2, 2, hspace=0.5)
+    gs2 = gridspec.GridSpec(2, 2, hspace=0.3)
     ax = plt.subplot(gs2[0, 0])
     markerline, stemlines, baseline = ax.stem(freqs[pltrange], s11[pltrange], '-.')
     plt.setp(baseline, 'linewidth', 0)
@@ -275,7 +304,7 @@ def plot_antenna_params(filename, tlnumber=1, rxnumber=None, rxcomponent=None):
     ax.grid()
 
     # Plot frequency spectra of s21
-    if rxnumber:
+    if s21:
         ax = plt.subplot(gs2[0, 1])
         markerline, stemlines, baseline = ax.stem(freqs[pltrange], s21[pltrange], '-.')
         plt.setp(baseline, 'linewidth', 0)
@@ -352,7 +381,7 @@ def plot_antenna_params(filename, tlnumber=1, rxnumber=None, rxcomponent=None):
     #fig1.savefig(os.path.splitext(os.path.abspath(filename))[0] + '_tl_params.pdf', dpi=None, format='pdf', bbox_inches='tight', pad_inches=0.1)
     #fig2.savefig(os.path.splitext(os.path.abspath(filename))[0] + '_ant_params.pdf', dpi=None, format='pdf', bbox_inches='tight', pad_inches=0.1)
 
-    plt.show()
+    return plt
 
 
 if __name__ == "__main__":
@@ -365,5 +394,7 @@ if __name__ == "__main__":
     parser.add_argument('--rx-component', type=str, help='receiver antenna - output electric field component', choices=['Ex', 'Ey', 'Ez'])
     args = parser.parse_args()
 
-    plot_antenna_params(args.outputfile, args.tl_num, args.rx_num, args.rx_component)
+    antennaparams = calculate_antenna_params(args.outputfile, args.tl_num, args.rx_num, args.rx_component)
+    plt = mpl_plot(**antennaparams)
+    plt.show()
 

tools/plot_builtin_wave.py

@@ -56,7 +56,7 @@ def check_timewindow(timewindow, dt):
     return timewindow, iterations
 
 
-def make_plot(w, timewindow, dt, iterations, fft=False):
+def mpl_plot(w, timewindow, dt, iterations, fft=False):
     """Plots waveform and prints useful information about its properties.
             
     Args:
@@ -65,6 +65,9 @@ def make_plot(w, timewindow, dt, iterations, fft=False):
         dt (float): Time discretisation.
         iterations (int): Number of iterations.
         fft (boolean): Plot FFT switch.
+        
+    Returns:
+        plt (object): matplotlib plot object.
     """
     
     time = np.linspace(0, 1, iterations)
@@ -134,7 +137,7 @@ def make_plot(w, timewindow, dt, iterations, fft=False):
     #fig.savefig(os.path.dirname(os.path.abspath(__file__)) + os.sep + w.type + '.pdf', dpi=None, format='pdf', bbox_inches='tight', pad_inches=0.1)
     #fig.savefig(os.path.dirname(os.path.abspath(__file__)) + os.sep + w.type + '.png', dpi=150, format='png', bbox_inches='tight', pad_inches=0.1)
 
-    plt.show()
+    return plt
 
 
 if __name__ == "__main__":
@@ -162,8 +165,6 @@ if __name__ == "__main__":
     w.freq = args.freq
 
     timewindow, iterations = check_timewindow(args.timewindow, args.dt)
-    make_plot(w, timewindow, args.dt, iterations, args.fft)
-
-
-
+    plt = mpl_plot(w, timewindow, args.dt, iterations, args.fft)
+    plt.show()