Generating a dipolar kernel with background does not work as expected

[mtessmer]

I would expect generating a kernel with dl.dipolarkernel(t, r, B=B) would produce a kernel that incorporates the background signal however it does not:

import numpy as np
import matplotlib.pyplot as plt
import deerlab as dl

r = np.linspace(1.5, 8.0, 256)
t = np.linspace(-0.2, 5, 256)
P = dl.dd_gauss(r, (4.2, 0.2))
lam = 0.4
B = dl.bg_hom3d(t, 100, lam)

K = dl.dipolarkernel(t, r, B=B)         
_K = dl.dipolarkernel(t, r, integralop=False)

Kb = (1 - lam  + lam * _K) * B[:,None]
Kb *= np.diff(r).mean()

fig, ax = plt.subplots()
plt.plot(t, K @ P, label='DeerLab')
plt.plot(t, Kb @ P, label='Manual')
plt.legend()
plt.show()

[stestoll]

You are not providing a modulation depth to dipolarkernel, so the function assumes it to be 100% (equivalent to calling the function one of the following ways:

K = dl.dipolarkernel(t, r, 1, B=B)
K = dl.dipolarkernel(t, r, pathways=1, B=B)

Consequently, you won't get an unmodulated component in the DEER trace. The modulated component, however, is attenuated. You can see this with a sufficiently steep background by comparing signal generated with the two following kernels:

Kb = dl.dipolarkernel(t, r, B=B)
K = dl.dipolarkernel(t, r)

So the behavior of dipolarkernel is as intended.

Maybe we can add a keyword argument lambda that is equivalent to pathways if only a single scalar is given. However, since the modulation is also a positional argument, I am not sure this is needed,

[stestoll]

Here's a proposal, based in part on discussion with @luisfabib :

1. Make all dipolarkernel arguments except t and r keyword-only. (def dipolarkernel(t, r, *, ...). This makes sense, since there is no reason for any particular positional order of any arguments except t and r. For these two, positional arguments make sense, since V(t) = K(t,r)P(r).
2. Restrict pathways to accept only pathway lists, with default None.
3. Provide a new keyword argument that only accepts a single number and provides the modulation depth/amplitude for the standard single-pathway model.

Name for the new keyword argument:

• lam as an abbreviation for lambda, which is the conventional symbol used for this quantity. lambda itself cannot be use, since it is a Python keyword.
• mod is brief and accurate.
• modamp is more explicit, although reminiscent of CW EPR modulation amplitude - which is probably not an issue.
• moddepth is closest to the conventional name of this quantity, but the longest (contrast: background keyword is only one letter.)

Default value for the new keyword argument:

• 0.5 or so. Then both unmodulated and modulate contribution are visible. This solves the OP use case. If the user wants modulated only, they need to specify modamp=1 .
• 1. But then we still have the OP use case.
• Make the default depend on whether a background is given in B or not: 1 if not given, 0.5 when given. This also solves the OP use case.

Here are the simplest calls to dipolarkernel:

dipolarkernel(t,r)                         # Default modulation depth (1 or 0.5), default background (None)
dipolarkernel(t,r,modamp=0.2)              # Mod.depth given, default background (None)
dipolarkernel(t,r,B=bg_hom3d)              # Default modulation depth (1 or 0.5), background given
dipolarkernel(t,r,modamp=0.2,B=bg_hom3d)   # Both mod.depth and background are given