Initial subgridding example

docs/source/examples_advanced.rst

@@ -41,6 +41,34 @@ More information, including adding surface water and vegetation, can be found in
 Using subgrid(s)
 ================
 
+Including finely detailed objects or regions of high dielectric strength in FDTD modeling can dramatically increase the computational burden of the method. This is because the conditionally stable nature of the algorithm requires a minimum time step for a given spatial discretization. Thus, when the spatial discretization is lowered, either to reduce numerical dispersion or include small-sized features, the time step must be reduced. Also, the number of spatial cells is increased. One approach to reducing the overall computational cost is to introduce local finely discretized regions into a coarser finite-difference grid. This approach is known as subgridding. The computing time is reduced since there are fewer cells to solve. Also, there are fewer iterations since the coarse time step is maintained in the coarse region. gprMax uses a new Huygens subgridding (HSG) algorithm with a novel artificial loss mechanism called the switched Huygens subgridding (SHSG). For a detailed description of subgridding and the SHSG method please read [HAR2021]_.
+
+Subgridding functionality requires using our :ref:`Python API <input-api>`.
+
+.. _examples-subgrid:
+
+High dielectric example
+-----------------------
+
+:download:`cylinder_fs.py <../../examples/subgrids/cylinder_fs.py>`
+
+This example is a basic demonstration of how to use subgrids. The geometry is 3D (required for any use of subgrids) and is of a water-filled (high dielectric constant) cylindrical object in freespace. The subgrid encloses the cylinderical object using a fine spatial discretisation (1mm), and a courser spatial discretisation (5mm) is used in the rest of the model (main grid). A simple Hertzian dipole source is used with a waveform shaped as the first derivative of a gaussian.
+
+.. literalinclude:: ../../examples/subgrids/cylinder_fs.py
+    :language: none
+    :linenos:
+
+
+Antenna modelling example
+-------------------------
+
+:download:`gssi_400_over_fractal_subsurface.py <../../examples/subgrids/gssi_400_over_fractal_subsurface.py>`
+
+This example....
+
+.. literalinclude:: ../../examples/subgrids/gssi_400_over_fractal_subsurface.py
+    :language: none
+    :linenos:
 
 
 

docs/source/features.rst

@@ -6,6 +6,20 @@ Software Features
 
 This section highlights some of the key features of gprMax that are useful for GPR modelling as well as more general electromagnetic simulations.
 
+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.
+3. The API can interface with other Python libraries. For example, the API could be used to create a parametric antenna and the external library Scipy could then be used to optimise its parameters.
+
+Subgridding
+===========
+
+Including finely detailed objects or regions of high dielectric strength in FDTD modeling can dramatically increase the computational burden of the method. This is because the conditionally stable nature of the algorithm requires a minimum time step for a given spatial discretization. Thus, when the spatial discretization is lowered, either to reduce numerical dispersion or include small-sized features, the time step must be reduced. Also, the number of spatial cells is increased. One approach to reducing the overall computational cost is to introduce local finely discretized regions into a coarser finite-difference grid. This approach is known as subgridding. The computing time is reduced since there are fewer cells to solve. Also, there are fewer iterations since the coarse time step is maintained in the coarse region. gprMax uses a new Huygens subgridding (HSG) algorithm with a novel artificial loss mechanism called the switched Huygens subgridding (SHSG). For a detailed description of subgridding and the SHSG method please read [HAR2021]_. Examples of how to use the subgridding functionality can be found in the :ref:`Advanced features <examples-subgrid>` section.
+
 Dispersive materials
 ====================
 
@@ -47,15 +61,6 @@ Perfectly Matched Layer (PML) absorbing boundary conditions
 
 With increased research into quantitative information from GPR, it has become necessary for models to be able to have more efficient and better-performing Perfectly Matched Layer (PML) absorbing boundary conditions. Since 2005 gprMax has featured PML absorbing boundary conditions based on the uniaxial PML (UPML) [GED1998]_ formulation. A PML based on a recursive integration approach to the complex frequency shifted (CFS) PML [GIA2012]_ has been adopted in the new version of gprMax. A general formulation of this RIPML, which can be used to develop any order of PML, has been used to implement first and second order CFS stretching functions. One of the attractions of the RIPML is that it is easily applied as a correction to the field quantities after the complete FDTD grid has been updated using the standard FDTD update equations. 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. Additionally, since the RIPML is media agnostic it can be used without change to problems involving dispersive and anisotropic materials.
 
-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.
-3. The API can interface with other Python libraries. For example, the API could be used to create a parametric antenna and the external library Scipy could then be used to optimise its parameters.
-
 Open source, robust, file formats
 =================================
 

docs/source/input_api.rst

@@ -33,7 +33,7 @@ This example is used to give an introduction to the gprMax Python API.
 
 1. Import the gprMax module.
 2. Objects for the model are created from the gprMax module by passing object parameters as key=value arguments. The example shows the creation of objects and also their equivalent input file (hash) command for clarity.
-3. Create a :class:`gprMax.scene.Scene` object. The scene is a container for all the objects required in a simulation. Simulations with multiple models, e.g. A-scans, should have a separate scene for each model (A-scan). Each scene must contain the essential commands and objects required for that particular model.
+3. Create a :class:`gprMax.scene.Scene` object. The scene is a container for all the objects required in a simulation. Simulations with multiple models, e.g. A-scans, should have a separate scene for each model (A-scan). Each scene must contain the essential functions and objects required for that particular model.
 4. Add objects are to the scene.
 5. Run the simulation.
 
@@ -48,7 +48,7 @@ It is important to note that gprMax converts spatial and temporal parameters giv
 
 The fundamental spatial and temporal discretization steps are denoted as :math:`\Delta x` , :math:`\Delta y`, :math:`\Delta z` and :math:`\Delta t` respectively.
 
-The commands have been grouped into six categories:
+The functions have been grouped into six categories:
 
 * **Essential** - required to run any model, such as the domain size and spatial discretization
 * **General** - provide further control over the model
@@ -57,20 +57,11 @@ The commands have been grouped into six categories:
 * **Source and output** - used to place source and output points in the model
 * **PML** - provide advanced customisation and optimisation of the absorbing boundary conditions
 
-The commands have been grouped into six categories:
+Essential functions
+===================
+Most of the functions are optional but there are some essential functions which are necessary in order to construct any model. For example, none of the media and object functions are necessary to run a model. However, without specifying any objects in the model gprMax will simulate free space (air), which on its own, is not particularly useful for GPR modelling. If you have not specified a functions which is essential in order to run a model, for example the size of the model, gprMax will terminate execution and issue an appropriate error message.
 
-* **Essential** - required to run any model, such as the domain size and spatial discretization
+The essential functions are:
-* **General** - provide further control over the model
-* **Material** - used to introduce different materials into the model
-* **Object construction** - used to build geometric shapes with different constitutive parameters
-* **Source and output** - used to place source and output points in the model
-* **PML** - provide advanced customisation and optimisation of the absorbing boundary conditions
-
-Essential
-=========
-Most of the commands are optional but there are some essential commands which are necessary in order to construct any model. For example, none of the media and object commands are necessary to run a model. However, without specifying any objects in the model gprMax will simulate free space (air), which on its own, is not particularly useful for GPR modelling. If you have not specified a command which is essential in order to run a model, for example the size of the model, gprMax will terminate execution and issue an appropriate error message.
-
-The essential commands are:
 
 Running model(s)
 ----------------
@@ -92,8 +83,8 @@ Time Window
 -----------
 .. autoclass:: gprMax.cmds_singleuse.TimeWindow
 
-General
+General functions
-=======
+=================
 
 Title
 -----
@@ -111,8 +102,8 @@ Output Directory
 ----------------
 .. autoclass:: gprMax.cmds_singleuse.OutputDir
 
-Material
+Material functions
-========
+==================
 
 Material
 --------
@@ -135,8 +126,8 @@ Soil Peplinski
 .. autoclass:: gprMax.cmds_multiuse.SoilPeplinski
 
 
-Object Construction
+Object construction functions
-===================
+=============================
 
 Object construction commands are processed in the order they appear in the scene. Therefore space in the model allocated to a specific material using for example the :class:`gprMax.cmds_geometry.box.Box` command can be reallocated to another material using the same or any other object construction command. Space in the model can be regarded as a canvas in which objects are introduced and one can be overlaid on top of the other overwriting its properties in order to produce the desired geometry. The object construction commands can therefore be used to create complex shapes and configurations.
 
@@ -192,8 +183,8 @@ Geometry Objects Write
 ----------------------
 .. autoclass:: gprMax.cmds_multiuse.GeometryObjectsWrite
 
-Source and Output
+Source and output functions
-=================
+===========================
 
 Waveform
 --------
@@ -244,8 +235,8 @@ Subgrid
 .. autoclass:: gprMax.subgrids.user_objects.SubGridHSG
 
 
-PML
+PML functions
-===
+=============
 
 The default behaviour for the absorbing boundary conditions (ABC) is first order Complex Frequency Shifted (CFS) Perfectly Matched Layers (PML), with thicknesses of 10 cells on each of the six sides of the model domain. The PML can be customised using the following commands:
 

docs/source/references.rst

@@ -13,6 +13,7 @@ References
 .. [GIA2014] Giannakis, I., & Giannopoulos, A. (2014). A Novel Piecewise Linear Recursive Convolution Approach for Dispersive Media Using the Finite-Difference Time-Domain Method. Antennas and Propagation, IEEE Transactions on, 62(5), 2669-2678. (http://dx.doi.org/10.1109/tap.2014.2308549)
 .. [GIA1997] Giannopoulos, A. (1997). The investigation of Transmission-Line Matrix and Finite-Difference Time-Domain Methods for the Forward Problem of Ground Probing Radar, D.Phil thesis, Department of Electronics, University of York, UK. (http://etheses.whiterose.ac.uk/id/eprint/2443)
 .. [GIA2012] Giannopoulos, A. (2012). Unsplit implementation of higher order PMLs. Antennas and Propagation, IEEE Transactions on, 60(3), 1479-1485. (http://dx.doi.org/10.1109/tap.2011.2180344)
+.. [HAR2021] Hartley, J., Giannopoulos, A., & Davidson, N. (2022). Switched Huygens Subgridding for the FDTD Method. IEEE Transactions on Antennas and Propagation, 70(8), 6872-6882. (http://dx.doi.org/10.1109/TAP.2022.3161371)
 .. [IRE2013] Ireland, D., & Abbosh, A. (2013). Modeling human head at microwave frequencies using optimized Debye models and FDTD method. Antennas and Propagation, IEEE Transactions on, 61(4), 2352-2355. (http://dx.doi.org/10.1109/tap.2013.2242037)
 .. [KEL2007] Kelley, D. F., Destan, T. J., & Luebbers, R. J. (2007). Debye function expansions of complex permittivity using a hybrid particle swarm-least squares optimization approach. IEEE Transactions on Antennas and propagation, 55(7), 1999-2005. (https://doi.org/10.1109/TAP.2007.900230)
 .. [KUN1993] Kunz, K. S., & Luebbers, R. J. (1993). The finite difference time domain method for electromagnetics. CRC press.

gprMax/config.py

@@ -139,6 +139,7 @@ class ModelConfig:
         else: return None
 
     def get_usernamespace(self):
+        """Namespace only used with #python blocks which are deprecated."""
         tmp = {'number_model_runs': sim_config.model_end,
                'current_model_run': model_num + 1,
                'inputfile': sim_config.input_file_path.resolve()}