Roadmap to version 1.0

[ali-ramadhan]

Kinda feels like we're getting closer to a version 1.0 release, although I don't think we need to put a time frame on it. Is it worth discussing which major development milestones we think should be part of v1.0?

Since we're following SemVer I guess it's not really about which features we want to see in v1.0 but more about whether we think the user interface will be relatively stable. New features could be introduced in v1.1, v1.2, etc. but if we make any breaking changes we'll have to release v2.0.

Maybe it's still useful to list some major milestones as they're quite likely to introduce breaking changes?

I'll start with the three big ones on my mind:

• Pressure solvers for all topologies and grids (Poisson solvers for all types of domains (triply/doubly periodic, channels, boxes) and grids (regular, stretched) #586)
• MPI distributed parallelism (MPI distributed parallelism #590) [not necessarily super optimized, just something that works okay]
• Vertically stretched grid (Strategy for implementing and testing models with vertically stretched grids #471)
• Abstraction for vectors. It's only for simple grids that we can really get away with referring to the velocity field component wise with u, v, w.
• Specifying architecture when building grid (Should we store architecture in grid? #1825).
• Simplify grids. We really only need one RectilinearGrid, one LatitudeLongitudeGrid, and one "arbitrary" (not aligned with a coordinate system, like what's used for the cubed sphere)
• Finalize spherical implementations
• Finalize bathymetry

Would be great to hear what people think and if anyone has any thoughts on v1.0.

Might also be good to include @whitleyv's immersed boundary implementation and @francispoulin's shallow water model since both might bring some breaking changes as well.

PS: Stuff added on 2021-07-23.

[navidcy]

pressure solver for all topologies -> definitely
MPI -> yeah, I think that's needed also
vertically stretched grid -> good feature but not a deal breaker for v1.0 in my opinion

[francispoulin]

I agree with @navidcy on all counts. Will add that I hope to have Shallow water model together by early next week. Not needed for 1.0 but I am happy to get it done before 1.0, if possible.

[ali-ramadhan]

Ah I don't see us tagging v1.0 for at least a few, probably even several, months so early next week is way ahead of v1.0 haha.

[glwagner]

I'd vote for resolving #1138 and #963 before releasing a 1.0, and also some usability issues like #890 .

#1175 is also breaking.

Something to consider: vertically-stretched grids may require specifying the architecture in grid, rather than model... ? This would be a substantial change to the API. So one motivation for requiring a vertically stretched grid implementation for 1.0 would be so that we don't have to "anticipate" breaking changes that the stretched grid requires.

I'm slightly concerned about boundary conditions too (in principle, we should be able to coalesce TracerBoundaryConditions, UVelocityBoundaryConditions into a single FieldBoundaryConditions specifier). But because it's not super high priority we haven't found time to attend to that and maybe it doesn't matter for 1.0.

[navidcy]

#1168 is resolved! no?

[glwagner]

Ahh I meant #1138. Ha!

[navidcy]

ok, makes much more sense :)

[tomchor]

I just thought I'd drop by with my point of view as user and (for now) not a developer. Talking with other people who have tried Oceananigans, the most important thing from our point of view may be the MPI parallelism. I know there is some debate to be had in this topic (I've had a couple discussions with @glwagner myself), but for now my understanding is that it's much easier to have access to CPUs then GPUs. Also if I understand correctly that would allow the model to be run on multiple GPUs, which will allow for some really big simulations resolving a huge array of scales. I bet there's new physics to be found there among the nonlinear interactions between all these scales!

From my point of view (now without talking to other users) #1241 seems like a pretty big issue. It's hard to use Oceananigans if you're not sure you're going to be able to calculate the statistics you need to do your science straightforwardly. For what I want right now it seems like I can use LESbrary.jl, but that might not always be the case. I'd definitely put that in the list of issues to be resolved asap.

From a user perspective I think #890 is also important. I've suffered the consequences of lack of attention to BCs already and it'd be nice to have the model check those for me.

I also think #471 would be nice to have. I agree with @navidcy that it's not a deal breaker, but it would save computation and (if I understand correctly) all the hard work for that has been done already, no?

Anyway, I'm still learning about Oceananigans and might be kind of naive in relation to some of the model's particularities. So please that fact into consideration when assessing my suggestions!

Cheers

[glwagner]

It's hard to use Oceananigans if you're not sure you're going to be able to calculate the statistics you need to do your science straightforwardly. For what I want right now it seems like I can use LESbrary.jl, but that might not always be the case.

If we did not have AbstractOperations at all, then isn't Oceananigans still better off than existing codes? I'd argue that even without AbstractOperations, users are still in decent shape for complicated diagnostics compared to other codes, since they can write their diagnostics code in julia (rather than some other language...)

But perhaps I'm missing something? What special diagnostics features are available in other LES codes? Why is writing a kernel using julia code less straightforward than what you'd have to do in another code?

[glwagner]

I guess I agree that it'd be really nice to solve #1241... I've beat my head against the wall for quite a while on that problem.

One solution is to invest more effort in trying to resolve it. Another possibility is to make the "backup plan" a bit easier (developing custom fields for complicated output). Since it's unlikely AbstractOperations will meet all of users diagnostics needs (considering the possibilty of weird / computationally intensive diagnostics...) I think this is a worthwhile investment anyways, even if we can make AbstractOperations more powerful.

@tomchor perhaps including some examples about how to develop custom diagnostics kernels in your own scripts will be useful, so that you don't feel like you are out of luck unless you have something like the LESbrary? What do you think?

[glwagner]

#1245 might need to be addressed too, since its solution might lead to breaking changes.

[tomchor]

Basically, from the docs, I thought the only way to calculate statistics with Oceananigans was to use abstract operations. I have recently found that you can also write kernels, so I guess my comment on that part is invalid.

[tomchor]

All the checkboxes are ticked for this issue. Should we close it? Maybe create another one for v1.0 since apparently there are many more things until v1.0?

[navidcy]

Or modify it to add more checkboxes to be checked in when ready?

[tomchor]

Added it to the main post.

Also, just my personal opinion: I think it would be great to have all those features/modifications ready, but I think there's also a big advantage in having a v1.0 relatively soon. The code is mature enough to write scientific papers with at this point (IMO), but not having a v1.0 might give out a impression that the code is "half-baked" or something, making some people reluctant accept it as a "serious code".

v1.0 isn't gonna be the last version we ever release, so I think it's okay to release a v1 with a subset of these features and push the other items to a v2.0 that might come out afterwards.

[glwagner]

The code is mature enough to write scientific papers with at this point (IMO)

👀

but not having a v1.0 might give out a impression that the code is "half-baked" or something, making some people reluctant accept it as a "serious code".

I don't agree with this statement. Many extant codes don't use versioning at all. I would argue that people who make those judgements aren't "serious people", and it's their problem, not ours.

I think the purpose of versioning is to communicate to users and developers about bug fixes and API changes, and we should stick to that when motivating our decisions.

[glwagner]

v1.0 isn't gonna be the last version we ever release, so I think it's okay to release a v1 with a subset of these features and push the other items to a v2.0 that might come out afterwards.

I agree with this in general. But the API is changing week by week, and not just small changes either. I think we are designing a really complex system without a good guide to take from.

[tomchor]

I think the purpose of versioning is to communicate to users and developers about bug fixes and API changes, and we should stick to that when motivating our decisions.

I pretty much agree with @glwagner, and I'm not arguing against that. Just to be clear, I never said not to follow SemVer. I'm also not advocating to release v1.0 now. I'm just saying I see a reason to tag v1 before all the items in the wishlist are done.

[ali-ramadhan]

I feel like this issue has become stale and should maybe be closed?

At least when this issue was first opened we thought (at least I thought) v1.0 would only include one model on one grid so it was easy to come up with a short checklist/roadmap to v1.0.

But now with more models and grids (a great thing!) the API will probably be unstable for a long time (not a bad thing) so a v1.0 may not be close enough for a short checklist?

If people are interested in maintaining a roadmap we could go the long checklist route as @navidcy suggests: JuliaData/DataFrames.jl#1678 and FluxML/Flux.jl#1431 might be inspirations.

I for one wouldn't mind seeing v0.100.

[glwagner]

This discussion is stale; we aren't ready for 1.0, so we'll have to start the discussion again when we're ready.