Docs moves.

docs/source/include_user_libs_DebyeFit.rst

@@ -0,0 +1 @@
+.. include:: ../../user_libs/DebyeFit/docs/README.rst

docs/source/include_user_libs_antenna_patterns.rst

@@ -0,0 +1 @@
+.. include:: ../../user_libs/antenna_patterns/docs/README.rst

docs/source/include_user_libs_antennas.rst

@@ -1 +1 @@
-.. include:: ../../user_libs/antennas/README.rst
+.. include:: ../../user_libs/antennas/docs/README.rst

docs/source/include_user_libs_austinman.rst

@@ -0,0 +1 @@
+.. include:: ../../user_libs/AustinManWoman/docs/README.rst

docs/source/include_user_libs_landmines.rst

@@ -0,0 +1 @@
+.. include:: ../../user_libs/landmines/docs/README.rst

docs/source/include_user_libs_materials.rst

@@ -0,0 +1 @@
+.. include:: ../../user_libs/materials/docs/README.rst

docs/source/include_user_libs_stltovoxel.rst

@@ -0,0 +1 @@
+.. include:: ../../user_libs/stltovoxel/docs/README.rst

docs/source/index.rst

@@ -39,9 +39,12 @@ gprMax User Guide
     :caption: User libraries
 
     include_user_libs_antennas
-    user_libs_antenna_patterns
-    user_libs_austinman
-    user_libs_materials
+    include_user_libs_antenna_patterns
+    include_user_libs_austinman
+    include_user_libs_DebyeFit
+    include_user_libs_landmines
+    include_user_libs_materials
+    include_user_libs_stltovoxel
 
 .. toctree::
     :maxdepth: 2

docs/source/user_libs_antenna_patterns.rst

@@ -1,54 +0,0 @@
-User libraries is a sub-package where useful Python modules contributed by users are stored.
-
-****************
-Antenna patterns
-****************
-
-Information
-===========
-
-**Author/Contact**: Craig Warren (craig.warren@northumbria.ac.uk), Northumbria University, UK
-
-**License**: `Creative Commons Attribution-ShareAlike 4.0 International License <http://creativecommons.org/licenses/by-sa/4.0/>`_
-
-**Attribution/cite**: Warren, C., Giannopoulos, A. (2016). Characterisation of a Ground Penetrating Radar Antenna in Lossless Homogeneous and Lossy Heterogeneous Environments. *Signal Processing* (http://dx.doi.org/10.1016/j.sigpro.2016.04.010)
-
-The package features contains modules to help calculate, process, and visualise field patterns from simulations that contain models of antennas.
-
-.. warning::
-
-    Although the principals of calculating and visualising field patterns are straightforward, this package should be used with care. The package:
-
-    * Does not calculate/plot conventional field patterns, i.e. at a single frequency. It uses a measure of the total energy of the electric field at a certain angle and radius, see http://dx.doi.org/10.1016/j.jappgeo.2013.08.001
-    * Requires knowledge of Python to contruct input files with antenna models and positioning of receivers, as well as to edit/modify the saving and processing modules
-    * Can require simulations that demand significant computational resource depending on the distance from the antenna at which the field patterns are observed, e.g. the example models, set with a maximum observation distance of 0.6m, require ~30GB of RAM
-
-Module overview
-===============
-
-* ``initial_save.py`` is a module that calculates and stores (in a Numpy file) the field patterns from the output file of a simulation.
-* ``plot_fields.py`` is a module that plots the field patterns. It should be used after the field pattern data has been processed and stored using the ``initial_save.py`` module.
-
-The package has been designed to work with input files that follow examples found in the ``user_models`` directory:
-
-* ``antenna_like_GSSI_1500_patterns_E.in`` is an input file that includes an antenna model similar to a GSSI 1.5 GHz antenna and receivers to calculate a field pattern in the principal E-plane of the antenna
-* ``antenna_like_GSSI_1500_patterns_H.in`` is an input file that includes an antenna model similar to a GSSI 1.5 GHz antenna and receivers to calculate a field pattern in the principal H-plane of the antenna
-
-
-How to use the module
-=====================
-
-* Firstly you should familiarise yourself with the example model input file. Edit the input file as desired and run one of the simulations for either E-plane or H-plane patterns.
-* Whilst the simulation is running edit the 'user configurable parameters' sections of the ``initial_save.py`` and ``plot_fields.py`` modules to match the setup of the simulation.
-* Once the simulation has completed, run the ``initial_save.py`` module on the output file, e.g. for the E-plane ``python -m user_libs.antenna_patterns.initial_save user_models/antenna_like_GSSI_1500_patterns_E_Er5.h5``. This will produce a Numpy file containing the field pattern data.
-* Plot the field pattern data by running the ``plot_fields.py`` module on the Numpy file, e.g. for the E-plane ``python -m user_libs.antenna_patterns.plot_fields user_models/antenna_like_GSSI_1500_patterns_E_Er5.npy``
-
-.. tip::
-
-    If you want to create different plots you just need to edit and re-run the ``plot_fields.py`` module on the Numpy file, i.e. you don't have to re-process the output file.
-
-
-.. figure:: images/user_libs/antenna_like_GSSI_1500_patterns_E_Er5.png
-    :width: 600 px
-
-    Example of the E-plane pattern from a simulation containing an antenna model similar to a GSSI 1.5 GHz antenna over a homogeneous, lossless half-space with a relative permittivity of five.

docs/source/user_libs_austinman.rst

@@ -1,82 +0,0 @@
-User libraries is a sub-package where useful Python modules contributed by users are stored.
-
-*********************
-AustinMan/AustinWoman
-*********************
-
-Information
-===========
-
-**Authors**: Jackson W. Massey, Cemil S. Geyik, Jungwook Choi, Hyun-Jae Lee, Natcha Techachainiran, Che-Lun Hsu, Robin Q. Nguyen, Trevor Latson, Madison Ball, and Ali E. Yılmaz
-
-**Contact**: Ali E. Yılmaz (ayilmaz@mail.utexas.edu), The University of Texas at Austin
-
-**License**: `Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License <http://creativecommons.org/licenses/by-nc-nd/3.0/>`_
-
-**Attribution/cite**: Please follow the instructions at http://web.corral.tacc.utexas.edu/AustinManEMVoxels/AustinMan/citing_the_model/index.html
-
-`AustinMan and AustinWoman <http://bit.ly/AustinMan>`_ are open source electromagnetic voxel models of the human body, which are developed by the `Computational Electromagnetics Group <http://www.ece.utexas.edu/research/areas/electromagnetics-acoustics>`_ at `The University of Texas at Austin <http://www.utexas.edu>`_. The models are based on data from the `National Library of Medicine’s Visible Human Project <https://www.nlm.nih.gov/research/visible/visible_human.html>`_.
-
-.. figure:: images/user_libs/AustinMan_head.png
-    :width: 600 px
-
-    FDTD geometry mesh showing the head of the AustinMan model (2x2x2mm :math:`^3`).
-
-The following whole body models are available.
-
-=========== ========================== ==================
-Model       Resolution (mm :math:`^3`) Dimensions (cells)
-=========== ========================== ==================
-AustinMan   8x8x8                      86 x 47 x 235
-AustinMan   4x4x4                      171 x 94 x 470
-AustinMan   2x2x2                      342 x 187 x 939
-AustinMan   1x1x1                      683 x 374 x 1877
-AustinWoman 8x8x8                      86 x 47 x 217
-AustinWoman 4x4x4                      171 x 94 x 433
-AustinWoman 2x2x2                      342 x 187 x 865
-AustinWoman 1x1x1                      683 x 374 x 1730
-=========== ========================== ==================
-
-Package overview
-================
-
-.. code-block:: none
-
-    AustinManWoman_materials.txt
-    AustinManWoman_materials_dispersive.txt
-    head_only_h5.py
-
-* ``AustinManWoman_materials.txt`` is a text file containing `non-dispersive material properties at 900 MHz <http://niremf.ifac.cnr.it/tissprop/>`_.
-* ``AustinManWoman_materials_dispersive.txt`` is a text file containing `dispersive material properties using a 3-pole Debye model <http://dx.doi.org/10.1109/LMWC.2011.2180371>`_.
-
-.. note::
-
-    * The main body tissues are described using a 3-pole Debye model, but not all materials have a dispersive description.
-    * The dispersive material properties can only be used with the 1x1x1mm or 2x2x2mm AustinMan/Woman models. This is because the time step of the model must always be less than any of the relaxation times of the poles of the Debye models used for the dispersive material properties.
-
-* ``head_only_h5.py`` is a script to assist with creating a model of only the head from a full body AustinMan/Woman model.
-
-How to use the models
-=====================
-
-The AustinMan and AustinWoman models themselves are not included in the user libraries sub-package.
-
-* `Download a HDF5 file (.h5) of AustinMan or AustinWoman <http://bit.ly/AustinMan>`_ at the resolution you wish to use
-
-To insert either AustinMan or AustinWoman models into a simulation use the ``#geometry_objects_read``.
-
-Example
--------
-
-To insert a 2x2x2mm :math:`^3` AustinMan with the lower left corner 40mm from the origin of the domain, using disperive material properties, and with no dielectric smoothing, use the command:
-
-.. code-block:: none
-
-    #geometry_objects_read: 0.04 0.04 0.04 ../user_libs/AustinManWoman/AustinMan_v2.3_2x2x2.h5 ../user_libs/AustinManWoman/AustinManWoman_materials_dispersive.txt
-
-For further information on the ``#geometry_objects_read`` see the section on object contruction commands in the :ref:`Input commands section <commands>`.
-
-.. figure:: images/user_libs/AustinMan.png
-    :width: 300 px
-
-    FDTD geometry mesh showing the AustinMan body model (2x2x2mm :math:`^3`).

docs/source/user_libs_landmines.rst

@@ -1,87 +0,0 @@
-User libraries is a sub-package where useful Python modules contributed by users are stored.
-
-*********
-Landmines
-*********
-
-Information
-===========
-
-**Author/Contact**: Iraklis Giannakis (I.Giannakis@ed.ac.uk), University of Edinburgh, UK
-
-**License**: `Creative Commons Attribution-ShareAlike 4.0 International License <http://creativecommons.org/licenses/by-sa/4.0/>`_
-
-**Attribution/cite**: Giannakis, I., Giannopoulos, A., Warren, C. (2016). A Realistic FDTD Numerical Modeling Framework of Ground Penetrating Radar for Landmine Detection. *IEEE Journal of Selected Topics in Applied Earth Observations and Remote Sensing*, 9(1), 37-51. (http://dx.doi.org/10.1109/JSTARS.2015.2468597)
-
-The module currently features models of different anti-personnel (AP) landmines and a metal can which can be used as a false target. They are:
-
-* **PMA-1**: a blast AP landmine with minimum metal content, manufactured in the former Yugoslavia. It is possible to detect the PMA-1 with a metal detector because it contains a metal fuse, but there are reports of types of PMA-1 with plastic fuses. The PMA-1 contains 200g of high explosive (TNT). The dimensions of the PMA-1 model are: 140x64x34mm.
-* **PMN**: one of the oldest and most widely used landmines, it is a palm shaped cylindrical blast AP landmine, manufactured in Russia. Similar to PMA-1, the PMN contains a large amount, 240g, of high explosive (TNT). It has a minimum metal content which can make it detectable with a metal detector. The dimensions of the PMN model are: 116x156x50mm.
-* **TS-50**: a blast AP landmine with minimum metal content, manufactured in Italy. The dimensions of the TS-50 model are: 90x90x44mm.
-* **Metal can**: a cylindrical metal can which is can be useful as a false target. The dimensions of the metal can model are: 76x76x108mm.
-
-The landmine models and the metal can be used with a cubic spatial resolution of either 1mm or 2mm.
-
-The dielectric properties of the landmines were obtained through an iterative process of matching numerical and laboratory measurements of scattered electromagnetic fields in free space. A full description of how the models were created can be found at the reference given by the aforementioned attribution/cite.
-
-Package overview
-================
-
-.. code-block:: none
-
-    can_1x1x1.h5
-    can_2x2x2.h5
-    can_materials.txt
-    PMA_1x1x1.h5
-    PMA_2x2x2.h5
-    PMA_materials.txt
-    PMN_1x1x1.h5
-    PMN_2x2x2.h5
-    PMN_materials.txt
-    TS50_1x1x1.h5
-    TS50_2x2x2.h5
-    TS50_materials.txt
-
-* ``can_1x1x1.h5`` is a HDF5 file containing a description of the geometry of the metal can (false target) with a cubic spatial resolution of 1mm
-* ``can_2x2x2.h5`` is a HDF5 file containing a description of the geometry of the metal can (false target) with a cubic spatial resolution of 2mm
-* ``can_materials.txt`` is a text file containing material properties associated with the metal can
-* ``PMA_1x1x1.h5`` is a HDF5 file containing a description of the geometry of the PMA landmine with a cubic spatial resolution of 1mm
-* ``PMA_2x2x2.h5`` is a HDF5 file containing a description of the geometry of the PMA landmine with a cubic spatial resolution of 2mm
-* ``PMA_materials.txt`` is a text file containing material properties associated with the PMA landmine
-* ``PMN_1x1x1.h5`` is a HDF5 file containing a description of the geometry of the PMN landmine with a cubic spatial resolution of 1mm
-* ``PMN_2x2x2.h5`` is a HDF5 file containing a description of the geometry of the PMN landmine with a cubic spatial resolution of 2mm
-* ``PMN_materials.txt`` is a text file containing material properties associated with the PMN landmine
-* ``TS50_1x1x1.h5`` is a HDF5 file containing a description of the geometry of the TS-50 landmine with a cubic spatial resolution of 1mm
-* ``TS50_2x2x2.h5`` is a HDF5 file containing a description of the geometry of the TS-50 landmine with a cubic spatial resolution of 2mm
-* ``TS50_materials.txt`` is a text file containing material properties associated with the TS-50 landmine
-
-How to use the models
-=====================
-
-To insert any of the landmine models or metal can into a simulation use the ``#geometry_objects_read`` command.
-
-Example
--------
-
-The input file for inserting the PMN landmine, with the lower left corner 10mm from the origin of the domain, into an empty domain (free-space) would be:
-
-.. code-block:: none
-
-    #title: PMN landmine (116x156x50mm) in free space
-    #domain: 0.136 0.176 0.070
-    #dx_dy_dz: 0.001 0.001 0.001
-    #time_window: 5e-9
-    #geometry_objects_read: 0.010 0.010 0.010 ../user_libs/landmines/PMN_1x1x1.h5 ../user_libs/landmines/PMN_materials.txt
-    #geometry_view: 0 0 0 0.136 0.176 0.070 0.001 0.001 0.001 landmine_PMN_fs n
-
-For further information on the ``#geometry_objects_read`` see the section on object contruction commands in the :ref:`Input commands section <commands>`.
-
-.. figure:: images/user_libs/PMA.png
-    :width: 600 px
-
-    FDTD geometry mesh showing the PMA-1 landmine model.
-
-.. figure:: images/user_libs/PMN.png
-    :width: 600 px
-
-    FDTD geometry mesh showing the PMN landmine model.

docs/source/user_libs_materials.rst

@@ -1,70 +0,0 @@
-User libraries is a sub-package where useful Python modules contributed by users are stored.
-
-*********
-Materials
-*********
-
-Information
-===========
-
-The module is intended to provide a database of electromagnetic properties of different materials. It currently includes the following material libraries:
-
-* ``eccosorb.txt`` contains information on some of the `Eccosorb LS series <http://www.eccosorb.com/products-eccosorb-ls.htm>`_ of electromagnetic absorber materials manufactured by `Laird NV <http://www.eccosorb.eu>`_ (formerly Emerson & Cuming Microwave Products NV). LS 14, 16, 18, 20, 22, 26, 28, and 30 are included. They are simulated using a 3-pole Debye model.
-
-How to use the module
-=====================
-
-Example
--------
-
-The simplest way to access any of the material libraries is to use the ``#include_file`` command, after which the name of the material can then be used with any object construction command:
-
-.. code-block:: none
-
-    #include_file: user_libs/materials/eccosorb.txt
-    #box: 0 0 0 0.5 0.5 0.5 eccosorb_ls22
-
-Eccosorb
-========
-
-`Eccosorb <http://www.eccosorb.eu>`_ are electromagnetic absorber materials manufactured by `Laird NV <http://www.eccosorb.eu>`_ (formerly Emerson & Cuming Microwave Products NV). Currently models for some of the LS series (14, 16, 18, 20, 22, 26, 28, and 30) are included in this library. The models were created by fitting a 3-pole Debye model to the real and imaginary parts of the relative permittivity taken from the `manufacturers datasheet <http://www.eccosorb.com/Collateral/Documents/English-US/Electrical%20Parameters/ls%20parameters.pdf>`_. The following figures show the fitting.
-
-.. figure:: images/user_libs/eccosorb_ls14.png
-    :width: 600 px
-
-    3-pole Debye fit for Eccosorb LS14 absorber (HN indicates data from manufacturer datasheet)
-
-.. figure:: images/user_libs/eccosorb_ls16.png
-    :width: 600 px
-
-    3-pole Debye fit for Eccosorb LS16 absorber (HN indicates data from manufacturer datasheet)
-
-.. figure:: images/user_libs/eccosorb_ls18.png
-    :width: 600 px
-
-    3-pole Debye fit for Eccosorb LS18 absorber (HN indicates data from manufacturer datasheet)
-
-.. figure:: images/user_libs/eccosorb_ls20.png
-    :width: 600 px
-
-    3-pole Debye fit for Eccosorb LS20 absorber (HN indicates data from manufacturer datasheet)
-
-.. figure:: images/user_libs/eccosorb_ls22.png
-    :width: 600 px
-
-    3-pole Debye fit for Eccosorb LS22 absorber (HN indicates data from manufacturer datasheet)
-
-.. figure:: images/user_libs/eccosorb_ls26.png
-    :width: 600 px
-
-    3-pole Debye fit for Eccosorb LS26 absorber (HN indicates data from manufacturer datasheet)
-
-.. figure:: images/user_libs/eccosorb_ls28.png
-    :width: 600 px
-
-    3-pole Debye fit for Eccosorb LS28 absorber (HN indicates data from manufacturer datasheet)
-
-.. figure:: images/user_libs/eccosorb_ls30.png
-    :width: 600 px
-
-    3-pole Debye fit for Eccosorb LS30 absorber (HN indicates data from manufacturer datasheet)