groups.c File Reference

Demonstrates NetCDF-4 hierarchical groups, nested groups, and dimension visibility. More...

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <netcdf.h>

Macros
#define	FILE_NAME   "groups.nc"
#define	NX   3
#define	NY   4
#define	NZ   2
#define	NDIMS_2D   2
#define	NDIMS_3D   3
#define	ERRCODE   2
#define	ERR(e)   {printf("Error: %s\n", nc_strerror(e)); exit(ERRCODE);}

Functions
int	main ()

Detailed Description

Demonstrates NetCDF-4 hierarchical groups, nested groups, and dimension visibility.

This example showcases NetCDF-4's hierarchical group feature, which enables organizing datasets into logical groupings similar to directories in a filesystem. Groups provide namespace isolation for variables while allowing dimensions to be shared across the hierarchy through dimension visibility rules.

The program creates a three-level group hierarchy (root → SubGroup1, root → SubGroup2 → NestedGroup), demonstrates dimension visibility across group boundaries, and showcases all five new NetCDF-4 integer types (NC_UBYTE, NC_USHORT, NC_UINT, NC_INT64, NC_UINT64).

Learning Objectives:

• Understand NetCDF-4 hierarchical group structures
• Learn to create and navigate nested groups
• Master dimension visibility rules across group boundaries
• Work with all five new NetCDF-4 integer types
• Recognize when groups provide organizational benefits

Key Concepts:

• Hierarchical Groups: Organize datasets into logical groupings (like directories)
• Dimension Visibility: Parent dimensions visible in all child groups
• Variable Scoping: Variables only visible in their defining group
• Group Navigation: Use nc_inq_grp_ncid() to navigate by name
• New Integer Types: NC_UBYTE, NC_USHORT, NC_UINT, NC_INT64, NC_UINT64

NetCDF-4 Group Architecture:

• Groups implemented via NC_GRP_INFO_T structures (libsrc4/libhdf5)
• Dimensions visible in child groups via parent chain lookup
• Variables NOT inherited (scoped to defining group only)
• Requires NC_NETCDF4 flag (HDF5 backend)
• Not compatible with NC_CLASSIC_MODEL

Dimension Visibility Rules:

• Dimensions defined in a group are visible in that group and all descendants
• Root dimensions (x, y) visible in SubGroup1, SubGroup2, and NestedGroup
• Local dimensions (z in NestedGroup) only visible in defining group
• Dimension lookup walks parent chain: child → parent → root

Use Cases for Groups:

• Multi-instrument datasets: Group data by instrument or sensor
• Model ensembles: Separate ensemble members into groups
• Quality levels: Organize raw, calibrated, and derived products
• Temporal organization: Group data by year, month, or campaign
• Namespace management: Avoid variable name conflicts

Prerequisites:

• simple_nc4.c - Basic NetCDF-4 file operations
• multi_unlimited.c - Advanced NetCDF-4 features

Related Examples:

• f_groups.f90 - Fortran equivalent (future)
• user_types.c - User-defined compound types in groups

Compilation:

gcc -o groups groups.c -lnetcdf

Usage:

./groups
ncdump groups.nc
ncdump -h groups.nc  # Header only

Expected Output: Creates groups.nc in NetCDF-4/HDF5 format containing:

• Root group with dimensions x(3), y(4) and variable ubyte_var(NC_UBYTE)
• SubGroup1 with variable ushort_var(NC_USHORT)
• SubGroup2 with variable uint_var(NC_UINT)
• NestedGroup (under SubGroup2) with dimension z(2) and variables:
  • int64_var(NC_INT64, 2D: x, y)
  • uint64_var(NC_UINT64, 3D: x, y, z)

Author

Edward Hartnett, Intelligent Data Design, Inc.

Date

2026

Macro Definition Documentation

ERR

#define ERR

(

e

)

{printf("Error: %s\n", nc_strerror(e)); exit(ERRCODE);}

ERRCODE

#define ERRCODE   2

FILE_NAME

#define FILE_NAME   "groups.nc"

NDIMS_2D

#define NDIMS_2D   2

NDIMS_3D

#define NDIMS_3D   3

NX

#define NX   3

NY

#define NY   4

NZ

#define NZ   2

Function Documentation

main()

int main

(

)