NetCDF I/O Helpers

OLMT provides two lightweight NetCDF I/O helper modules that abstract read and write operations for variables within NetCDF files. Both modules expose the same two-function API (getvar and putvar) but differ in their underlying NetCDF backend.

Which Module to Use

netcdf4_functions (preferred)

Use this module for all new code. It wraps the modern netCDF4 Python library and is the actively maintained option.

netcdf_functions (legacy)

Legacy module that falls back from Scientific.IO.NetCDF to scipy.io.netcdf (both deprecated). No longer used in the codebase; retained for backwards compatibility only.

Current Usage in Codebase

As of June 2026, netcdf4_functions is imported (as nffun) in:

  • runcase.py

  • makepointdata.py

  • manage_ensemble.py

  • ensemble_copy.py

  • adjust_restart.py

The legacy netcdf_functions module is not actively used.

API Reference

Both modules expose the same interface:

getvar(fname, varname)

Read a variable from a NetCDF file.

Parameters:

  • fname (str): Path to the NetCDF file

  • varname (str): Name of the variable to read

Returns:

numpy array or scalar containing the variable’s data

netcdf4_functions behavior:

Raises ValueError if varname does not exist in the file.

netcdf_functions behavior:

Returns the variable value; behavior on missing variable is undefined.

Example:

import netcdf4_functions as nffun
lat = nffun.getvar('domain.nc', 'lat')

putvar(fname, varname, varvals)

Write a variable to an existing NetCDF file (append mode).

Parameters:

  • fname (str): Path to the NetCDF file

  • varname (str): Name of the variable to write

  • varvals (array-like): Values to assign to the variable

Returns:

0 on success (always; no actual error signaling)

netcdf4_functions behavior:

Prints a warning if varname does not exist in the file; does not raise an exception.

netcdf_functions behavior:

For scipy backend, silently skips scalar writes; multi-element arrays are written. For Scientific backend, uses assignValue.

Example:

import netcdf4_functions as nffun
nffun.putvar('domain.nc', 'mask', mask_array)

Implementation Details

netcdf4_functions

Uses the netCDF4 Python library (from netCDF4 import Dataset). Opens files in read mode ('r') for getvar and append mode ('a') for putvar. Always closes the file handle before returning.

Read operations use NumPy-style slicing (variables[varname][:]); write operations use ellipsis assignment (variables[varname][...] = varvals).

netcdf_functions

Attempts to import Scientific.IO.NetCDF; falls back to scipy.io.netcdf if unavailable. Both backends are deprecated and may not be available in modern Python environments.

The scipy path uses netcdf_file with mmap=False; the Scientific path uses the older NetCDFFile API with .getValue() and .assignValue().

Migration Notes

To convert code from netcdf_functions to netcdf4_functions:

  1. Change the import statement:

    # Old
import netcdf_functions
# New
import netcdf4_functions as nffun

  2. No other changes needed; the API is identical.

  3. Be aware that getvar will now raise ValueError for missing variables rather than silently returning an undefined value.