Skip to content

CMIP7-Input Documentation

Welcome to the technical documentation for ACCESS-NRI/CMIP7-Input, the ancillary generation and forcing interpolation workflow for ACCESS-ESM1.6.

Overview

The CMIP7-Input suite automates the ingestion, regridding, temporal interpolation, formatting, and model configuration patching of CMIP7 input4MIPs datasets. Orchestrated by a unified Cylc 8 workflow, the system produces binary Unified Model (UM) ancillary files (.anc), ASCII boundary condition tables (.dat), and Fortran namelist patches (&clmchfcg, &coupling, &RUN_Radiation) required across historical, pre-industrial, emission-driven, and future projection climate experiments.

flowchart TD
    %% Custom Styles for W3C PROV Semantics
    classDef inputStyle fill:#e1f5fe,stroke:#0288d1,stroke-width:1.5px,color:#01579b
    classDef activityStyle fill:#e8f5e9,stroke:#2e7d32,stroke-width:1.5px,color:#1b5e20
    classDef outputStyle fill:#fff3e0,stroke:#e65100,stroke-width:1.5px,color:#bf360c
    classDef agentStyle fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1.5px,color:#4a148c
    classDef targetStyle fill:#ede7f6,stroke:#4527a0,stroke-width:2px,color:#311b92

    %% Top Level: Inputs and Agents
    subgraph S_TOP["1. Source Inputs and Orchestrating Agents"]
        direction LR
        subgraph S_IN["Input Entities (prov:Entity)"]
            direction TB
            E_Raw[("Primary input4MIPs NetCDF<br><code>/g/data/qv56/...</code>")]:::inputStyle
            E_Ref[("Reference Auxiliary Data<br><i>N96 qrparm.mask / CMIP6 DMS</i>")]:::inputStyle
        end

        subgraph Agents["Agents (prov:Agent)"]
            direction TB
            AgCylc{{"Cylc 8 Suite Scheduler"}}:::agentStyle
            AgPkg{{"esm1p6_ancil (Iris / Ants / Mule)"}}:::agentStyle
            AgUK{{"UKESM Upstream Pipelines"}}:::agentStyle
        end
    end

    %% Middle Level: Transformation Pipeline
    subgraph S_ACT["2. Transformation Pipeline (prov:Activity)"]
        direction TB
        A_Ingest["Ingest and Validate<br><i>variables, units, dimensions</i>"]:::activityStyle
        A_Combine["Select and Combine<br><i>sector sum, species and time slice</i>"]:::activityStyle
        A_Regrid["Regrid and Interpolate<br><i>N96 area-weighted, Jan 1 realignment</i>"]:::activityStyle
        A_Pack["Reformat and Encode<br><i>Mule binary / ASCII / namelists</i>"]:::activityStyle

        A_Ingest --> A_Combine --> A_Regrid --> A_Pack
    end

    %% Lower Middle Level: Output Entities
    subgraph S_OUT["3. Forcing Products (prov:Entity)"]
        direction TB
        E_Anc[("Binary Ancillaries (<code>.anc</code>)<br><i>Aerosols, Ozone, Nitrogen, CO2, AMIP</i>")]:::outputStyle
        E_Dat[("ASCII Forcing Tables (<code>.dat</code>)<br><i>Solar TSI, Volcanic SAOD</i>")]:::outputStyle
        E_Nml[("Fortran Namelist Patches<br><i>clmchfcg, coupling, RUN_Radiation</i>")]:::outputStyle
    end

    %% Bottom Level: Downstream Model Configuration
    subgraph S_DEPLOY["4. Downstream Model Configuration"]
        E_Model[["ACCESS-ESM1.6 Configs<br><code>ACCESS-NRI/access-esm1.6-configs</code>"]]:::targetStyle
    end

    %% Provenance Relationships (flowing Top -> Bottom)
    E_Raw -->|prov:used| A_Ingest
    E_Ref -->|prov:used| A_Regrid

    A_Pack -->|prov:wasGeneratedBy| E_Anc
    A_Pack -->|prov:wasGeneratedBy| E_Dat
    A_Pack -->|prov:wasGeneratedBy| E_Nml

    E_Anc -->|staged into| E_Model
    E_Dat -->|staged into| E_Model
    E_Nml -->|Git commit and push| E_Model

    %% Agent Associations
    AgPkg -.->|prov:wasAssociatedWith| A_Ingest
    AgPkg -.->|prov:wasAssociatedWith| A_Combine
    AgPkg -.->|prov:wasAssociatedWith| A_Regrid
    AgPkg -.->|prov:wasAssociatedWith| A_Pack
    AgUK -.->|prov:wasAssociatedWith| A_Regrid
    AgCylc -.->|orchestrates| S_ACT

Documentation Structure

This documentation is organized into three complementary perspectives to support workflow developers, domain scientists focused on specific physical forcings, and model operators configuring experiments:

1. Suite Orchestration & Configuration

Central orchestration, environment variables, and parameterization governing the Cylc 8 workflow suite:

  • Suite Configuration & Parameters Reference: A reference classifying suite configuration objects defined in rose-suite.conf and site/nci-gadi/variables.cylc. It documents master forcing switches (ANCIL_CREATE_*), experiment and scenario selectors (USE_EXP, USE_SCEN), timeline extension controls (EXTEND_SM_*), supercomputing site filesystem roots, input4MIPs dataset versions, target filenames, and downstream Git branch synchronization rules.

2. Forcing Specifications

Detailed 9-dimension technical specifications for all workflow tasks, grouped by physical forcing domain and sub-grouped by experiment:

  • Greenhouse Gases (GHG): Annual global-mean surface concentrations and &clmchfcg namelist patching.
  • Aerosol Emissions: Anthropogenic surface, aircraft, biomass burning, and background DMS emissions (BC, Bio, OC, SO2).
  • Carbon Dioxide Fluxes: Spatially distributed monthly surface CO2 emissions for carbon-cycle experiments.
  • Nitrogen Deposition: Reactive nitrogen deposition ancillaries (Ndep).
  • Ozone Pipeline: Multi-stage UKESM1 zonal-mean regridding and UM ozone ancillary generation.
  • Solar Irradiance: Total Solar Irradiance (TSI) constant and annual timeseries (TSI_CMIP7_ESM).
  • Volcanic Optical Depth: Stratospheric aerosol optical depth (SAOD) constants and timeseries (volcts_cmip7.dat).
  • AMIP (SST & Sea Ice): UKESM-derived sea surface temperature and sea-ice concentration ancillaries.
  • Configuration Git Synchronization: Automated cloning, branching, namelist injection, and git synchronisation for access-esm1.6-configs.

3. Experiments

Comprehensive pages covering experiment naming conventions, task execution flows, and configuration parameters for each supported climate experiment:

4. Python API Reference

Automated function-level API documentation generated via Sphinx:

  • Python API Reference: Complete reference covering all 55 modules and 192 functions in the esm1p6_ancil package across common utilities and 8 physical forcing domains (aerosol, amip, co2, ghg, nitrogen, ozone, solar, volcanic).

The 9 Technical Dimensions

Every task specification in this documentation provides exhaustive coverage across 9 technical dimensions:

  1. Description & Purpose: Physical domain scope and role in the workflow.
  2. CLI Arguments Passed: Complete command-line arguments and flags.
  3. Input4MIPs Versions & Temporal Coverage: Dataset versions, vdate timestamps, and date ranges.
  4. Input4MIPs Directory Paths & Filenames: Absolute source file paths and naming patterns.
  5. Python Scripts & Functions Called: Entrypoint script and internal calling structure.
  6. Function-Level Cube Transformations & Constraints: Input and created Iris cubes, coordinate bounds handling, and applied constraints (name, date, wavelength).
  7. Produced File Versions & Date Ranges: Ancillary versioning, temporal coverage, and calendar alignment.
  8. Produced File Directory Paths & Filenames: Destination paths and output filenames.
  9. Namelist Updates: Target namelist file, namelist group, and modified variables (or None for binary .anc files).

Licensing & Acknowledgments