Repository navigation
NEXTCDF-4 Documentation and Logging
NEP v4.1.0 — NEXTCDF-4 Documentation and Logging
NEP 4.1.0 follows the NEXTCDF-4 backend introduced in 4.0.0 with complete user and developer documentation, an independent NEP diagnostic logging framework, and a streamlined example collection. This release does not change the NEP ABI, UDF slot assignments, file-format behavior, or NEXTCDF-4 on-disk format.
Highlights
- Complete NEXTCDF-4 documentation covering configuration, file selection, compatibility modes, supported types, storage layout, reference APIs, and known limitations.
- Independent NEP logging enabled by default and controlled at runtime with
nep_set_log_level()orNEP_LOG_LEVEL. - NEP-specific logging macros (
ELOG,EBAIL,EBAIL2,EBAILLOG, andEBAIL_QUIET) that do not conflict with NetCDF-C's internal logging macros. - Focused example collection after moving standalone Earth-observation mission applications to the dedicated Earth Observation in Practice project.
NEXTCDF-4 Documentation
The new docs/nextcdf4.md reference describes the NEXTCDF-4 backend delivered on UDF9:
- Enabling the backend with
-DNEP_ENABLE_NEXTCDF4=ON. - Creating and opening files with
NC_NEXTCDF4. - UDF9
.ncrcautoload configuration. - Native,
NC_CLASSIC_MODEL, andNC_NETCDF4_MODELcompatibility modes. - HDF5 1.14.0 minimum and HDF5 2.1.1 recommendations.
- Standard NetCDF atomic types and NEXTCDF-4 small-float, complex, bitfield, and reference types.
- Dimension scales and hidden metadata attributes such as
_Nextcdf4Backend,_Nextcdf4Model,_Netcdf4Coordinates, and_Netcdf4Dimid. - Object and region reference APIs.
- Current limitations and complete C usage examples.
NEXTCDF-4 is also integrated into the Doxygen landing page, format overview, architecture documentation, product requirements, and FAQ. The project README now links directly to the NEXTCDF-4 reference.
Independent NEP Logging
NEP no longer depends on whether NetCDF-C was compiled with its own logging support. Logging is built and controlled independently.
Build configuration
cmake -B build -DNEP_ENABLE_LOGGING=ONNEP_ENABLE_LOGGING defaults to ON. The generated nep_meta.h reports the configured capability through:
#define NEP_HAS_LOGGING 1When configured with -DNEP_ENABLE_LOGGING=OFF, diagnostic calls compile to no-ops and nep_set_log_level() remains callable as a no-op.
Runtime control
The new public C API sets the maximum emitted severity:
#include <nep.h>
nep_set_log_level(3); /* Errors and messages at levels 1-3. */
nep_set_log_level(-1); /* Disable NEP logging. */NC_NEXTCDF4_initialize() also reads NEP_LOG_LEVEL, allowing diagnostics to be selected before an application opens a NEXTCDF-4 file:
export NEP_LOG_LEVEL=3Messages are written to stderr. Severity 0 is reserved for errors; higher numbers provide progressively more detailed lifecycle and metadata diagnostics.
Internal logging interface
include/nep_logging.h provides NEP-specific E-prefixed macros:
ELOG((severity, format, ...))emits a message throughnep_log().EBAILLOG(error)reports a NetCDF error with its source location.EBAIL(error)reports an error and transfers control to anexit:cleanup label.EBAIL_QUIET(error)transfers control without logging.EBAIL2(error)is the NEXTCDF-4 HDF5-aware variant; it also prints the HDF5 error stack.
The separate names prevent collisions with NetCDF-C's LOG, BAIL, and BAIL2 macros. NEXTCDF-4 instrumentation covers create, open, close, abort, sync, define-mode transitions, format inquiries, dimension and variable definition, and metadata loading.
Public API Changes
The following function is added to include/nep.h:
int nep_set_log_level(int new_level);-1disables diagnostic output.0enables errors only.- Positive values enable progressively more verbose messages.
- The function returns
NC_NOERR.
No existing public API was removed or changed.
Build-System Changes
- Added
NEP_ENABLE_LOGGING, defaulting toON. - Added the private
NEP_LOGGINGcompile-time definition when logging is enabled. - Added
NEP_HAS_LOGGINGto generated build metadata. - Linked the NEXTCDF-4 plugin against the core
neplibrary so all NEP components share one logging level. - Logging remains independent of NetCDF-C's
NC_HAS_LOGGINGsetting andnc_set_log_level()implementation.
Tests
A new tst_nextcdf4_logging regression test verifies that:
- Expected NEXTCDF-4 lifecycle messages are emitted at level 3.
nep_set_log_level(-1)suppresses subsequent output.- An intentional HDF5 open failure emits a severity-0 NEP error.
- Builds configured with
NEP_ENABLE_LOGGING=OFFskip logging-specific checks cleanly.
Release verification completed with:
- A clean CMake configure and build.
- All 20 enabled CTest tests passing; one pre-existing test remains disabled.
- A successful Doxygen build with no warnings or unresolved references.
- Logging-enabled and logging-disabled build configurations tested successfully.
Earth-Observation Example Migration
The standalone NISAR, SWOT, GOES-R ABI, and Sentinel-3 OLCI Python applications have moved to the Earth Observation in Practice repository. Their mission-specific companion articles, figures, dependency files, implementation plans, and maintenance skills have been removed from NEP.
The companion book, Earth Observation in Practice: A Mission-by-Mission Guide to Reading Satellite Data with NetCDF and Python, provides additional mission-focused guidance.
This migration does not remove examples that directly exercise NEP functionality. The repository continues to include examples for:
- NEP UDF format readers and visualizations.
- Compression filters.
- Classic NetCDF and NetCDF-4.
- NcZarr and OPeNDAP.
- Parallel I/O and performance tuning.
- NEXTCDF-4.
The external Earth-observation repository and book are informational resources, not NEP build-time, runtime, test, or packaging dependencies.
Compatibility and Upgrade Notes
- No NEP ABI break is introduced in 4.1.0.
- Existing UDF slot assignments are unchanged.
- Existing NEXTCDF-4 files remain compatible with the 4.1.0 backend.
- Applications using NetCDF-C logging continue to control it with
nc_set_log_level(); NEP diagnostics are controlled separately withnep_set_log_level(). - Scripts or documentation that referenced the removed mission-example paths should use the dedicated Earth-observation repository instead.
NEP_ENABLE_NEXTCDF4remains opt-in and requires NetCDF-C with UDF9 support and HDF5 1.14.0 or newer.
Dependencies
- NetCDF-C 4.10.1 or newer with UDF plugin and
NC_Dispatchsupport. - HDF5 1.14.0 or newer when NEXTCDF-4 is enabled.
- HDF5 2.1.1 or newer is recommended for the complete small floating-point type set.
Documentation
docs/nextcdf4.md— NEXTCDF-4 user and developer reference.docs/design.md— updated NEXTCDF-4 architecture and source organization.docs/formats.md— NEXTCDF-4 UDF9 selection and autoload information.docs/prd.md— NEXTCDF-4 product requirements.docs/prfaq.md— NEXTCDF-4 user FAQ.docs/roadmap.md— v4.1.0 sprint plans and acceptance criteria.
Release Summary
- Version: 4.1.0
- Released: September 24, 2026
- Scope: NEXTCDF-4 documentation, independent NEP logging, and example migration
- Contributors: Edward Hartnett