Are we ready to release a 1.0 at long last?

[glwagner]

I'm opening this issue to discuss the possibility of releasing a version 1.0. @giordano thinks it is about time.

For myself, the major API issue that remains is the fact that grid is a keyword argument for NonhydrostaticModel and HydrostaticFreeSurfaceModel. I would like this to be a positional argument. But if others feel strongly, we can leave it.

Are there any other major lingering API issues we should sort out before releasing a 1.0?

There is also #3793, but that is not a breaking change. So it does not have to be part of 1.0.

[glwagner]

I think another big change we had discussed was to eliminate mathematical symbols from the API. For example, using

ScalarDiffusivity(viscosity=1, diffusivity=2)

rather than

ScalarDiffusivity(ν=1, κ=2)

I thought this might be a good idea at one point, but then when considering the full scope of changes required, plus the difficulty of even coming up with names everything (eg what do we call f₀ for BetaPlane?) I sort of gave up. I'd be ok with leaving this for 2.0 😂

A separate issue is eliminating mandatory unicode from the API, eg Simulation.dt instead of Simulation.Δt and BetaPlane.f0 instead of BetaPlane.f₀, perhaps. I think I would prefer to keep the unicode but am open to discussing it. We can also just provide alternative constructors for unicode parameters. But thats messy.

[giordano]

I'm perhaps a bit radical here, but I don't personally give much significance to v1.0 anymore. Software will never be "ready", for some definition of "readiness", it'll keep evolving anyway. My suggestion was mostly practical: after going to v1.0 you'll have more versioning space to distinguish breaking changes vs new features vs bug fixes, with only two numbers available they become compressed. If there'll be the occasion to do a v2.0 shortly after v1.0, that's not a big deal in my view, you've had 100 breaking changes so far, I don't think it's bad for a package like Oceananigans to have several major versions.

[glwagner]

I think that with a 1.0 we should commit to lumping our breaking changes, versus the "release immediately" philosophy that we used in the past which lead to 100 breaking changes. I think it is a good thing. There are a few packages, and growing, which depend on Oceananigans, and the development of those packages might benefit from fewer breaking changes.

[navidcy]

related: https://github.com/CliMA/Oceananigans.jl/issues/1234 with some recent posts

[navidcy]

I like this idea.

Perhaps a side-track, but I've been long thinking in the back of my mind whether it'd be good to split Oceananigans into two packages, one for the finite-volume calculus, abstractions, fields, operations, etc and one other for the ocean-dynamics models, closures.

But that sounds like a lot of work... Perhaps won't give us much. Will also add to the burden of ensuring packages depend on particular versions of other packages?

[glwagner]

It is on paper a good idea to split up Oceananigans into two packages. The question is whether the ocean-model-specific elements are really all that heavyweight. If they are not, we don't gain much and it will be a lot of work. cc @bgroenks96

I think this is independent of 1.0 issues though or rather probably a longer term consideration.

[simone-silvestri]

Maybe we could lay out the goals we need to achieve to get to version 1 and work toward them. As for me, I would really like to have a consolidated benchmarking infrastructure, and personally also a well-refactored hydrostatic model #4811, then I feel like we can launch version 1.0

[simone-silvestri]

Also, I would probably add #4590 to the list of PRs which should make it in main before a version 1.0

[bgroenks96]

I don't feel that strongly about splitting up the package. It would be nice, in principle, but not essential... I guess the main argument in favor of it would be to have a nice, re-usable, and extensible FVM and numerical modeling toolkit that could see more widespread use.

There is also a nonzero chance that some of the ocean-model components might be relevant in downstream projects like Terrarium (e.g. in ocean shelf or lake modeling), so we might anyway keep the Oceananigans dependency.

[glwagner]

I don't feel that strongly about splitting up the package. It would be nice, in principle, but not essential... I guess the main argument in favor of it would be to have a nice, re-usable, and extensible FVM and numerical modeling toolkit that could see more widespread use.

There is also a nonzero chance that some of the ocean-model components might be relevant in downstream projects like Terrarium (e.g. in ocean shelf or lake modeling), so we might anyway keep the Oceananigans dependency.

Thanks @bgroenks96 . I basically agree, there are clear benefits to a split, but not a lot of immediate short-term gain. With stable long-term funding for all of this work, we should pursue it.

[milankl]

Splitting a package into several packages in one monorepo was a non-breaking change for SpeedyWeather, so you can do that anytime. It just registers modules in subfolders. We can recommend a monorepo in your case too. It's a little trickier to get your head around how Pkg.jl and the registering is meant to be done but then you end up in the nice situation that Oceananigans version N ships with main of all its subpackages which can occasionally get a new release for other packages that don't want to depend on everything. You then just have to check whether a new release of, say, OceananigansGrids.jl is breaking or not.

For myself, the major API issue that remains is the fact that grid is a keyword argument for NonhydrostaticModel and HydrostaticFreeSurfaceModel. I would like this to be a positional argument. But if others feel strongly, we can leave it.

In SpeedyWeather we allow both: PrimitiveWetModel(spectral_grid, ...) as well as PrimitiveWetModel(; spectral_grid, ...) the latter is the underlying interface and then we added

# also allow spectral grid to be passed on as first and only positional argument to model constructors
(M::Type{<:AbstractModel})(SG::SpectralGrid; kwargs...) = M(; spectral_grid=SG, kwargs...)

[milankl]

I think another big change we had discussed was to eliminate mathematical symbols from the API. ... I sort of gave up

I was at that point too. Decided to have fields named as close to how we say it when creating, as you give an example

ScalarDiffusivity(viscosity=1, diffusivity=2)

but then do internally

function foo(..., closure, ...)
    ν = clousure.viscosity
    κ = clousure.diffusivity
    ...
end

that way there's less ambiguity in the user-facing "what options does ScalarDiffusivity have?" but you can still write math inside functions/kernels by unpacking which then also nicely reads like "let ν be the viscosity ..."

[glwagner]

@milankl I think that is a nice approach for sure. It'd be a huge change to the API, eg

BetaPlane(reference_coriolis_parameter=1e-4, planetary_vorticity_gradient=1e-11)

We use mathematical symbols in a LOT of places. So if we decide to go this route, we've gotta dive in head first, its a leap!