Updated example on wire dipole model.

docs/source/examples_antennas.rst

@@ -4,25 +4,22 @@ Antenna models
 
 This section provides some example models of antennas. Each example comes with an input file which you can download and run.
 
+.. _example-wire-dipole:
+
 Wire dipole antenna model
 =========================
 
-**INFO ON THIS MODEL IN PROGRESS**
-
 :download:`antenna_wire_dipole_fs.in <../../user_models/antenna_wire_dipole_fs.in>`
 
-This example demonstrates a model of a half-wavelength wire dipole antenna in free space. The length of the dipole is 150mm with a diameter of 6mm, and a 1mm gap between the arms.
+This example demonstrates a model of a half-wavelength wire dipole antenna in free space. It is a balanced antenna and it's characteristics are well known from theory _[BAL2005]. The length of the dipole is 150mm with a 1mm gap between the arms.
 
 .. literalinclude:: ../../user_models/antenna_wire_dipole_fs.in
     :language: none
     :linenos:
 
-.. figure:: images/antenna_wire_dipole.png
-    :width: 600 px
+The wire is modelled using the ``#edge`` command which specifies properties of the edge of the Yee cell. The antenna is fed using the ``#transmission_line`` command. The one-dimensional transmission line model virtually attaches to the dipole at the gap between the arms. The antenna has an input impedance (:math:`Z_0`) of 73 Ohms specified in the ``#transmission_line`` command, and uses a Gaussian waveform with a centre frequency of 1GHz.
 
-    FDTD geometry mesh showing a wire dipole antenna model.
-
-The antenna is fed using the ``#transmission_line`` command. The one-dimensional transmission line model virtually attaches to the dipole at the gap between the arms. The antenna has an input impedance (:math:`Z_0`) of 73 Ohms specified in the ``#transmission_line`` command. The transmission line uses a Gaussian waveform with a centre frequency of 1GHz.
+Time histories of voltage and current values in the transmission line are saved to the output file. These are documented in the :ref:`output file section <output>`. These parameters are useful for calculating characteristics of the antenna such as the input impedance or S-parameters. gprMax includes a Python module (in the ``tools`` package) to help you view the input impedance and admittance and s11 parameter from an antenna model fed using a transmission line. Details of how to use this module is given in the :ref:`tools section <plotting>`.
 
 Results
 -------
@@ -31,15 +28,15 @@ Results
 
 .. figure:: images/antenna_wire_dipole_fs_tl_params.png
 
-    Time and frequency domain plots of the incident and reflected (scattered) voltages in the transmission line.
-
-Explanation of figures.
+    Time and frequency domain plots of the incident and total (incident + reflected) voltages and currents in the transmission line.
 
 .. _antenna_wire_dipole_fs_ant_params:
 
 .. figure:: images/antenna_wire_dipole_fs_ant_params.png
 
-    s11 parameter and input impedance (resistance and reactance) of the antenna.
+    Input admittance and impedance (resistance and reactance) and s11 parameter of the antenna.
+
+:numref:`antenna_wire_dipole_fs_tl_params` shows time histories and frequency spectra of the incident and total (incident + reflected) voltages and currents in the transmission line. :numref:`antenna_wire_dipole_fs_ant_params` shows the input admittance and impedance (resistance and reactance), and s11 parameter of the half-wavelength wire dipole. The s11 parameter shows that the antenna is resonant at 1GHz which is what is expected from the geometry and feeding. The input resistance (the real part of the input impedance) is 73 Ohms which is what is predicted by theory. The input reactance (the imaginery part of the input impedance) is a function of the length of the dipole and is zero in this case.
 
 
 Bowtie antenna model

docs/source/faqs.rst

@@ -20,12 +20,12 @@ No, but it can be beneficial to know a little Python. We have made it easier to
 Yes, we have provided tools to help you read the new HDF5-based output file in MATLAB.
 
 **But converting my input file from the old version of gprMax will be really painful**
-Hopefully not! We have provided a Python script to help you convert input files from the old version of gprMax to use syntax introduced in the version.
+Hopefully not! We have provided a Python script to help you convert input files from the old version of gprMax to use syntax introduced in version 3.
 
 **How do I choose a spatial resolution for my simulation?**
 Spatial resolution should be chosen to mitigate numerical dispersion and to adequately resolve geometry in your simulation. :ref:`A 2D example of modelling a metal cylinder in a dielectric <example-2D-Ascan>` provides guidance on how to determine spatial resolution.
 
-**I specified a certain piece of geometry but I don’t see when I view my geometry file.**
+**I specified a certain piece of geometry but I don’t see it when I view my geometry file.**
 gprMax builds objects in a model in the order the objects were specified in the input file, using a layered canvas approach. This means, for example, a cylinder object which comes after a box object in the input file will overwrite the properties of the box object at any locations where they overlap. This approach allows complex geometries to be created using basic object building blocks.
 
 **Can I run gprMax on my HPC/cluster?**

docs/source/features.rst

@@ -31,7 +31,7 @@ New commands
 * ``#add_dispersion_lorentz`` is used to add Lorentz dispersive properties to a ``#material``.
 * ``#add_dispersion_drude`` is used to add Drude dispersive properties to a ``#material``.
 * ``#soil_peplinski`` is a soil mixing model that can be used with ``#fractal_box`` to generate soil(s) with more realistic dielectric and geometric properties.
-* ``#cylindrical_sector`` (like a slice of pie shape) is a new object building command.
+* ``#cylindrical_sector`` is a new object building command.
 * ``#geometry_view`` replaces ``#geometry_file`` or ``#geometry_vtk`` and is used to create views of the geometry of the model in 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).
 * ``#fractal_box`` is used to create a volume with a fractal distribution of properties.
 * ``#add_surface_roughness`` is used to add a rough surface to a ``#fractal_box``.
@@ -51,7 +51,7 @@ Changed commands
 * ``#pml_cells`` replaces ``#pml_layers`` and can now be used to control the number of cells of PML on the six faces of the model domain. The number of cells can be set to zero on any of the faces to turn that PML off if desired. The default behaviour (if this command is not specified) is to use 10 cells.
 * ``#hertzian_dipole`` and ``#voltage_source`` now specify polarisation, location, any additional parameters, and an identifier to link to a ``#waveform`` command.
 * ``#snapshot`` no longer requires a type, as only VTK snapshot files are now produced.
-* ``#num_of_procs`` is now called ``#num_omp_threads``.
+* ``#num_of_procs`` is now called ``#num_threads``.
 * ``#tx_steps`` is now called ``#src_steps``.
 
 
@@ -75,7 +75,7 @@ Retired commands
 Commands yet to be implemented
 ------------------------------
 
-There are commands from previous versions of gprMax that are planned for this version, but are yet to be implemented. These will be introduced in a future update. They are``#thin_wire`` and ``#plane_wave``.
+There are commands from previous versions of gprMax that are planned for this version, but are yet to be implemented. These will be introduced in a future update. They are ``#thin_wire`` and ``#plane_wave``.
 
 
 Migrating old input files

docs/source/input.rst

@@ -764,7 +764,7 @@ For example, to specify a y directed voltage source with an internal resistance
 #transmission_line:
 -------------------
 
-Allows you to introduce a one-dimensional transmission line model at an electric field location. The transmission line has a specified resistance. It is useful for exciting antennas when the physical properties of the antenna are included in the model. The syntax of the command is:
+Allows you to introduce a one-dimensional transmission line model [MAL1994]_ at an electric field location. The transmission line has a specified resistance. It is useful for exciting antennas when the physical properties of the antenna are included in the model. The syntax of the command is:
 
 .. code-block:: none
 
@@ -776,10 +776,12 @@ Allows you to introduce a one-dimensional transmission line model at an electric
 * ``f5 f6`` are optional parameters. ``f5`` is a time delay in starting the excitation of the transmission line. ``f6`` is a time to remove the excitation of the transmission line. If the time window is longer than the excitation of the transmission line removal time then the excitation of the transmission line will stop after the excitation of the transmission line removal time. If the excitation of the transmission line removal time is longer than the time window then the excitation of the transmission line will be active for the entire time window. If ``f5 f6`` are omitted the excitation of the transmission line will start at the beginning of time window and stop at the end of the time window.
 * ``str1`` is the identifier of the waveform that should be used with the source.
 
-Time histories of voltage and current values in the transmission line are saved to the output file. These are documented in the :ref:`output file section <output>`. These parameters are useful for calculating characteristics of an antenna such as the input impedance or S-parameters.
+Time histories of voltage and current values in the transmission line are saved to the output file. These are documented in the :ref:`output file section <output>`. These parameters are useful for calculating characteristics of an antenna such as the input impedance or S-parameters. gprMax includes a Python module (in the ``tools`` package) to help you view the input impedance and s11 parameter from an antenna model fed using a transmission line. Details of how to use this module is given in the :ref:`tools section <plotting>`.
 
 For example, to specify a z directed transmission line source with a resistance of 75 Ohms, an amplitude of five, and a 1.2 GHz centre frequency Gaussian waveform use: ``#waveform: gaussian 5 1.2e9 my_gauss_pulse`` and ``#transmission_line: z 0.05 0.05 0.05 75 my_gauss_pulse``.
 
+An example antenna model using a transmission line can be found in the :ref:`examples section <example-wire-dipole>`.
+
 #rx:
 ----
 

docs/source/plotting.rst

@@ -48,6 +48,24 @@ where:
 * ``--field`` is the name of field component to plot, e.g. ``Ex``, ``Ey``, ``Ez``, ``Hx``, ``Hy`` or ``Hz``
 
 
+Antenna parameters
+==================
+
+plot_antenna_params.py
+----------------------
+
+This module uses matplotlib to plot the input impedance (resistance and reactance) and s11 parameter from an antenna model fed using a transmission line. It also plots the time history of the incident and reflected voltages in the transmission line and their frequency spectra. Usage (from the top-level gprMax directory) is:
+
+.. code-block:: none
+
+    python -m tools.plot_antenna_params outputfile --tln transmissionlinenumber
+
+where:
+
+* ``outputfile`` is the name of output file including the path
+* ``--tln`` is the number of the transmission line (default is one). Transmission lines are numbered (starting at one) in the order they appear in the input file.
+
+
 .. _waveforms:
 
 Built-in waveforms

docs/source/references.rst

@@ -2,6 +2,7 @@
 References
 **********
 
+.. [BAL2005] Balanis, C. A. (2005). Antenna theory: analysis and design (Vol. 1). John Wiley & Sons.
 .. [BER1998] Bergmann, T., Robertsson, J. O., & Holliger, K. (1998). Finite-difference modeling of electromagnetic wave propagation in dispersive and attenuating media. Geophysics, 63(3), 856-867. (http://dx.doi.org/10.1190/1.1444396)
 .. [BOU1996] Bourgeois, J. M., & Smith, G. S. (1996). A fully three-dimensional simulation of a ground-penetrating radar: FDTD theory compared with experiment. Geoscience and Remote Sensing, IEEE Transactions on, 34(1), 36-44. (http://dx.doi.org/10.1109/36.481890)
 .. [BUR1981] Burrough, P. A. (1981). Fractal dimensions of landscapes and other environmental data. Nature, 294(5838), 240-242. (http://dx.doi.org/10.1038/294240a0)
@@ -16,6 +17,7 @@ References
 .. [KUN1993] Kunz, K. S., & Luebbers, R. J. (1993). The finite difference time domain method for electromagnetics. CRC press.
 .. [LI2013] Li, J., Guo, L. X., Jiao, Y. C., & Wang, R. (2013). Composite scattering of a plasma-coated target above dispersive sea surface by the ADE-FDTD method. Geoscience and Remote Sensing Letters, IEEE, 10(1), 4-8. (http://dx.doi.org/10.1109/lgrs.2012.2189751)
 .. [LUE1994] Luebbers, R., Steich, D., & Kunz, K. (1993). FDTD calculation of scattering from frequency-dependent materials. Antennas and Propagation, IEEE Transactions on, 41(9), 1249-1257. (http://dx.doi.org/10.1109/8.247751)
+.. [MAL1994] Maloney, J. G., Shlager, K. L., & Smith, G. S. (1994). A simple FDTD model for transient excitation of antennas by transmission lines. Antennas and Propagation, IEEE Transactions on, 42(2), 289-292.
 .. [PIE2009] Pieraccini, M., Bicci, A., Mecatti, D., Macaluso, G., & Atzeni, C. (2009). Propagation of large bandwidth microwave signals in water. Antennas and Propagation, IEEE Transactions on, 57(11), 3612-3618. (http://dx.doi.org/10.1109/tap.2009.2025674)
 .. [TAF2005] Taflove, A., & Hagness, S. C. (2005). Computational electrodynamics. Artech house.
 .. [TEI1998] Teixeira, F. L., Chew, W. C., Straka, M., Oristaglio, M. L., & Wang, T. (1998). Finite-difference time-domain simulation of ground penetrating radar on dispersive, inhomogeneous, and conductive soils. Geoscience and Remote Sensing, IEEE Transactions on, 36(6), 1928-1937. (http://dx.doi.org/10.1109/36.729364)