M3 Linkages

The M3 linkages repository automates running several open models in sequence so that the outputs of one become the inputs of the next: energy-technology choice (CIMS), electricity capacity expansion (COPPER), hourly dispatch (SILVER), probabilistic resource adequacy (PRAS), the provincial macro-economy (MacroABM-CA) and the labour market (LabourABM).

M3 is not one workflow. It is a set of linkages, each a separate workflow with its own orchestrator, scenario folders, pinned model versions and documentation. Running one linkage never touches another.

This documentation has two halves:

  • Linkages describe each workflow in general: what it does, how to install it, how to run it, and what every configuration key means.
  • Publications and projects record specific applications of M3: the exact model versions, scenarios, assumptions and data behind a piece of published analysis, and how to replicate it.

Linkages

Linkage What it answers Models Start here
Electricity supply and demand (CIMS-COPPER-SILVER) How does the electricity system have to expand, and can it dispatch hour by hour, under an economy-wide policy scenario? CIMS ⇄ COPPER → SILVER, iterated until electricity prices converge Overview
Energy-economy (CIMS-COPPER-MacroABM-LabourABM) What does a self-consistent energy pathway do to provincial GDP, investment, employment and occupations? CIMS + COPPER → MacroABM-CA → LabourABM, one-way Overview
Energy-economy feedback loop (CIMS-MacroABM) Would the economy sustain the energy pathway once its own response feeds back into energy demand? CIMS ⇄ MacroABM-CA, iterated Overview
Resource adequacy (COPPER-PRAS) Does a COPPER capacity plan keep the lights on under random outages, extreme weather and limited-energy resources? COPPER → PRAS via the pras-linkage preprocessor Overview

Which energy-economy linkage? The one-way CIMS-COPPER-MacroABM-LabourABM linkage is the default for scenario analysis: it takes a finished CIMS-COPPER scenario as fixed input, adds COPPER's electricity supply explicitly, and costs one macroABM run per scenario. Use the CIMS-MacroABM feedback loop only when the question is specifically whether the economy would re-solve the energy pathway, so the economic response must feed back into CIMS.

Publications and projects

Each project page records what a technically-enabled reader needs to understand and replicate the analysis: the publication it supports, the linkage and the exact model versions (repository, branch, commit) used, the scenarios, every assumption and data source that differs from the linkage defaults, the run recipe, and where the outputs live.

Project Linkage Status of this page
Powering Canada's Growth CER-MacroABM Methodology and quick-start
CP Saskatchewan (A Nuclear Grand Bargain, Clean Prosperity) CIMS-COPPER-SILVER Model versions, scenarios and assumptions recorded; dashboard to come
Building Grid Resilience through Interprovincial Interties (Electricity Canada) COPPER-PRAS Model versions, scenarios and assumptions recorded; dashboard to come
EPM Budget 2026 Dry Run CIMS-COPPER (+ MacroABM / LabourABM handoff) CIMS–COPPER design and scenarios recorded; MacroABM details and pinned commits to complete

Adding to this documentation

The site is built with MkDocs from the Markdown files under docs/ and is published by GitLab Pages on every push to main (see .gitlab-ci.yml; the build runs in strict mode, so a broken link fails the pipeline rather than publishing a broken page).

  • A new linkage gets a folder docs/linkages/<workflow_name>/ with at least index.md (overview), setup.md and quickstart.md, plus configFile.md or methodology.md where they earn their place, and a block in the nav: section of mkdocs.yml under Linkages.
  • A new project gets docs/projects/<project_name>/index.md following the section layout of the existing project pages, and one line under Publications and projects in mkdocs.yml. A methodology page can sit beside it in the same folder; dated working notes stay on the project's own branch rather than in these docs.
  • To preview locally: pip install mkdocs then mkdocs serve from the repository root.