Skip to content

NEXTCDF-4 Documentation and Logging

Choose a tag to compare

@captainkirk99 captainkirk99 released this 25 Sep 02:15
· 7 commits to main since this release
c091f12

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() or NEP_LOG_LEVEL.
  • NEP-specific logging macros (ELOG, EBAIL, EBAIL2, EBAILLOG, and EBAIL_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 .ncrc autoload configuration.
  • Native, NC_CLASSIC_MODEL, and NC_NETCDF4_MODEL compatibility 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=ON

NEP_ENABLE_LOGGING defaults to ON. The generated nep_meta.h reports the configured capability through:

#define NEP_HAS_LOGGING 1

When 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=3

Messages 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 through nep_log().
  • EBAILLOG(error) reports a NetCDF error with its source location.
  • EBAIL(error) reports an error and transfers control to an exit: 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);
  • -1 disables diagnostic output.
  • 0 enables 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 to ON.
  • Added the private NEP_LOGGING compile-time definition when logging is enabled.
  • Added NEP_HAS_LOGGING to generated build metadata.
  • Linked the NEXTCDF-4 plugin against the core nep library so all NEP components share one logging level.
  • Logging remains independent of NetCDF-C's NC_HAS_LOGGING setting and nc_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=OFF skip 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 with nep_set_log_level().
  • Scripts or documentation that referenced the removed mission-example paths should use the dedicated Earth-observation repository instead.
  • NEP_ENABLE_NEXTCDF4 remains 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_Dispatch support.
  • 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