Add complex number support

[ZedThree]

Closes #1280

This adds support for reading/writing complex numbers in a variety of conventions, using my nc-complex library to do the heavy lifting. It's taken awhile because I had to go back and polish up the base library. It now supports writing complex numbers to netCDF3/classic model by automatically creating the complex dimension.

Complex number support is enabled by passing auto_complex=True to Dataset:

import netCDF4
import numpy as np

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

filename = "complex.nc"
with netCDF4.Dataset(filename, "w", auto_complex=True) as f:
    f.createDimension("x", size=len(complex_array))
    c_var = f.createVariable("data", "c16", ("x",))
    c_var[:] = complex_array

with netCDF4.Dataset(filename, "r", auto_complex=True) as f:
    print(f["data"])

# <class 'netCDF4._netCDF4.Variable'>
# compound data(x)
# compound data type: complex128
# unlimited dimensions: 
# current shape = (5,)

Internally, auto_complex is then used to switch between calling the nc_* and pfnc_* versions of the various functions. pfnc_def_var is always used to create variables, as this just falls through to nc_def_var if it's not a complex datatype.

I still need to add an example and update the docs, but all the code is working and I've added some tests, so I thought I'd open the PR so you can see what it looks like and maybe try it out.

There's probably still some sharp edges around vlen or compound types with nested complex numbers. I've not tested them.

[jswhit]

thanks @ZedThree! I see you are adding a submodule that points to your repo - which is fine, but I think it should still be possible to build netcdf4-python without that submodule. How hard would it be to add the ability to bypass the complex number support?

and BTW, do you plan to try to get this integrated into netcdf-c?

[ZedThree]

How hard would it be to add the ability to bypass the complex number support?

Definitely possible, but a little complicated. We'd need to do something like I added for the optional parallel support, switching out a .pxi header at build time. And then a runtime check if auto_complex=True but complex support is disabled.

The intention with the current implementation is that the complex number support is completely opt-in anyway. The underlying nc-complex C library is a single file and very cheap to build, so using the default auto_complex=False shouldn't add any overhead.

Happy to do this, but honestly I'm not sure it's worth making it optional at build-time.

do you plan to try to get this integrated into netcdf-c?

From this discussion: Unidata/netcdf-c#2652 it seems unlikely to be accepted unfortunately.

[jswhit]

I guess I was thinking there were two reasons to make it easily disable-able.

1. in case it was included upstream in netcdf-c (agree this does not seem likely in the foreseeable future)
2. in case your repo is broken or unavailable at build time (again unlikely, but possible)
   I wouldn't want to a lot more complexity to make it happen though.

[ZedThree]

in case your repo is broken or unavailable at build time

That was exactly my thinking for including it as a submodule, so that it would always be available :)

[jswhit]

Looks good - guess all it needs is a Changelog entry

[ZedThree]

Yep, will do! There's one more thing I want to add to the base library first, will get on that this week

[ZedThree]

Ok, I think this is complete from my side