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.

graph TD RawMIP["Input4MIPs NetCDF Replicas<br>/g/data/qv56/replicas/input4MIPs/CMIP7/"] --> Ingest["Ingestion and Validation<br>esm1p6_ancil Python Libraries"] Ingest --> CylcSuite["Cylc 8 Suite Orchestration<br>flow.cylc and rose-suite.conf"] CylcSuite --> ForcingGen["Forcing and Ancillary Engines<br>(Iris, Ants, Mule, NetCDF4)"] ForcingGen --> AncilFiles["Binary Ancillary Files (.anc)<br>Aerosols, Ozone, Nitrogen, CO2, AMIP SST/SeaIce"] ForcingGen --> AsciiFiles["ASCII Forcing Files (.dat)<br>Volcanic SAOD, Solar TSI"] ForcingGen --> NmlPatches["Model Namelist Patches<br>&amp;clmchfcg, &amp;coupling, &amp;RUN_Radiation"] AncilFiles --> DownstreamConfig["Downstream Model Configuration<br>ACCESS-NRI/access-esm1.6-configs"] AsciiFiles --> DownstreamConfig NmlPatches --> DownstreamConfig

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