add ESA driving functions docstring examples for monopoles

[fs446]

in all ESA driving functions we need to check the handling at

if Nc is None: what type to return such that no error occurs The returned Nc = double is not working with the subsequent np.ones(Nc)

Furthermore for ease of documentation, i.e. same grid as all other examples, this nan-handling plot(np.nan_to_num(d), selection, secondary_source) helps to plot. NaN presumably occurs since grid and secondary source position coincide. Is there a more elegant way to avoid this. Anyway, I'd vote to change the grid for these examples.

[narahahn]

Furthermore for ease of documentation, i.e. same grid as all other examples, this nan-handling plot(np.nan_to_num(d), selection, secondary_source) helps to plot. NaN presumably occurs since grid and secondary source position coincide. Is there a more elegant way to avoid this. Anyway, I'd vote to change the grid for these examples.

I didn't check all cases, but nan is already in the driving signals. Presumably this is due to the Hankel function which returns nan for argument 0.

https://github.com/sfstoolbox/sfs-python/blob/552c3065bb6bff8fa05df565a2e68f3cfdf2dab4/sfs/mono/drivingfunction.py#L1199

[mgeier]

The reason for the first problem is that np.ceil() returns floating point values instead of integers.

There are numerous issues about that, e.g.:

• https://github.com/numpy/numpy/issues/5700
• https://github.com/numpy/numpy/issues/9068
• https://github.com/numpy/numpy/issues/11557
• https://github.com/numpy/numpy/issues/11810

I see two options:

import math
Nc = math.ceil(2 * k * max(r) * alpha/np.pi)

or

Nc = np.ceil(2 * k * np.max(r) * alpha/np.pi).astype(int)

[mgeier]

Regarding NaN values, I don't think we should convert them to zero, right?

Since now the ESA driving functions are in their own module, it's no problem to choose a different grid and/or array for the examples.

[fs446]

Regarding NaN values, I don't think we should convert them to zero, right?

Yeah, that would be inappropriate. We rather should check what precisely happens. I have it on my list.

Since now the ESA driving functions are in their own module, it's no problem to choose a different grid and/or array for the examples.

Yeah, that's nice about the new handling. I will cover this as well ASAP.

[fs446]

I see two options:

import math
Nc = math.ceil(2 * k * max(r) * alpha/np.pi)

or

Nc = np.ceil(2 * k * np.max(r) * alpha/np.pi).astype(int)

I'd vote for the second one, then we give a more clearer hint, that something is happening and we explicitly take care of it. The first solution is blurry, because it might only raise wondering why the coders did not use np.ceil...which is good, but we don't tell then.

[spors]

I see two options:

import math
Nc = math.ceil(2 * k * max(r) * alpha/np.pi)

or

Nc = np.ceil(2 * k * np.max(r) * alpha/np.pi).astype(int)

I'd vote for the second one, then we give a more clearer hint, that something is happening and we explicitly take care of it. The first solution is blurry, because it might only raise wondering why the coders did not use np.ceil...which is good, but we don't tell then.

I also like the second variant!