Docs restructuring in preparation for descriptions on tools usage.

docs/source/examples_2D.rst

@@ -165,7 +165,7 @@ You can now view an image of the B-scan using the command:
 
 .. code-block:: none
 
-    python -m tools.plot_Bscan cylinder_Bscan_2D_all.out Ez
+    python -m tools.plot_Bscan cylinder_Bscan_2D_all.out --field Ez
 
 :numref:`cylinder_Bscan_results` shows the B-scan (image of the Ez field). As expected a hyperbolic response is present from the metal cylinder.
 

docs/source/helper.rst

@@ -0,0 +1,7 @@
+.. _helper:
+
+****************
+Helper utilities
+****************
+
+This section provides information on how to use the Python modules (in the ``tools`` package) that help manage gprMax files.

docs/source/index.rst

@@ -19,6 +19,13 @@ gprMax User Guide
     geometry_snapshots
     output
 
+.. toctree::
+    :maxdepth: 2
+    :caption: Tools
+
+    plotting
+    helper
+
 .. toctree::
     :maxdepth: 2
     :caption: Advanced topics
@@ -27,7 +34,7 @@ gprMax User Guide
 
 .. toctree::
     :maxdepth: 2
-    :caption: Help and Support
+    :caption: Support
 
     examples_2D
     examples_3D
@@ -38,5 +45,4 @@ gprMax User Guide
     :maxdepth: 2
     :caption: Appendices
 
-    app_waveforms
-    app_references
+    references

docs/source/output.rst

@@ -61,21 +61,6 @@ Within each individual ``tx`` group is the following dataset:
 Viewing output
 ==============
 
-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:
-
-A-scans
--------
-
-* Plot A-scans using the Python module ``plot_Ascan.py``. The module uses matplotlib to plot the time history for the electric and magnetic field components for all receivers in a model (each receiver gets a separate figure window). Usage (from the top-level gprMax directory) is: ``python -m tools.plot_Ascan my_outputfile.out``.
-
-* Plot A-scans using the MATLAB script ``plot_Ascan.m``. The script plots the time history for the electric and magnetic field components for all receivers in a model (each receiver gets a separate figure window).
-
-B-scans
--------
-
-gprMax produces a separate output file for each trace (A-scan) in the B-scan.
-
-* Combine the separate output files into one file using the Python module ``outputfiles_merge.py``. Usage (from the top-level gprMax directory) is: ``python -m tools.outputfiles_merge basefilename modelruns``, where ``basefilename`` is the base name file of the output file series, e.g. for ``myoutput1.out``, ``myoutput2.out`` the base file name would be ``myoutput``, and ``modelruns`` is the number of output files to combine.
-* Plot an image of the B-scan using the Python module ``plot_Bscan.py``. Usage (from the top-level gprMax directory) is: ``python -m tools.plot_Bscan my_outputfile.out field``, where ``field`` is the name of field to plot, e.g. ``Ex``, ``Ey`` or ``Ez``.
+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/plotting.rst

@@ -1,13 +1,35 @@
+
+.. _plotting:
+
+********
+Plotting
+********
+
+A-scans
+=======
+
+* Plot A-scans using the Python module ``plot_Ascan.py``. The module uses matplotlib to plot the time history for the electric and magnetic field components for all receivers in a model (each receiver gets a separate figure window). Usage (from the top-level gprMax directory) is: ``python -m tools.plot_Ascan my_outputfile.out``.
+
+* Plot A-scans using the MATLAB script ``plot_Ascan.m``. The script plots the time history for the electric and magnetic field components for all receivers in a model (each receiver gets a separate figure window).
+
+B-scans
+=======
+
+gprMax produces a separate output file for each trace (A-scan) in the B-scan.
+
+* Combine the separate output files into one file using the Python module ``outputfiles_merge.py``. Usage (from the top-level gprMax directory) is: ``python -m tools.outputfiles_merge basefilename modelruns``, where ``basefilename`` is the base name file of the output file series, e.g. for ``myoutput1.out``, ``myoutput2.out`` the base file name would be ``myoutput``, and ``modelruns`` is the number of output files to combine.
+* Plot an image of the B-scan using the Python module ``plot_Bscan.py``. Usage (from the top-level gprMax directory) is: ``python -m tools.plot_Bscan my_outputfile.out field``, where ``field`` is the name of field to plot, e.g. ``Ex``, ``Ey`` or ``Ez``.
+
+
 .. _waveforms:
 
-******************
 Built-in waveforms
-******************
+==================
 
 This section provides definitions of the functions that are used to create the built-in waveforms. Example plots are shown using the parameters: amplitude of one, frequency of 1GHz, time window of 6ns, and a time step of 1.926ps.
 
 gaussian
-========
+--------
 
 A Gaussian waveform.
 
@@ -21,7 +43,7 @@ where :math:`I` is the current, :math:`\zeta = 2\pi^2f^2`, :math:`\chi=\frac{1}{
 
 
 gaussiandot
-===========
+-----------
 
 First derivative of a Gaussian waveform.
 
@@ -35,7 +57,7 @@ where :math:`I` is the current, :math:`\zeta = 2\pi^2f^2`, :math:`\chi=\frac{1}{
 
 
 gaussiandotnorm
-===============
+---------------
 
 Normalised first derivative of a Gaussian waveform.
 
@@ -49,7 +71,7 @@ where :math:`I` is the current, :math:`\zeta = 2\pi^2f^2`, :math:`\chi=\frac{1}{
 
 
 gaussiandotdot
-==============
+--------------
 
 Second derivative of a Gaussian waveform.
 
@@ -63,7 +85,7 @@ where :math:`I` is the current, :math:`\zeta = \pi^2f^2`, :math:`\chi=\frac{\sqr
 
 
 gaussiandotdotnorm
-==================
+------------------
 
 Normalised second derivative of a Gaussian waveform.
 
@@ -77,7 +99,7 @@ where :math:`I` is the current, :math:`\zeta = \pi^2f^2`, :math:`\chi=\frac{\sqr
 
 
 ricker
-======
+------
 
 A Ricker (or Mexican Hat) waveform which is the negative, normalised second derivative of a Gaussian waveform.
 
@@ -91,7 +113,7 @@ where :math:`I` is the current, :math:`\zeta = \pi^2f^2`, :math:`\chi=\frac{\sqr
 
 
 sine
-====
+----
 
 A single cycle of a sine waveform.
 
@@ -115,7 +137,7 @@ and
 
 
 contsine
-========
+--------
 
 A continuous sine waveform. In order to avoid introducing noise into the calculation the amplitude of the waveform is modulated for the first cycle of the sine wave (ramp excitation).
 

tools/plot_waveform.py

@@ -1,77 +0,0 @@
-# Copyright (C) 2015: The University of Edinburgh
-#            Authors: Craig Warren and Antonis Giannopoulos
-#
-# This file is part of gprMax.
-#
-# gprMax is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# gprMax is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# 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, argparse
-import numpy as np
-import matplotlib.pyplot as plt
-
-from gprMax.waveforms import Waveform
-
-
-"""Plot waveforms that can be used for sources."""
-
-# Parse command line arguments
-parser = argparse.ArgumentParser(description='Plot waveforms that can be used for sources.', usage='cd gprMax; python -m tools.plot_waveform type amp freq timewindow dt')
-parser.add_argument('type', help='type of waveform, e.g. gaussian, ricker etc...')
-parser.add_argument('amp', type=float, help='amplitude of waveform')
-parser.add_argument('freq', type=float, help='centre frequency of waveform')
-parser.add_argument('timewindow', type=float, help='time window to view waveform')
-parser.add_argument('dt', type=float, help='time step to view waveform')
-args = parser.parse_args()
-
-w = Waveform()
-w.type = args.type
-w.amp = args.amp
-w.freq = args.freq
-timewindow = args.timewindow
-dt = args.dt
-
-time = np.arange(0, timewindow, dt)
-waveform = np.zeros(len(time))
-timeiter = np.nditer(time, flags=['c_index'])
-
-while not timeiter.finished:
-    waveform[timeiter.index] = w.calculate_value(timeiter[0], dt)
-    timeiter.iternext()
-
-# Calculate frequency spectra of waveform
-power = 20 * np.log10(np.abs(np.fft.fft(waveform))**2)
-f = np.fft.fftfreq(power.size, d=dt)
-
-# Shift powers so any spectra with negative DC component will start at zero
-power -= np.amax(power)
-
-# Set plotting range to 4 * centre frequency
-pltrange = np.where(f > (4 * w.freq))[0][0]
-
-# Plot waveform
-fig, (ax1, ax2) = plt.subplots(nrows=1, ncols=2, num=w.type, figsize=(20, 10), facecolor='w', edgecolor='w')
-ax1.plot(time, waveform, 'r', lw=2)
-ax1.set_xlabel('Time [ns]')
-ax1.set_ylabel('Amplitude')
-[label.set_bbox(dict(facecolor='white', edgecolor='None', alpha=0.65)) for label in ax1.get_xticklabels() + ax1.get_yticklabels()]
-
-# Plot frequency spectra
-ax2.stem(f[0:pltrange]/1e9, power[0:pltrange],'b', lw=2)
-ax2.set_xlabel('Frequency [GHz]')
-ax2.set_ylabel('Power [dB]')
-[ax.grid() for ax in fig.axes] # Turn on grid
-plt.show()
-
-# Save a PDF of the figure
-#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)