From 3ca08d20e5e3ab44feb860e65643457cf171d94f Mon Sep 17 00:00:00 2001 From: Craig Warren Date: Thu, 19 Nov 2015 15:58:20 +0000 Subject: [PATCH] Updates to docs for Debye, Lorentz, Drude dispersion. Lorentz and Drude docs need further work. --- docs/source/input.rst | 64 +++++++++++++++++++++++++---------- gprMax/input_cmds_multiuse.py | 13 ++++--- 2 files changed, 52 insertions(+), 25 deletions(-) diff --git a/docs/source/input.rst b/docs/source/input.rst index 7a37f510..8309cd69 100644 --- a/docs/source/input.rst +++ b/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. -* ``f2`` is the relaxation time (seconds), :math:`\tau`, for the first Drude pole. -* ``f3`` is the **x** for the first 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. -* ``f5`` is the relaxation time (seconds), :math:`\tau`, for the second Drude pole. -* ``f6`` is the **x** for the second Drude pole. +* ``f1`` is the relaxation time (seconds), :math:`\tau`, for the first Drude pole. +* ``f2`` is the **x** for the first Drude pole. +* ``f3`` is the relaxation time (seconds), :math:`\tau`, for the second Drude pole. +* ``f4`` 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: diff --git a/gprMax/input_cmds_multiuse.py b/gprMax/input_cmds_multiuse.py index a1b84c26..52feab05 100644 --- a/gprMax/input_cmds_multiuse.py +++ b/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): - if float(tmp[pole]) > 0 and float(tmp[pole + 1]) > G.dt and float(tmp[pole + 2]) > G.dt: - material.deltaer.append(float(tmp[pole])) - material.tau.append(float(tmp[pole + 1])) - material.alpha.append(float(tmp[pole + 2])) + for pole in range(1, 2 * poles, 2): + if float(tmp[pole]) > 0 and float(tmp[pole + 1]) > G.dt: + material.tau.append(float(tmp[pole ])) + material.alpha.append(float(tmp[pole + 1])) 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'