ambition, reference paper, user base, external contribution, roadmap, and other ...

[apatlpo]

Food for thoughts ...

I am under the impression this library could become a landmark tool for underwater acoustic modeling.
Is it the ambition you had @mchitre ?

If this is the case, there are a couple of points that would deserve an attention at least equal to that dedicated to adding new functionalities:

• a reference paper describing the library, maybe the physics behind the RaySolver would be welcome. It will increase visibility, reinsure potential users and ultimately help grow the user and contributer base, which leads to the next point:

• the issue tracker shows a growing list of actions to be performed and it is likely as the user base grows that it will only grow faster. My opinion is that it could become very critical that you get help on pushing the library forward @mchitre. This leads to the next two points:

• the first item to address in order to enable external contribution is to add a Contributing Guide section. I am a big user of xarray and their Contributing Guide is quite an impressive example. What is going to be key here however is that you may have to guide non-native julia users (like me) and dedicated information will be needed.

• the second item deals with coverage which looks pretty low at the moment. This may become a problem with external contributions.

• Finally, it would be useful to provide in the documentation a roadmap for the library. This would help new users to see in what direction the library is going, where contributions would be welcome, ...

what do you think?

[mchitre]

All great points.

I started this library because I felt excited by the potential of what Julia could bring to the table for the underwater acoustics world. There's no reason to not put out what I develop for my own (and my collaborators' and students') use, and if others find that useful, then to develop it further. I feel motivated to work on it beyond my own use cases if others find it useful too, and ask for fixes and features. I find it even more motivating if others contribute too, and collaborate. So, yes, I do hope to be able to develop this library into the go to scientific tool for underwater acoustics -- and the current version is an experiment to see if there's enough interest around to warrant the effort.

Specific answers/thoughts:

1. RaySolver paper is in the works. I should find time to finish it in the next few months hopefully.
2. Absolutely agree. We'll need more than just me to be contributing code, if we're to make this a landmark tool.
3. I'll take a look at the contributing guide you point to, and study a few others, and maybe try to draft something as a starting point.
4. Coverage, as in regression test coverage? That's on the cards for improving as we grow the library, although coverage alone is often a poor metric. But I take your point on this, and agree it needs fixing.
5. Roadmap is an excellent idea. There's much that I have in mind, and if we are to align directions, that does need to be articulated so that others may help refine and expand. I will take a stab at a first draft in the next few weeks once I get some time to think through.

Thanks for getting this conversation started. I'd love to hear your (and others') thoughts on this. This includes potential use cases, ideas, thoughts, questions, directions, ...

[apatlpo]

I think you have already answered quite a bit already @mchitre

I did mean regression test coverage indeed.

My first concern is to convince my collaborators to use UnderwaterAcoustics.jl in a project focused on underwater positioning of freely drifting underwater platforms. Preliminary results indicate sound speed uncertainty & variability will be the leading error source. We will work typically with ocean circulation numerical simulation outputs in order to design appropriate algorithms to mitigate such uncertainty.
Please remember my area of expertise is physical oceanography and that it's difficult for me to tell you precisely what test cases would be most relevant to convince typically my collaborators.
Range dependence is going to be essential and it seems that we will have to rely on RaySolver.
I would thus say that having a test case relevant to underwater positioning, in a range dependent environment, and, comparing RaySolver with Bellhop would help making a case for the use of UnderwaterAcoustics.jl

Here are a couple of thoughts that may be useful (apologizes if material already exists):

• IO: my impression is that it could be quickly useful to have an IO capability in order to load environments and model configurations and store simulations outputs.
  One may have to conduct postprocessing with external codes, potentially not julia based.
  I would advocate for a standard and widely used file format like netcdf.

• Distributed computing for larger problems. I understand it may be broad issue.

• Showcasing UnderwaterAcoustics.jl as an pluggable entry point to multiple underwater acoustic models seems to me like a very powerful and interesting idea.
  Providing guidance about how to plug models will ultimately be needed if you want external collaborators to be able to do so.

I hope this useful

[apatlpo]

@mchitre , I am trying to planning ahead (months time scales) and it would be very useful if the library had the contributing guide mentioned above, let's say by September. Would that be feasible for you?

It's probable I may give a try implementing some IO then.
While I could do it aside the library, it would conter-productive and I' rather propose directly a PR instead about this.

[mchitre]

Yes, we can get guidelines for contribution in place in August.

And even before we do that... contributions are most welcome. It would be good to raise an issue to discuss the planned contribution first, so we can discuss it and ensure that it'll fit in well with the library without too much surgery. And then a PR once you've some form of an implementation, so that we can refine it and merge.

[mchitre]

@apatlpo I've gotten a basic draft of contribution guidelines done. Comments/suggestions most welcome.

[apatlpo]

I like very much this contribution guideline and have not much to say at first glance.
This may change once I give contribution a try.
In any case, well done !

[mchitre]

The code coverage is actually not bad... about 90%, excluding plot.jl and pm_bellhop.jl:

The problem is that plotting routines are hard to meaningfully run CI on.

Bellhop requires a working copy of the FORTRAN code in the CI build server, and without that, currently we don't run those tests in CI (we do run them locally if Bellhop is installed). While this should be fixable, the right way to do this is to build a binary of Bellhop for the all architectures (perhaps via BinaryBuilder.jl), and then use it for CI, and so might take some effort to get right.

So, as long as the contributions aren't in Bellhop/plotting code, I don't think current coverage is a barrier to contributions.