Is your feature request related to a problem?

Complex numbers are not natively handled by netCDF, and currently only the h5netcdf engine in xarray can handle them. However, it produces files unreadable by current versions of netCDF. There are also many different conventions, and h5netcdf can only read a few of them.

Describe the solution you'd like

I've written a drop-in extension to netCDF that seamlessly handles complex numbers, and can read many different conventions.

The Python API is built on top of netCDF4-python, so only a very simple change to xarray is needed to use it:

```diff modified xarray/backends/api.py @@ -115,7 +115,10 @@ def _get_default_engine_gz() -> Literal["scipy"]: def _get_default_engine_netcdf() -> Literal["netcdf4", "scipy"]: engine: Literal["netcdf4", "scipy"] try: - import netCDF4 # noqa: F401 + try: + import nc_complex # noqa: F401 + except ImportError: + import netCDF4 # noqa: F401

     engine = "netcdf4"
 except ImportError:  # pragma: no cover

modified xarray/backends/netCDF4_.py @@ -327,7 +327,10 @@ class NetCDF4DataStore(WritableCFDataStore): def init( self, manager, group=None, mode=None, lock=NETCDF4_PYTHON_LOCK, autoclose=False ): - import netCDF4 + try: + import nc_complex as netCDF4 + except ImportError: + import netCDF4

     if isinstance(manager, netCDF4.Dataset):
         if group is None:

@@ -364,7 +367,10 @@ class NetCDF4DataStore(WritableCFDataStore): lock_maker=None, autoclose=False, ): - import netCDF4 + try: + import nc_complex as netCDF4 + except ImportError: + import netCDF4

     if isinstance(filename, os.PathLike):
         filename = os.fspath(filename)

```

and then it works out of the box:

```python import numpy as np import xarray as xr

complex_array = np.array([0 + 0j, 1 + 0j, 0 + 1j, 1 + 1j, 0.25 + 0.75j], dtype="c16")

ds = xr.Dataset({"complex_data": ("x", complex_array)}) ds.to_netcdf("test.nc")

with xr.open_dataset("test.nc") as df: print(df.complex_data) assert ds == df

<xarray.DataArray 'complex_data' (x: 5)>

[5 values with dtype=complex128]

Dimensions without coordinates: x

```

If the library is built against the latest main of netCDF-C, then it also supports files written by h5netcdf. And while the package isn't on PyPI yet, built wheels with this feature are available from CI jobs.

nc_complex is not quite ready yet, but I wanted to gauge interest for adding it as an optional replacement for netCDF4 in xarray.

Describe alternatives you've considered

No response

Additional context

No response

See #8288

• [ ] Closes #xxxx
• [ ] Tests added
• [ ] User visible changes (including notable bug fixes) are documented in whats-new.rst
• [ ] New functions/methods are listed in api.rst

These changes allow me to make a pretty minimal subclass that just swaps out the netCDF4.Dataset class for my version:

```python from xarray.backends.netCDF4_ import NetCDF4BackendEntrypoint, NetCDF4DataStore from ._wrapper import Dataset # This is my netCDF extension

class NcComplexDataStore(NetCDF4DataStore): @classmethod def DatasetClass(self) -> type: return Dataset

class NcComplexBackendEntrypoint(NetCDF4BackendEntrypoint): DataStore = NcComplexDataStore ```

Uses sphinx-inline-tabs for pretty and compact options.

Also reword surrounding text a little for clarity.

This is more consistent with the other exceptions raised in this function, and helps to more quickly diagnose issues when e.g. creating datasets.

• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst

Is this a large enough change to warrant an entry in whats-new?