Introduce AbstractLocation hierarchy and replace Nothing with Reduced

[glwagner]

Summary

Introduces abstract type AbstractLocation with Center, Face, and a new singleton Reduced, and constrains the type parameters of AbstractField{LX, LY, LZ, ...} so that location parameters must subtype AbstractLocation. Reduced and Flat dimensions, which previously used Nothing as a location, now use Reduced.

Fixes the AbstractOperations type piracy flagged in #5601:

• Every operator signature in AbstractOperations (+, -, *, /, ^, <, >, <=, >=, atan, atand, mod, plus the unary forms) now dispatches on Oceananigans-owned types (LocationTuple, LocationTypeTuple) instead of bare Base.Tuples.
• After this change *((Nothing, Nothing, Nothing), nothing, nothing) correctly throws MethodError even after using Oceananigans — see the regression added to test_quality_assurance.jl.
• AbstractOperations is removed from the pirate_modules = (...) skip list in the Aqua test, and Aqua.test_piracies(Oceananigans.AbstractOperations) now passes.

Naming

We picked Reduced because it cohabits cleanly with existing vocabulary in the codebase: ReducedField, XReducedField, reduced_dimensions(::AbstractField), etc. Alternatives we considered:

• Reduced (chosen) — matches existing aliases, no rename cascade, semantically clear in the reduction context. Honest critique: names the state of the dimension (past-tense) rather than a position on the cell the way Center and Face do. It also has to cover both "a dim that got averaged/integrated out" and "a Flat-topology dim that was never there." Semantically these are one concept (no spatial coordinate in this slot), but the name leans toward the reduction story.
• Collapsed — similarly state-describing, and less tightly tied to existing terms.
• Singleton — describes the size-1 array dimension neutrally on cause. Less tied to existing API.
• Nil — short and "nothing-like", but cryptic.

Happy to revisit if any of those land better with reviewers.

Breaking

This breaks any downstream code that writes Field{Nothing, ...} (or AbstractField{Nothing, ...}, or matches (Nothing, Center, Center) location tuples in dispatch). All such sites in src/, test/, and ext/ are updated. The Julia pre-1.0 convention puts breaking changes in the minor version, so this bumps 0.108.0 → 0.109.0.

What changed

• src/Grids/Grids.jl — new AbstractLocation, Reduced, LocationTuple, LocationTypeTuple; Center and Face retroactively made subtypes; types exported from Oceananigans.
• src/Fields/abstract_field.jl — AbstractField{LX, LY, LZ, G, T, N} now requires LX/LY/LZ <: AbstractLocation.
• src/Fields/field.jl, src/Fields/abstract_field.jl — the XReducedField, XReducedAF, ReducedField and related aliases now use Reduced instead of Nothing.
• src/Fields/show_fields.jl — location_str(::Type{Reduced}) = "⋅".
• src/AbstractOperations/{unary,binary,multiary}_operations.jl — operator codegen retyped; choose_location(::Reduced, ...) etc. AbstractOperations.Location = AbstractLocation.
• src/Grids/{grid_utils,nodes_and_spacings,vertical_discretization,new_data,input_validation}.jl — all ::Nothing dispatches that take a location switched to ::Reduced.
• src/Fields/{scans,interpolate}.jl — same; reduced_location now returns Reduced/Reduced(); filter_nothing_dims renamed to filter_reduced_dims with predicate loc[d] isa Reduced.
• src/BoundaryConditions/{field_boundary_conditions,fill_halo_kernels}.jl — default_prognostic_bc(...) etc. retyped; halo bookkeeping uses Reduced.
• src/Models/{boundary_mean,boundary_condition_operation,NonhydrostaticModels/nonhydrostatic_model,HydrostaticFreeSurfaceModels/SplitExplicitFreeSurfaces/split_explicit_free_surface}.jl, src/ImmersedBoundaries/{grid_fitted_bottom,partial_cell_bottom,active_cells_map,immersed_reductions,mask_immersed_field}.jl, src/MultiRegion/cubed_sphere_grid.jl, src/StokesDrifts.jl, src/DistributedComputations/distributed_immersed_boundaries.jl, src/OutputReaders/field_time_series_indexing.jl, src/TurbulenceClosures/.../catke_vertical_diffusivity.jl — Field{..., Nothing} / (..., Nothing) literals replaced with Reduced (the Nothing-as-grid slot is preserved everywhere).
• ext/OceananigansReactantExt/Grids/Grids.jl — reactant_offset_indices(::Reduced, ...).
• ext/OceananigansNCDatasetsExt/utils.jl — docstring example updated.
• test/ — all Field{Nothing, ...} / FieldTimeSeries{Nothing, ...} / (Nothing, ..., ...) test fixtures updated to Reduced.
• test/test_quality_assurance.jl — AbstractOperations removed from the broken-piracy skip list; new regression @test_throws MethodError *((Nothing, Nothing, Nothing), nothing, nothing).
• Project.toml — version = "0.109.0".

Test plan

• CI passes on CPU
• CI passes on GPU
• Aqua piracy test passes on Oceananigans.AbstractOperations
• Downstream packages (ClimaOcean, NumericalEarth, Breeze) build against this branch — at minimum, identify the Field{Nothing, ...} literals that need updating downstream
• Smoke test locally: using Oceananigans; Average/Integral; Field{Center, Center, Reduced}; arithmetic on reduced fields — all green

🤖 Generated with Claude Code

[giordano]

I see LLMs don't understand Julia's type system. This tuple doesn't make sense.

julia> typeof((Reduced, Reduced, Reduced))
Tuple{DataType, DataType, DataType}

there's no way that's matched by LocationTypeTuple

[glwagner]

ahah no that is me not understanding it

[glwagner]

ok no I asked for LocationTuple but not the "type tuple". ummm

[giordano]

ahah no that is me not understanding it

I tried hard to make ChatGPT reason about it, and it always gave me falsities like the following will be true

julia> (Reduced,) isa Tuple{Type{Reduced}}
false

do we need <:Type{<:AbstractLocation} is that right?

No, any of this can't possibly work, because the type in the type parameter will always have type DataType, so you can't really dispatch on something related to AbstractLocation.

[glwagner]

LLMs don't understand anything at all btw -- not just Julia's type system. "Understanding" is not the point of an LLM

[giordano]

Replacing Nothing with Reduced is definitely a move in the right direction, but this tuple-based method (together with all the similar ones below) is still problematic: as mentioned above, using a tuple here is flawed (and LocationTypeTuple in particular is useless), because tuples are special

[glwagner]

we can instantiate the locations upon input, before they arrive in this function

[giordano]

LocationTypeTuple = Tuple is not right because this is still type piracy (the test checking for type piracies in AbstractOperators will fail), but I want to see what else breaks besides the type piracy

[glwagner]

can I remove LocationTypeTuple or are you still testing?

[giordano]

The non-distributed tests on Buildkite haven't started yet, I was hoping to see what still fails.

Of the tests in GitHub Actions, most of them are now passing, but I'm confused by https://github.com/CliMA/Oceananigans.jl/actions/runs/26230990735/job/77191416849?pr=5614#step:6:570

Distributed output combining - RectilinearGrid (2x2): Error During Test at /home/runner/work/Oceananigans.jl/Oceananigans.jl/test/test_distributed_output_combining.jl:331
  Got exception outside of a @test
  BoundsError: attempt to access 10×10×1 Array{Float32, 3} at index [4:7, 4:7, 4:7]
  Stacktrace:
    [1] throw_boundserror(A::Array{Float32, 3}, I::Tuple{UnitRange{Int64}, UnitRange{Int64}, UnitRange{Int64}})
      @ Base ./essentials.jl:15
    [2] checkbounds
      @ ./abstractarray.jl:699 [inlined]
    [3] view(::Array{Float32, 3}, ::UnitRange{Int64}, ::UnitRange{Int64}, ::UnitRange{Int64})
      @ Base ./subarray.jl:214
    [4] load_combined_field_data!(field::Field{Center, Center, Reduced, Nothing, RectilinearGrid{Float64, Periodic, Periodic, Bounded, Oceananigans.Grids.StaticVerticalDiscretization{OffsetVector{Float64, StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}}, OffsetVector{Float64, StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}}, Float64, Float64}, Float64, Float64, OffsetVector{Float64, StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}}, OffsetVector{Float64, StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}}, CPU}, Tuple{Colon, Colon, Colon}, OffsetArray{Float64, 3, SubArray{Float64, 3, Array{Float64, 4}, Tuple{Base.Slice{Base.OneTo{Int64}}, Base.Slice{Base.OneTo{Int64}}, Base.Slice{Base.OneTo{Int64}}, Int64}, true}}, Float64, Nothing, Oceananigans.Fields.FixedTime{Float64}, Nothing}, all_ranks::Vector{Oceananigans.OutputReaders.RankOutputData{RectilinearGrid{Float64, FullyConnected, FullyConnected, Bounded, Oceananigans.Grids.StaticVerticalDiscretization{OffsetVector{Float64, StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}}, OffsetVector{Float64, StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}}, Float64, Float64}, Float64, Float64, OffsetVector{Float64, StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}}, OffsetVector{Float64, StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}}, Distributed{CPU, false, Partition{Int64, Int64, Nothing}, Tuple{Int64, Int64, Int64}, Int64, Tuple{Int64, Int64, Int64}, Oceananigans.DistributedComputations.NeighboringRanks{Int64, Int64, Int64, Int64, Int64, Int64, Int64, Int64}, MPI.Comm, Vector{MPI.Request}, Base.RefValue{Int64}, Nothing}}, Tuple{Int64, Int64, Int64}}}, name::String, iter::Int64; reader_kw::@NamedTuple{})
      @ Oceananigans.OutputReaders ~/work/Oceananigans.jl/Oceananigans.jl/src/OutputReaders/combining_field_time_series.jl:452
  [...]

[glwagner]

let me know when you're ready for more commits here

[giordano]

Feel free to push now, thanks for waiting

[glwagner]

I think I can fix this as well. Since we require the types (not Type{location}) we have to instantiate at all entry points. Doing so in broadcasting fixes this error

[glwagner]

possibly fixed by this: 9ea6d96

[glwagner]

@navidcy @simone-silvestri this PR is going to cause a nuclear explosion throughout the ecosystem.

We need to be absolutely sure that "Reduced" is the name we want here.

There is some illogic in it, because it is not actually a location at all. Instead it refers to (supposed) the operation that produced the data.

"Nothing" was actually a good name, because it is more explicitly true. Another one could be "All" ... I think it's worth discussing before merging this PR hastily

[simone-silvestri]

What about NoLocation or Absent to return to the Nothing idea?

[glwagner]

What about NoLocation or Absent to return to the Nothing idea?

Those do seem better.

One crucial property of this location is that it implies that the "nothing" location is extruded for operations. In other words, if we form Uc = U * c where U is averaged in the vertical, the result Uc is a 3D field in which each c[i, j, k] is multiplied by the column-average value of U[i, j, 1].

This concept could be captured by All (this also corresponds to the "a" that we use in notation). But it's also not so intuitive to me.

Claude also suggested Nil which is more compact (this is nice bc we have to write Field{Center, Center, NoLocation})

[glwagner]

More thoughts:

• All is nice for @at -- for example, new_op = @at (Center, Center, All) old_op. This will move/interpolate horizontal locations to Center, but keep the vertical location untouched (will get default).

• Uniform is another idea --- for example Field{Center, Center, Uniform}(grid) implies the Field is uniform in the vertical. Constant is similar to Uniform.

• Singleton might work. This is connected to broadcasting semantics ("singleton" dimensions are extruded in broadcasting). Field{Center, Center, Singleton}(grid) is interpretable I think.

• Absent, trying to parse if Field{Center, Center, Absent}(grid) is intuitive

[glwagner]

Math / set-theory family

• Singular — "singular dimension" is established applied-math vocabulary for length-1. Reads cleanly: Field{Center, Center, Singular}.
  Pro: physics/math native. Con: also means "weird/anomalous" colloquially, mild ambiguity.
• Unit — math-native "unit set" / "unit length". Short (4 chars). Field{Center, Center, Unit}. Con: collides with Unitful.jl-style
  unit-of-measure intuition.
• Atom / Atomic — set-theory "atom" = singleton element. Short and evocative. Field{Center, Center, Atomic}. Vibe: physics-ish,
  indivisible.

Geometric family

• Point — "this dim collapses to a point." Short, evocative. Field{Center, Center, Point} reads as "x and y vary; z is a point." Slight
  collision with point-coordinate intuition though.

English "just one" family

• Single — direct. Field{Center, Center, Single}. Reads naturally; faint MtG / Java-singleton echoes.
• Sole — "sole z value." Slightly archaic.
• Solo — Field{Center, Center, Solo}. Charming but too informal.
• Solitary — accurate, long, melodramatic.
• Lone — poetic.
• Standalone — too programmer-y.

Greek/Latin roots

• Mono — Greek "one." Compact (4 chars). Field{Center, Center, Mono}. Technical-sounding without being heavy; slight
  foreign-prefix-without-a-suffix awkwardness ("mono-what?").
• Uni — Latin "one." Field{Center, Center, Uni}. Even shorter. Same incomplete-prefix feel.

Programming / API ecosystem

• Singleton (the original)
• Squeezed — past tense of NumPy/Torch squeeze. State-describing like Reduced.

[simone-silvestri]

Singleton is nice but maybe a bit verbose? All is also nice and short and connects well with the idea of Reduced

[ewquon]

Maybe I'm missing the point, but what about NA (not applicable)?

[glwagner]

Maybe I'm missing the point, but what about NA (not applicable)?

acronym ❌

more seriously, I don't think it is interpretable, Field{Center, Center, NA} -- what's "NA"?

But None could work. That is not taken, is it?

[ewquon]

Interesting that both All and None are on the table 🤯

None would be a very small shift away from "Nothing" and has compactness going for it -- I'm unopposed.

[glwagner]

Interesting that both All and None are on the table 🤯

None would be a very small shift away from "Nothing" and has compactness going for it -- I'm unopposed.

Indeed, this is a philosophical question. Does the field have "all" locations (this is how it is treated in broadcasting) or does it have "no location" (which implies that it must be broadcasted with all locations of a 3D field)

[tomchor]

I'm kinda late to the discussion so forgive me if I'm missing something, but does it make sense to lump together the location for a Field in a Flat dimension with the location of a Field in a non-Flat dimension that was reduced?

To me it makes sense that a Field has location==nothing in a dimension that is Flat since there was never any reasonable location to begin with. But that is different (at least conceptually to me) from a Field dimension that had a well-defined location that then was reduced. But maybe that doesn't matter numerically? Anyway I just wanted to ask.

[glwagner]

@tomchor I'm not entirely sure how to achieve your suggestion. For example what should Field{Center, Center, Center}(grid) do if grid is Flat in the 3rd direction? Convert the 3rd location under the hood, or perhaps error?

We have strived to always return the type asked for by the user (eg if you read a type from a constructor, it unambiguously tells you the type of the object that is constructed). I don't think we can preserve this convention without taking the erroring approach. But on the other hand, I worry that throwing such an error is inconvenient. It might require a lot of special casing, especially in downstream packages.

This is actually the benefit of distinguishing between the grid topology and the field location, I think. It allows us to write more general code more easily.

[tomchor]

This is actually the benefit of distinguishing between the grid topology and the field location, I think. It allows us to write more general code more easily.

Hmm, I see your point. Thanks for clarifying!

[glwagner]

This is actually the benefit of distinguishing between the grid topology and the field location, I think. It allows us to write more general code more easily.

Hmm, I see your point. Thanks for clarifying!

In part this lesson was learned when we switched the set! / function interface so that the coordinate match the dimensionality of the field. Ie you need to write set!(vertically_reduced, (x, y) -> x + y). This results in scripts that I think are easier to read. BUT it also makes it more difficult to prototype code on a 2D grid, and then switch the grid to 3D. I am actually still not sure the readability benefit is worth the productivity cost 🥲