WFS 2.5D point source

[fs446]

I remember we had this discussion a while ago in the Matlab toolbox. I try it here again :-)
I'd vote to change our default WFS 2.5D point source to that driving function originating from Delft, which is compatible with the recent works of Firtha, i.e. the unified WFS framework.
Our currently used version is -- due to the further approximation -- not easy to handle in terms of

• consistent and proper amplitude normalization
• introducing/defining other referencing schemes

The PR is merge prepared in terms of our latest changes w.r.t. driving function and docstring example handling, but not for literature references.

I would not mind to supply both driving functions with a consistent and proper name scheme. I did not come up with a meaningful idea, though.

[hagenw]

The actual implementation of the equation looks good, I was not able to spot an error.

As I was no longer involved in actual WFS theory for some time now, I totally trust you with the decision that this is the better default driving function ;)

[fs446]

The actual implementation of the equation looks good, I was not able to spot an error.

As I was no longer involved in actual WFS theory for some time now, I totally trust you with the decision that this is the better default driving function ;)

Thanks!
Don't wait for this issue for the next larger release. I'm not sure if/when to handle this within the next days.

[fs446]

I made a new push including a master rebase, so this version is up to date with latest dev.
I've added some more comments on the 3D/2D Rayleigh integral handling to give the reader more hints what's going on. I'd vote to leave the cited literature in the docstring for now to give users/readers the chance for fast access of the change.
I've introduced 'point_25d_legacy' that implements the point_25d of versions <=0.4.0 . This could get another name though. I've thought about something like
def _point_25d_from_3d()
def _point_25d_from_2d() (the legacy)
and having point_25d = _point_25d_from_3d

I also introduced a normalising gain in both the examples (which is open for all other examples as well) to make more clear that legacy is not amplitude correct at ref point, but the new one is.

[fs446]

I've thought about something like
def _point_25d_from_3d()
def _point_25d_from_2d() (the legacy)
and having point_25d = _point_25d_from_3d

I'm not sure how to handle the docstring docu then.

[mgeier]

I like the name point_25d_legacy().

[mgeier]

You should define the "legacy" function after the new function.

[fs446]

IMO it's not about having internet connection or not. It's about the inconsistency providing information of the underlying equation (either as ASCII or LaTex math) within the docstring as useful raw data to be rendered somewhere else, but not doing the same principle for the referencing part. The bibtex entry tag alone does not hold this information, I hope we agree on this. The bibtex entry works fine and it is kind of failsafe within our environment, but if you would ask for following same principles, I'd expect something like providing the DOI, or the bibtex code or plain ASCII within the docstring and a rendering stage within sphinx. I could imagine that parsing a DOI out of docstring and grabbing all information for creating a reference list is something people ask for or even have done. Just an idea for future work. The current framework is very good, but we should always try to improve.

…

On 15. Mar 2019, at 7:10 PM, Matthias Geier ***@***.***> wrote: @mgeier commented on this pull request. In sfs/mono/wfs.py: > @@ -185,6 +191,16 @@ def point_25d(omega, x0, n0, xs, xref=[0, 0, 0], c=None, omalias=None): Notes ----- + `point_25d_legacy` originates from deriving 2.5D WFS from the 2D + Neumann-Rayleigh integral (i.e. the approach by Rabenstein & Spors), cf. + Spors, S.; Rabenstein, R.; Ahrens, J. (2008): The theory of Wave Field + Synthesis revisited. In: Proc. of 124th Audio Eng. Soc. Convention, + Amsterdam, #7358. + Also cf. Eq. (2.145)-(2.147) in https://doi.org/10.18453/rosdok_id00001765 It's true that in the case where you have previously installed the SFS Toolbox with pip and you don't have an internet connection, you will not be able to access the references.bib file (because it's not part of the wheel package). But the DOI doesn't help either, because you don't have an internet connection, remember? If you do have an internet connection, you should really just go to https://sfs-python.readthedocs.io/ and look at the documentation. And if you know that you'll be offline at some point, you can get the PDF docs, which also include the references. Or you can build the HTML docs locally. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or mute the thread.

[mgeier]

but not doing the same principle for the referencing part

Indeed.

We could, instead of using BibTeX, manually add plain Sphinx citations (https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#citations) to the docstrings.

Then your concern would be satisfied.

I just don't think it's worth it.

The bibtex entry tag alone does not hold this information, I hope we agree on this.

We do.

I could imagine that parsing a DOI out of docstring and grabbing all information for creating a reference list is something people ask for or even have done.

I don't know if anyone has asked for it, but I'm quite sure nobody has implemented it.

The current framework is very good, but we should always try to improve.

Sure, there is room for improvement in the current situation.
But I think the BibTeX extension we are using is state-of-the-art, I didn't find any better extensions.

[fs446]

But I think the BibTeX extension we are using is state-of-the-art, I didn't find any better extensions.

Good job on that. I will remind myself from time to time to have a look on this issue. Can be closed for the moment.

[fs446]

thx for your support!!