Aerosol Forcing Specifications¶

The aerosol forcing suite processes CMIP7 monthly anthropogenic, aircraft, and biomass burning emissions alongside climatological marine dimethyl sulfide (DMS) emissions to manufacture binary Unified Model (UM) ancillary files (.anc) for the classic aerosol and sulfur cycle schemes in ACCESS-ESM1.6.

Physical Domain & Scientific Scope¶

Species & Output Ancillaries:
- Black Carbon (BC): Surface anthropogenic and aircraft black carbon emissions. Target STASH item: m01s00i057. Filename: BC_<range>_cmip7.anc.
- Organic Carbon (OC): Fossil fuel and anthropogenic organic carbon emissions. Target STASH item: m01s00i059. Filename: OCFF_<range>_cmip7.anc.
- Biomass Burning (Bio): Total particulate emissions from wildland fires, agricultural burning, and deforestation. Target STASH item: m01s00i086. Filename: Bio_<range>_cmip7.anc.
- Sulfur Cycle (SO2 / scycl): Multi-level sulfur dioxide emissions partitioned into low-level surface emissions (STASH item 58), high-level industrial/stack emissions (STASH item 126), and marine dimethyl sulfide (DMS). Filename: scycl_<range>_cmip7.anc.
Spatial Regridding & Masking: All species are regridded from native CMIP7 resolution ($0.5^\circ \times 0.5^\circ$) to the target atmospheric grid (global.N96, $1.875^\circ \times 1.25^\circ$) using conservative area-weighted regridding: $$\text{INTERPOLATION\_SCHEME} = \text{iris.analysis.AreaWeighted}(\text{mdtol}=0.5)$$ against the UM land-sea mask cube generated by esm_grid_mask_cube(args).
Polar Boundary Treatment: Due to the mathematical singularity at the poles on the regular latitude-longitude grid, zero_poles(cube) forces the outermost polar rows to 0.0 to prevent numerical instabilities.

Provenance & Dataflow Architecture¶

The aerosol pipeline follows the W3C PROV framework, explicitly separating Carbonaceous & Biomass Particulate Processing (BC, OCFF, Bio) from the multi-component Sulfur Cycle (SO2 / scycl, incorporating sector height splitting, sulfur scaling, and baseline DMS climatology tiling). Each experiment features dedicated dataflow diagrams for both streams: * Pre-Industrial Control (PI): Generates 1850 perpetual 12-month cyclic ancillaries for particulate species (BC_1850, OCFF_1850, Bio_1850) and the sulfur cycle (scycl_1850). See Pre-Industrial Experiment Dataflow Architecture. * Historical (HI): Generates continuous monthly multi-decadal time-series ancillaries spanning 1849–2023 for particulate species and the sulfur cycle. See Historical Experiment Dataflow Architecture. * ScenarioMIP (SM): Ingests baseline projection datasets and extension chunks (*-ext-*), concatenates time slices, and manufactures future ancillaries up to 2150 across both streams. See ScenarioMIP Experiment Dataflow Architecture.

Controlling Suite Switches¶

The execution and temporal extent of aerosol tasks are governed by parameters in rose-suite.conf:

Master Activation Switch: ANCIL_CREATE_AEROSOL = true
When set to false, all aerosol processing tasks across all experiments are excluded from the execution graph.
Experiment Activation: Governed by USE_EXP['PI'], USE_EXP['HI'], and USE_EXP['SM'].
Scenario Extension Controls (EXTEND_SM_AEROSOL):
Controls whether future pathways are generated through 2100 or extended to 2150 with --ext:
- 'h': True (Extended to 2150 via IIASA-IAMC-h-ext-1-1-1)
- 'hl': False (Bounded to 2100)
- 'm': False (Bounded to 2100)
- 'vl': True (Extended to 2150 via IIASA-IAMC-vl-ext-1-1-1)
Reference: See Suite Configuration & Parameters Reference for full object declarations.

1. Pre-Industrial Experiment (PI)¶

The pre-industrial aerosol suite generates cyclic 1850-representative annual ancillaries (12 monthly slices) for Black Carbon, Biomass Burning, Organic Carbon, and Sulfur Cycle emissions.

Dataflow Architecture¶

The pre-industrial aerosol workflow is divided into two distinct pipelines: 1. Carbonaceous & Biomass Particulate Pipeline: Processes Black Carbon (BC), Organic Carbon (OCFF), and Biomass Burning (Bio) emissions, regridding them conservatively to N96 and packaging single-variable 12-month cyclic ancillaries. 2. Sulfur Cycle Pipeline: Splits anthropogenic $\text{SO}_2$ into high-level and low-level emissions, scales sulfur mass, integrates baseline marine DMS climatology, and packages a composite 3-variable cyclic ancillary.

Carbonaceous & Biomass Particulate Pipeline (BC, OCFF, Bio)¶

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 Agents"]
        direction LR
        subgraph Inputs["Input Entities (prov:Entity)"]
            direction TB
            E_CEDS_BC[("1850 CEDS BC NetCDF<br><code>BC_em_anthro (surface and aircraft)</code>")]:::inputStyle
            E_CEDS_OC[("1850 CEDS OC NetCDF<br><code>OC_em_anthro (surface)</code>")]:::inputStyle
            E_Bio[("1850 BB4CMIP7 NetCDF<br><code>Biomass burning particulate</code>")]:::inputStyle
            E_Mask[("Reference Grid Mask<br><code>qrparm.mask (N96)</code>")]:::inputStyle
        end

        subgraph Agents["Agents (prov:Agent)"]
            direction TB
            AgCylc{{"Cylc 8 Suite Scheduler"}}:::agentStyle
            AgPy{{"esm1p6_ancil.aerosol (Iris, Ants, Mule)"}}:::agentStyle
        end
    end

    %% Middle Level: Transformation Pipeline
    subgraph S_ACT["2. Transformation Pipeline (prov:Activity)"]
        direction TB
        A_Comb["Sum Sectors and AreaWeighted Regrid<br><i>collapse sectors, AreaWeighted(mdtol=0.5) to N96, zero poles</i>"]:::activityStyle
        A_Mule_C["Pack Single-Variable Ancillaries<br><i>STASH 57 (BC), 59 (OCFF), 86 (Bio)</i>"]:::activityStyle
        A_Comb --> A_Mule_C
    end

    %% Lower Level: Output Entities
    subgraph Outputs["3. Output Entities (prov:Entity)"]
        direction TB
        E_BC[("BC Cyclic Ancillary<br><code>BC_1850_cmip7.anc (STASH 57)</code>")]:::outputStyle
        E_Bio_Anc[("Biomass Cyclic Ancillary<br><code>Bio_1850_cmip7.anc (STASH 86)</code>")]:::outputStyle
        E_OC[("OCFF Cyclic Ancillary<br><code>OCFF_1850_cmip7.anc (STASH 59)</code>")]:::outputStyle
    end

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

    %% Relationships
    E_CEDS_BC & E_CEDS_OC & E_Bio -->|prov:used| A_Comb
    E_Mask -->|prov:used| A_Comb

    A_Mule_C -->|prov:wasGeneratedBy| E_BC & E_Bio_Anc & E_OC

    E_BC & E_Bio_Anc & E_OC -->|staged for model execution| E_Model

    %% Agent Associations
    AgPy -.->|prov:wasAssociatedWith| A_Comb
    AgPy -.->|prov:wasAssociatedWith| A_Mule_C
    AgCylc -.->|orchestrates| S_ACT

Sulfur Cycle Pipeline (scycl)¶

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 Agents"]
        direction LR
        subgraph Inputs["Input Entities (prov:Entity)"]
            direction TB
            E_CEDS_SO2[("1850 CEDS SO2 NetCDFs<br><code>SO2_em_anthro (surface and aircraft)</code>")]:::inputStyle
            E_DMS[("Baseline CMIP6 DMS Ancillary<br><code>dms_1850.anc (marine DMS)</code>")]:::inputStyle
            E_Mask[("Reference Grid Mask<br><code>qrparm.mask (N96)</code>")]:::inputStyle
        end

        subgraph Agents["Agents (prov:Agent)"]
            direction TB
            AgCylc{{"Cylc 8 Suite Scheduler"}}:::agentStyle
            AgPy{{"esm1p6_ancil.aerosol (Iris, Ants, Mule)"}}:::agentStyle
        end
    end

    %% Middle Level: Transformation Pipeline
    subgraph S_ACT["2. Transformation Pipeline (prov:Activity)"]
        direction TB
        A_Split["Split SO2 Sectors<br><i>High: Energy + 50% Ind (STASH 126)<br>Low: remaining surface (STASH 58)</i>"]:::activityStyle
        A_Scale["Scale Mass of Sulfur<br><i>factor of 0.5 (SO2 -> S)</i>"]:::activityStyle
        A_Regrid["AreaWeighted Regrid and Zero Poles<br><i>AreaWeighted(mdtol=0.5) to N96</i>"]:::activityStyle
        A_DMS["Calendar Alignment<br><i>fix_esm15_pi_ancil_date on DMS</i>"]:::activityStyle
        A_Mule_S["Pack Sulfur Ancillary<br><i>save_ancil([so2_low, so2_high, dms])</i>"]:::activityStyle

        A_Split --> A_Scale --> A_Regrid --> A_Mule_S
        A_DMS --> A_Mule_S
    end

    %% Lower Level: Output Entities
    subgraph Outputs["3. Output Entities (prov:Entity)"]
        direction TB
        E_Scycl[("Sulfur Cycle Ancillary<br><code>scycl_1850_cmip7.anc (items 58, 126, DMS)</code>")]:::outputStyle
    end

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

    %% Relationships
    E_CEDS_SO2 -->|prov:used| A_Split
    E_Mask -->|prov:used| A_Regrid
    E_DMS -->|prov:used| A_DMS

    A_Mule_S -->|prov:wasGeneratedBy| E_Scycl

    E_Scycl -->|staged for model execution| E_Model

    %% Agent Associations
    AgPy -.->|prov:wasAssociatedWith| A_Split
    AgPy -.->|prov:wasAssociatedWith| A_Scale
    AgPy -.->|prov:wasAssociatedWith| A_Regrid
    AgPy -.->|prov:wasAssociatedWith| A_DMS
    AgPy -.->|prov:wasAssociatedWith| A_Mule_S
    AgCylc -.->|orchestrates| S_ACT

`PI_ancil_aerosol_BC`¶

1. Description & Purpose: Interpolates CMIP7 1850 anthropogenic surface Black Carbon emissions to the N96 grid, assigns STASH item 57, and saves BC_1850_cmip7.anc.

2. CLI Arguments:

python -m esm1p6_ancil.aerosol.cmip7_PI_BC_interpolate \
    --ancil-target-dirname "${VAR.ANCIL_TARGET_PATH}" \
    # Current: "/g/data/${PROJECT}/${USER}/CMIP7/esm1p6_ancil/$(isodatetime -f CCYY.MM.DD)"
    --cmip7-source-data-dirname "${VAR.CMIP7_SOURCE_PATH}" \
    # Current: "/g/data/qv56/replicas/input4MIPs/CMIP7"
    --esm15-inputs-dirname "${VAR.ESM15_INPUTS_PATH}" \
    # Current: "/g/data/vk83/configurations/inputs/access-esm1p5"
    --esm-grid-rel-dirname "${ESM_GRID_DIRNAME}" \
    # Current: "global.N96"
    --esm15-grid-version "${ESM15_GRID_VERSION}" \
    # Current: "2020.05.19"
    --dataset-version "${CMIP7_AEROSOL_ANTHRO_VERSION}" \
    # Current: "CEDS-CMIP-2025-04-18"
    --dataset-vdate "${CMIP7_AEROSOL_ANTHRO_VDATE}" \
    # Current: "v20250421"
    --dataset-date-range "${CMIP7_PI_AEROSOL_ANTHRO_DATE_RANGE}" \
    # Current: "185001-189912"
    --save-filename "${ESM_PI_AEROSOL_SAVE_FILENAME['BC']}"
    # Current: "BC_1850_cmip7.anc"

3. Input4MIPs Metadata: Version ${CMIP7_AEROSOL_ANTHRO_VERSION} (CEDS-CMIP-2025-04-18), date tag ${CMIP7_AEROSOL_ANTHRO_VDATE} (v20250421), range ${CMIP7_PI_AEROSOL_ANTHRO_DATE_RANGE} (185001-189912).
4. Input4MIPs Path: ${VAR.CMIP7_SOURCE_PATH}/CMIP/CEDS/${CMIP7_AEROSOL_ANTHRO_VERSION}/atmos/mon/BC_em_anthro/gn/${CMIP7_AEROSOL_ANTHRO_VDATE}/
(Evaluated: /g/data/qv56/replicas/input4MIPs/CMIP7/CMIP/CEDS/CEDS-CMIP-2025-04-18/atmos/mon/BC_em_anthro/gn/v20250421/)
5. Scripts & Functions: esm1p6_ancil.aerosol.cmip7_PI_BC_interpolate, load_cmip7_pi_aerosol_anthro, cmip7_aerosol_anthro_interpolate, esm_grid_mask_cube, zero_poles, save_ancil.
6. Cube Transformations: Loads 4D (time, sector, lat, lon) cube via load_cmip7_aerosol, collapses sectors (collapsed(["sector"], SUM)), regrids with AreaWeighted(mdtol=0.5), zero poles, assigns STASH m01s00i057.
7. Produced Coverage: 12 monthly slices for year 1850, STASH m01s00i057. Filename: ${ESM_PI_AEROSOL_SAVE_FILENAME['BC']} (BC_1850_cmip7.anc).
8. Output Path: ${VAR.ANCIL_TARGET_PATH}/modern/pre-industrial/atmosphere/aerosol/${ESM_GRID_DIRNAME}/<DATE>/${ESM_PI_AEROSOL_SAVE_FILENAME['BC']}.
9. Namelist Updates: None (Generates binary ancillary .anc file).

`PI_ancil_aerosol_Bio`¶

Outputs: Bio_1850_cmip7.anc (STASH m01s00i086).
Source Dataset: DRES-CMIP-BB4CMIP7-2-0, v20250227, range 175001-189912.
Script: esm1p6_ancil.aerosol.cmip7_PI_Bio_interpolate.

`PI_ancil_aerosol_OC`¶

Outputs: OCFF_1850_cmip7.anc (STASH m01s00i059).
Source Dataset: CEDS-CMIP-2025-04-18, v20250421, range 185001-189912.
Script: esm1p6_ancil.aerosol.cmip7_PI_OC_interpolate.

`PI_ancil_aerosol_SO2`¶

Outputs: scycl_1850_cmip7.anc (contains items 58, 126, and background DMS).
Source Dataset: CEDS-CMIP-2025-04-18 + baseline DMS ancillary dms_1850.anc.
Script: esm1p6_ancil.aerosol.cmip7_PI_SO2_interpolate.
Cube Pipeline: Splits SO2 into high stack and low surface components, regrids both, fixes 360-day calendar bounds on DMS via fix_esm15_pi_ancil_date, and combines 3 cubes into the output file.

2. Historical Experiment (HI)¶

Dataflow Architecture¶

The historical aerosol workflow processes continuous multi-decadal time series (1849–2023) across two distinct pipelines: 1. Carbonaceous & Biomass Particulate Pipeline: Aggregates continuous monthly emissions for Black Carbon (BC), Organic Carbon (OCFF), and Biomass Burning (Bio), regrids to N96, and produces continuous 175-year single-variable ancillaries. 2. Sulfur Cycle Pipeline: Decomposes continuous $\text{SO}_2$ into high/low stacks, scales elemental sulfur mass, tiles 12-month marine DMS climatology across 175 years, and packages a multi-variable time-series ancillary (scycl_1849_2023_cmip7.anc).

Carbonaceous & Biomass Particulate Pipeline (BC, OCFF, Bio)¶

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 Agents"]
        direction LR
        subgraph Inputs["Input Entities (prov:Entity)"]
            direction TB
            E_HI_BC[("Historical CEDS BC NetCDFs<br><code>BC_em_anthro (1849-2023)</code>")]:::inputStyle
            E_HI_OC[("Historical CEDS OC NetCDFs<br><code>OC_em_anthro (1849-2023)</code>")]:::inputStyle
            E_HI_Bio[("Historical BB4CMIP7 NetCDFs<br><code>Biomass burning (1849-2023)</code>")]:::inputStyle
            E_Mask[("Reference Grid Mask<br><code>qrparm.mask (N96)</code>")]:::inputStyle
        end

        subgraph Agents["Agents (prov:Agent)"]
            direction TB
            AgCylc{{"Cylc 8 Suite Scheduler"}}:::agentStyle
            AgPy{{"esm1p6_ancil.aerosol (Iris, Ants, Mule)"}}:::agentStyle
        end
    end

    %% Middle Level: Transformation Pipeline
    subgraph S_ACT["2. Transformation Pipeline (prov:Activity)"]
        direction TB
        A_Comb["Sum Multi-Year Sectors and Regrid<br><i>AreaWeighted N96, zero_poles, timeline padding</i>"]:::activityStyle
        A_Mule_C["Pack Single-Variable Ancillaries<br><i>STASH 57 (BC), 59 (OCFF), 86 (Bio)</i>"]:::activityStyle
        A_Comb --> A_Mule_C
    end

    %% Lower Level: Output Entities
    subgraph Outputs["3. Output Entities (prov:Entity)"]
        direction TB
        E_HI_Ancs[("Historical Particulate Ancillaries (1849-2023)<br><code>BC, Bio, OCFF_1849_2023_cmip7.anc</code>")]:::outputStyle
    end

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

    %% Relationships
    E_HI_BC & E_HI_OC & E_HI_Bio -->|prov:used| A_Comb
    E_Mask -->|prov:used| A_Comb

    A_Mule_C -->|prov:wasGeneratedBy| E_HI_Ancs

    E_HI_Ancs -->|staged for model execution| E_Model

    %% Agent Associations
    AgPy -.->|prov:wasAssociatedWith| A_Comb
    AgPy -.->|prov:wasAssociatedWith| A_Mule_C
    AgCylc -.->|orchestrates| S_ACT

Sulfur Cycle Pipeline (scycl)¶

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 Agents"]
        direction LR
        subgraph Inputs["Input Entities (prov:Entity)"]
            direction TB
            E_HI_SO2[("Historical CEDS SO2 NetCDFs<br><code>SO2_em_anthro (1849-2023)</code>")]:::inputStyle
            E_DMS[("Baseline CMIP6 DMS Ancillary<br><code>dms_1850.anc (12-month climatology)</code>")]:::inputStyle
            E_Mask[("Reference Grid Mask<br><code>qrparm.mask (N96)</code>")]:::inputStyle
        end

        subgraph Agents["Agents (prov:Agent)"]
            direction TB
            AgCylc{{"Cylc 8 Suite Scheduler"}}:::agentStyle
            AgPy{{"esm1p6_ancil.aerosol (Iris, Ants, Mule)"}}:::agentStyle
        end
    end

    %% Middle Level: Transformation Pipeline
    subgraph S_ACT["2. Transformation Pipeline (prov:Activity)"]
        direction TB
        A_Split["Split SO2 Sectors (High/Low)<br><i>High: STASH 126 | Low: STASH 58</i>"]:::activityStyle
        A_Scale["Scale Mass of Sulfur<br><i>factor of 0.5 (SO2 -> S)</i>"]:::activityStyle
        A_Tile["Time-Tile DMS Climatology<br><i>repeat 12 months across 175 years (1849-2023)</i>"]:::activityStyle
        A_Regrid["AreaWeighted Regrid and Zero Poles<br><i>AreaWeighted(mdtol=0.5) to N96</i>"]:::activityStyle
        A_Mule_S["Pack Sulfur Time-Series Ancillary<br><i>save_ancil([so2_low, so2_high, dms])</i>"]:::activityStyle

        A_Split --> A_Scale --> A_Regrid --> A_Mule_S
        A_Tile --> A_Mule_S
    end

    %% Lower Level: Output Entities
    subgraph Outputs["3. Output Entities (prov:Entity)"]
        direction TB
        E_HI_Scycl[("Historical Sulfur Cycle Ancillary<br><code>scycl_1849_2023_cmip7.anc (1849-2023)</code>")]:::outputStyle
    end

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

    %% Relationships
    E_HI_SO2 -->|prov:used| A_Split
    E_Mask -->|prov:used| A_Regrid
    E_DMS -->|prov:used| A_Tile

    A_Mule_S -->|prov:wasGeneratedBy| E_HI_Scycl

    E_HI_Scycl -->|staged for model execution| E_Model

    %% Agent Associations
    AgPy -.->|prov:wasAssociatedWith| A_Split
    AgPy -.->|prov:wasAssociatedWith| A_Scale
    AgPy -.->|prov:wasAssociatedWith| A_Regrid
    AgPy -.->|prov:wasAssociatedWith| A_Tile
    AgPy -.->|prov:wasAssociatedWith| A_Mule_S
    AgCylc -.->|orchestrates| S_ACT

The historical aerosol suite produces continuous time-series monthly ancillary files spanning 1849 to 2023 (including model padding years).

Task Name	Script Entrypoint	Primary Input Dataset	Output Ancillary Filename	STASH Code
`HI_ancil_aerosol_BC`	`aerosol.cmip7_HI_BC_interpolate`	`CEDS-CMIP-2025-04-18`	`BC_1849_2023_cmip7.anc`	57
`HI_ancil_aerosol_Bio`	`aerosol.cmip7_HI_Bio_interpolate`	`DRES-CMIP-BB4CMIP7-2-0`	`Bio_1849_2023_cmip7.anc`	86
`HI_ancil_aerosol_OC`	`aerosol.cmip7_HI_OC_interpolate`	`CEDS-CMIP-2025-04-18`	`OCFF_1849_2023_cmip7.anc`	59
`HI_ancil_aerosol_SO2`	`aerosol.cmip7_HI_SO2_interpolate`	`CEDS-CMIP` + ESM1.5 DMS	`scycl_1849_2023_cmip7.anc`	58, 126, DMS

`HI_ancil_aerosol_SO2` Specification Details¶

1. Description & Purpose: Generates historical sulfur cycle emissions (1849–2023). Ingests chunked historical files (180001-184912 through 200001-202312), decomposes into low-level and high-level emissions, tiles climatological DMS across 175 years, and writes ${ESM_HI_AEROSOL_SAVE_FILENAME['SO2']} (scycl_1849_2023_cmip7.anc).

2. CLI Arguments:

python -m esm1p6_ancil.aerosol.cmip7_HI_SO2_interpolate \
    --ancil-target-dirname "${VAR.ANCIL_TARGET_PATH}" \
    # Current: "/g/data/${PROJECT}/${USER}/CMIP7/esm1p6_ancil/$(isodatetime -f CCYY.MM.DD)"
    --cmip7-source-data-dirname "${VAR.CMIP7_SOURCE_PATH}" \
    # Current: "/g/data/qv56/replicas/input4MIPs/CMIP7"
    --esm15-inputs-dirname "${VAR.ESM15_INPUTS_PATH}" \
    # Current: "/g/data/vk83/configurations/inputs/access-esm1p5"
    --esm-grid-rel-dirname "${ESM_GRID_DIRNAME}" \
    # Current: "global.N96"
    --esm15-grid-version "${ESM15_GRID_VERSION}" \
    # Current: "2020.05.19"
    --dataset-version "${CMIP7_AEROSOL_ANTHRO_VERSION}" \
    # Current: "CEDS-CMIP-2025-04-18"
    --dataset-vdate "${CMIP7_AEROSOL_ANTHRO_VDATE}" \
    # Current: "v20250421"
    --dataset-date-range-list "${CMIP7_HI_AEROSOL_ANTHRO_DATE_RANGE_LIST}" \
    # Current: "['180001-184912','185001-189912','190001-194912','195001-199912','200001-202312']"
    --esm15-aerosol-version "${ESM15_AEROSOL_VERSION['HI']}" \
    # Current: "2021.06.22"
    --save-filename "${ESM_HI_AEROSOL_SAVE_FILENAME['SO2']}"
    # Current: "scycl_1849_2023_cmip7.anc"

6. Cube Transformations:
- Uses netCDF4.Dataset to extract sector indices for Energy and Industrial.
- Computes high-level emissions: cmip7_so2[:, Energy] + 0.5 * cmip7_so2[:, Industrial].
- Computes low-level emissions: cmip7_so2.collapsed(["sector"], SUM) - cmip7_so2_high.
- Scales by 0.5 to convert molecular SO2 to mass of elemental Sulfur ($S$).
- Regrids via AreaWeighted(mdtol=0.5) to N96 grid, fills missing values with 0.0, and zeroes poles.
- Climatological DMS is read from dms_1850.anc, date-converted from 360-day to Gregorian calendar via fix_esm15_pi_ancil_date, tiled across 175 years using tile_yearly_data, and packaged into a matching 3D Cube.
7. Produced Coverage: 1849–2023 (2100 monthly slices). STASH items 58, 126, and DMS. Output file: ${ESM_HI_AEROSOL_SAVE_FILENAME['SO2']} (scycl_1849_2023_cmip7.anc).
8. Destination Path: ${VAR.ANCIL_TARGET_PATH}/modern/historical/atmosphere/aerosol/${ESM_GRID_DIRNAME}/<DATE>/${ESM_HI_AEROSOL_SAVE_FILENAME['SO2']}.

3. ScenarioMIP Experiment (SM)¶

Dataflow Architecture¶

The ScenarioMIP aerosol suite manufactures future projection ancillaries across scenarios h, hl, m, and vl spanning 2022 to 2150 (when --ext is activated), structured into two distinct pipelines: 1. Carbonaceous & Biomass Particulate Pipeline: Processes baseline (2022–2100) and extension (2101–2150) Black Carbon, Organic Carbon, and Biomass Burning emissions, concatenates chunks via --ext, and packages single-variable future ancillaries (BC, OCFF, Bio). 2. Sulfur Cycle Pipeline: Ingests baseline and extension surface and aircraft $\text{SO}_2$ emissions, validates extension availability via check_aerosol_ext_available, splits high/low injection sectors, tiles marine DMS across 129 years (2022–2150), and writes multi-variable future ancillaries (scycl_SCEN_2022_2150_cmip7.anc).

Carbonaceous & Biomass Particulate Pipeline (BC, OCFF, Bio)¶

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 Agents"]
        direction LR
        subgraph Inputs["Input Entities (prov:Entity)"]
            direction TB
            E_Base_CEDS[("Base ScenarioMIP CEDS NetCDFs<br><code>IIASA-IAMC-SCEN-1-1-1 (BC, OC, 2022-2100)</code>")]:::inputStyle
            E_Ext_CEDS[("Extension CEDS NetCDFs<br><code>IIASA-IAMC-SCEN-ext-1-1-1 (2101-2150)</code>")]:::inputStyle
            E_Base_Bio[("Base BB4CMIP7 NetCDFs<br><code>BB4CMIP7-SCEN-1-0 (2022-2100)</code>")]:::inputStyle
            E_Ext_Bio[("Extension BB4CMIP7 NetCDFs<br><code>BB4CMIP7-SCEN-ext-1-0 (2101-2150)</code>")]:::inputStyle
            E_Mask[("Reference Grid Mask<br><code>qrparm.mask (N96)</code>")]:::inputStyle
        end

        subgraph Agents["Agents (prov:Agent)"]
            direction TB
            AgCylc{{"Cylc 8 Suite Scheduler"}}:::agentStyle
            AgPy{{"esm1p6_ancil.aerosol (Iris, Ants, Mule)"}}:::agentStyle
        end
    end

    %% Middle Level: Transformation Pipeline
    subgraph S_ACT["2. Transformation Pipeline (prov:Activity)"]
        direction TB
        A_Validate["Validate Extension Availability<br><i>check_aerosol_ext_available (--ext)</i>"]:::activityStyle
        A_Concat["Concatenate Time Chunks<br><i>CubeList.concatenate_cube (2022-2150)</i>"]:::activityStyle
        A_Comb["Sum Multi-Year Sectors and Regrid<br><i>AreaWeighted N96, zero_poles</i>"]:::activityStyle
        A_Mule_C["Pack Single-Variable Ancillaries<br><i>STASH 57 (BC), 59 (OCFF), 86 (Bio)</i>"]:::activityStyle

        A_Validate --> A_Concat --> A_Comb --> A_Mule_C
    end

    %% Lower Level: Output Entities
    subgraph Outputs["3. Output Entities (prov:Entity)"]
        direction TB
        E_SM_Part[("ScenarioMIP Particulate Ancillaries<br><code>BC, Bio, OCFF_SCEN_2022_2150_cmip7.anc</code>")]:::outputStyle
    end

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

    %% Relationships
    E_Base_CEDS & E_Ext_CEDS & E_Base_Bio & E_Ext_Bio -->|prov:used| A_Validate
    E_Mask -->|prov:used| A_Comb

    A_Mule_C -->|prov:wasGeneratedBy| E_SM_Part

    E_SM_Part -->|staged for model execution| E_Model

    %% Agent Associations
    AgPy -.->|prov:wasAssociatedWith| A_Validate
    AgPy -.->|prov:wasAssociatedWith| A_Concat
    AgPy -.->|prov:wasAssociatedWith| A_Comb
    AgPy -.->|prov:wasAssociatedWith| A_Mule_C
    AgCylc -.->|orchestrates| S_ACT

Sulfur Cycle Pipeline (scycl)¶

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 Agents"]
        direction LR
        subgraph Inputs["Input Entities (prov:Entity)"]
            direction TB
            E_Base_SO2[("Base ScenarioMIP SO2 NetCDFs<br><code>IIASA-IAMC-SCEN-1-1-1 (surface, 2022-2100)</code>")]:::inputStyle
            E_Base_Air[("Base ScenarioMIP SO2 Aircraft<br><code>IIASA-IAMC-SCEN-1-1-2 (aircraft, 2022-2100)</code>")]:::inputStyle
            E_Ext_SO2[("Extension SO2 NetCDF<br><code>IIASA-IAMC-SCEN-ext-1-1-1 (2101-2150)</code>")]:::inputStyle
            E_DMS[("Baseline CMIP6 DMS Ancillary<br><code>dms_1850.anc (12-month climatology)</code>")]:::inputStyle
            E_Mask[("Reference Grid Mask<br><code>qrparm.mask (N96)</code>")]:::inputStyle
        end

        subgraph Agents["Agents (prov:Agent)"]
            direction TB
            AgCylc{{"Cylc 8 Suite Scheduler"}}:::agentStyle
            AgPy{{"esm1p6_ancil.aerosol (Iris, Ants, Mule)"}}:::agentStyle
        end
    end

    %% Middle Level: Transformation Pipeline
    subgraph S_ACT["2. Transformation Pipeline (prov:Activity)"]
        direction TB
        A_Validate["Validate Extension Availability<br><i>check_aerosol_ext_available (--ext)</i>"]:::activityStyle
        A_Concat["Concatenate Time Chunks<br><i>CubeList.concatenate_cube (2022-2150)</i>"]:::activityStyle
        A_Split["Split SO2 Sectors (High/Low)<br><i>High: STASH 126 | Low: STASH 58</i>"]:::activityStyle
        A_Scale["Scale Mass of Sulfur<br><i>factor of 0.5 (SO2 -> S)</i>"]:::activityStyle
        A_Tile["Time-Tile DMS Climatology<br><i>repeat 12 months across 129 years (2022-2150)</i>"]:::activityStyle
        A_Regrid["AreaWeighted Regrid and Zero Poles<br><i>AreaWeighted(mdtol=0.5) to N96</i>"]:::activityStyle
        A_Mule_S["Pack Sulfur Time-Series Ancillary<br><i>save_ancil([so2_low, so2_high, dms])</i>"]:::activityStyle

        A_Validate --> A_Concat --> A_Split --> A_Scale --> A_Regrid --> A_Mule_S
        A_Tile --> A_Mule_S
    end

    %% Lower Level: Output Entities
    subgraph Outputs["3. Output Entities (prov:Entity)"]
        direction TB
        E_SM_Scycl[("ScenarioMIP Sulfur Cycle Ancillary<br><code>scycl_SCEN_2022_2150_cmip7.anc (items 58, 126, DMS)</code>")]:::outputStyle
    end

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

    %% Relationships
    E_Base_SO2 & E_Base_Air & E_Ext_SO2 -->|prov:used| A_Validate
    E_Mask -->|prov:used| A_Regrid
    E_DMS -->|prov:used| A_Tile

    A_Mule_S -->|prov:wasGeneratedBy| E_SM_Scycl

    E_SM_Scycl -->|staged for model execution| E_Model

    %% Agent Associations
    AgPy -.->|prov:wasAssociatedWith| A_Validate
    AgPy -.->|prov:wasAssociatedWith| A_Concat
    AgPy -.->|prov:wasAssociatedWith| A_Split
    AgPy -.->|prov:wasAssociatedWith| A_Scale
    AgPy -.->|prov:wasAssociatedWith| A_Regrid
    AgPy -.->|prov:wasAssociatedWith| A_Tile
    AgPy -.->|prov:wasAssociatedWith| A_Mule_S
    AgCylc -.->|orchestrates| S_ACT

The ScenarioMIP aerosol suite manufactures future projection ancillaries across scenarios h, hl, m, and vl. When extension is active (EXTEND_SM_AEROSOL[SCEN] == True, passing --ext), datasets concatenate extension files to span the full timeline to 2150.

`SM_{h,hl,m,vl}_ancil_aerosol_SO2`¶

Scenario h (High)Scenario hl (High-Low)Scenario m (Medium)Scenario vl (Very Low)

1. Description & Purpose: Generates sulfur cycle emissions ancillaries for ScenarioMIP scenario h. Combines anthropogenic surface emissions, aircraft emissions, and biomass burning emissions from CMIP7 with background dimethyl sulfide (DMS) emissions from CMIP6/ESM1.5 inputs. Interpolates monthly fields, handles extension to 2150 with constant padding if EXTEND_SM_AEROSOL['h'] is active (--ext), zeroes the poles, assigns STASH code 89, and saves the .anc file.

2. CLI Arguments:

python -m esm1p6_ancil.aerosol.cmip7_SM_SO2_interpolate \
    --scenario "${SCEN}" \
    # Current: "h"
    --ancil-target-dirname "${VAR.ANCIL_TARGET_PATH}" \
    # Current: "/g/data/${PROJECT}/${USER}/CMIP7/esm1p6_ancil/$(isodatetime -f CCYY.MM.DD)"
    --cmip7-source-data-dirname "${VAR.CMIP7_SOURCE_PATH}" \
    # Current: "/g/data/qv56/replicas/input4MIPs/CMIP7"
    --esm15-inputs-dirname "${VAR.ESM15_INPUTS_PATH}" \
    # Current: "/g/data/vk83/configurations/inputs/access-esm1p5"
    --esm-grid-rel-dirname "${ESM_GRID_DIRNAME}" \
    # Current: "global.N96"
    --esm15-grid-version "${ESM15_GRID_VERSION}" \
    # Current: "2020.05.19"
    --dataset-version "${CMIP7_SM_AEROSOL_VERSION[SCEN]}" \
    # Current: "IIASA-IAMC-h-1-1-1"
    --dataset-vdate "${CMIP7_SM_AEROSOL_VDATE[SCEN]}" \
    # Current: "v20260409"
    --dataset-date-range "${CMIP7_SM_AEROSOL_DATE_RANGE}" \
    # Current: "202201-210012"
    --esm15-aerosol-version "${ESM15_AEROSOL_VERSION['PI']}" \
    # Current: "2020.05.19"
    --ext \
    --dataset-ext-version "${CMIP7_SM_EXT_AEROSOL_VERSION[SCEN]}" \
    # Current: "IIASA-IAMC-h-ext-1-1-1"
    --dataset-ext-vdate "${CMIP7_SM_EXT_AEROSOL_VDATE[SCEN]}" \
    # Current: "v20260409"
    --dataset-ext-date-range "${CMIP7_SM_EXT_AEROSOL_DATE_RANGE}" \
    # Current: "210101-215012"
    --save-filename "${ESM_SM_EXT_AEROSOL_SAVE_FILENAME[SCEN]['SO2']}"
    # Current: "scycl_h_2022_2150_cmip7.anc"

3. Input4MIPs Versions & Temporal Metadata:
- Surface Anthro: ${CMIP7_SM_AEROSOL_VERSION['h']} (IIASA-IAMC-h-1-1-1), ${CMIP7_SM_AEROSOL_VDATE['h']} (v20260409), ${CMIP7_SM_AEROSOL_DATE_RANGE} (202201-210012)
- Aircraft Anthro: ${CMIP7_SM_AEROSOL_AIR_VERSION['h']} (IIASA-IAMC-h-1-1-2), ${CMIP7_SM_AEROSOL_AIR_VDATE['h']} (v20260624), ${CMIP7_SM_AEROSOL_DATE_RANGE} (202201-210012)
- Extension Anthro: ${CMIP7_SM_EXT_AEROSOL_VERSION['h']} (IIASA-IAMC-h-ext-1-1-1), ${CMIP7_SM_EXT_AEROSOL_VDATE['h']} (v20260409), ${CMIP7_SM_EXT_AEROSOL_DATE_RANGE} (210101-215012)
- Baseline DMS: ${ESM15_AEROSOL_VERSION['PI']} (2020.05.19, dms_1850.anc)
4. Input4MIPs Directory Path & Filenames:
- Surface: ${VAR.CMIP7_SOURCE_PATH}/ScenarioMIP/IIASA-IAMC/${CMIP7_SM_AEROSOL_VERSION['h']}/atmos/mon/SO2_em_anthro/gn/${CMIP7_SM_AEROSOL_VDATE['h']}/SO2-em-anthro_input4MIPs_emissions_ScenarioMIP_${CMIP7_SM_AEROSOL_VERSION['h']}_gn_${CMIP7_SM_AEROSOL_DATE_RANGE}.nc
- Aircraft: ${VAR.CMIP7_SOURCE_PATH}/ScenarioMIP/IIASA-IAMC/${CMIP7_SM_AEROSOL_AIR_VERSION['h']}/atmos/mon/SO2_em_AIR_anthro/gn/${CMIP7_SM_AEROSOL_AIR_VDATE['h']}/SO2-em-AIR-anthro_input4MIPs_emissions_ScenarioMIP_${CMIP7_SM_AEROSOL_AIR_VERSION['h']}_gn_${CMIP7_SM_AEROSOL_DATE_RANGE}.nc
- Extension: ${VAR.CMIP7_SOURCE_PATH}/ScenarioMIP/IIASA-IAMC/${CMIP7_SM_EXT_AEROSOL_VERSION['h']}/atmos/mon/SO2_em_anthro/gn/${CMIP7_SM_EXT_AEROSOL_VDATE['h']}/SO2-em-anthro_input4MIPs_emissions_ScenarioMIP_${CMIP7_SM_EXT_AEROSOL_VERSION['h']}_gn_${CMIP7_SM_EXT_AEROSOL_DATE_RANGE}.nc
5. Scripts & Functions: esm1p6_ancil.aerosol.cmip7_SM_SO2_interpolate, load_cmip7_sm_so2_aerosol_anthro, load_cmip7_sm_aerosol_anthro, load_sm_dms, load_dms, save_cmip7_so2_aerosol_anthro, tile_yearly_data, zero_poles, esm_grid_mask_cube, save_ancil.
6. Cube Transformations:
- Base cube (2022–2100) constrained by cmip7_date_constraint_from_years(2022, 2100).
- Extension cube (2101–2150) constrained by cmip7_date_constraint_from_years(2101, 2150).
- Concatenated via CubeList.concatenate_cube() after attribute equalization.
- High and low components separated via sector indices, scaled by 0.5, regridded to N96, and zeroed at poles.
- DMS cube constructed by tiling 12-month climatology across 129 years.
7. Produced File: ${ESM_SM_EXT_AEROSOL_SAVE_FILENAME['h']['SO2']} (scycl_h_2022_2150_cmip7.anc, 1548 monthly slices, 2022–2150).
8. Destination Path: ${VAR.ANCIL_TARGET_PATH}/modern/scen7-h/atmosphere/aerosol/${ESM_GRID_DIRNAME}/<DATE>/${ESM_SM_EXT_AEROSOL_SAVE_FILENAME['h']['SO2']}.
9. Namelist Updates: None (Generates binary ancillary .anc file).

Dataset Versions: Base IIASA-IAMC-hl-1-1-1 (v20260327), Extension IIASA-IAMC-hl-ext-1-1-1 (v20260327).
Produces: BC_hl_2022_2150_cmip7.anc, Bio_hl_2022_2150_cmip7.anc, OCFF_hl_2022_2150_cmip7.anc, scycl_hl_2022_2150_cmip7.anc.

Dataset Versions: Base IIASA-IAMC-m-1-1-1 (v20260327), Extension IIASA-IAMC-m-ext-1-1-1 (v20260327).
Produces: BC_m_2022_2150_cmip7.anc, Bio_m_2022_2150_cmip7.anc, OCFF_m_2022_2150_cmip7.anc, scycl_m_2022_2150_cmip7.anc.

Dataset Versions: Base IIASA-IAMC-vl-1-1-1 (v20260409), Extension IIASA-IAMC-vl-ext-1-1-1 (v20260409).
Produces: BC_vl_2022_2150_cmip7.anc, Bio_vl_2022_2150_cmip7.anc, OCFF_vl_2022_2150_cmip7.anc, scycl_vl_2022_2150_cmip7.anc.

Aerosol Forcing Specifications¶

Physical Domain & Scientific Scope¶

Provenance & Dataflow Architecture¶

Controlling Suite Switches¶

1. Pre-Industrial Experiment (PI)¶

Dataflow Architecture¶

Carbonaceous & Biomass Particulate Pipeline (BC, OCFF, Bio)¶

Sulfur Cycle Pipeline (scycl)¶

PI_ancil_aerosol_BC¶

PI_ancil_aerosol_Bio¶

PI_ancil_aerosol_OC¶

PI_ancil_aerosol_SO2¶

2. Historical Experiment (HI)¶

Dataflow Architecture¶

Carbonaceous & Biomass Particulate Pipeline (BC, OCFF, Bio)¶

Sulfur Cycle Pipeline (scycl)¶

HI_ancil_aerosol_SO2 Specification Details¶

3. ScenarioMIP Experiment (SM)¶

Dataflow Architecture¶

Carbonaceous & Biomass Particulate Pipeline (BC, OCFF, Bio)¶

Sulfur Cycle Pipeline (scycl)¶

SM_{h,hl,m,vl}_ancil_aerosol_SO2¶

`PI_ancil_aerosol_BC`¶

`PI_ancil_aerosol_Bio`¶

`PI_ancil_aerosol_OC`¶

`PI_ancil_aerosol_SO2`¶

`HI_ancil_aerosol_SO2` Specification Details¶

`SM_{h,hl,m,vl}_ancil_aerosol_SO2`¶