Updates to docs for Debye, Lorentz, Drude dispersion. Lorentz and Drude docs need further work.

docs/source/input.rst

@@ -283,16 +283,24 @@ For example ``#material: 3 0.01 1 0 my_sand`` creates a material called ``my_san
 #add_dispersion_debye:
 ----------------------
 
-Allows you to add dispersive properties to an already defined ``#material`` based on a multiple pole Debye formulation (see :ref:`capabilities` section). The syntax of the command is:
+Allows you to add dispersive properties to an already defined ``#material`` based on a multiple pole Debye formulation (see :ref:`capabilities` section). For example, the susceptability function for a single-pole Debye material is given by:
+
+.. math::
+
+    \chi_p (t) = \frac{\epsilon_{rs} - \epsilon_{r \infty}}{\tau_p} e^{-t/\tau_p} \equiv \frac{\Delta \epsilon_r}{\tau_p} e^{-t/\tau_p},
+
+where :math:`\epsilon_{rs}` is the zero-frequency relative permittivity, :math:`\epsilon_{r \infty}` is the relative permittivity at infinite frequency, and :math:`\tau_p` is the pole relaxation time.
+
+The syntax of the command is:
 
 .. code-block:: none
 
     #add_dispersion_debye: i1 f1 f2 f3 f4 ... str1
 
 * ``i1`` is the number of Debye poles.
-* ``f1`` is the difference between the DC (static) relative permittivity and the relative permittivity at infinite frequency, i.e. :math:`\Delta \epsilon_r = \epsilon_{rs} - \epsilon_{r \infty}` , for the first Debye pole.
+* ``f1`` is the difference between the zero-frequency relative permittivity and the relative permittivity at infinite frequency, i.e. :math:`\Delta \epsilon_r = \epsilon_{rs} - \epsilon_{r \infty}` , for the first Debye pole.
 * ``f2`` is the relaxation time (seconds), :math:`\tau`, for the first Debye pole.
-* ``f3`` is the difference between the DC (static) relative permittivity and the relative permittivity at infinite frequency, i.e. :math:`\Delta \epsilon_r = \epsilon_{rs} - \epsilon_{r \infty}` , for the second Debye pole.
+* ``f3`` is the difference between the zero-frequency relative permittivity and the relative permittivity at infinite frequency, i.e. :math:`\Delta \epsilon_r = \epsilon_{rs} - \epsilon_{r \infty}` , for the second Debye pole.
 * ``f4`` is the relaxation time (seconds), :math:`\tau`, for the second Debye pole.
 * ``str1`` identifies the material to add the dispersive properties to.
 
@@ -302,23 +310,37 @@ Important notes:
 
 * You can continue to add pairs of values for :math:`\Delta \epsilon_r` and :math:`\tau` for as many Debye poles as you have specified with ``i1``.
 * The relative permittivity in the ``#material`` command should be given as the relative permittivity at infinite frequency, i.e. :math:`\epsilon_{r \infty}`.
-* Values for the relaxation times should always be greater than the time step :math:`\Delta t` used in the model. gprMax checks and verifies this condition and if it does not then will exit raising an error.
+* Values for the relaxation times should always be greater than the time step :math:`\Delta t` used in the model.
 
 
 #add_dispersion_lorenz:
 -----------------------
 
-Allows you to add dispersive properties to an already defined ``#material`` based on a multiple pole Lorenz formulation (see :ref:`capabilities` section). The syntax of the command is:
+Allows you to add dispersive properties to an already defined ``#material`` based on a multiple pole Lorenz formulation (see :ref:`capabilities` section). For example, the susceptability function for a single-pole Lorentz material is given by:
+
+.. math::
+
+    \chi_p (t) = \Re \left\{ -j\gamma_p e^{(-\delta_p + j\beta_p)t} \right\},
+
+where
+
+.. math::
+
+    \beta_p = \sqrt{\omega_p^2 - \delta_p^2} \quad \textrm{and} \quad \gamma_p = \frac{\omega_p^2 \Delta \epsilon_r}{\beta_p},
+
+where :math:`\omega_p` is the frequency of the pole pair, :math:`\delta_p` is the damping coefficient, and :math:`j=\sqrt{-1}`.
+
+The syntax of the command is:
 
 .. code-block:: none
 
     #add_dispersion_lorenz: i1 f1 f2 f3 f4 f5 f6 ... str1
 
 * ``i1`` is the number of Lorenz poles.
-* ``f1`` is the difference between the DC (static) relative permittivity and the relative permittivity at infinite frequency, i.e. :math:`\Delta \epsilon_r = \epsilon_{rs} - \epsilon_{r \infty}` , for the first Lorenz pole.
+* ``f1`` is the difference between the zero-frequency relative permittivity and the relative permittivity at infinite frequency, i.e. :math:`\Delta \epsilon_r = \epsilon_{rs} - \epsilon_{r \infty}` , for the first Lorenz pole.
 * ``f2`` is the relaxation time (seconds), :math:`\tau`, for the first Lorenz pole.
 * ``f3`` is the damping factor for the first Lorenz pole.
-* ``f4`` is the difference between the DC (static) relative permittivity and the relative permittivity at infinite frequency, i.e. :math:`\Delta \epsilon_r = \epsilon_{rs} - \epsilon_{r \infty}` , for the second Lorenz pole.
+* ``f4`` is the difference between the zero-frequency relative permittivity and the relative permittivity at infinite frequency, i.e. :math:`\Delta \epsilon_r = \epsilon_{rs} - \epsilon_{r \infty}` , for the second Lorenz pole.
 * ``f5`` is the relaxation time (seconds), :math:`\tau`, for the second Lorenz pole.
 * ``f6`` is the damping factor for the second Lorenz pole.
 * ``str1`` identifies the material to add the dispersive properties to.
@@ -329,34 +351,40 @@ Important notes:
 
 * You can continue to add triplets of values for :math:`\Delta \epsilon_r` and :math:`\tau` for as many Lorenz poles as you have specified with ``i1``.
 * The relative permittivity in the ``#material`` command should be given as the relative permittivity at infinite frequency, i.e. :math:`\epsilon_{r \infty}`.
-* Values for the relaxation times should always be greater than the time step :math:`\Delta t` used in the model. gprMax checks and verifies this condition and if it does not then will exit raising an error.
+* Values for the relaxation times should always be greater than the time step :math:`\Delta t` used in the model.
 
 
 #add_dispersion_drude:
 ----------------------
 
-Allows you to add dispersive properties to an already defined ``#material`` based on a multiple pole Drude formulation (see :ref:`capabilities` section). The syntax of the command is:
+Allows you to add dispersive properties to an already defined ``#material`` based on a multiple pole Drude formulation (see :ref:`capabilities` section). For example, the susceptability function for a single-pole Drude material is given by:
+
+.. math::
+
+    \chi_p (t) = \frac{\omega_p^2}{\gamma_p} (1-e^{-\gamma_p t}),
+
+where :math:`\omega_p` is the frequency of the pole, :math:`\gamma_p` is the inverse of the pole relaxation time.
+
+The syntax of the command is:
 
 .. code-block:: none
 
-    #add_dispersion_drude: i1 f1 f2 f3 f4 f5 f6 ... str1
+    #add_dispersion_drude: i1 f1 f2 f3 f4 ... str1
 
 * ``i1`` is the number of Drude poles.
-* ``f1`` is the difference between the DC (static) relative permittivity and the relative permittivity at infinite frequency, i.e. :math:`\Delta \epsilon_r = \epsilon_{rs} - \epsilon_{r \infty}` , for the first Drude pole.
+* ``f1`` is the relaxation time (seconds), :math:`\tau`, for the first Drude pole.
-* ``f2`` is the relaxation time (seconds), :math:`\tau`, for the first Drude pole.
+* ``f2`` is the **x** for the first Drude pole.
-* ``f3`` is the **x** for the first Drude pole.
+* ``f3`` is the relaxation time (seconds), :math:`\tau`, for the second Drude pole.
-* ``f4`` is the difference between the DC (static) relative permittivity and the relative permittivity at infinite frequency, i.e. :math:`\Delta \epsilon_r = \epsilon_{rs} - \epsilon_{r \infty}` , for the second Drude pole.
+* ``f4`` is the **x** for the second Drude pole.
-* ``f5`` is the relaxation time (seconds), :math:`\tau`, for the second Drude pole.
-* ``f6`` is the **x** for the second Drude pole.
 * ``str1`` identifies the material to add the dispersive properties to.
 
 *For example...*
 
 Important notes:
 
-* You can continue to add triplets of values for :math:`\Delta \epsilon_r` and :math:`\tau` for as many Drude poles as you have specified with ``i1``.
+* You can continue to add pairs of values for :math:`\tau` and **x** for as many Drude poles as you have specified with ``i1``.
 * The relative permittivity in the ``#material`` command should be given as the relative permittivity at infinite frequency, i.e. :math:`\epsilon_{r \infty}`.
-* Values for the relaxation times should always be greater than the time step :math:`\Delta t` used in the model. gprMax checks and verifies this condition and if it does not then will exit raising an error.
+* Values for the relaxation times should always be greater than the time step :math:`\Delta t` used in the model.
 
 
 #soil_peplinski:

gprMax/input_cmds_multiuse.py

@@ -492,18 +492,17 @@ def process_multicmds(multicmds, G):
                 material.type = 'drude'
                 material.poles = poles
                 material.average = False
-                for pole in range(1, 3 * poles, 3):
+                for pole in range(1, 2 * poles, 2):
-                    if float(tmp[pole]) > 0 and float(tmp[pole + 1]) > G.dt and float(tmp[pole + 2]) > G.dt:
+                    if float(tmp[pole]) > 0 and float(tmp[pole + 1]) > G.dt:
-                        material.deltaer.append(float(tmp[pole]))
+                        material.tau.append(float(tmp[pole ]))
-                        material.tau.append(float(tmp[pole + 1]))
+                        material.alpha.append(float(tmp[pole + 1]))
-                        material.alpha.append(float(tmp[pole + 2]))
                     else:
-                        raise CmdInputError("'" + cmdname + ': ' + ' '.join(tmp) + "'" + ' requires positive values for the permittivity difference and relaxation times, and relaxation times that are greater than the time step for the model.')
+                        raise CmdInputError("'" + cmdname + ': ' + ' '.join(tmp) + "'" + ' requires positive values for the relaxation times, and relaxation times that are greater than the time step for the model.')
                 if material.poles > Material.maxpoles:
                     Material.maxpoles = material.poles
 
                 if G.messages:
-                    print('Drude-type disperion added to {} with delta_epsr={}, tau1={} secs, and tau2={} secs created.'.format(material.ID, ','.join('%4.2f' % deltaer for deltaer in material.deltaer), ','.join('%4.3e' % tau for tau in material.tau), ','.join('%4.3e' % alpha for alpha in material.alpha)))
+                    print('Drude-type disperion added to {} with tau1={} secs, and tau2={} secs created.'.format(material.ID, ','.join('%4.3e' % tau for tau in material.tau), ','.join('%4.3e' % alpha for alpha in material.alpha)))
 
 
     cmdname = '#soil_peplinski'