diff --git a/docs/source/examples_2D.rst b/docs/source/examples_2D.rst index bcd70fc8..01173406 100644 --- a/docs/source/examples_2D.rst +++ b/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. diff --git a/docs/source/helper.rst b/docs/source/helper.rst new file mode 100644 index 00000000..452c1ebe --- /dev/null +++ b/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. diff --git a/docs/source/images/contsine.pdf b/docs/source/images/contsine.pdf deleted file mode 100644 index c6c0b8d1..00000000 Binary files a/docs/source/images/contsine.pdf and /dev/null differ diff --git a/docs/source/images/contsine.png b/docs/source/images/contsine.png index e60f73a3..900933ca 100644 Binary files a/docs/source/images/contsine.png and b/docs/source/images/contsine.png differ diff --git a/docs/source/images/gaussian.pdf b/docs/source/images/gaussian.pdf deleted file mode 100644 index 04cb9999..00000000 Binary files a/docs/source/images/gaussian.pdf and /dev/null differ diff --git a/docs/source/images/gaussian.png b/docs/source/images/gaussian.png index e8d73bc8..542d1ffa 100644 Binary files a/docs/source/images/gaussian.png and b/docs/source/images/gaussian.png differ diff --git a/docs/source/images/gaussiandot.pdf b/docs/source/images/gaussiandot.pdf deleted file mode 100644 index 78d33998..00000000 Binary files a/docs/source/images/gaussiandot.pdf and /dev/null differ diff --git a/docs/source/images/gaussiandot.png b/docs/source/images/gaussiandot.png index 7ff4dc17..e4dc76a4 100644 Binary files a/docs/source/images/gaussiandot.png and b/docs/source/images/gaussiandot.png differ diff --git a/docs/source/images/gaussiandotdot.pdf b/docs/source/images/gaussiandotdot.pdf deleted file mode 100644 index b3765fb8..00000000 Binary files a/docs/source/images/gaussiandotdot.pdf and /dev/null differ diff --git a/docs/source/images/gaussiandotdot.png b/docs/source/images/gaussiandotdot.png index 5e8ba940..7d61ffbf 100644 Binary files a/docs/source/images/gaussiandotdot.png and b/docs/source/images/gaussiandotdot.png differ diff --git a/docs/source/images/gaussiandotdotnorm.pdf b/docs/source/images/gaussiandotdotnorm.pdf deleted file mode 100644 index a0ff04f6..00000000 Binary files a/docs/source/images/gaussiandotdotnorm.pdf and /dev/null differ diff --git a/docs/source/images/gaussiandotdotnorm.png b/docs/source/images/gaussiandotdotnorm.png index b55a8c1e..644f59ae 100644 Binary files a/docs/source/images/gaussiandotdotnorm.png and b/docs/source/images/gaussiandotdotnorm.png differ diff --git a/docs/source/images/gaussiandotnorm.pdf b/docs/source/images/gaussiandotnorm.pdf deleted file mode 100644 index e677ea6e..00000000 Binary files a/docs/source/images/gaussiandotnorm.pdf and /dev/null differ diff --git a/docs/source/images/gaussiandotnorm.png b/docs/source/images/gaussiandotnorm.png index bfdec29e..133c263d 100644 Binary files a/docs/source/images/gaussiandotnorm.png and b/docs/source/images/gaussiandotnorm.png differ diff --git a/docs/source/images/ricker.pdf b/docs/source/images/ricker.pdf deleted file mode 100644 index a71c27bd..00000000 Binary files a/docs/source/images/ricker.pdf and /dev/null differ diff --git a/docs/source/images/ricker.png b/docs/source/images/ricker.png index cf6b5638..f5c46623 100644 Binary files a/docs/source/images/ricker.png and b/docs/source/images/ricker.png differ diff --git a/docs/source/images/sine.pdf b/docs/source/images/sine.pdf deleted file mode 100644 index ba0dad5a..00000000 Binary files a/docs/source/images/sine.pdf and /dev/null differ diff --git a/docs/source/images/sine.png b/docs/source/images/sine.png index bfcae490..c67be15d 100644 Binary files a/docs/source/images/sine.png and b/docs/source/images/sine.png differ diff --git a/docs/source/index.rst b/docs/source/index.rst index 6f3536db..4bfed446 100644 --- a/docs/source/index.rst +++ b/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 \ No newline at end of file + references \ No newline at end of file diff --git a/docs/source/output.rst b/docs/source/output.rst index 565fdfd4..bf4b4300 100644 --- a/docs/source/output.rst +++ b/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 `. diff --git a/docs/source/app_waveforms.rst b/docs/source/plotting.rst similarity index 69% rename from docs/source/app_waveforms.rst rename to docs/source/plotting.rst index c42f07ce..cd810cac 100644 --- a/docs/source/app_waveforms.rst +++ b/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). diff --git a/docs/source/app_references.rst b/docs/source/references.rst similarity index 100% rename from docs/source/app_references.rst rename to docs/source/references.rst diff --git a/tools/plot_waveform.py b/tools/plot_waveform.py deleted file mode 100644 index 3c20b340..00000000 --- a/tools/plot_waveform.py +++ /dev/null @@ -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 . - -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) \ No newline at end of file