Adding a New Machine

Support for a new HPC machine in E3SM-Unified requires coordinated updates across multiple tools — primarily in mache, but also in the E3SM Spack fork and deployment scripts.

This page provides guidance for E3SM-Unified maintainers and infrastructure developers integrating new machines into the release and deployment workflow.

🔗 Main Mache Documentation

Most of the process is already documented in the official mache developer guide:

Start in mache to:

Add a machine-specific config file (e.g., pm-cpu.cfg)
Add hostname detection logic in discover.py
Create Spack templates for supported compiler/MPI stacks
Optionally add shell script templates for environment setup

⚠️ Machines not listed in the E3SM config_machines.xml must first be added upstream before mache can support them.

🧩 Integration with E3SM-Unified Deployment

After updating mache, you’ll need to:

Reference your mache branch in E3SM-Unified Deployment
- Use the --mache_fork and --mache_branch flags to deploy using the updated branch
- Confirm the new machine is recognized and templates are applied correctly
Update Spack if needed
- If new versions of external tools are required, update the spack_for_mache_<version> branch of the E3SM Spack fork

✅ Testing Your Changes

Use the standard test deployment approach from Deploying on HPCs:

cd e3sm_supported_machines
./deploy_e3sm_unified.py --conda ~/miniforge3 \
                         --mache_fork <your_fork> \
                         --mache_branch <your_branch>

You can also supply these flags:

                         --machine <new_machine> \
                         --compiler <compiler> \
                         --mpi <mpi> \

but they should not be needed if you have set things up in mache correctly.

During testing, focus on:

Spack external package detection and successful builds
Shell script generation and activation behavior
Module compatibility and performance of tools like zppy and e3sm_diags

💡 Tips and Best Practices

Reuse YAML templates from similar machines to minimize effort
Add common system tools as buildable: false in the Spack environment
Avoid identifying machines using environment variables unless absolutely necessary. Instead use the hostnames for login and compute nodes if possible
Use utils/update_cime_machine_config.py to verify mache remains in sync with E3SM

➡ Next: Publishing the Final Release