Docs update.

docs/source/user_libs_landmines.rst

@@ -0,0 +1,86 @@
+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
+
+**License**: Creative Commons Attribution-ShareAlike 4.0 International License (http://creativecommons.org/licenses/by-sa/4.0/)
+
+.. code-block:: python
+
+    # Copyright (C) 2016, Iraklis Giannakis
+    #
+    # This module is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License.
+    # To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/.
+    #
+    # Please use the attribution at http://dx.doi.org/10.1109/JSTARS.2015.2468597
+
+The module currently features models of different anti-personnel (AP) landmines and a metal can (false target). They are:
+
+* PMA-1: a blast AP landmine with minimum metal content. It was manufactured in former Yugoslavia and was used in the Balkans. 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 that is 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, made in Italy. The dimensions of the TS-50 model are: 90x90x44mm.
+* Metal can: a cylindrical metal can which is often found as a false target. The dimensions of the metal can model are: 76x76x108mm.
+
+The landmine models and the metal can must be used with a cubic spatial resolution of 1mm.
+
+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 http://dx.doi.org/10.1109/JSTARS.2015.2468597.
+
+Package overview
+================
+
+.. code-block:: none
+
+    can_gprMax_materials.txt
+    can.h5
+    PMA_gprMax_materials.txt
+    PMA.h5
+    PMN_gprMax_materials.txt
+    PMN.h5
+    TS50_gprMax_materials.txt
+    TS50.h5
+
+* ``can_gprMax_materials.txt`` is a text file containing material properties associated with the metal can
+* ``can.h5`` is a HDF5 file containing a description of the geometry of the metal can (false target)
+* ``PMA_gprMax_materials.txt`` is a text file containing material properties associated with the PMA landmine
+* ``PMA.h5`` is a HDF5 file containing a description of the geometry of the PMA landmine
+* ``PMN_gprMax_materials.txt`` is a text file containing material properties associated with the PMN landmine
+* ``PMN.h5`` is a HDF5 file containing a description of the geometry of the PMN landmine
+* ``TS50_gprMax_materials.txt`` is a text file containing material properties associated with the TS-50 landmine
+* ``TS50.h5`` is a HDF5 file containing a description of the geometry of 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_file`` 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_file: 0.010 0.010 0.010 ../user_libs/landmines/PMN.h5 ../user_libs/landmines/PMN_gprMax_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_file`` 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.