Re-structuring package layout

toolboxes/Plotting/plot_Ascan.py

@@ -0,0 +1,282 @@
+# Copyright (C) 2015-2022: The University of Edinburgh, United Kingdom
+#                 Authors: Craig Warren, Antonis Giannopoulos, and John Hartley
+#
+# 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 argparse
+import logging
+from pathlib import Path
+
+import h5py
+import matplotlib.gridspec as gridspec
+import matplotlib.pyplot as plt
+import numpy as np
+from gprMax.receivers import Rx
+from gprMax.utilities.utilities import fft_power
+
+logger = logging.getLogger(__name__)
+
+
+def mpl_plot(filename, outputs=Rx.defaultoutputs, 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.
+    """
+
+    file = Path(filename)
+
+    # Open output file and read iterations
+    f = h5py.File(file, 'r')
+
+    # Paths to grid(s) to traverse for outputs
+    paths = ['/']
+
+    # Check if any subgrids and add path(s)
+    is_subgrids = "/subgrids" in f
+    if is_subgrids:
+        paths = paths + ['/subgrids/' + path + '/' for path in f['/subgrids'].keys()]
+
+    # Get number of receivers in grid(s)
+    nrxs = []
+    for path in paths:
+        if f[path].attrs['nrx'] > 0:
+            nrxs.append(f[path].attrs['nrx'])
+        else:
+            paths.remove(path)
+
+    # Check there are any receivers
+    if not paths:
+        logger.exception(f'No receivers found in {file}')
+        raise ValueError
+
+    # Loop through all grids
+    for path in paths:
+        iterations = f[path].attrs['Iterations']
+        nrx = f[path].attrs['nrx']
+        dt = f[path].attrs['dt']
+        time = np.linspace(0, (iterations - 1) * dt, num=iterations)
+
+        # Check for single output component when doing a FFT
+        if fft:
+            if not len(outputs) == 1:
+                logger.exception('A single output must be specified when using the -fft option')
+                raise ValueError
+
+        # New plot for each receiver
+        for rx in range(1, nrx + 1):
+            rxpath = path + 'rxs/rx' + str(rx) + '/'
+            availableoutputs = list(f[rxpath].keys())
+
+            # If only a single output is required, create one subplot
+            if len(outputs) == 1:
+
+                # Check for polarity of output and if requested output is in file
+                if outputs[0][-1] == '-':
+                    polarity = -1
+                    outputtext = '-' + outputs[0][0:-1]
+                    output = outputs[0][0:-1]
+                else:
+                    polarity = 1
+                    outputtext = outputs[0]
+                    output = outputs[0]
+
+                if output not in availableoutputs:
+                    logger.exception(f"{output} output requested to plot, but the available output for receiver 1 is {', '.join(availableoutputs)}")
+                    raise ValueError
+
+                outputdata = f[rxpath + output][:] * polarity
+
+                # Plotting if FFT required
+                if fft:
+                    # FFT
+                    freqs, power = fft_power(outputdata, dt)
+                    freqmaxpower = np.where(np.isclose(power, 0))[0][0]
+
+                    # Set plotting range to -60dB from maximum power or 4 times
+                    # frequency at maximum power
+                    try:
+                        pltrange = np.where(power[freqmaxpower:] < -60)[0][0] + freqmaxpower + 1
+                    except:
+                        pltrange = freqmaxpower * 4
+
+                    pltrange = np.s_[0:pltrange]
+
+                    # Plot time history of output component
+                    fig, (ax1, ax2) = plt.subplots(nrows=1, ncols=2,
+                                                   num=rxpath + ' - ' + f[rxpath].attrs['Name'],
+                                                   figsize=(20, 10), facecolor='w',
+                                                   edgecolor='w')
+                    line1 = ax1.plot(time, outputdata, 'r', lw=2, label=outputtext)
+                    ax1.set_xlabel('Time [s]')
+                    ax1.set_ylabel(outputtext + ' field strength [V/m]')
+                    ax1.set_xlim([0, np.amax(time)])
+                    ax1.grid(which='both', axis='both', linestyle='-.')
+
+                    # Plot frequency spectra
+                    markerline, stemlines, baseline = ax2.stem(freqs[pltrange],
+                                                               power[pltrange], '-.',
+                                                               use_line_collection=True)
+                    plt.setp(baseline, 'linewidth', 0)
+                    plt.setp(stemlines, 'color', 'r')
+                    plt.setp(markerline, 'markerfacecolor', 'r', 'markeredgecolor', 'r')
+                    line2 = ax2.plot(freqs[pltrange], power[pltrange], 'r', lw=2)
+                    ax2.set_xlabel('Frequency [Hz]')
+                    ax2.set_ylabel('Power [dB]')
+                    ax2.grid(which='both', axis='both', linestyle='-.')
+
+                    # Change colours and labels for magnetic field components or currents
+                    if 'H' in outputs[0]:
+                        plt.setp(line1, color='g')
+                        plt.setp(line2, color='g')
+                        plt.setp(ax1, ylabel=outputtext + ' field strength [A/m]')
+                        plt.setp(stemlines, 'color', 'g')
+                        plt.setp(markerline, 'markerfacecolor', 'g', 'markeredgecolor', 'g')
+                    elif 'I' in outputs[0]:
+                        plt.setp(line1, color='b')
+                        plt.setp(line2, color='b')
+                        plt.setp(ax1, ylabel=outputtext + ' current [A]')
+                        plt.setp(stemlines, 'color', 'b')
+                        plt.setp(markerline, 'markerfacecolor', 'b', 'markeredgecolor', 'b')
+
+                    plt.show()
+
+                # Plotting if no FFT required
+                else:
+                    fig, ax = plt.subplots(subplot_kw=dict(xlabel='Time [s]',
+                                           ylabel=outputtext + ' field strength [V/m]'),
+                                           num=rxpath + ' - ' + f[rxpath].attrs['Name'],
+                                           figsize=(20, 10), facecolor='w', edgecolor='w')
+                    line = ax.plot(time, outputdata, 'r', lw=2, label=outputtext)
+                    ax.set_xlim([0, np.amax(time)])
+                    # ax.set_ylim([-15, 20])
+                    ax.grid(which='both', axis='both', linestyle='-.')
+
+                    if 'H' in output:
+                        plt.setp(line, color='g')
+                        plt.setp(ax, ylabel=outputtext + ', field strength [A/m]')
+                    elif 'I' in output:
+                        plt.setp(line, color='b')
+                        plt.setp(ax, ylabel=outputtext + ', current [A]')
+
+            # If multiple outputs required, create all nine subplots and populate only the specified ones
+            else:
+                fig, ax = plt.subplots(subplot_kw=dict(xlabel='Time [s]'),
+                                       num=rxpath + ' - ' + f[rxpath].attrs['Name'],
+                                       figsize=(20, 10), facecolor='w', edgecolor='w')
+                if len(outputs) == 9:
+                    gs = gridspec.GridSpec(3, 3, hspace=0.3, wspace=0.3)
+                else:
+                    gs = gridspec.GridSpec(3, 2, hspace=0.3, wspace=0.3)
+
+                for output in outputs:
+                    # Check for polarity of output and if requested output is in file
+                    if output[-1] == 'm':
+                        polarity = -1
+                        outputtext = '-' + output[0:-1]
+                        output = output[0:-1]
+                    else:
+                        polarity = 1
+                        outputtext = output
+
+                    # Check if requested output is in file
+                    if output not in availableoutputs:
+                        logger.exception(f"Output(s) requested to plot: {', '.join(outputs)}, but available output(s) for receiver {rx} in the file: {', '.join(availableoutputs)}")
+                        raise ValueError
+
+                    outputdata = f[rxpath + output][:] * polarity
+
+                    if output == 'Ex':
+                        ax = plt.subplot(gs[0, 0])
+                        ax.plot(time, outputdata, 'r', lw=2, label=outputtext)
+                        ax.set_ylabel(outputtext + ', field strength [V/m]')
+                    # ax.set_ylim([-15, 20])
+                    elif output == 'Ey':
+                        ax = plt.subplot(gs[1, 0])
+                        ax.plot(time, outputdata, 'r', lw=2, label=outputtext)
+                        ax.set_ylabel(outputtext + ', field strength [V/m]')
+                    # ax.set_ylim([-15, 20])
+                    elif output == 'Ez':
+                        ax = plt.subplot(gs[2, 0])
+                        ax.plot(time, outputdata, 'r', lw=2, label=outputtext)
+                        ax.set_ylabel(outputtext + ', field strength [V/m]')
+                    # ax.set_ylim([-15, 20])
+                    elif output == 'Hx':
+                        ax = plt.subplot(gs[0, 1])
+                        ax.plot(time, outputdata, 'g', lw=2, label=outputtext)
+                        ax.set_ylabel(outputtext + ', field strength [A/m]')
+                    # ax.set_ylim([-0.03, 0.03])
+                    elif output == 'Hy':
+                        ax = plt.subplot(gs[1, 1])
+                        ax.plot(time, outputdata, 'g', lw=2, label=outputtext)
+                        ax.set_ylabel(outputtext + ', field strength [A/m]')
+                    # ax.set_ylim([-0.03, 0.03])
+                    elif output == 'Hz':
+                        ax = plt.subplot(gs[2, 1])
+                        ax.plot(time, outputdata, 'g', lw=2, label=outputtext)
+                        ax.set_ylabel(outputtext + ', field strength [A/m]')
+                    # ax.set_ylim([-0.03, 0.03])
+                    elif output == 'Ix':
+                        ax = plt.subplot(gs[0, 2])
+                        ax.plot(time, outputdata, 'b', lw=2, label=outputtext)
+                        ax.set_ylabel(outputtext + ', current [A]')
+                    elif output == 'Iy':
+                        ax = plt.subplot(gs[1, 2])
+                        ax.plot(time, outputdata, 'b', lw=2, label=outputtext)
+                        ax.set_ylabel(outputtext + ', current [A]')
+                    elif output == 'Iz':
+                        ax = plt.subplot(gs[2, 2])
+                        ax.plot(time, outputdata, 'b', lw=2, label=outputtext)
+                        ax.set_ylabel(outputtext + ', current [A]')
+                for ax in fig.axes:
+                    ax.set_xlim([0, np.amax(time)])
+                    ax.grid(which='both', axis='both', linestyle='-.')
+
+            # Save a PDF/PNG of the figure
+            savename = file.stem + '_rx' + str(rx)
+            savename = file.parent / savename
+            # fig.savefig(savename.with_suffix('.pdf'), dpi=None, format='pdf',
+            #             bbox_inches='tight', pad_inches=0.1)
+            # fig.savefig(savename.with_suffix('.png'), dpi=150, format='png',
+            #             bbox_inches='tight', pad_inches=0.1)
+
+    f.close()
+
+    return plt
+
+
+if __name__ == "__main__":
+
+    # Parse command line arguments
+    parser = argparse.ArgumentParser(description='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.', usage='cd gprMax; python -m tools.plot_Ascan outputfile')
+    parser.add_argument('outputfile', help='name of output file including path')
+    parser.add_argument('--outputs', help='outputs to be plotted',
+                        default=Rx.defaultoutputs,
+                        choices=['Ex', 'Ey', 'Ez', 'Hx', 'Hy', 'Hz', 'Ix', 'Iy', 'Iz', 'Ex-', 'Ey-', 'Ez-', 'Hx-', 'Hy-', 'Hz-', 'Ix-', 'Iy-', 'Iz-'],
+                        nargs='+')
+    parser.add_argument('-fft', action='store_true', help='plot FFT (single output must be specified)',
+                        default=False)
+    args = parser.parse_args()
+
+    plthandle = mpl_plot(args.outputfile, args.outputs, fft=args.fft)
+    plthandle.show()

toolboxes/Plotting/plot_Bscan.py

@@ -0,0 +1,101 @@
+# Copyright (C) 2015-2022: The University of Edinburgh, United Kingdom
+#                 Authors: Craig Warren, Antonis Giannopoulos, and John Hartley
+#
+# 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 argparse
+import logging
+from pathlib import Path
+
+import h5py
+import matplotlib.pyplot as plt
+import numpy as np
+
+from .outputfiles_merge import get_output_data
+
+logger = logging.getLogger(__name__)
+
+
+def mpl_plot(filename, outputdata, dt, rxnumber, rxcomponent):
+    """Creates a plot (with matplotlib) of the B-scan.
+
+    Args:
+        filename (string): Filename (including path) of output file.
+        outputdata (array): Array of A-scans, i.e. B-scan data.
+        dt (float): Temporal resolution of the model.
+        rxnumber (int): Receiver output number.
+        rxcomponent (str): Receiver output field/current component.
+
+    Returns:
+        plt (object): matplotlib plot object.
+    """
+
+    file = Path(filename)
+
+    fig = plt.figure(num=file.stem + ' - rx' + str(rxnumber), figsize=(20, 10),
+                     facecolor='w', edgecolor='w')
+    plt.imshow(outputdata, extent=[0, outputdata.shape[1], outputdata.shape[0] * dt, 0],
+               interpolation='nearest', aspect='auto', cmap='seismic',
+               vmin=-np.amax(np.abs(outputdata)), vmax=np.amax(np.abs(outputdata)))
+    plt.xlabel('Trace number')
+    plt.ylabel('Time [s]')
+
+    # Grid properties
+    ax = fig.gca()
+    ax.grid(which='both', axis='both', linestyle='-.')
+
+    cb = plt.colorbar()
+    if 'E' in rxcomponent:
+        cb.set_label('Field strength [V/m]')
+    elif 'H' in rxcomponent:
+        cb.set_label('Field strength [A/m]')
+    elif 'I' in rxcomponent:
+        cb.set_label('Current [A]')
+
+    # Save a PDF/PNG of the figure
+    # fig.savefig(file.with_suffix('.pdf'), dpi=None, format='pdf',
+    #             bbox_inches='tight', pad_inches=0.1)
+    # fig.savefig(file.with_suffix('.png'), dpi=150, format='png',
+    #             bbox_inches='tight', pad_inches=0.1)
+
+    return plt
+
+
+if __name__ == "__main__":
+
+    # Parse command line arguments
+    parser = argparse.ArgumentParser(description='Plots a B-scan image.',
+                                     usage='cd gprMax; python -m tools.plot_Bscan outputfile output')
+    parser.add_argument('outputfile', help='name of output file including path')
+    parser.add_argument('rx_component', help='name of output component to be plotted',
+                        choices=['Ex', 'Ey', 'Ez', 'Hx', 'Hy', 'Hz', 'Ix', 'Iy', 'Iz'])
+    args = parser.parse_args()
+
+    # Open output file and read number of outputs (receivers)
+    f = h5py.File(args.outputfile, 'r')
+    nrx = f.attrs['nrx']
+    f.close()
+
+    # Check there are any receivers
+    if nrx == 0:
+        logger.exception(f'No receivers found in {args.outputfile}')
+        raise ValueError
+
+    for rx in range(1, nrx + 1):
+        outputdata, dt = get_output_data(args.outputfile, rx, args.rx_component)
+        plthandle = mpl_plot(args.outputfile, outputdata, dt, rx, args.rx_component)
+
+    plthandle.show()

toolboxes/Plotting/plot_antenna_params.py

@@ -0,0 +1,446 @@
+# Copyright (C) 2015-2022: The University of Edinburgh, United Kingdom
+#                 Authors: Craig Warren, Antonis Giannopoulos, and John Hartley
+#
+# 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 argparse
+import logging
+from pathlib import Path
+
+import h5py
+import matplotlib.gridspec as gridspec
+import matplotlib.pyplot as plt
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+def calculate_antenna_params(filename, tltxnumber=1, tlrxnumber=None, 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.
+        tltxnumber (int): Transmitter antenna - transmission line number
+        tlrxnumber (int): Receiver 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
+    file = Path(filename)
+    f = h5py.File(file, 'r')
+    dxdydz = f.attrs['dx_dy_dz']
+    dt = f.attrs['dt']
+    iterations = f.attrs['Iterations']
+
+    # Calculate time array and frequency bin spacing
+    time = np.linspace(0, (iterations - 1) * dt, num=iterations)
+    df = 1 / np.amax(time)
+
+    logger.info(f'Time window: {np.amax(time):g} s ({iterations} iterations)')
+    logger.info(f'Time step: {dt:g} s')
+    logger.info(f'Frequency bin spacing: {df:g} Hz')
+
+    # Read/calculate voltages and currents from transmitter antenna
+    tltxpath = '/tls/tl' + str(tltxnumber) + '/'
+
+    # Incident voltages/currents
+    Vinc = f[tltxpath + 'Vinc'][:]
+    Iinc = f[tltxpath + 'Iinc'][:]
+
+    # Total (incident + reflected) voltages/currents
+    Vtotal = f[tltxpath + 'Vtotal'][:]
+    Itotal = f[tltxpath + 'Itotal'][:]
+
+    # Reflected voltages/currents
+    Vref = Vtotal - Vinc
+    Iref = Itotal - Iinc
+
+    # If a receiver antenna is used (with a transmission line or receiver), get received voltage for s21
+    if tlrxnumber:
+        tlrxpath = '/tls/tl' + str(tlrxnumber) + '/'
+        Vrec = f[tlrxpath + 'Vtotal'][:]
+
+    elif rxnumber:
+        rxpath = '/rxs/rx' + str(rxnumber) + '/'
+        availableoutputs = list(f[rxpath].keys())
+
+        if rxcomponent not in availableoutputs:
+            logger.exception(f"{rxcomponent} output requested, but the available output for receiver {rxnumber} is {', '.join(availableoutputs)}")
+            raise ValueError
+
+        rxpath += rxcomponent
+
+        # Received voltage
+        if rxcomponent == 'Ex':
+            Vrec = f[rxpath][:] * -1 * dxdydz[0]
+        elif rxcomponent == 'Ey':
+            Vrec = f[rxpath][:] * -1 * dxdydz[1]
+        elif rxcomponent == 'Ez':
+            Vrec = f[rxpath][:] * -1 * dxdydz[2]
+    f.close()
+
+    # Frequency bins
+    freqs = np.fft.fftfreq(Vinc.size, d=dt)
+
+    # Delay correction - current lags voltage, so delay voltage to match current timestep
+    delaycorrection = np.exp(1j * 2 * np.pi * freqs * (dt / 2))
+
+    # Calculate s11 and (optionally) s21
+    s11 = np.abs(np.fft.fft(Vref) / np.fft.fft(Vinc))
+    if tlrxnumber or rxnumber:
+        s21 = np.abs(np.fft.fft(Vrec) / np.fft.fft(Vinc))
+
+    # Calculate input impedance
+    zin = (np.fft.fft(Vtotal) * delaycorrection) / np.fft.fft(Itotal)
+
+    # Calculate input admittance
+    yin = np.fft.fft(Itotal) / (np.fft.fft(Vtotal) * delaycorrection)
+
+    # Convert to decibels (ignore warning from taking a log of any zero values)
+    with np.errstate(divide='ignore'):
+        Vincp = 20 * np.log10(np.abs((np.fft.fft(Vinc) * delaycorrection)))
+        Iincp = 20 * np.log10(np.abs(np.fft.fft(Iinc)))
+        Vrefp = 20 * np.log10(np.abs((np.fft.fft(Vref) * delaycorrection)))
+        Irefp = 20 * np.log10(np.abs(np.fft.fft(Iref)))
+        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)
+
+    # Replace any NaNs or Infs from zero division
+    Vincp[np.invert(np.isfinite(Vincp))] = 0
+    Iincp[np.invert(np.isfinite(Iincp))] = 0
+    Vrefp[np.invert(np.isfinite(Vrefp))] = 0
+    Irefp[np.invert(np.isfinite(Irefp))] = 0
+    Vtotalp[np.invert(np.isfinite(Vtotalp))] = 0
+    Itotalp[np.invert(np.isfinite(Itotalp))] = 0
+    s11[np.invert(np.isfinite(s11))] = 0
+
+    # 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 tlrxnumber or rxnumber:
+        with np.errstate(divide='ignore'): # Ignore warning from taking a log of any zero values
+            s21 = 20 * np.log10(s21)
+        s21[np.invert(np.isfinite(s21))] = 0
+        antennaparams['s21'] = s21
+
+    return antennaparams
+
+
+def mpl_plot(filename, 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:
+        filename (string): Filename (including path) of output file.
+        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
+    # To a certain drop from maximum power
+    pltrangemax = np.where((np.amax(Vincp[1::]) - Vincp[1::]) > 60)[0][0] + 1
+    # To a maximum frequency
+    pltrangemax = np.where(freqs > 3e9)[0][0]
+    pltrange = np.s_[pltrangemin:pltrangemax]
+
+    # Print some useful values from s11, and input impedance
+    s11minfreq = np.where(s11[pltrange] == np.amin(s11[pltrange]))[0][0]
+    logger.info(f's11 minimum: {np.amin(s11[pltrange]):g} dB at {freqs[s11minfreq + pltrangemin]:g} Hz')
+    logger.info(f'At {freqs[s11minfreq + pltrangemin]:g} Hz...')
+    logger.info(f'Input impedance: {np.abs(zin[s11minfreq + pltrangemin]):.1f}{zin[s11minfreq + pltrangemin].imag:+.1f}j Ohms')
+    # logger.info(f'Input admittance (mag): {np.abs(yin[s11minfreq + pltrangemin]):g} S')
+    # logger.info(f'Input admittance (phase): {np.angle(yin[s11minfreq + pltrangemin], deg=True):.1f} deg')
+
+    # Figure 1
+    # Plot incident voltage
+    fig1, ax = plt.subplots(num='Transmitter transmission line parameters',
+                            figsize=(20, 12), facecolor='w', edgecolor='w')
+    gs1 = gridspec.GridSpec(4, 2, hspace=0.7)
+    ax = plt.subplot(gs1[0, 0])
+    ax.plot(time, Vinc, 'r', lw=2, label='Vinc')
+    ax.set_title('Incident voltage')
+    ax.set_xlabel('Time [s]')
+    ax.set_ylabel('Voltage [V]')
+    ax.set_xlim([0, np.amax(time)])
+    ax.grid(which='both', axis='both', linestyle='-.')
+
+    # Plot frequency spectra of incident voltage
+    ax = plt.subplot(gs1[0, 1])
+    markerline, stemlines, baseline = ax.stem(freqs[pltrange], Vincp[pltrange],
+                                              '-.', use_line_collection=True)
+    plt.setp(baseline, 'linewidth', 0)
+    plt.setp(stemlines, 'color', 'r')
+    plt.setp(markerline, 'markerfacecolor', 'r', 'markeredgecolor', 'r')
+    ax.plot(freqs[pltrange], Vincp[pltrange], 'r', lw=2)
+    ax.set_title('Incident voltage')
+    ax.set_xlabel('Frequency [Hz]')
+    ax.set_ylabel('Power [dB]')
+    ax.grid(which='both', axis='both', linestyle='-.')
+
+    # Plot incident current
+    ax = plt.subplot(gs1[1, 0])
+    ax.plot(time, Iinc, 'b', lw=2, label='Vinc')
+    ax.set_title('Incident current')
+    ax.set_xlabel('Time [s]')
+    ax.set_ylabel('Current [A]')
+    ax.set_xlim([0, np.amax(time)])
+    ax.grid(which='both', axis='both', linestyle='-.')
+
+    # Plot frequency spectra of incident current
+    ax = plt.subplot(gs1[1, 1])
+    markerline, stemlines, baseline = ax.stem(freqs[pltrange], Iincp[pltrange],
+                                              '-.', use_line_collection=True)
+    plt.setp(baseline, 'linewidth', 0)
+    plt.setp(stemlines, 'color', 'b')
+    plt.setp(markerline, 'markerfacecolor', 'b', 'markeredgecolor', 'b')
+    ax.plot(freqs[pltrange], Iincp[pltrange], 'b', lw=2)
+    ax.set_title('Incident current')
+    ax.set_xlabel('Frequency [Hz]')
+    ax.set_ylabel('Power [dB]')
+    ax.grid(which='both', axis='both', linestyle='-.')
+
+    # Plot total voltage
+    ax = plt.subplot(gs1[2, 0])
+    ax.plot(time, Vtotal, 'r', lw=2, label='Vinc')
+    ax.set_title('Total (incident + reflected) voltage')
+    ax.set_xlabel('Time [s]')
+    ax.set_ylabel('Voltage [V]')
+    ax.set_xlim([0, np.amax(time)])
+    ax.grid(which='both', axis='both', linestyle='-.')
+
+    # Plot frequency spectra of total voltage
+    ax = plt.subplot(gs1[2, 1])
+    markerline, stemlines, baseline = ax.stem(freqs[pltrange], Vtotalp[pltrange],
+                                              '-.', use_line_collection=True)
+    plt.setp(baseline, 'linewidth', 0)
+    plt.setp(stemlines, 'color', 'r')
+    plt.setp(markerline, 'markerfacecolor', 'r', 'markeredgecolor', 'r')
+    ax.plot(freqs[pltrange], Vtotalp[pltrange], 'r', lw=2)
+    ax.set_title('Total (incident + reflected) voltage')
+    ax.set_xlabel('Frequency [Hz]')
+    ax.set_ylabel('Power [dB]')
+    ax.grid(which='both', axis='both', linestyle='-.')
+
+    # Plot total current
+    ax = plt.subplot(gs1[3, 0])
+    ax.plot(time, Itotal, 'b', lw=2, label='Vinc')
+    ax.set_title('Total (incident + reflected) current')
+    ax.set_xlabel('Time [s]')
+    ax.set_ylabel('Current [A]')
+    ax.set_xlim([0, np.amax(time)])
+    ax.grid(which='both', axis='both', linestyle='-.')
+
+    # Plot frequency spectra of total current
+    ax = plt.subplot(gs1[3, 1])
+    markerline, stemlines, baseline = ax.stem(freqs[pltrange], Itotalp[pltrange],
+                                              '-.', use_line_collection=True)
+    plt.setp(baseline, 'linewidth', 0)
+    plt.setp(stemlines, 'color', 'b')
+    plt.setp(markerline, 'markerfacecolor', 'b', 'markeredgecolor', 'b')
+    ax.plot(freqs[pltrange], Itotalp[pltrange], 'b', lw=2)
+    ax.set_title('Total (incident + reflected) current')
+    ax.set_xlabel('Frequency [Hz]')
+    ax.set_ylabel('Power [dB]')
+    ax.grid(which='both', axis='both', linestyle='-.')
+
+    # Plot reflected (reflected) voltage
+    # ax = plt.subplot(gs1[4, 0])
+    # ax.plot(time, Vref, 'r', lw=2, label='Vref')
+    # ax.set_title('Reflected voltage')
+    # ax.set_xlabel('Time [s]')
+    # ax.set_ylabel('Voltage [V]')
+    # ax.set_xlim([0, np.amax(time)])
+    # ax.grid(which='both', axis='both', linestyle='-.')
+
+    # Plot frequency spectra of reflected voltage
+    # ax = plt.subplot(gs1[4, 1])
+    # markerline, stemlines, baseline = ax.stem(freqs[pltrange], Vrefp[pltrange],
+    #                                           '-.', use_line_collection=True)
+    # plt.setp(baseline, 'linewidth', 0)
+    # plt.setp(stemlines, 'color', 'r')
+    # plt.setp(markerline, 'markerfacecolor', 'r', 'markeredgecolor', 'r')
+    # ax.plot(freqs[pltrange], Vrefp[pltrange], 'r', lw=2)
+    # ax.set_title('Reflected voltage')
+    # ax.set_xlabel('Frequency [Hz]')
+    # ax.set_ylabel('Power [dB]')
+    # ax.grid(which='both', axis='both', linestyle='-.')
+
+    # Plot reflected (reflected) current
+    # ax = plt.subplot(gs1[5, 0])
+    # ax.plot(time, Iref, 'b', lw=2, label='Iref')
+    # ax.set_title('Reflected current')
+    # ax.set_xlabel('Time [s]')
+    # ax.set_ylabel('Current [A]')
+    # ax.set_xlim([0, np.amax(time)])
+    # ax.grid(which='both', axis='both', linestyle='-.')
+
+    # Plot frequency spectra of reflected current
+    # ax = plt.subplot(gs1[5, 1])
+    # markerline, stemlines, baseline = ax.stem(freqs[pltrange], Irefp[pltrange],
+    #                                           '-.', use_line_collection=True)
+    # plt.setp(baseline, 'linewidth', 0)
+    # plt.setp(stemlines, 'color', 'b')
+    # plt.setp(markerline, 'markerfacecolor', 'b', 'markeredgecolor', 'b')
+    # ax.plot(freqs[pltrange], Irefp[pltrange], 'b', lw=2)
+    # ax.set_title('Reflected current')
+    # ax.set_xlabel('Frequency [Hz]')
+    # ax.set_ylabel('Power [dB]')
+    # ax.grid(which='both', axis='both', linestyle='-.')
+
+    # 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.3)
+    ax = plt.subplot(gs2[0, 0])
+    markerline, stemlines, baseline = ax.stem(freqs[pltrange], s11[pltrange],
+                                              '-.', use_line_collection=True)
+    plt.setp(baseline, 'linewidth', 0)
+    plt.setp(stemlines, 'color', 'g')
+    plt.setp(markerline, 'markerfacecolor', 'g', 'markeredgecolor', 'g')
+    ax.plot(freqs[pltrange], s11[pltrange], 'g', lw=2)
+    ax.set_title('s11')
+    ax.set_xlabel('Frequency [Hz]')
+    ax.set_ylabel('Power [dB]')
+    # ax.set_xlim([0, 5e9])
+    # ax.set_ylim([-25, 0])
+    ax.grid(which='both', axis='both', linestyle='-.')
+
+    # Plot frequency spectra of s21
+    if s21 is not None:
+        ax = plt.subplot(gs2[0, 1])
+        markerline, stemlines, baseline = ax.stem(freqs[pltrange], s21[pltrange],
+                                                  '-.', use_line_collection=True)
+        plt.setp(baseline, 'linewidth', 0)
+        plt.setp(stemlines, 'color', 'g')
+        plt.setp(markerline, 'markerfacecolor', 'g', 'markeredgecolor', 'g')
+        ax.plot(freqs[pltrange], s21[pltrange], 'g', lw=2)
+        ax.set_title('s21')
+        ax.set_xlabel('Frequency [Hz]')
+        ax.set_ylabel('Power [dB]')
+        # ax.set_xlim([0.88e9, 1.02e9])
+        # ax.set_ylim([-25, 50])
+        ax.grid(which='both', axis='both', linestyle='-.')
+
+    # Plot input resistance (real part of impedance)
+    ax = plt.subplot(gs2[1, 0])
+    markerline, stemlines, baseline = ax.stem(freqs[pltrange], zin[pltrange].real,
+                                              '-.', use_line_collection=True)
+    plt.setp(baseline, 'linewidth', 0)
+    plt.setp(stemlines, 'color', 'g')
+    plt.setp(markerline, 'markerfacecolor', 'g', 'markeredgecolor', 'g')
+    ax.plot(freqs[pltrange], zin[pltrange].real, 'g', lw=2)
+    ax.set_title('Input impedance (resistive)')
+    ax.set_xlabel('Frequency [Hz]')
+    ax.set_ylabel('Resistance [Ohms]')
+    # ax.set_xlim([0.88e9, 1.02e9])
+    ax.set_ylim(bottom=0)
+    # ax.set_ylim([0, 300])
+    ax.grid(which='both', axis='both', linestyle='-.')
+
+    # Plot input reactance (imaginery part of impedance)
+    ax = plt.subplot(gs2[1, 1])
+    markerline, stemlines, baseline = ax.stem(freqs[pltrange], zin[pltrange].imag,
+                                              '-.', use_line_collection=True)
+    plt.setp(baseline, 'linewidth', 0)
+    plt.setp(stemlines, 'color', 'g')
+    plt.setp(markerline, 'markerfacecolor', 'g', 'markeredgecolor', 'g')
+    ax.plot(freqs[pltrange], zin[pltrange].imag, 'g', lw=2)
+    ax.set_title('Input impedance (reactive)')
+    ax.set_xlabel('Frequency [Hz]')
+    ax.set_ylabel('Reactance [Ohms]')
+    # ax.set_xlim([0.88e9, 1.02e9])
+    # ax.set_ylim([-300, 300])
+    ax.grid(which='both', axis='both', linestyle='-.')
+
+    # Plot input admittance (magnitude)
+    # ax = plt.subplot(gs2[2, 0])
+    # markerline, stemlines, baseline = ax.stem(freqs[pltrange], np.abs(yin[pltrange]),
+    #                                           '-.', use_line_collection=True)
+    # plt.setp(baseline, 'linewidth', 0)
+    # plt.setp(stemlines, 'color', 'g')
+    # plt.setp(markerline, 'markerfacecolor', 'g', 'markeredgecolor', 'g')
+    # ax.plot(freqs[pltrange], np.abs(yin[pltrange]), 'g', lw=2)
+    # ax.set_title('Input admittance (magnitude)')
+    # ax.set_xlabel('Frequency [Hz]')
+    # ax.set_ylabel('Admittance [Siemens]')
+    # ax.set_xlim([0.88e9, 1.02e9])
+    # ax.set_ylim([0, 0.035])
+    # ax.grid(which='both', axis='both', linestyle='-.')
+
+    # Plot input admittance (phase)
+    # ax = plt.subplot(gs2[2, 1])
+    # markerline, stemlines, baseline = ax.stem(freqs[pltrange], np.angle(yin[pltrange], deg=True),
+    #                                           '-.', use_line_collection=True)
+    # plt.setp(baseline, 'linewidth', 0)
+    # plt.setp(stemlines, 'color', 'g')
+    # plt.setp(markerline, 'markerfacecolor', 'g', 'markeredgecolor', 'g')
+    # ax.plot(freqs[pltrange], np.angle(yin[pltrange], deg=True), 'g', lw=2)
+    # ax.set_title('Input admittance (phase)')
+    # ax.set_xlabel('Frequency [Hz]')
+    # ax.set_ylabel('Phase [degrees]')
+    # ax.set_xlim([0.88e9, 1.02e9])
+    # ax.set_ylim([-40, 100])
+    # ax.grid(which='both', axis='both', linestyle='-.')
+
+    # Save a PDF/PNG of the figure
+    savename1 = filename.stem + '_tl_params'
+    savename1 = filename.parent / savename1
+    savename2 = filename.stem + '_ant_params'
+    savename2 = filename.parent / savename2
+    # fig1.savefig(savename1.with_suffix('.png'), dpi=150, format='png',
+    #              bbox_inches='tight', pad_inches=0.1)
+    # fig2.savefig(savename2.with_suffix('.png'), dpi=150, format='png',
+    #              bbox_inches='tight', pad_inches=0.1)
+    # fig1.savefig(savename1.with_suffix('.pdf'), dpi=None, format='pdf',
+    #              bbox_inches='tight', pad_inches=0.1)
+    # fig2.savefig(savename2.with_suffix('.pdf'), dpi=None, format='pdf',
+    #              bbox_inches='tight', pad_inches=0.1)
+
+    return plt
+
+
+if __name__ == "__main__":
+
+    # Parse command line arguments
+    parser = argparse.ArgumentParser(description='Plots antenna parameters (s11, s21 parameters and input impedance) from an output file containing a transmission line source.', usage='cd gprMax; python -m tools.plot_antenna_params outputfile')
+    parser.add_argument('outputfile', help='name of output file including path')
+    parser.add_argument('--tltx-num', default=1, type=int, help='transmitter antenna - transmission line number')
+    parser.add_argument('--tlrx-num', type=int, help='receiver antenna - transmission line number')
+    parser.add_argument('--rx-num', type=int, help='receiver antenna - output number')
+    parser.add_argument('--rx-component', type=str, help='receiver antenna - output electric field component', choices=['Ex', 'Ey', 'Ez'])
+    args = parser.parse_args()
+
+    antennaparams = calculate_antenna_params(args.outputfile, args.tltx_num, args.tlrx_num, args.rx_num, args.rx_component)
+    plthandle = mpl_plot(args.outputfile, **antennaparams)
+    plthandle.show()

toolboxes/Plotting/plot_source_wave.py

@@ -0,0 +1,184 @@
+# Copyright (C) 2015-2022: The University of Edinburgh, United Kingdom
+#                 Authors: Craig Warren, Antonis Giannopoulos, and John Hartley
+#
+# 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 argparse
+import logging
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
+from gprMax.utilities.utilities import fft_power, round_value
+from gprMax.waveforms import Waveform
+
+logger = logging.getLogger(__name__)
+
+
+def check_timewindow(timewindow, dt):
+    """Checks and sets time window and number of iterations.
+
+    Args:
+        timewindow (float): Time window.
+        dt (float): Time discretisation.
+
+    Returns:
+        timewindow (float): Time window.
+        iterations (int): Number of interations.
+    """
+
+    # Time window could be a string, float or int, so convert to string then check
+    timewindow = str(timewindow)
+
+    try:
+        timewindow = int(timewindow)
+        iterations = timewindow
+        timewindow = (timewindow - 1) * dt
+
+    except:
+        timewindow = float(timewindow)
+        if timewindow > 0:
+            iterations = round_value((timewindow / dt)) + 1
+        else:
+            logger.exception('Time window must have a value greater than zero')
+            raise ValueError
+
+    return timewindow, iterations
+
+
+def mpl_plot(w, timewindow, dt, iterations, fft=False):
+    """Plots waveform and prints useful information about its properties.
+
+    Args:
+        w (class): Waveform class instance.
+        timewindow (float): Time window.
+        dt (float): Time discretisation.
+        iterations (int): Number of iterations.
+        fft (boolean): Plot FFT switch.
+
+    Returns:
+        plt (object): matplotlib plot object.
+    """
+
+    time = np.linspace(0, (iterations - 1) * dt, num=iterations)
+    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()
+
+    logger.info('Waveform characteristics...')
+    logger.info(f'Type: {w.type}')
+    logger.info(f'Maximum (absolute) amplitude: {np.max(np.abs(waveform)):g}')
+
+    if w.freq and not w.type == 'gaussian':
+        logger.info(f'Centre frequency: {w.freq:g} Hz')
+
+    if (w.type == 'gaussian' or w.type == 'gaussiandot' or w.type == 'gaussiandotnorm'
+        or w.type == 'gaussianprime' or w.type == 'gaussiandoubleprime'):
+        delay = 1 / w.freq
+        logger.info(f'Time to centre of pulse: {delay:g} s')
+    elif w.type == 'gaussiandotdot' or w.type == 'gaussiandotdotnorm' or w.type == 'ricker':
+        delay = np.sqrt(2) / w.freq
+        logger.info(f'Time to centre of pulse: {delay:g} s')
+
+    logger.info(f'Time window: {timewindow:g} s ({iterations} iterations)')
+    logger.info(f'Time step: {dt:g} s')
+
+    if fft:
+        # FFT
+        freqs, power = fft_power(waveform, dt)
+
+        # Set plotting range to 4 times frequency at max power of waveform or
+        # 4 times the centre frequency
+        freqmaxpower = np.where(np.isclose(power, 0))[0][0]
+        if freqs[freqmaxpower] > w.freq:
+            pltrange = np.where(freqs > 4 * freqs[freqmaxpower])[0][0]
+        else:
+            pltrange = np.where(freqs > 4 * w.freq)[0][0]
+        pltrange = np.s_[0:pltrange]
+
+        fig, (ax1, ax2) = plt.subplots(nrows=1, ncols=2, num=w.type,
+                                       figsize=(20, 10), facecolor='w',
+                                       edgecolor='w')
+
+        # Plot waveform
+        ax1.plot(time, waveform, 'r', lw=2)
+        ax1.set_xlabel('Time [s]')
+        ax1.set_ylabel('Amplitude')
+
+        # Plot frequency spectra
+        markerline, stemlines, baseline = ax2.stem(freqs[pltrange], power[pltrange],
+                                                   '-.', use_line_collection=True)
+        plt.setp(baseline, 'linewidth', 0)
+        plt.setp(stemlines, 'color', 'r')
+        plt.setp(markerline, 'markerfacecolor', 'r', 'markeredgecolor', 'r')
+        ax2.plot(freqs[pltrange], power[pltrange], 'r', lw=2)
+        ax2.set_xlabel('Frequency [Hz]')
+        ax2.set_ylabel('Power [dB]')
+
+    else:
+        fig, ax1 = plt.subplots(num=w.type, figsize=(20, 10), facecolor='w',
+                                edgecolor='w')
+
+        # Plot waveform
+        ax1.plot(time, waveform, 'r', lw=2)
+        ax1.set_xlabel('Time [s]')
+        ax1.set_ylabel('Amplitude')
+
+    # Turn on grid
+    [ax.grid(which='both', axis='both', linestyle='-.') for ax in fig.axes]
+
+    # Save a PDF/PNG of the figure
+    savefile = Path(__file__).parent / w.type
+    # fig.savefig(savefile.with_suffix('.pdf'), dpi=None, format='pdf',
+    #             bbox_inches='tight', pad_inches=0.1)
+    # fig.savefig(savefile.with_suffix('.png'), dpi=150, format='png',
+    #             bbox_inches='tight', pad_inches=0.1)
+
+    return plt
+
+
+if __name__ == "__main__":
+
+    # Parse command line arguments
+    parser = argparse.ArgumentParser(description='Plot built-in waveforms that can be used for sources.', usage='cd gprMax; python -m tools.plot_source_wave type amp freq timewindow dt')
+    parser.add_argument('type', help='type of waveform', choices=Waveform.types)
+    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', help='time window to view waveform')
+    parser.add_argument('dt', type=float, help='time step to view waveform')
+    parser.add_argument('-fft', action='store_true', help='plot FFT of waveform', default=False)
+    args = parser.parse_args()
+
+    # Check waveform parameters
+    if args.type.lower() not in Waveform.types:
+        logger.exception(f"The waveform must have one of the following types {', '.join(Waveform.types)}")
+        raise ValueError
+    if args.freq <= 0:
+        logger.exception('The waveform requires an excitation frequency value of greater than zero')
+        raise ValueError
+
+    # Create waveform instance
+    w = Waveform()
+    w.type = args.type
+    w.amp = args.amp
+    w.freq = args.freq
+
+    timewindow, iterations = check_timewindow(args.timewindow, args.dt)
+    plthandle = mpl_plot(w, timewindow, args.dt, iterations, args.fft)
+    plthandle.show()