Skip to content

jgfs_fcst ecf (v17) Analysis

Jump to bottom
Terry McGuinness edited this page Jun 11, 2026 · 2 revisions

jgfs_fcst.ecf (GFS v17)

Branch / tenant: dev/gfs.v17 (gw_v17) Path: ecf/scripts/gfs/forecast/jgfs_fcst.ecf Analysis date: 2026-06-11 Method: AWS Bedrock AgentCore agentcore-mcp-rag MCP (graph traversal, GraphRAG, code-context) cross-checked against the on-disk v17 worktree.

Summary

jgfs_fcst.ecf is the GFS deterministic forecast task — the single most important and resource-intensive job in the entire GFS suite. It runs the UFS Weather Model (coupled atmosphere/ocean/ice/wave) for the 16-day (384-hour) GFS forecast. This is a single-instance task per cycle calling the shared JGLOBAL_FORECAST J-Job, which drives exglobal_forecast.sh. It uses 295 nodes x 128 cpus = 37,760 MPI ranks with exclusive host placement and a 6-hour walltime.

1. The script itself

#PBS -S /bin/bash
#PBS -N gfs_fcst_%CYC%
#PBS -j oe
#PBS -q %QUEUE%
#PBS -A %PROJ%-%PROJENVIR%
#PBS -l walltime=06:00:00
#PBS -l select=295:mpiprocs=128:ompthreads=1:ncpus=128
#PBS -l place=vscatter:exclhost
#PBS -l debug=true

model=gfs
export cyc="%CYC%"
%include <head.h>
%include <envir-p1.h>

############################################################
# Load modules
############################################################
source ${HOMEgfs}/dev/ush/load_modules.sh ufswm

module list
############################################################
# CALL executable job script here
############################################################
export CDATE=${PDY}${cyc}
export HOMEglobal=${HOMEgfs}
export FCST_SEGMENT='0'
#### ${HOMEgfs}/dev/job_cards/rocoto/fcst.sh
${HOMEgfs}/jobs/JGLOBAL_FORECAST
if [ $? -ne 0 ]; then
   ecflow_client --msg="***JOB ${ECF_NAME} ERROR RUNNING J-SCRIPT ***"
   ecflow_client --abort
   exit
fi

%include <tail.h>
%manual

%end

What each part does

Section Role
#PBS directives PBS Pro: 295 nodes, 128 cpus/node = 37,760 MPI ranks. Exclusive host placement. 6-hour wall. This is the largest job in the GFS suite by resource count.
load_modules.sh ufswm Loads the UFS Weather Model module set (FV3, MOM6, CICE6, WW3, CMEPS, ESMF).
FCST_SEGMENT='0' Identifies this as forecast segment 0 (first/only segment in non-FSM mode).
${HOMEgfs}/jobs/JGLOBAL_FORECAST The shared forecast J-Job (used by GFS, GDAS, EnKF).

2. Single-instance pattern

This is a single task per cycle (gfs_fcst_%CYC%). Unlike _master templates, there is only one GFS forecast per cycle — it runs the full 0-384 hour integration.

3. Execution chain

ecf/defs/gfs_prod.def : task jgfs_fcst
  +-- jgfs_fcst.ecf                               (PBS submit)
       +-- ${HOMEgfs}/jobs/JGLOBAL_FORECAST         (J-Job, shared GFS/GDAS/EnKF)
            +-- ${SCRglobal}/exglobal_forecast.sh   (ex-script)
                 +-- pygfs / wxflow Python drivers
                      +-- UFS Weather Model executable (ufs_model.x)
                           +-- FV3 (atmosphere)
                           +-- MOM6 (ocean, if DO_OCN=YES)
                           +-- CICE6 (ice, if DO_ICE=YES)
                           +-- WW3 (wave, if DO_WAVE=YES)
                           +-- GOCART (aerosol, if DO_AERO_FCST=YES)
                           +-- CMEPS (mediator)

4. What the J-Job actually produces

The forecast generates all model output fields for the entire GFS cycle:

Component Output Location
Atmosphere history NetCDF .nc files per forecast hour ${COMOUT_ATMOS_HISTORY}/
Atmosphere master GRIB2 master files ${COMOUT_ATMOS_MASTER}/
Atmosphere restart Restart files for next cycle ${COMOUT_ATMOS_RESTART}/
Ocean history NetCDF ocean output (if DO_OCN) ${COMOUT_OCEAN_HISTORY}/
Ocean restart MOM6 restart files (if DO_OCN) ${COMOUT_OCEAN_RESTART}/
Ice history CICE6 output (if DO_ICE) ${COMOUT_ICE_HISTORY}/
Ice restart CICE6 restart files (if DO_ICE) ${COMOUT_ICE_RESTART}/
Wave history WW3 output (if DO_WAVE) ${COMOUT_WAVE_HISTORY}/
Wave restart WW3 restart files (if DO_WAVE) ${COMOUT_WAVE_RESTART}/
Chemistry history GOCART output (if DO_AERO_FCST) ${COMOUT_CHEM_HISTORY}/
Mediator restart CMEPS restart (if DO_OCN) ${COMOUT_MED_RESTART}/
Configuration Model config/namelist archive ${COMOUT_CONF}/

Error handling

Uses the EE2-correct pattern: "${FORECASTSH}" && true followed by err_exit on non-zero.

5. Key environment variables

Variable Origin Meaning
FCST_SEGMENT ECF script ('0') Forecast segment index (0 = first/only).
FCST_SEGMENTS config.fcst Comma-separated segment boundaries (e.g. 0,384 for single-segment).
rCDUMP J-Job Restart source RUN (GFS reads from GDAS).
COMIN_ATMOS_RESTART_PREV J-Job Previous cycle GDAS restart directory (initial conditions).
COMIN_ATMOS_ANALYSIS J-Job Atmospheric analysis from current cycle.
DO_WAVE / DO_OCN / DO_ICE / DO_AERO_FCST config.base Component coupling switches.
FHMAX config.fcst Maximum forecast hour (384 for GFS).
DATArestart / DATAoutput J-Job Temporary storage for model restarts/output.
FORECASTSH default exglobal_forecast.sh The forecast driver script.
assim_freq config.base Data assimilation frequency (hours between cycles).

Configuration

The J-Job sources jjob_header.sh -e "fcst" -c "base fcst", loading:

  • config.base — fundamental paths, coupling switches, resolution settings.
  • config.fcst — forecast-specific settings (segment info, FHMAX, threading).

6. v17-specific notes

  • Massive scale: 295 nodes is the operational GFS C768 configuration at NCO. This is by far the largest resource request in the suite.
  • UFS Weather Model modules: load_modules.sh ufswm loads the coupled model executable and all its dependencies (FV3, MOM6, CICE6, WW3, ESMF, CMEPS).
  • Shared J-Job: JGLOBAL_FORECAST handles GFS, GDAS, and EnKF forecasts — differentiated by RUN, ENSMEM, and config settings.
  • Segment support: FCST_SEGMENT='0' supports the Forecast Segmentation Manager (FSM) pattern where a forecast is split into segments for checkpointing.
  • GDAS restart dependency: GFS forecast reads initial conditions from the previous GDAS cycle (rCDUMP logic: gfs -> gdas).
  • Conditional coupling: wave, ocean, ice, and aerosol components are optionally enabled via DO_* flags.
  • Centralized module loading via load_modules.sh ufswm.
  • HOMEglobal shim bridges v17 naming to NCO.

7. Change-impact snapshot (from MCP, gw_v17)

Symbol Change type Risk Direct dependents
JGLOBAL_FORECAST behavior HIGH (per operational reality) All downstream product/post/gempak/verification tasks
exglobal_forecast.sh signature HIGH Single J-Job caller but all products depend on its output

Note: The MCP graph shows 0 direct graph dependents (suite leaf per recorded edges), but in operational reality this is the most critical job — every downstream product, post-processing, GEMPAK, AWIPS, verification, and archival task depends on its successful completion. The graph representation does not capture ecFlow trigger dependencies. Change risk in practice is CRITICAL.

Sources

  • On-disk v17 worktree: ecf/scripts/gfs/forecast/jgfs_fcst.ecf, dev/jobs/JGLOBAL_FORECAST.
  • agentcore-mcp-rag MCP (tenant gw_v17): get_change_impact.

Clone this wiki locally