Add-on functions¶
empymod.scripts.fdesign Module¶
empymod.scripts.fdesign – Digital Linear Filter (DLF) design¶
The add-on fdesign can be used to design digital linear filters for the Hankel or Fourier transform, or for any linear transform ([Ghos70]). For this included or provided theoretical transform pairs can be used. Alternatively, one can use the EM modeller empymod to use the responses to an arbitrary 1D model as numerical transform pair.
More information can be found in the following places:
The article about fdesign is in the repo https://github.com/emsig/article-fdesign
Example notebooks to design a filter can be found in the repo https://empymod.readthedocs.io/en/stable/examples
This filter designing tool uses the direct matrix inversion method as described in [Kong07] and is based on scripts by [Key12]. The whole project of fdesign started with the Matlab scripts from Kerry Key, which he used to design his filters for [Key09], [Key12]. Fruitful discussions with Evert Slob and Kerry Key improved the add-on substantially.
Note that the use of empymod to create numerical transform pairs is, as of now, only implemented for the Hankel transform.
Implemented analytical transform pairs¶
The following tables list the transform pairs which are implemented by default. Any other transform pair can be provided as input. A transform pair is defined in the following way:
from empymod.scripts import fdesign
def my_tp_pair(var):
'''My transform pair.'''
def lhs(l):
return func(l, var)
def rhs(r):
return func(r, var)
return fdesign.Ghosh(name, lhs, rhs)
Here, name must be one of j0, j1, sin, or cos, depending what type of transform pair it is. Additional variables are provided with var. The evaluation points of the lhs are denoted by l, and the evaluation points of the rhs are denoted as r. As an example here the implemented transform pair j0_1
def j0_1(a=1):
'''Hankel transform pair J0_1 ([Ande75]_).'''
def lhs(l):
return l*np.exp(-a*l**2)
def rhs(r):
return np.exp(-r**2/(4*a))/(2*a)
return Ghosh('j0', lhs, rhs)
Implemented Hankel transforms¶
j0_1 [Ande75]
(1)¶\[\int^\infty_0 l \exp\left(-al^2\right) J_0(lr) dl = \frac{\exp\left(\frac{-r^2}{4a}\right)}{2a}\]j0_2 [Ande75]
(2)¶\[\int^\infty_0 \exp\left(-al\right) J_0(lr) dl = \frac{1}{\sqrt{a^2+r^2}}\]j0_3 [GuSi97]
(3)¶\[\int^\infty_0 l\exp\left(-al\right) J_0(lr) dl = \frac{a}{(a^2 + r^2)^{3/2}}\]j0_4 [ChCo82]
(4)¶\[\int^\infty_0 \frac{l}{\beta} \exp\left(-\beta z_v \right) J_0(lr) dl = \frac{\exp\left(-\gamma R\right)}{R}\]j0_5 [ChCo82]
(5)¶\[\int^\infty_0 l \exp\left(-\beta z_v \right) J_0(lr) dl = \frac{ z_v (\gamma R + 1)}{R^3}\exp\left(-\gamma R\right)\]j1_1 [Ande75]
(6)¶\[\int^\infty_0 l^2 \exp\left(-al^2\right) J_1(lr) dl = \frac{r}{4a^2} \exp\left(-\frac{r^2}{4a}\right)\]j1_2 [Ande75]
(7)¶\[\int^\infty_0 \exp\left(-al\right) J_1(lr) dl = \frac{\sqrt{a^2+r^2}-a}{r\sqrt{a^2 + r^2}}\]j1_3 [Ande75]
(8)¶\[\int^\infty_0 l \exp\left(-al\right) J_1(lr) dl = \frac{r}{(a^2 + r^2)^{3/2}}\]j1_4 [ChCo82]
(9)¶\[\int^\infty_0 \frac{l^2}{\beta} \exp\left(-\beta z_v \right) J_1(lr) dl = \frac{r(\gamma R+1)}{R^3}\exp\left(-\gamma R\right)\]j1_5 [ChCo82]
(10)¶\[\int^\infty_0 l^2 \exp\left(-\beta z_v \right) J_1(lr) dl = \frac{r z_v(\gamma^2R^2+3\gamma R+3)}{R^5}\exp\left(-\gamma R\right)\]
Where
Implemented Fourier transforms¶
sin_1 [Ande75]
(11)¶\[\int^\infty_0 l\exp\left(-a^2l^2\right) \sin(lr) dl = \frac{\sqrt{\pi}r}{4a^3} \exp\left(-\frac{r^2}{4a^2}\right)\]sin_2 [Ande75]
(12)¶\[\int^\infty_0 \exp\left(-al\right) \sin(lr) dl = \frac{r}{a^2 + r^2}\]sin_3 [Ande75]
(13)¶\[\int^\infty_0 \frac{l}{a^2+l^2} \sin(lr) dl = \frac{\pi}{2} \exp\left(-ar\right)\]cos_1 [Ande75]
(14)¶\[\int^\infty_0 \exp\left(-a^2l^2\right) \cos(lr) dl = \frac{\sqrt{\pi}}{2a} \exp\left(-\frac{r^2}{4a^2}\right)\]cos_2 [Ande75]
(15)¶\[\int^\infty_0 \exp\left(-al\right) \cos(lr) dl = \frac{a}{a^2 + r^2}\]cos_3 [Ande75]
(16)¶\[\int^\infty_0 \frac{1}{a^2+l^2} \cos(lr) dl = \frac{\pi}{2a} \exp\left(-ar\right)\]
Functions¶
|
Digital linear filter (DLF) design |
|
Save DLF-filter and inversion output to plain text files. |
|
Load saved DLF-filter and inversion output from text files. |
|
QC the inversion result. |
|
Print best filter information. |
|
Hankel transform pair J0_1 ([Ande75]). |
|
Hankel transform pair J0_2 ([Ande75]). |
|
Hankel transform pair J0_3 ([GuSi97]). |
|
Hankel transform pair J0_4 ([ChCo82]). |
|
Hankel transform pair J0_5 ([ChCo82]). |
|
Hankel transform pair J1_1 ([Ande75]). |
|
Hankel transform pair J1_2 ([Ande75]). |
|
Hankel transform pair J1_3 ([Ande75]). |
|
Hankel transform pair J1_4 ([ChCo82]). |
|
Hankel transform pair J1_5 ([ChCo82]). |
|
Fourier sine transform pair sin_1 ([Ande75]). |
|
Fourier sine transform pair sin_2 ([Ande75]). |
|
Fourier sine transform pair sin_3 ([Ande75]). |
|
Fourier cosine transform pair cos_1 ([Ande75]). |
|
Fourier cosine transform pair cos_2 ([Ande75]). |
|
Fourier cosine transform pair cos_3 ([Ande75]). |
|
Numerical transform pair with empymod. |
empymod.scripts.tmtemod Module¶
empymod.scripts.tmtemod – Calculate up- and down-going TM and TE modes¶
This add-on for empymod adjusts [HuTS15] for TM/TE-split. The development was initiated by the development of https://github.com/emsig/csem-ziolkowski-and-slob ([ZiSl19]).
This is a stripped-down version of empymod with a lot of simplifications but an important addition. The modeller empymod returns the total field, hence not distinguishing between TM and TE mode, and even less between up- and down-going fields. The reason behind this is simple: The derivation of [HuTS15], on which empymod is based, returns the total field. In this derivation each mode (TM and TE) contains non-physical contributions. The non-physical contributions have opposite signs in TM and TE, so they cancel each other out in the total field. However, in order to obtain the correct TM and TE contributions one has to remove these non-physical parts.
This is what this routine does, but only for an x-directed electric source with
an x-directed electric receiver, and in the frequency domain (src and rec in
same layer). This version of empymod.dipole() returns the signal
separated into TM++, TM+-, TM-+, TM–, TE++, TE+-, TE-+, and TE– as well as
the direct field TM and TE contributions. The first superscript denotes the
direction in which the field diffuses towards the receiver and the second
superscript denotes the direction in which the field diffuses away from the
source. For both the plus-sign indicates the field diffuses in the downward
direction and the minus-sign indicates the field diffuses in the upward
direction. It uses empymod wherever possible. See the corresponding functions
in empymod for more explanation and documentation regarding input parameters.
There are important limitations:
ab == 11 [=> x-directed el. source & el. receivers]
signal == None [=> only frequency domain]
xdirect == False [=> direct field calc. in wavenr-domain]
ht == ‘dlf’
htarg == ‘key_201_2012’
Options ft, ftarg, and loop are not available.
lsrc == lrec [=> src & rec are assumed in same layer!]
Model must have more than 1 layer
Electric permittivity and magnetic permeability are isotropic.
Only one frequency at once.
Theory¶
The derivation of [HuTS15], on which empymod is based, returns the total field. Internally it also calculates TM and TE modes, and sums these up. However, the separation into TM and TE mode introduces a singularity at \(\kappa = 0\). It has no contribution in the space-frequency domain to the total fields, but it introduces non-physical events in each mode with opposite sign (so they cancel each other out in the total field). In order to obtain the correct TM and TE contributions one has to remove these non-physical parts.
This routine removes the non-physical part. It is basically a heavily simplified version of empymod with the following limitations outlined above.
It returns the signal separated into TM++, TM+-, TM-+, TM–, TE++, TE+-, TE-+, and TE– as well as the direct field TM and TE contributions. The first superscript denotes the direction in which the field diffuses towards the receiver and the second superscript denotes the direction in which the field diffuses away from the source. For both the plus-sign indicates the field diffuses in the downward direction and the minus-sign indicates the field diffuses in the upward direction. The routine uses empymod wherever possible, see the corresponding functions in empymod for more explanation and documentation regarding input parameters.
Please note that the notation in [HuTS15] differs from the notation in [ZiSl19]. I specify therefore always, which notification applies, either Hun15 or Zio19.
We start with equation (105) in Hun15:
Ignoring the incident field, and using \(J_2 = \frac{2}{\kappa r}J_1 - J_0\) to avoid \(J_2\)-integrals, we get
From this the TM- and TE-parts follow as
Equations (108) and (109) in Hun15 yield the required parameters \(\tilde{g}^{tm}_{hh;s}\) and \(\tilde{g}^{te}_{zz;s}\),
The parameters \(P^{u\pm}_s\) and \(P^{d\pm}_s\) are given in equations (81) and (82), \(\bar{P}^{u\pm}_s\) and \(\bar{P}^{d\pm}_s\) in equations (A-8) and (A-9); \(W^u_s\) and \(W^d_s\) in equation (74) in Hun15. This yields
where \(d^\pm\) is taken from the text below equation (67). There are four terms in the right-hand side, two in the first line and two in the second line. The first term in the first line is the integrand of TE+-, the second term in the first line corresponds to TE++, the first term in the second line is TE-+, and the second term in the second line is TE–.
If we look at TE+-, we have
and therefore
We can compare this to equation (4.165) in Zio19, with \(\hat{I}^e_x=1\) and slightly re-arranging it to look more alike, we get
The notation in this equation follows Zio19.
The difference between the two previous equations is that the first one contains non-physical contributions. These have opposite signs in TM+- and TE+-, and therefore cancel each other out. But if we want to know the specific contributions from TM and TE we have to remove them. The non-physical contributions only affect the \(J_1\)-integrals, and only for \(\kappa = 0\).
The following lists for all 8 cases the term that has to be removed, in the notation of Zio19 (for the notation as in Hun15 see the implementation in this file):
Note that in the first and fourth equations the correction terms have opposite sign as those in the fifth and eighth equations because at \(\kappa=0\) the TM and TE mode correction terms are equal. Also note that in the second and third equations the correction terms have the same sign as those in the sixth and seventh equations because at \(\kappa=0\) the TM and TE mode reflection responses in those terms are equal but with opposite sign: \(R^\pm_{V;1}(\kappa=0) = -R^\pm_{V;1}(\kappa=0)\).
Hun15 uses \(\phi\), whereas Zio19 uses \(x\), \(y\), for which we can use