Sorted broken links

docs/source/accelerators.rst

@@ -74,7 +74,8 @@ Run one of the test models:
 
 .. note::
 
-    If you want to select a specific GPU card on your system, you can specify an integer after the ``-gpu`` flag. The integer should be the NVIDIA CUDA device ID for a specific GPU card. If it is not specified it defaults to device ID 0.
+    * If you want to select a specific GPU card on your system, you can specify an integer after the ``-gpu`` flag. The integer should be the NVIDIA CUDA device ID for a specific GPU card. If it is not specified it defaults to device ID 0. 
+    * You can use the ``get_host_spec.py`` module (in ``toolboxes/Utilities``) to help you understand what hardware (CPU/GPU) you have and how gprMax can use it.
 
 
 OpenCL
@@ -85,20 +86,29 @@ Software required
 
 The following steps provide guidance on how to install the extra components to allow gprMax to use OpenCL:
 
-TODO: Add OpenCL instructions
+1. Install the pyopencl Python module. Open a Terminal (Linux/macOS) or Command Prompt (Windows), navigate into the top-level gprMax directory, and if it is not already active, activate the gprMax conda environment ``conda activate gprMax``. Run ``pip install pyopencl``
-*****************************
 
 Example
 -------
 
+Open a Terminal (Linux/macOS) or Command Prompt (Windows), navigate into the top-level gprMax directory, and if it is not already active, activate the gprMax conda environment ``conda activate gprMax``
 
+Run one of the test models:
 
+.. code-block:: none
+
+    (gprMax)$ python -m gprMax examples/cylinder_Ascan_2D.in -opencl
+
+.. note::
+
+    * If you want to select a specific computer device on your system, you can specify an integer after the ``-opencl`` flag. The integer should be the device ID for a specific compute device. If it is not specified it defaults to device ID 0.
+    * You can use the ``get_host_spec.py`` module (in ``toolboxes/Utilities``) to help you understand what hardware (CPU/GPU) you have and how gprMax can use it.
 
 
 CUDA/MPI
 ========
 
-Message Passing Interface (MPI) has been utilised to implement a simple task farm that can be used to distribute a series of models as independent tasks. This is described in more detail in the :ref:`HPC section <hpc>`. MPI can be combined with the GPU functionality to allow a series models to be distributed to multiple GPUs on the same machine (node). 
+Message Passing Interface (MPI) has been utilised to implement a simple task farm that can be used to distribute a series of models as independent tasks. This is described in more detail in the :ref:`HPC <hpc>` section. MPI can be combined with the GPU functionality to allow a series models to be distributed to multiple GPUs on the same machine (node). 
 
 Example
 -------

docs/source/examples_antennas.rst

@@ -19,7 +19,7 @@ This example demonstrates a model of a half-wavelength wire dipole antenna in fr
 
 The wire is modelled using an edge which specifies properties of the edge of the Yee cell. The antenna is fed using a transmission line The one-dimensional transmission line model virtually attaches to the dipole at the gap between the arms. The antenna has an input resistance :math:`Z_{in} = 73~\Omega` specified in the transmissions, and uses a Gaussian waveform with a centre frequency of 1GHz. A time window of 60ns is used: firstly, to give enough time for the response to decay down to zero; and secondly, to allow a reasonable resolution (17MHz) for calculating antenna parameters that involve taking a FFT (:math:`\Delta f=1/T` where :math:`\Delta f` is the frequency bin spacing and :math:`T` is the time window).
 
-Time histories of voltage and current values in the transmission line are saved to the output file. These are documented in the :ref:`<output>` section. 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 ``toolboxes\Plotting`` 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 are given in the README.rst for that package.
+Time histories of voltage and current values in the transmission line are saved to the output file. These are documented in the :ref:`output` section. 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 ``toolboxes\Plotting`` 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 are given in the README.rst for that package.
 
 Results
 -------
@@ -131,7 +131,7 @@ The antenna must be moved to a new position for every single A-scan (trace) in t
 Results
 -------
 
-After merging the A-scans into a single file you can now view an image of the B-scan using the command see :ref:`output` and :ref:`tools<plotting>` sections:
+After merging the A-scans into a single file you can now view an image of the B-scan using the command (see :ref:`output` section and README.rst for the ``toolboxes/Plotting`` package):
 
 .. code-block:: none
 

docs/source/examples_simple_2D.rst

@@ -137,7 +137,7 @@ This example uses the same geometry as the previous example but this time a B-sc
     :language: none
     :linenos:
 
-The differences between this input file and the one from the A-scan are the x coordinates of the source and receiver (lines 11 and 12), and the commands needed to move the source and receiver (lines 13 and 14). As before, the source and receiver are offset by 40mm from each other as before but they are now shifted to a starting position for the scan. The ``#src_steps`` command is used to move every source in the model by specified steps each time the model is run. Similarly, the ``#rx_steps`` command is used to move every receiver in the model by specified steps each time the model is run. Note, the same functionality can be achieved by using our Python API to move the source and receiver individually (see the :ref:`Python API <input_api>` section).
+The differences between this input file and the one from the A-scan are the x coordinates of the source and receiver (lines 11 and 12), and the commands needed to move the source and receiver (lines 13 and 14). As before, the source and receiver are offset by 40mm from each other as before but they are now shifted to a starting position for the scan. The ``#src_steps`` command is used to move every source in the model by specified steps each time the model is run. Similarly, the ``#rx_steps`` command is used to move every receiver in the model by specified steps each time the model is run. Note, the same functionality can be achieved by using our Python API to move the source and receiver individually (see the :ref:`Python API <input-api>` section).
 
 To run the model to create a B-scan you must pass an optional argument to specify the number of times the model should be run. In this case this is the number of A-scans (traces) that will comprise the B-scan. For a B-scan over a distance of 120mm with a step of 2mm that is 60 A-scans.
 

docs/source/faqs.rst

@@ -32,4 +32,4 @@ Spatial resolution should be chosen to mitigate numerical dispersion and to adeq
 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?**
-Yes. gprMax has been parallelised using OpenMP and features a task farm based on MPI. For more information read the :ref:`parallel performance section of the User Guide <openmp-mpi>`
+Yes. gprMax has been parallelised using OpenMP and features a task farm based on MPI. For more information read the :ref:`HPC <hpc>` section.

docs/source/features.rst

@@ -25,7 +25,7 @@ Fractal correlated noise [TUR1997]_ is used to describe the stochastic distribut
 Library of antenna models
 =========================
 
-gprMax now includes Python modules with pre-defined models of antennas that behave similarly to commercial antennas [WAR2011]_ [STA2017]_. Currently models of antennas similar to `Geophysical Survey Systems, Inc. (GSSI) <http://www.geophysical.com>`_ 1.5 GHz (Model 5100) antenna, and 400 MHz antenna, as well as `MALA Geoscience <http://www.malags.com/>`_ 1.2 GHz antenna are included. By taking advantage of our Python API, using such complex structures in a model is straightforward without having to be built step-by-step by the user. For further details see the :ref:`Python API <input_api>` section.
+gprMax now includes Python modules with pre-defined models of antennas that behave similarly to commercial antennas [WAR2011]_ [STA2017]_. Currently models of antennas similar to `Geophysical Survey Systems, Inc. (GSSI) <http://www.geophysical.com>`_ 1.5 GHz (Model 5100) antenna, and 400 MHz antenna, as well as `MALA Geoscience <http://www.malags.com/>`_ 1.2 GHz antenna are included. By taking advantage of our Python API, using such complex structures in a model is straightforward without having to be built step-by-step by the user. For further details see the :ref:`Python API <input-api>` section.
 
 Anisotropic materials
 =====================
@@ -50,7 +50,7 @@ With increased research into quantitative information from GPR, it has become ne
 Python API
 ==========
 
-There is now a **Python API**, which includes all the functionality of the input file (hash) commands as well as several more advanced features. It allows users to access to gprMax functions directly from Python through importing the gprMax module. This method is recommended for those who prefer to use Python or need access to specific API-only advanced features, and is described in the :ref:`Python API <input_api>` section. There are several advantages to using the Python API: 
+There is now a **Python API**, which includes all the functionality of the input file (hash) commands as well as several more advanced features. It allows users to access to gprMax functions directly from Python through importing the gprMax module. This method is recommended for those who prefer to use Python or need access to specific API-only advanced features, and is described in the :ref:`Python API <input-api>` section. There are several advantages to using the Python API: 
 
 1. Users can take advantage of the Python language - for instance, the structural elements of Python can be utilised more easily.
 2. gprMax objects can be used directly within functions, classes, modules and packages. In this way collections of components can be defined, reused and modified. For example, complex targets can be imported from a separate module and combined with an antenna from another module.

docs/source/gprmodelling.rst

@@ -133,6 +133,6 @@ The ABCs employed in gprMax will, in general, perform well (i.e. without introdu
 
 The cells of the RIPML, which have a user adjustable thickness, very efficiently absorb most waves that propagate in them. Although, source and output points can be specified inside these cells **it is wrong to do so** from the point of view of correct modelling. The fields inside these cells are not of interest to GPR modelling. Placing sources inside these cells could have effects that have not been studied and will certainly provide erroneous results from the perspective of GPR modelling. The requirement to keep sources and targets at least 15 cells away for the PML has to be taken into account when deciding the size of the model domain. Additionally, free space (i.e. air) should be always included above a source for at least 15-20 cells in GPR models. Obviously, the more cells there are between observation points, sources, targets and the absorbing boundaries, the better the results will be.
 
-gprMax now offers the ability (for advanced users) to customise the parameters of the PML which allows its performance to be better optimised for specific applications. For further details see the :ref:`PML commands section <pml-commands>`.
+gprMax now offers the ability (for advanced users) to customise the parameters of the PML which allows its performance to be better optimised for specific applications. For further details see the :ref:`Python API <input-api>` section.
 
 All other *boundary conditions* which apply at interfaces between different media in the FDTD model are automatically enforced in gprMax.

docs/source/input_api.rst

@@ -1,15 +1,15 @@
-.. _api:
+.. _input-api:
 
-**************************************
+************************************
-Model Building (Advanced - Python API)
+Model Building (Advanced/Python API)
-**************************************
+************************************
 
 Introduction
 ============
 
 gprMax has a choice of two methods for building a model to simulate:
 
-1. A **text-based (ASCII) input file**, which can be created with any text editor, and uses a series of gprMax commands which begin with the hash character (``#``). This method is recommended for beginners and those not familiar with Python, and is described in the :ref:`input_hash_cmds` section.
+1. A **text-based (ASCII) input file**, which can be created with any text editor, and uses a series of gprMax commands which begin with the hash character (``#``). This method is recommended for beginners and those not familiar with Python, and is described in the :ref:`input-hash-cmds` section.
 2. A **Python API**, which includes all the functionality of method 1 as well as several more advanced features. This method is recommended for those who prefer to use Python or need access to specific API-only advanced features, and is described in this section of the documentation.
 
 The Python API in gprMax allows users to access to gprMax functions directly from Python through importing the gprMax module. There are several advantages to using the API: 
@@ -116,7 +116,7 @@ Material
 
 Material
 --------
-.. autoclass:: gprMax.cmds_multiple.Material
+.. autoclass:: gprMax.cmds_multiuse.Material
 
 Debye Dispersion
 ----------------

docs/source/input_hash_cmds.rst

@@ -1,4 +1,4 @@
-.. _commands:
+.. _input-hash-cmds:
 
 **************
 Model Building
@@ -10,7 +10,7 @@ Introduction
 gprMax has a choice of two methods for building a model to simulate:
 
 1. A **text-based (ASCII) input file**, which can be created with any text editor, and uses a series of gprMax commands which begin with the hash character (``#``). This method is recommended for beginners and those not familiar with Python, and is described in this section of the documentation.
-2. A **Python API**, which includes all the functionality of method 1 as well as several more advanced features. This method is recommended for those who prefer to use Python or need access to specific API-only advanced features, and is documented in the :ref:`Python API <input_api>` section.
+2. A **Python API**, which includes all the functionality of method 1 as well as several more advanced features. This method is recommended for those who prefer to use Python or need access to specific API-only advanced features, and is documented in the :ref:`Python API <input-api>` section.
 
 The general syntax of the hash commands is:
 
@@ -878,7 +878,7 @@ or
 For example to save a snapshot of the electromagnetic fields in the model at a simulated time of 3 nanoseconds use: ``#snapshot: 0 0 0 1 1 1 0.1 0.1 0.1 3e-9 snap1``
 
 .. tip::
-    A series of snapshots can be more easily defined using a loop and our :ref:`Python API <input_api>`, see :ref:`outputs-snaps`.
+    A series of snapshots can be more easily defined using a loop and our :ref:`Python API <input-api>`, see :ref:`outputs-snaps`.
 
 
 PML commands

docs/source/output.rst

@@ -1,3 +1,5 @@
+.. _output:
+
 *****************
 Simulation Output
 *****************
@@ -5,7 +7,7 @@ Simulation Output
 Field(s) output
 ===============
 
-gprMax produces an output file that primarily contains time history data for electromagnetic field outputs (receivers) in the model. The output file has the same name as the input file but with ``.h5`` appended, and therefore uses the widely-supported `HDF5 <https://www.hdfgroup.org/HDF5/>`_ format which was designed to store and organize large amounts of numerical data. 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 ``toolboxes/plotting`` package) to help you view output data. These are documented in :ref:`plotting toolbox section <plotting>`.
+gprMax produces an output file that primarily contains time history data for electromagnetic field outputs (receivers) in the model. The output file has the same name as the input file but with ``.h5`` appended, and therefore uses the widely-supported `HDF5 <https://www.hdfgroup.org/HDF5/>`_ format which was designed to store and organize large amounts of numerical data. 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 ``toolboxes/plotting`` package) to help you view output data, which are documented in the README.rst file for that package.
 
 File structure
 --------------

toolboxes/DebyeFit/README.rst

@@ -56,7 +56,7 @@ Relaxation Class
 
 This class is designed for modelling different relaxation functions, like Havriliak-Negami (``HavriliakNegami``), Jonscher (``Jonscher``), Complex Refractive Index Mixing (`CRIM`) models, and arbitrary dielectric data derived experimentally or calculated using some other function (``Rawdata``).
 
-More about the ``Relaxation`` class structure can be found in the :doc:`Relaxation doc <relaxation.rst>`.
+More about the ``Relaxation`` class structure can be found in the :doc:`Relaxation doc <../../toolboxes/DebyeFit/relaxation.rst>`.
 
 Havriliak-Negami Function
 ^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -185,7 +185,7 @@ Class Optimizer
 This class supports global optimization algorithms (particle swarm, dual annealing, evolutionary algorithms) for finding an optimal set of relaxation times that minimise the error between the actual and the approximated electric permittivity, and calculates optimised weights for the given relaxation times.
 Code written here is mainly based on external libraries, like ``scipy`` and ``pyswarm``.
 
-More about the ``Optimizer`` class structure can be found in the :doc:`Optimisation doc <optimisation.rst>`.
+More about the ``Optimizer`` class structure can be found in the :doc:`Optimisation doc <../../toolboxes/DebyeFit/optimisation.rst>`.
 
 PSO_DLS Class
 ^^^^^^^^^^^^^