E3SM `hdf5` & `netcdf` Modules Not Loading: A Fix

Nov 13, 2025 by Alex Johnson 50 views

E3SM `hdf5` / `netcdf` Modules Are Not Loaded When `use_e3sm_hdf5_netcdf` Is True

This article addresses a specific issue within the E3SM (Energy Exascale Earth System Model) unified environment where the hdf5 and netcdf modules are not being loaded as expected, even when the use_e3sm_hdf5_netcdf flag is set to True. This problem can lead to complications in accessing necessary tools and libraries within the E3SM ecosystem. Let's dive into the details and explore the root cause.

Understanding the Problem

The core of the issue lies in how the include_e3sm_hdf5_netcdf keyword argument is handled within the E3SM-unified framework. Specifically, the bootstrap.py script, a crucial component of the E3SM setup, doesn't explicitly specify this argument in a particular section of its code. As a result, the default value of False is applied to include_e3sm_hdf5_netcdf. This occurs even when the machine configuration file (mache) has use_e3sm_hdf5_netcdf set to True. The discrepancy between the intended configuration (as specified in the machine config file) and the actual behavior (due to the default value in bootstrap.py) leads to the modules not being loaded.

Why is this important? Because these modules provide essential tools like nf-config, which are indispensable for working with NetCDF files—a standard format for storing scientific data. When nf-config is unavailable, users encounter errors, hindering their ability to interact with and process E3SM model outputs effectively. The unavailability of nf-config arises because the necessary NetCDF modules haven't been loaded into the environment. This is directly attributable to the include_e3sm_hdf5_netcdf flag defaulting to False within the bootstrap.py script, despite the machine configuration indicating otherwise.

Let's consider a practical example. Imagine a user working on the pm-cpu system. They attempt to use nf-config after sourcing the E3SM unified environment script. Ideally, nf-config should be readily available, allowing them to query NetCDF configurations and settings. However, because the hdf5 and netcdf modules haven't been loaded, the system throws an error message indicating that NETCDF_DIR is not set, and prompting the user to load a NetCDF module. This illustrates the direct impact of the issue on user workflows and highlights the need for a resolution.

Diagnosing the Root Cause

To pinpoint the origin of the problem, it's necessary to delve into the bootstrap.py script within the E3SM-unified repository. The relevant section of the code, specifically lines 478-480, is where the include_e3sm_hdf5_netcdf keyword argument is not explicitly specified. This omission causes the argument to default to False, overriding any True setting in the machine configuration file. Therefore, even if the machine is configured to use the E3SM-specific HDF5 and NetCDF modules, the bootstrap.py script prevents them from being loaded.

The issue manifests due to a combination of factors. First, the machine configuration file correctly specifies the intention to use the E3SM-provided HDF5 and NetCDF modules via the use_e3sm_hdf5_netcdf flag. Second, the bootstrap.py script, responsible for setting up the environment, fails to propagate this intention because it doesn't explicitly handle the include_e3sm_hdf5_netcdf argument. This discrepancy results in a mismatch between the desired environment configuration and the actual environment setup. Consequently, the necessary modules are not loaded, leading to the observed errors when tools like nf-config are invoked. The key takeaway is that the default behavior of bootstrap.py overrides the machine-specific configuration, causing the HDF5 and NetCDF modules to be omitted from the environment.

Reproducing the Error

To illustrate the problem, consider the following steps executed on the pm-cpu system:

Set a dummy SLURM_JOB_ID:
```
SLURM_JOB_ID="kfjdkls"
```

Source the E3SM unified environment script:

source /global/common/software/e3sm/anaconda_envs/load_latest_e3sm_unified_pm-cpu.sh

Attempt to use nf-config:
```
nf-config --help
```

This sequence of commands will likely result in the following error message:

/opt/cray/pe/netcdf-hdf5parallel/4.9.0.9/gnu/12.3/bin/nf-config: line 6: NETCDF_DIR: not set; please load a netcdf module

This error message clearly indicates that the NetCDF module is not loaded, and therefore, nf-config cannot function properly. The root cause, as explained earlier, is the incorrect handling of the include_e3sm_hdf5_netcdf argument within the bootstrap.py script. By reproducing this error, users can confirm the issue and verify that the proposed solution effectively addresses the problem.

Proposed Solution

To resolve this issue, the include_e3sm_hdf5_netcdf keyword argument needs to be explicitly specified within the bootstrap.py script. This can be achieved by modifying the relevant section of the code to ensure that the value of use_e3sm_hdf5_netcdf from the machine configuration file is correctly propagated to the include_e3sm_hdf5_netcdf argument. By doing so, the E3SM-specific HDF5 and NetCDF modules will be loaded as intended when use_e3sm_hdf5_netcdf is set to True in the machine configuration.

The modification involves accessing the value of use_e3sm_hdf5_netcdf from the machine configuration and then explicitly passing it as the value for include_e3sm_hdf5_netcdf. This ensures that the bootstrap.py script respects the machine-specific setting and loads the appropriate modules. Here's a conceptual example of how this could be implemented:

# Within bootstrap.py
use_hdf5_netcdf = machine_config.get('use_e3sm_hdf5_netcdf', False)  # Get the value from machine config

# ... later in the code when calling a function that uses include_e3sm_hdf5_netcdf
function_call(..., include_e3sm_hdf5_netcdf=use_hdf5_netcdf, ...)

This change ensures that the include_e3sm_hdf5_netcdf argument is no longer defaulting to False but is instead dynamically set based on the machine configuration. With this fix, users will be able to reliably access tools like nf-config and work with NetCDF files without encountering the previously described errors.

Benefits of the Solution

Implementing this solution offers several key advantages:

Correct Module Loading: Ensures that the E3SM hdf5 and netcdf modules are loaded as intended when use_e3sm_hdf5_netcdf is set to True in the machine configuration file.
Availability of nf-config: Makes nf-config and other related tools readily available in the compute environment, allowing users to work with NetCDF files seamlessly.
Improved User Experience: Eliminates the error messages and complications associated with missing NetCDF modules, leading to a smoother and more productive user experience.
Consistency: Aligns the environment setup with the intended configuration specified in the machine configuration file, ensuring consistency across different systems.

By addressing the root cause of the issue, this solution provides a reliable and long-term fix that benefits all users of the E3SM unified environment.

Conclusion

The issue of E3SM hdf5 and netcdf modules not loading when use_e3sm_hdf5_netcdf is True stems from the include_e3sm_hdf5_netcdf keyword argument defaulting to False within the bootstrap.py script. This overrides the intended configuration specified in the machine configuration file. By explicitly setting the include_e3sm_hdf5_netcdf argument based on the value of use_e3sm_hdf5_netcdf in the machine configuration, the problem can be resolved. This ensures that the necessary modules are loaded, tools like nf-config are available, and users can work with NetCDF files without encountering errors. Implementing this solution improves the user experience, ensures consistency, and aligns the environment setup with the intended configuration.

For more information about NetCDF and its configuration, please visit the Unidata NetCDF website. This website provides comprehensive documentation, tutorials, and resources for working with NetCDF data.