design

empymod.scripts.fdesign.design(n, spacing, shift, fI, fC=False, r=None, r_def=(1, 1, 2), reim=None, cvar='amp', error=0.01, name=None, full_output=False, finish=False, save=True, path='filters', verb=2, plot=1)[source]

Digital linear filter (DLF) design

This routine 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.

This filter designing tool uses the direct matrix inversion method as described in [Kong07] and is based on scripts by [Key12]. The tool is an add-on to the electromagnetic modeller empymod [Wert17]. Fruitful discussions with Evert Slob and Kerry Key improved the add-on substantially.

Example notebooks of its usage can be found in the documentation-gallery, https://empymod.emsig.xyz/en/stable/gallery

Parameters
nint

Filter length.

spacing: float or tuple (start, stop, num)

Spacing between filter points. If tuple, it corresponds to the input for np.linspace with endpoint=True.

shift: float or tuple (start, stop, num)

Shift of base from zero. If tuple, it corresponds to the input for np.linspace with endpoint=True.

fI, fCtransform pairs

Theoretical or numerical transform pair(s) for the inversion (I) and for the check of goodness (fC). fC is optional. If not provided, fI is used for both fI and fC.

rarray, optional

Right-hand side evaluation points for the check of goodness (fC). Defaults to r = np.logspace(0, 5, 1000), which are a lot of evaluation points, and depending on the transform pair way too long r’s.

r_deftuple (add_left, add_right, factor), optional

Definition of the right-hand side evaluation points r of the inversion. r is derived from the base values, default is (1, 1, 2).

  • rmin = log10(1/max(base)) - add_left

  • rmax = log10(1/min(base)) + add_right

  • r = logspace(rmin, rmax, factor*n)

reimnp.real or np.imag, optional

Which part of complex transform pairs is used for the inversion. Defaults to np.real.

cvarstring {‘amp’, ‘r’}, optional

If ‘amp’, the inversion minimizes the amplitude. If ‘r’, the inversion maximizes the right-hand side evaluation point r. Defaults is ‘amp’.

errorfloat, optional

Up to which relative error the transformation is considered good in the evaluation of the goodness. Default is 0.01 (1 %).

namestr, optional

Name of the filter. Defaults to dlf_+str(n).

full_outputbool, optional

If True, returns best filter and output from scipy.optimize.brute; else only filter. Default is False.

finishNone, True, or callable, optional

If callable, it is passed through to scipy.optimize.brute: minimization function to find minimize best result from brute-force approach. Default is None. You can simply provide True in order to use scipy.optimize.fmin_powell(). Set this to None if you are only interested in the actually provided spacing/shift-values.

savebool, optional

If True, best filter is saved to plain text files in ./filters/. Can be loaded with fdesign.load_filter(name). If full, the inversion output is stored too. You can add ‘.gz’ to name, which will then save the full inversion output in a compressed file instead of plain text.

pathstring, optional

Absolute or relative path where output will be saved if save=True. Default is ‘filters’.

verb{0, 1, 2}, optional

Level of verbosity, default is 2:

  • 0: Print nothing.

  • 1: Print warnings.

  • 2: Print additional time, progress, and result

plot{0, 1, 2, 3}, optional

Level of plot-verbosity, default is 1:

  • 0: Plot nothing.

  • 1: Plot brute-force result

  • 2: Plot additional theoretical transform pairs, and best inv.

  • 3: Plot additional inversion result (can result in lots of plots depending on spacing and shift) If you are using a notebook, use %matplotlib notebook to have all inversion results appear in the same plot.

Returns
filterempymod.filter.DigitalFilter instance

Best filter for the input parameters.

fulltuple

Output from scipy.optimize.brute with full_output=True. (Returned when full_output is True.)