HEMCO to CECE Migration Guide¶

This guide walks HEMCO users through migrating their emission configurations to CECE. CECE supports all HEMCO capabilities and adds new features including Kokkos GPU acceleration, provenance tracking, and dynamic species registration.

Table of Contents¶

1. Overview of Differences
2. Automated Conversion Tool
3. Configuration Mapping Reference
4. Diagnostic Conversion
5. Temporal Profiles
6. Vertical Distribution
7. Regional Inventories and Hierarchy
8. Scale Factors and Masks
9. New CECE Capabilities
10. Troubleshooting

Overview of Differences¶

Automated Conversion Tool¶

The fastest way to migrate is the provided conversion script:

python3 scripts/hemco_to_cece.py HEMCO_Config.rc -o cece_config.yaml --diagn HEMCO_Diagn.rc

This converts: - All base emissions to species: layers - Scale factors to scale_fields: references or temporal_profiles: - Masks to mask: references - HEMCO_Diagn.rc variables to the diagnostics: block - $ROOT path substitution

Review the output YAML and adjust file paths as needed before running CECE.

Configuration Mapping Reference¶

HEMCO Base Emission Entry¶

# HEMCO_Config.rc
# ExtNr Name       File                  Var   Time  CRE Dim Unit  Species ScalIDs Cat Hier
  0     MACCITY_CO data/MACCity.nc       CO    2000  1   2   kg/m2 CO      1/2     1   1

Equivalent CECE YAML¶

species:
  co:
    - field: MACCITY_CO
      operation: add
      hierarchy: 1
      category: anthropogenic
      scale: 1.0
      scale_fields: [hourly_scalfact]

cece_data:
  streams:
    - name: MACCITY_CO
      file: data/MACCity.nc

Operation Mapping¶

Category Mapping¶

Diagnostic Conversion¶

HEMCO_Diagn.rc¶

# Name           Spec ExtNr Cat Hier Dim Unit     LongName
EmisNO_Total     NO   -1    -1  -1   2   kg/m2/s  NO_emission_flux_from_all_sectors
EmisCO_Anthro    CO   0     1   1    2   kg/m2/s  CO_anthropogenic_emissions

Equivalent CECE YAML¶

diagnostics:
  output_interval: 3600
  variables:
    - name: EmisNO_Total
      species: NO
      units: kg/m2/s
      long_name: NO_emission_flux_from_all_sectors
      dim: 2
    - name: EmisCO_Anthro
      species: CO
      units: kg/m2/s
      long_name: CO_anthropogenic_emissions
      dim: 2

Temporal Profiles¶

HEMCO Inline Diurnal Profile (24 values)¶

# ScalID Name         File                          Var  Time CRE Dim Unit Oper
1        HOURLY_SCALFACT 0.5/0.6/0.7/.../1.2/1.1  -    -    1   1   1    1

Equivalent CECE YAML¶

temporal_profiles:
  hourly_scalfact: [0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.3, 1.2, 1.1, 1.0,
                    1.0, 1.1, 1.2, 1.3, 1.2, 1.1, 1.0, 0.9, 0.8, 0.7, 0.6, 0.5]

species:
  co:
    - field: MACCITY_CO
      operation: add
      hierarchy: 1
      scale: 1.0
      diurnal_cycle: hourly_scalfact

Weekly Profile (7 values, Mon-Sun)¶

temporal_profiles:
  weekly_nox: [1.0, 1.1, 1.1, 1.1, 1.1, 0.8, 0.7]

species:
  nox:
    - field: CEDS_NOx
      operation: add
      hierarchy: 1
      scale: 1.0
      weekly_cycle: weekly_nox

Seasonal Profile (12 values, Jan-Dec)¶

temporal_profiles:
  seasonal_biogenic: [0.3, 0.4, 0.6, 0.8, 1.0, 1.2, 1.3, 1.2, 1.0, 0.8, 0.5, 0.3]

species:
  isop:
    - field: MEGAN_ISOP
      operation: add
      hierarchy: 1
      scale: 1.0
      seasonal_cycle: seasonal_biogenic

All three cycle types can be combined — CECE applies them as a product: effective_scale = base_scale × diurnal_factor × weekly_factor × seasonal_factor

Vertical Distribution¶

HEMCO Vertical Distribution Keywords¶

Example: Pressure-Based Distribution¶

species:
  aircraft_nox:
    - field: AEIC_NOx
      operation: add
      hierarchy: 1
      scale: 1.0
      vdist:
        method: pressure
        p_start: 20000.0   # 200 hPa in Pa
        p_end: 80000.0     # 800 hPa in Pa

Example: PBL Distribution¶

species:
  soil_nox:
    - field: SOILNOX
      operation: add
      hierarchy: 1
      scale: 1.0
      vdist:
        method: pbl

All vertical distribution methods conserve column mass within 1e-10 relative error.

Regional Inventories and Hierarchy¶

HEMCO uses hierarchy levels to allow regional inventories to override global ones. CECE replicates this with hierarchy and operation: replace.

HEMCO Example¶

# Global inventory (hierarchy 1)
0  CEDS_CO  data/CEDS_CO.nc  CO  2015  1  2  kg/m2  CO  -  1  1
# European inventory overrides global in masked region (hierarchy 2)
0  EMEP_CO  data/EMEP_CO.nc  CO  2015  1  2  kg/m2  CO  500  1  2

Where ScalID 500 is a Europe mask.

Equivalent CECE YAML¶

species:
  co:
    - field: CEDS_CO
      operation: add
      hierarchy: 1
      category: anthropogenic
      scale: 1.0
    - field: EMEP_CO
      operation: replace
      hierarchy: 2
      category: anthropogenic
      scale: 1.0
      mask: mask_europe

cece_data:
  streams:
    - name: CEDS_CO
      file: data/CEDS_CO.nc
    - name: EMEP_CO
      file: data/EMEP_CO.nc
    - name: mask_europe
      file: data/Europe_mask.nc

The replace operation zeroes out lower-hierarchy contributions in the masked region before adding the regional inventory value.

Scale Factors and Masks¶

HEMCO Scale Factor Section¶

# ScalID Name         File              Var    Time CRE Dim Unit Oper
1        HOURLY_SF    data/hourly.nc    HOURLY 2000 1   2   1    1
500      MASK_EUROPE  data/europe.nc    MASK   -    1   2   1    1

Equivalent CECE YAML¶

# Time-varying scale factor -> reference in scale_fields
species:
  co:
    - field: CEDS_CO
      operation: add
      hierarchy: 1
      scale: 1.0
      scale_fields: [hourly_sf]

# Geographical mask -> reference in mask
    - field: EMEP_CO
      operation: replace
      hierarchy: 2
      scale: 1.0
      mask: mask_europe

cece_data:
  streams:
    - name: hourly_sf
      file: data/hourly.nc
    - name: mask_europe
      file: data/europe.nc

Multiple scale factors and masks are supported as lists:

scale_fields: [sf_temporal, sf_spatial]
mask: [mask_land, mask_europe]

New CECE Capabilities¶

GPU Acceleration¶

CECE runs all emission stacking on GPU via Kokkos with no code changes:

# Build with CUDA support
cmake -DCECE_ENABLE_CUDA=ON ..
make -j4

# Run with GPU
CECE_DEVICE_ID=0 ./cece_nuopc_single_driver --config cece_config.yaml

Emission Provenance Tracking¶

CECE records which layers contributed to each species at each timestep:

// After StackingEngine::Execute()
const auto& prov = engine.GetProvenance();
const auto* co_prov = prov.GetProvenance("co");
std::cout << prov.FormatReport();

Dynamic Species Registration¶

Add new species at runtime without recompilation:

cece::EmissionLayer new_layer;
new_layer.field_name = "new_inventory";
new_layer.operation = "add";
new_layer.hierarchy = 1;
new_layer.scale = 1.0;

cece::AddSpecies(config, "new_species", {new_layer});
engine.AddSpecies("new_species");  // picks up from updated config

Troubleshooting¶

"Field not found" errors¶

Ensure the field name in species[].field matches the name in cece_data.streams or the external name in meteorology:.

Temporal profiles not applied¶

Check that diurnal_cycle, weekly_cycle, or seasonal_cycle names match keys in temporal_profiles: exactly (case-sensitive).

Vertical distribution not working¶

Ensure vertical_grid: is configured with the correct coordinate type (fv3, mpas, or wrf) and that the required coordinate fields (ak, bk, ps, height, hpbl) are present in the ESMF ImportState.

Mass conservation errors¶

All vertical distribution methods conserve column mass. If you observe discrepancies, verify that the source field is 2D (nz=1) when using SINGLE, RANGE, PRESSURE, HEIGHT, or PBL methods.

Performance below target¶

• Ensure Kokkos is built with OpenMP: -DKokkos_ENABLE_OPENMP=ON
• Set thread count: export OMP_NUM_THREADS=16
• For GPU: ensure CUDA toolkit matches Kokkos build configuration
• Run the benchmark: python3 scripts/benchmark_hemco_vs_cece.py --build-dir build