Add methods to write a field directly to NetCDF

[tomchor]

This PR does a bit of reorganizing but mainly it makes it possible to write a Field directly into a NetCDF file. The motivations are:

• Historically Oceananigans' NetCDF capabilities have been tied to simulations, but that doesn't need to be the case and this is a first step towards something more general
• More practically, it makes it easier for us to support immersed grid reconstruction from NetCDF (something I'll tackle after (0.98.0) Modify interface for OpenBoundaryConditions with schemes and use Tuples in boundary_mass_fluxes #4687 is merged, which supports non-immersed grid reconstruction)
• This feature also allows for fields with different underlying grids, or windowed different, and even fields from two completely different simulations, to live in the same NetCDF file. All that is needed is to pass a different dimension_name_generator for each.

Here's a quick example:

julia> grid = RectilinearGrid(size=(4, 4, 4), extent=(1, 1, 1));

julia> c = CenterField(grid);

julia> ds = NCDataset("test.nc", "c")
Dataset: test.nc
Group: /



julia> defVar(ds, "c", c, attrib=Dict("long_name" => "Center field", "units" => "kg/m³"));

julia> ds
Dataset: test.nc
Group: /

Dimensions
   x_caa = 4
   y_aca = 4
   z_aac = 4

Variables
  x_caa   (4)
    Datatype:    Float64 (Float64)
    Dimensions:  x_caa
    Attributes:
     units                = m
     long_name            = Cell center locations in the x-direction.

  y_aca   (4)
    Datatype:    Float64 (Float64)
    Dimensions:  y_aca
    Attributes:
     units                = m
     long_name            = Cell center locations in the y-direction.

  z_aac   (4)
    Datatype:    Float64 (Float64)
    Dimensions:  z_aac
    Attributes:
     units                = m
     long_name            = Cell center locations in the z-direction.

  c   (4 × 4 × 4)
    Datatype:    Float64 (Float64)
    Dimensions:  x_caa × y_aca × z_aac
    Attributes:
     units                = kg/m³
     long_name            = Center field



julia> c̄ = Average(c, dims=3);

julia> defVar(ds, "c̄", c̄, attrib=Dict("long_name" => "Average center field", "units" => "kg/m²"));

julia> ds
Dataset: test.nc
Group: /

Dimensions
   x_caa = 4
   y_aca = 4
   z_aac = 4

Variables
  x_caa   (4)
    Datatype:    Float64 (Float64)
    Dimensions:  x_caa
    Attributes:
     units                = m
     long_name            = Cell center locations in the x-direction.

  y_aca   (4)
    Datatype:    Float64 (Float64)
    Dimensions:  y_aca
    Attributes:
     units                = m
     long_name            = Cell center locations in the y-direction.

  z_aac   (4)
    Datatype:    Float64 (Float64)
    Dimensions:  z_aac
    Attributes:
     units                = m
     long_name            = Cell center locations in the z-direction.

  c   (4 × 4 × 4)
    Datatype:    Float64 (Float64)
    Dimensions:  x_caa × y_aca × z_aac
    Attributes:
     units                = kg/m³
     long_name            = Center field

  c̄   (4 × 4)
    Datatype:    Float64 (Float64)
    Dimensions:  x_caa × y_aca
    Attributes:
     units                = kg/m²
     long_name            = Average center field

For now I decided to extend the existing defVar in order to avoid creating new functions, but we can definitely also create a new function specifically for that (to_netcdf(field::AbstractField)?).

[glwagner]

Excited for this!

[Copilot]

Pull Request Overview

This PR adds the capability to write Oceananigans Field objects directly to NetCDF files by extending the defVar function. This decouples NetCDF writing from simulation contexts and enables writing fields from different grids to the same file.

Key changes:

• Extended defVar to handle AbstractField, AbstractOperation, and Reduction objects
• Moved dimension name generation utilities from extension to main module
• Added validation and creation of field dimensions in NetCDF datasets

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
src/OutputWriters/netcdf_writer.jl	Moved dimension name generation functions from extension module to main module
ext/OceananigansNCDatasetsExt.jl	Extended defVar for fields and added dimension validation/creation functions
test/test_netcdf_writer.jl	Added comprehensive tests for single field writing, dimension validation, and multiple grid support

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[tomchor]

Not sure what's going on with the distributed tests, but this should be ready to review/merge. @navidcy @glwagner can I get a review when you get the chance?

[ali-ramadhan]

Looks good to me! I think the PR could just do with some more testing:

1. I would run the newly added tests on both CPU and GPU, especially to ensure no scalar indexing occurs.
2. I would also run the newly added tests on LatitudeLongitudeGrid and immersed grids (both immersed rectilinear and immersed lat-lon).

This feature also allows for fields with different underlying grids, or windowed different, and even fields from two completely different simulations, to live in the same NetCDF file. All that is needed is to pass a different dimension_name_generator for each.

That's awesome! Just to confirm: for a user to utilize this feature, I assume it's the job of each dimension_name_generator to generate unique dimension names? Actually reading through the tests has answered my question (yes)!

[tomchor]

Looks good to me! I think the PR could just do with some more testing:

1. I would run the newly added tests on both CPU and GPU, especially to ensure no scalar indexing occurs.

2. I would also run the newly added tests on `LatitudeLongitudeGrid` and immersed grids (both immersed rectilinear and immersed lat-lon).

Good points! I actually was supposed to add GPU from the start (since those tests are on an archs loop) but I forgot, so thanks for catching that.

This feature also allows for fields with different underlying grids, or windowed different, and even fields from two completely different simulations, to live in the same NetCDF file. All that is needed is to pass a different dimension_name_generator for each.

That's awesome! Just to confirm: for a user to utilize this feature, I assume it's the job of each dimension_name_generator to generate unique dimension names? Actually reading through the tests has answered my question (yes)!

Yeah, I think this is a limitation of NetCDF unfortunately. Variables that use the same dimension name must have the same shape. So different shapes require different dimension names :(

[giordano]

What was this line supposed to do? It's defining a function which returns a function, I doubt this is what you meant. Also, this is untested: https://app.codecov.io/gh/CliMA/Oceananigans.jl/blob/main/src%2FOutputWriters%2Fnetcdf_writer.jl#L47