Medium-level netCDF bindings for Rust, allowing easy reading and writing of array-like structures to a file.
netCDF can read and write hdf5 files, which is a commonly used file format in scientific computing.
Supported:
- Variables
- Normal Dimensions
- Attributes
- Subgroups
- Open/Append/Create modes
- Reading from memory
- Unlimited dimensions
- User defined types, using the feature
derive(enum, compound, other types requires additional work)
Not (yet) supported (PRs welcome):
- Writing using memory-mapped file
All variable data is read into a contiguous buffer, or into an ndarray if the ndarray feature is activated.
This crate depends on the C library netcdf-c which must be installed on the machine, along with libraries such as hdf5 which netcdf-c depends on. For some platforms you might have to set the environment variable NETCDF_DIR which needs to point at the installation of netcdf-c you wish to use.
An alternative to using the system libraries is to enable static feature of this crate (cargo add netcdf --features static), which compiles libnetcdf from source. The static feature requires cmake, a c++ compiler and more to be installed on the build machine.
The crate is built on several platforms using github actions, and is currently known to build form from source on all major platforms (linux, macos, windows (gnu+msvc)), and through the package installers conda and apt. Please see the github workflows for tips on how to install netcdf.
git clone https://github.com/georust/netcdfgit submodule update --init --recursivecargo build --features static
Some examples of usage can be found in the tests/lib.rs file. The documentation can also be generated using cargo doc.
The netcdf crate is thread-safe, although the netcdf-c library is not itself threadsafe. To render a safe interface, a global mutex is used to serialize access to the underlying library. Consider using a non threadsafe version of hdf5 to avoid double locking (performance consideration).
Use of netcdf-sys is not thread-safe. Users of this library must take care that calls do not interfere with simultaneous use of e.g. netcdf or hdf5-sys. Use the lock provided by netcdf-sys to serialise access to the hdf5 and netCDF libraries.
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.