Machine_System_Conditionals - TerrenceMcGuinness-NOAA/global-workflow GitHub Wiki

Machine and System Conditionals in Global Workflow

This document provides a comprehensive reference of all locations where the Global Workflow codebase performs conditional operations based on the HPC system or machine where the code is executed. Understanding these conditionals is critical for platform portability, debugging system-specific issues, and onboarding new HPC platforms.

📋 Executive Summary

Metric	Count
Supported Platforms	11
Shell Scripts with MACHINE_ID Conditionals	11+
Python Files with Machine Detection	3
Platform Config Files	7
Host YAML Definitions	11
Primary Detection Method	Hostname + Path-based

🖥️ Supported Platforms

The Global Workflow officially supports the following HPC platforms:

Platform	Type	Detection Method
Hera	RDHPCS	Hostname pattern `hfe`, `hecflow`
Ursa	RDHPCS	Path `/scratch1`
Orion	RDHPCS	Hostname pattern `Orion-*`
Hercules	RDHPCS	Hostname pattern `hercules-*`
WCOSS2	Production	Path `/lfs/h1`, `/lfs/h2`, `/lfs/h3`
Gaea C5	RDHPCS	Hostname pattern `gaea5*`
Gaea C6	RDHPCS	Hostname pattern `gaea6*`
AWS	Cloud (PW)	Host includes `internal.cloudapp.net`
Azure	Cloud (PW)	Host includes `internal.cloudapp.net`
Google	Cloud (PW)	Host includes `internal`
Container	Fallback	Environment variable `SINGULARITY_COMMAND` or `PBS_NODEFILE`

🔍 Primary Machine Detection

Shell Detection: `ush/detect_machine.sh`

This is the authoritative source for machine detection in shell scripts. All shell-based workflow components should source this file rather than implementing their own detection logic.

Detection Algorithm:

# 1. Check for Orion/Hercules (hostname-based)
if [ "${host}" == "Orion-"* ](/TerrenceMcGuinness-NOAA/global-workflow/wiki/-"${host}"-==-"Orion-"*-); then
  MACHINE_ID=orion
elif [ "${host}" == "hercules-"* ](/TerrenceMcGuinness-NOAA/global-workflow/wiki/-"${host}"-==-"hercules-"*-); then
  MACHINE_ID=hercules

# 2. Check for Hera (hostname-based)
elif [ "${host}" == "hfe"* ](/TerrenceMcGuinness-NOAA/global-workflow/wiki/|-"${host}"-==-"hecflow"*-); then
  MACHINE_ID=hera

# 3. Check for Gaea C5/C6 (hostname-based)
elif [ "${host}" == "gaea5"* ](/TerrenceMcGuinness-NOAA/global-workflow/wiki/-"${host}"-==-"gaea5"*-); then
  MACHINE_ID=gaea-c5
elif [ "${host}" == "gaea6"* ](/TerrenceMcGuinness-NOAA/global-workflow/wiki/-"${host}"-==-"gaea6"*-); then
  MACHINE_ID=gaea-c6

# 4. Check for WCOSS2 (path-based)
elif [ -d /lfs/h1 && -d /lfs/h2 ](/TerrenceMcGuinness-NOAA/global-workflow/wiki/--d-/lfs/h1-&&--d-/lfs/h2-); then
  MACHINE_ID=wcoss2

# 5. Check for Ursa (path-based)  
elif [ -d /scratch1 ](/TerrenceMcGuinness-NOAA/global-workflow/wiki/--d-/scratch1-); then
  MACHINE_ID=ursa

# 6. Fallback to container/NOTFOUND
else
  MACHINE_ID=${MACHINE_ID:-NOTFOUND}
fi

Key Files:

ush/detect_machine.sh - Primary detection script

Python Detection: `dev/workflow/hosts.py`

For Python-based tooling (CI/CD, development scripts), machine detection uses the Host class:

class Host:
    SUPPORTED_HOSTS = ['HERA', 'URSA', 'ORION', 'HERCULES', 'JET', 
                       'WCOSS2', 'S4', 'GAEA-C5', 'GAEA-C6', 
                       'AWSPW', 'AZUREPW', 'GOOGLEPW', 'CONTAINER']
    
    def __init__(self, host=None):
        detected_host = self._detect()
        self.machine = self.validate(host if host else detected_host)

Key Files:

dev/workflow/hosts.py - Host class definition
dev/workflow/gw_setup.py - Uses Host class for setup
dev/ci/drivers/driver.sh - CI driver using platform configs

📁 Shell Scripts with MACHINE_ID Conditionals

1. `ush/module-setup.sh` — Module Loading

Contains the most extensive platform conditionals for loading HPC-specific module environments:

case "${MACHINE_ID}" in
  hera)
    source /apps/lmod/lmod/init/bash
    ;;
  orion)
    source /apps/lmod/lmod/init/bash
    ;;
  hercules)
    source /apps/other/lmod/lmod/init/bash
    ;;
  gaea-c5)
    source /lustre/f2/dev/role.epic/contrib/Lmod_init.sh
    ;;
  gaea-c6)
    source /lustre/f2/dev/role.epic/contrib/Lmod_init.sh
    ;;
  wcoss2)
    source /apps/prod/lmod/lmod/init/bash
    ;;
  *)
    echo "FATAL: Unknown MACHINE_ID = ${MACHINE_ID}"
    ;;
esac

Location: ush/module-setup.sh

2. `env/gfs/` — Environment Configurations

Platform-specific environment scripts:

File	Purpose
`env/gfs/gfs.env`	GFS general environment
`env/gdas/gdas.env`	GDAS general environment
`parm/config/gfs/config.base`	Base configuration with MACHINE conditionals

3. `ush/load_*.sh` Scripts

Scripts that load machine-specific modules:

Script	Conditional Pattern
`ush/load_fv3gfs_modules.sh`	`case "${MACHINE_ID}"` for FV3GFS modules
`ush/load_ufsda_modules.sh`	`case "${MACHINE_ID}"` for UFSDA modules
`ush/load_ufswm_modules.sh`	`case "${MACHINE_ID}"` for UFS WM modules

4. `workflow/hosts/` — Rocoto Host Definitions

YAML-based host configuration files for Rocoto workflow management:

File	Platform
`workflow/hosts/hera.yaml`	Hera RDHPCS
`workflow/hosts/orion.yaml`	Orion RDHPCS
`workflow/hosts/hercules.yaml`	Hercules RDHPCS
`workflow/hosts/wcoss2.yaml`	WCOSS2 Production
`workflow/hosts/gaea-c5.yaml`	Gaea C5
`workflow/hosts/gaea-c6.yaml`	Gaea C6
`workflow/hosts/awspw.yaml`	AWS Parallel Works
`workflow/hosts/azurepw.yaml`	Azure Parallel Works
`workflow/hosts/googlepw.yaml`	Google Parallel Works
`workflow/hosts/container.yaml`	Container/Singularity
`workflow/hosts/S4.yaml`	S4 (legacy)

Content Example (hera.yaml):

machine: hera
scheduler: slurm
rocoto_rocotorun: /apps/rocoto/default/bin/rocotorun
rocoto_rocotostat: /apps/rocoto/default/bin/rocotostat
base_git: /scratch1/NCEPDEV/global/glopara/git
account: !error "Set your account"

5. `dev/ci/platforms/` — CI Platform Configs

Configuration files for CI/CD testing on each platform:

File	Platform
`dev/ci/platforms/config.hera`	Hera
`dev/ci/platforms/config.orion`	Orion
`dev/ci/platforms/config.hercules`	Hercules
`dev/ci/platforms/config.wcoss2`	WCOSS2
`dev/ci/platforms/config.gaea-c5`	Gaea C5
`dev/ci/platforms/config.gaea-c6`	Gaea C6
`dev/ci/platforms/config.gaeac5_c6`	Gaea C5/C6 shared

Content Example (config.hera):

#!/bin/bash
export pslot="C96C48"
export RUNTESTS="${PROJECT_DIR}/ci"
export ACCOUNT="fv3-cam"
export max_concurrent_cases=4
export max_concurrent_pr=4
export ci_parm="./dev/ci/parm"

🔄 Conditional Patterns by Category

Pattern 1: Case Statements (Most Common)

case "${MACHINE_ID}" in
  hera)     # Hera-specific code ;;
  orion)    # Orion-specific code ;;
  wcoss2)   # WCOSS2-specific code ;;
  *)        echo "Unknown machine" ;;
esac

Found in: module-setup.sh, load_*.sh, job scripts

Pattern 2: If/Elif Chains

if [ "${MACHINE_ID}" == "hera" ](/TerrenceMcGuinness-NOAA/global-workflow/wiki/-"${MACHINE_ID}"-==-"hera"-); then
  export PATH=/apps/hera/bin:$PATH
elif [ "${MACHINE_ID}" == "wcoss2" ](/TerrenceMcGuinness-NOAA/global-workflow/wiki/-"${MACHINE_ID}"-==-"wcoss2"-); then
  export PATH=/apps/prod/bin:$PATH
fi

Found in: Environment setup scripts, env/*.sh

Pattern 3: Python Attribute Access

if self.machine == 'HERA':
    self.hpc_account = 'fv3-cam'
elif self.machine == 'WCOSS2':
    self.hpc_account = 'GFS-DEV'

Found in: hosts.py, gw_setup.py

Pattern 4: YAML-based Configuration

# workflow/hosts/hera.yaml
scheduler: slurm
partition: !error "Set partition"

Used by: Rocoto workflow manager, setup scripts

🛠️ Adding a New Platform

To add support for a new HPC platform:

Step 1: Update Detection Logic

Shell (ush/detect_machine.sh):

elif [ "${host}" == "newplatform-"* ](/TerrenceMcGuinness-NOAA/global-workflow/wiki/-"${host}"-==-"newplatform-"*-); then
  MACHINE_ID=newplatform

Python (dev/workflow/hosts.py):

SUPPORTED_HOSTS = [..., 'NEWPLATFORM']

Step 2: Create Host Configuration

Create workflow/hosts/newplatform.yaml:

machine: newplatform
scheduler: slurm  # or pbs, lsf
rocoto_rocotorun: /path/to/rocotorun
rocoto_rocotostat: /path/to/rocotostat
base_git: /path/to/git/repos
account: !error "Set your account"

Step 3: Update Module Setup

Add case in ush/module-setup.sh:

newplatform)
  source /path/to/lmod/init/bash
  ;;

Step 4: Create CI Config (Optional)

Create dev/ci/platforms/config.newplatform:

#!/bin/bash
export pslot="C96C48"
export RUNTESTS="${PROJECT_DIR}/ci"
export ACCOUNT="your-account"

Step 5: Update Documentation

Add platform to this wiki page
Update README.md with supported platforms list
Add to HPC Build page if build instructions differ

📊 Conditional Distribution by File Type

File Type	Count	Primary Use
Shell Scripts (`.sh`)	20+	Module loading, environment setup
Python Files (`.py`)	5	CI/CD, development tooling
YAML Config (`.yaml`)	11	Rocoto host definitions
Platform Configs	7	CI/CD testing

🔗 Related Documentation

HPC_Build - Building on specific HPC platforms
Run_Modes - Execution modes across platforms
CI_CD_Overview - Continuous integration across platforms
NOAA RDHPCS Documentation

Last updated: January 2026 Generated by EIB MCP/RAG System analysis