### Install python3-setuptools

Source: https://github.com/emsig/empymod/blob/main/docs/dev/release.rst

Install python3-setuptools if the conda skeleton build fails due to missing setuptools.

```default
sudo apt install python3-setuptools
```

--------------------------------

### Install development requirements

Source: https://github.com/emsig/empymod/blob/main/docs/dev/tests.rst

Installs all packages listed in requirements_dev.txt, which include tools for testing, linting, and documentation.

```console
pip install -r requirements_dev.txt
```

--------------------------------

### Install empymod with pip

Source: https://github.com/emsig/empymod/blob/main/docs/manual/installation.rst

Install empymod via pip.

```console
pip install empymod
```

--------------------------------

### Using Report with default and custom parameters

Source: https://github.com/emsig/empymod/blob/main/docs/api/empymod.utils.Report.md

Shows how to instantiate Report with default values, add a single package, or add a list of packages with a custom column count. Requires scooby installed via pip install scooby.

```pycon
>>> import pytest
>>> import dateutil
>>> from empymod import Report
>>> Report()                            # Default values
>>> Report(pytest)                      # Provide additional package
>>> Report([pytest, dateutil], ncol=5)  # Set nr of columns
```

--------------------------------

### Makefile commands for development tasks

Source: https://github.com/emsig/empymod/blob/main/docs/dev/tests.rst

Common Makefile targets for installing the package, checking linting, running tests, building documentation, and listing all available targets.

```console
make install
```

```console
make flake8
```

```console
make pytest
```

```console
make html
```

```console
make
```

--------------------------------

### printstartfinish

Source: https://github.com/emsig/empymod/blob/main/docs/api/empymod.utils.printstartfinish.md

Prints start and finish messages with time measurement and kernel count information.

```APIDOC
## printstartfinish

### Description
Prints start and finish messages with time measurement and kernel count information.

### Method
Function

### Signature
`empymod.utils.printstartfinish(verb, inp=None, kcount=None)`

### Parameters
- **verb** (int) - Required - Verbosity level controlling whether output is printed.
- **inp** (optional) - Optional - Additional input data.
- **kcount** (optional) - Optional - Kernel count information.

```

--------------------------------

### Install empymod with conda

Source: https://github.com/emsig/empymod/blob/main/docs/manual/installation.rst

Install empymod via the conda package manager from the conda-forge channel.

```console
conda install -c conda-forge empymod
```

--------------------------------

### Create EMArray and compute amplitude and phase

Source: https://github.com/emsig/empymod/blob/main/docs/api/empymod.utils.EMArray.md

Shows how to create an EMArray from a NumPy array and use its amp() and pha() methods. The pha() method supports deg, unwrap, and lag parameters; the example demonstrates radians, degrees, and lead-defined phase.

```pycon
>>> import numpy as np
>>> from empymod.utils import EMArray
>>> emvalues = EMArray(np.array([1+1j, 1-4j, -1+2j]))
>>> print(f"Amplitude         : {emvalues.amp()}")
Amplitude         : [1.41421356 4.12310563 2.23606798]
>>> print(f"Phase (rad)       : {emvalues.pha()}")
Phase (rad)       : [ 0.78539816 -1.32581766 -4.24874137]
>>> print(f"Phase (deg)       : {emvalues.pha(deg=True)}")
Phase (deg)       : [  45.          -75.96375653 -243.43494882]
>>> print(f"Phase (deg; lead) : {emvalues.pha(deg=True, lag=False)}")
Phase (deg; lead) : [-45.          75.96375653 243.43494882]
```

--------------------------------

### Dummy example of custom func_eta

Source: https://github.com/emsig/empymod/blob/main/docs/manual/info.rst

Shows the required signature and return values for a user-defined function passed via the 'func_eta' key in the 'res' dictionary. The function receives the user-provided dictionary 'inp' and empymod's parameter dictionary 'p_dict', and must return etaH and etaV.

```python
def my_new_eta(inp, p_dict):
    # Your computations, using the parameters you provided
    # in `inp` and the parameters from empymod in `p_dict`.
    # In the example line below, we provide, e.g.,  inp['tau']
    return etaH, etaV
```

--------------------------------

### Check README with python setup.py --long-description

Source: https://github.com/emsig/empymod/blob/main/docs/dev/release.rst

Check README rendering by converting the long description to HTML. Useful before a release to verify formatting.

```default
python setup.py --long-description | rst2html.py --no-raw > index.html
```

--------------------------------

### get_layer_nr

Source: https://github.com/emsig/empymod/blob/main/docs/api/utils.rst

Gets number of layer in which inp resides.

```APIDOC
## `get_layer_nr(inp, depth)`

### Description
Gets number of layer in which inp resides.

### Parameters
- **inp** (float) - Required - Input value.
- **depth** (array-like) - Required - Layer depths.

### Returns
- Layer number.

```

--------------------------------

### get_azm_dip

Source: https://github.com/emsig/empymod/blob/main/docs/api/utils.rst

Gets angles, interpolation weights and normalization weights.

```APIDOC
## `get_azm_dip(inp, iz, ninpz, intpts, ...)`

### Description
Gets angles, interpolation weights and normalization weights.

### Parameters
- **inp** (array-like) - Required - Input array.
- **iz** (int) - Required - Index.
- **ninpz** (int) - Required - Number of input points.
- **intpts** (int) - Required - Number of interpolation points.
- **...** - Additional parameters.

### Returns
- Angles, interpolation weights, normalization weights.

```

--------------------------------

### Compare analytical, quadrature, and DLF solutions for zero offset

Source: https://github.com/emsig/empymod/blob/main/docs/manual/info.rst

Script that computes responses for all source-receiver configurations in a fullspace, comparing analytical, quadrature, and DLF solutions. It sets minimum offset to 1e-3 for DLF and 0 for quadrature, then plots the results.

```python
import empymod
import numpy as np
import matplotlib.pyplot as plt

xy = np.arange(1001.)/500-1         # x=y-offsets
off = np.sign(xy)*np.sqrt(2*xy**2)  # Offset

res = 1   # Fullspace resistivity
zoff = 1  # Vertical distance
freq = 1  # Frequency

# Collect input
inp = {'src': [0, 0, 0], 'rec': [xy, xy, zoff], 'depth': [],
       'res': res, 'freqtime': freq, 'verb': 2}

pab = [11, 12, 13, 14, 15, 16, 21, 22, 23, 24, 25, 26,
       31, 32, 33, 34, 35, 36, 41, 42, 43, 44, 45, 46,
       51, 52, 53, 54, 55, 56, 61, 62, 63, 64, 65, 66]

# Loop over all source-receiver combinations
for ab in pab:

    # Enforce minimum offset
    empymod.set_minimum(min_off=1e-3)

    print('    --- DLF ---')
    num = empymod.dipole(
            ab=ab, xdirect=False, htarg={'pts_per_dec': 0}, **inp)

    # Remove minimum offset
    empymod.set_minimum(min_off=0)

    print('    --- QUAD ---')
    qua = empymod.dipole(
            ab=ab, xdirect=False, ht='quad', **inp,
            htarg={'a': 1e-3, 'b': 5e1, 'rtol': 1e-4, 'pts_per_dec': 100})
    print('    --- Analytical ---')
    ana = empymod.dipole(ab=ab, xdirect=True, **inp)

    # Plot the result
    plt.figure(num=ab)
    plt.suptitle(f"ab = {ab}")

    ax1 = plt.subplot(221)
    plt.title('Real')
    plt.ylabel('E-field (V/m)')
    plt.plot(off, ana.real, 'k-')
    plt.plot(off, qua.real, 'C0--')
    plt.plot(off, num.real, 'C1-.')
    plt.xticks([-1, -0.5, 0, 0.5, 1], ())

    ax3 = plt.subplot(223)
    plt.xlabel('Offset (m)')
    plt.ylabel('Rel. Error (%)')
    plt.plot(off, 100*abs((qua.real-ana.real)/ana.real), 'C0--')
    plt.plot(off, 100*abs((num.real-ana.real)/ana.real), 'C1-.')
    plt.yscale('log')

    ax2 = plt.subplot(222, sharey=ax1)
    plt.title('Imag')
    plt.plot(off, ana.imag, 'k-', label='analytical')
    plt.plot(off, qua.imag, 'C0--', label='QUAD')
    plt.plot(off, num.imag, 'C1-.', label='DLF')
    ax2.yaxis.set_label_position("right")
    ax2.yaxis.tick_right()
    plt.xticks([-1, -0.5, 0, 0.5, 1], ())
    plt.legend()

    ax4 = plt.subplot(224, sharey=ax3)
    plt.xlabel('Offset (m)')
    plt.plot(off, 100*abs((qua.imag-ana.imag)/ana.imag), 'C0--')
    plt.plot(off, 100*abs((num.imag-ana.imag)/ana.imag), 'C1-.')
    ax4.yaxis.set_label_position("right")
    ax4.yaxis.tick_right()
    plt.yscale('log')

    plt.tight_layout()
    plt.show()
```

--------------------------------

### get_abs

Source: https://github.com/emsig/empymod/blob/main/docs/api/utils.rst

Gets required ab's for given angles.

```APIDOC
## `get_abs(msrc, mrec, srcazm, srcdip, recazm, recdip, verb)`

### Description
Gets required ab's for given angles.

### Parameters
- **msrc** (str) - Required - Source type.
- **mrec** (str) - Required - Receiver type.
- **srcazm** (float) - Required - Source azimuth.
- **srcdip** (float) - Required - Source dip.
- **recazm** (float) - Required - Receiver azimuth.
- **recdip** (float) - Required - Receiver dip.
- **verb** (int) - Required - Verbosity level.

### Returns
- Required ab's.

```

--------------------------------

### get_geo_fact

Source: https://github.com/emsig/empymod/blob/main/docs/api/utils.rst

Gets required geometrical scaling factor for given angles.

```APIDOC
## `get_geo_fact(ab, srcazm, srcdip, recazm, recdip, verb)`

### Description
Gets required geometrical scaling factor for given angles.

### Parameters
- **ab** (int) - Required - Source-receiver configuration.
- **srcazm** (float) - Required - Source azimuth.
- **srcdip** (float) - Required - Source dip.
- **recazm** (float) - Required - Receiver azimuth.
- **recdip** (float) - Required - Receiver dip.
- **verb** (int) - Required - Verbosity level.

### Returns
- Geometrical scaling factor.

```

--------------------------------

### fromfile

Source: https://github.com/emsig/empymod/blob/main/docs/api/empymod.filters.DigitalFilter.md

Loads filter base and coefficients from ASCII files in a specified directory.

```APIDOC
## fromfile(path='filters')

### Description
Load filter values from ASCII-files. Load filter base and filter coefficients from ASCII files in the directory path; path can be a relative or absolute path.

### Method
fromfile

### Parameters
- **path** (str) - Optional - Directory path from which to load the ASCII files. Default is 'filters'.

### Example
```pycon
>>> import empymod
>>> # Create an empty filter;
>>> # Name has to be the base of the text files
>>> filt = empymod.filters.DigitalFilter('my-filter')
>>> # Load the ASCII-files
>>> filt.fromfile()
>>> # This will load the following three files:
>>> #    ./filters/my-filter_base.txt
>>> #    ./filters/my-filter_j0.txt
>>> #    ./filters/my-filter_j1.txt
>>> # and store them in filt.base, filt.j0, and filt.j1.
```
```

--------------------------------

### get_off_ang

Source: https://github.com/emsig/empymod/blob/main/docs/api/utils.rst

Gets depths, offsets, angles, hence spatial input parameters.

```APIDOC
## `get_off_ang(src, rec, nsrc, nrec, verb)`

### Description
Gets depths, offsets, angles, hence spatial input parameters.

### Parameters
- **src** (array-like) - Required - Source coordinates.
- **rec** (array-like) - Required - Receiver coordinates.
- **nsrc** (int) - Required - Number of sources.
- **nrec** (int) - Required - Number of receivers.
- **verb** (int) - Required - Verbosity level.

### Returns
- Depths, offsets, angles.

```

--------------------------------

### Load filter values with DigitalFilter.fromfile()

Source: https://github.com/emsig/empymod/blob/main/docs/api/empymod.filters.DigitalFilter.md

Loads filter base and coefficients from ASCII files in the directory 'filters'. The filter name must match the base of the text files. After calling fromfile(), the loaded values are stored in filt.base, filt.j0, and filt.j1.

```pycon
>>> import empymod
>>> # Create an empty filter;
>>> # Name has to be the base of the text files
>>> filt = empymod.filters.DigitalFilter('my-filter')
>>> # Load the ASCII-files
>>> filt.fromfile()
>>> # This will load the following three files:
>>> #    ./filters/my-filter_base.txt
>>> #    ./filters/my-filter_j0.txt
>>> #    ./filters/my-filter_j1.txt
>>> # and store them in filt.base, filt.j0, and filt.j1.
```

--------------------------------

### conv_warning

Source: https://github.com/emsig/empymod/blob/main/docs/api/utils.rst

Prints error if QWE/QUAD did not converge at least once.

```APIDOC
## `conv_warning(conv, targ, name, verb)`

### Description
Prints error if QWE/QUAD did not converge at least once.

### Parameters
- **conv** (bool) - Required - Convergence flag.
- **targ** (float) - Required - Target accuracy.
- **name** (str) - Required - Name of the transform.
- **verb** (int) - Required - Verbosity level.

### Returns
- None.

```

--------------------------------

### Save filter values with DigitalFilter.tofile()

Source: https://github.com/emsig/empymod/blob/main/docs/api/empymod.filters.DigitalFilter.md

Saves the filter base and coefficients to separate ASCII files in the 'filters' directory. The example loads the 'wer_201_2018' filter from the Hankel class and then calls tofile() to write the three files.

```pycon
>>> import empymod
>>> # Load a filter
>>> filt = empymod.filters.Hankel().wer_201_2018
>>> # Save it to pure ASCII-files
>>> filt.tofile()
>>> # This will save the following three files:
>>> #    ./filters/wer_201_2018_base.txt
>>> #    ./filters/wer_201_2018_j0.txt
>>> #    ./filters/wer_201_2018_j1.txt
```

--------------------------------

### check_solution

Source: https://github.com/emsig/empymod/blob/main/docs/api/utils.rst

Checks required solution with parameters.

```APIDOC
## `check_solution(solution, signal, ab, msrc, mrec)`

### Description
Checks required solution with parameters.

### Parameters
- **solution** (str) - Required - Solution type.
- **signal** (str) - Required - Signal type.
- **ab** (int) - Required - Source-receiver configuration.
- **msrc** (str) - Required - Source type.
- **mrec** (str) - Required - Receiver type.

### Returns
- Processed solution.

```

--------------------------------

### empymod.utils.get_abs(msrc, mrec, srcazm, srcdip, recazm, recdip, verb)

Source: https://github.com/emsig/empymod/blob/main/docs/api/empymod.utils.get_abs.md

Gets the required ab's for given angles. This function is called from modelling routines in empymod.model to determine which ab's to calculate for a given dipole configuration.

```APIDOC
## Function: empymod.utils.get_abs

### Description
Gets the required ab's for given angles. This check-function is called from one of the modelling routines in empymod.model. Consult these modelling routines for a detailed description of the input parameters.

### Parameters
- **msrc** (bool) - True if source is magnetic, else False.
- **mrec** (bool) - True if receiver is magnetic, else False.
- **srcazm** (float) - Horizontal source angle (azimuth).
- **srcdip** (float) - Vertical source angle (dip).
- **recazm** (float) - Horizontal receiver angle (azimuth).
- **recdip** (float) - Vertical receiver angle (dip).
- **verb** (int) - Level of verbosity.

### Returns
- **ab_calc** (list) - ab's to calculate for this dipole.
```

--------------------------------

### Upload to TestPyPI with twine

Source: https://github.com/emsig/empymod/blob/main/docs/dev/release.rst

Upload distribution files to TestPyPI for verification. Requires a ~/.pypirc file with TestPyPI credentials.

```default
~/anaconda3/bin/twine upload dist/* -r testpypi
```

--------------------------------

### check_solution(solution, signal, ab, msrc, mrec)

Source: https://github.com/emsig/empymod/blob/main/docs/api/empymod.utils.check_solution.md

Documentation for the check_solution function in empymod.utils.

```APIDOC
## check_solution(solution, signal, ab, msrc, mrec)

### Description
Checks required solution with parameters. This check-function is called from one of the modelling routines in `empymod.model`. Consult these modelling routines for a detailed description of the input parameters.

### Parameters
- **solution** (string) - Required - String to define analytical solution.
- **signal** (None, -1, 0, +1) - Required - Source signal: None for frequency-domain response, -1 for switch-off time-domain response, 0 for impulse time-domain response, +1 for switch-on time-domain response.
- **ab** (not specified) - Required - Parameter for the modelling routine.
- **msrc** (bool) - Required - True if source is magnetic, else False.
- **mrec** (bool) - Required - True if receiver is magnetic, else False.
```

--------------------------------

### Hankel transform pair j0_1

Source: https://github.com/emsig/empymod/blob/main/docs/LaTeX/fdesign.tex

Example of an implemented Hankel transform pair j0_1, based on Anderson (1975). It returns a Ghosh object with name 'j0' and the analytic expressions for the left-hand side (lhs) and right-hand side (rhs) of the transform pair.

```python
def j0_1(a=1):
        """Hankel transform pair J0_1 ([Anderson_1975]_)."""

        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)
```

--------------------------------

### empymod.kernel.reflections(depth, e_zH, Gam, lrec, lsrc)

Source: https://github.com/emsig/empymod/blob/main/docs/api/empymod.kernel.reflections.md

Documentation for the empymod.kernel.reflections function, which calculates reflection coefficients Rp and Rm.

```APIDOC
## empymod.kernel.reflections(depth, e_zH, Gam, lrec, lsrc)

### Description
Calculates the reflection coefficients Rp and Rm, corresponding to equations 64/65 and A-11/A-12 in HuTS15. This function is called from the function `greenfct`.

### Parameters
- **depth** (array-like) - Required - Depth values.
- **e_zH** (array-like) - Required - Exponential factor for the zH component.
- **Gam** (array-like) - Required - Gamma values.
- **lrec** (int) - Required - Index for receiver layer.
- **lsrc** (int) - Required - Index for source layer.

### Returns
- **Rp** - Reflection coefficient Rp.
- **Rm** - Reflection coefficient Rm.

### Notes
This function corresponds to equations 64/65 and A-11/A-12 in HuTS15, and loosely to the corresponding files Rmin.F90 and Rplus.F90.
```

--------------------------------

### empymod.io.load_input(fname)

Source: https://github.com/emsig/empymod/blob/main/docs/api/empymod.io.load_input.md

Loads input data from a file. The file format is determined by the file suffix, with only .json currently supported. Returns a dictionary containing the loaded input.

```APIDOC
## empymod.io.load_input(fname)

### Description
Loads input data from a file. The file format is determined by the file suffix, with only .json currently supported. Returns a dictionary containing the loaded input.

### Parameters
- **fname** (str) - Required - File name with absolute or relative path including suffix, which defines the used data format. Implemented is currently only `.json`.

### Returns
- **data** (dict) - Dictionary containing the input that was stored in the file.
```