diff --git a/code/index.md b/code/index.md new file mode 100644 index 00000000..5e761840 --- /dev/null +++ b/code/index.md @@ -0,0 +1,36 @@ +--- +title: "The code behind Cornerstone EEIO" +--- + +:::{tip} Summary +Cornerstone EEIO is built by two code pipelines. The open-source `bedrock` pipeline builds the U.S. part of the model. The `ceda` pipeline, currently closed-source, builds the rest of the global multi-regional model and calculates and publishes the emission factors. +::: + +| Model component | Built by | +|---|---| +| U.S. Make and Use tables, direct requirements (`Adom`, `Aimp`), output and final demand | `bedrock` | +| U.S. GHG extension (`B`) | `bedrock` | +| U.S. trade and transport margins (`A_margin`) and price indexes | `bedrock` | +| IO tables and emissions for all other countries (Tiers 1 to 3) | `ceda` | +| Trade linking, balancing and the multi-regional total requirements (`L`) | `ceda` | +| Emission factors (`M`, `N`), regional averages, price-year and purchaser-price adjustments, margin emission factors | `ceda` | +| Published release files | `ceda` | + +## bedrock: the U.S. model + +[`bedrock`](https://github.com/cornerstone-data/bedrock) is an open-source pipeline that builds the U.S. components of the model. It brings together the U.S. methods of USEEIO and CEDA. It produces the Cornerstone nowcast Make and Use tables for 2017 to 2024 on BEA's 2017 detailed schema, along with the U.S. direct requirements, GHG extension, margins and price indexes listed above. Every methodology choice is set in a configuration file, so the effect of each choice can be tested on its own, and the results of each release are pinned so they can be reproduced exactly. The code is publicly available on GitHub under the Cornerstone Data Pipeline Attribution License, which requires attribution when it is used. + +## ceda: the global model and the emission factors + +The `ceda` pipeline builds the rest of the global multi-regional model and produces the published emission factors. It takes the U.S. components from a pinned `bedrock` release, adds the IO tables and emissions for the Tier 1–3 countries, and maps them to the 405 common sectors with {term}`ABSR`. It then links countries through bilateral trade, balances the multi-regional table with {term}`RAS`, and solves for the total requirements. From that, it calculates the emission factors (including regional and global averages, price-year and purchaser-price variants, and margin factors) and writes the release files (see [](../factors/calculation.md)). The pipeline grew out of the code behind CEDA and is maintained by Cornerstone. It is currently closed-source. + +## How the code is checked + +Both pipelines are tested automatically on every change, and their main outputs are compared with pinned reference results. See [code validation](../validation/index.md#code-validation). + ++++ + +:::{div} +:class: page-status +Applies to: 2026-rc.1 · Last reviewed: 2026-rc.1 +::: diff --git a/index.md b/index.md index 39b4ac06..a3c1387d 100644 --- a/index.md +++ b/index.md @@ -42,6 +42,11 @@ From the model matrices to published factors, including price-year and purchaser How the emission factors of trade and transport margins are prepared. ::: +:::{card} The code +:link: code/index.md +The pipelines that build the model and publish the emission factors. +::: + :::{card} How we validate :link: validation/index.md The checks behind each release. diff --git a/myst.yml b/myst.yml index cd9685fe..878e723b 100644 --- a/myst.yml +++ b/myst.yml @@ -38,6 +38,7 @@ project: children: - file: factors/calculation.md - file: factors/margins.md + - file: code/index.md - file: validation/index.md - file: benchmarking/index.md - file: releases/index.md diff --git a/validation/index.md b/validation/index.md index 2b6a6a2a..8d46be44 100644 --- a/validation/index.md +++ b/validation/index.md @@ -13,9 +13,10 @@ Validation asks "did we build the model correctly?" It checks the code that buil Where each kind of validation runs in the build. Code validation covers every step; data validation follows the data in; model validation checks what comes out. Benchmarking against independent evidence follows the build and feeds the next release (see [](../benchmarking/index.md)). ::: +(code-validation)= ## 1. Code validation -The model is built by open-source code, and every change to that code is tested before it is merged. +The model is built by two code pipelines, described in [](../code/index.md), and every change to that code is tested before it is merged. - **Unit tests.** About 2,900 automated tests check individual steps against known answers. They include tests of the core formulas, such as `N = D × L`, and of the conservation rules the methods rely on: when emissions or output are split, mapped or reallocated, the totals before and after must match. Small worked examples, including a toy model of {term}`ABSR` and of {term}`RAS` balancing, are solved by hand and checked against the code. - **Schema checks.** The main tables are checked for their structure every time they are built: the full list of 405 sectors in the right order, every country present, no duplicates, and no missing values. Final demand and exports must not be negative.