Revise modelling principles

docs/main/co2-ccus.md

@@ -107,6 +107,6 @@ You can find more (advanced) information about the CCUS related CO<sub>2</sub> f
 
 ![CCUS graph](/img/docs/ccus-graph.png)
 
-The CCUS graph is linked with the [energy graph](energy-calculations) and information is exchanged between the two graphs. In many cases, the 'origin' of a carbon source lies within the energy graph. For example, the amount of CO<sub>2</sub> produced by a coal power plant (node: `energy_power_combined_cycle_ccs_coal_co2` in the CCUS graph) depends on the installed capacity and full load hours of that plant calculated by the energy graph (corresponding node: ` energy_power_combined_cycle_ccs_coal` in the energy graph). Vice versa, information calculated in the CCUS graph can be relevant for the energy graph. Capturing CO<sub>2</sub> in the CCUS graph, for example, leads to additional electricity and heat demand in the energy graph.
+The CCUS graph is linked with the [energy graph](how-the-etm-calculates/introduction.md) and information is exchanged between the two graphs. In many cases, the 'origin' of a carbon source lies within the energy graph. For example, the amount of CO<sub>2</sub> produced by a coal power plant (node: `energy_power_combined_cycle_ccs_coal_co2` in the CCUS graph) depends on the installed capacity and full load hours of that plant calculated by the energy graph (corresponding node: ` energy_power_combined_cycle_ccs_coal` in the energy graph). Vice versa, information calculated in the CCUS graph can be relevant for the energy graph. Capturing CO<sub>2</sub> in the CCUS graph, for example, leads to additional electricity and heat demand in the energy graph.
 
 By double clicking on any of the 'nodes' in the CCUS graph, a separate pages opens up with more detailed information, such as its 'counter-part' in the energy graph. See the [Molecules](../contrib/molecules.md) page in the Contributors section of the documentation for more details.

docs/main/how-the-etm-calculates/annual-and-hourly-calculations.md

@@ -0,0 +1,48 @@
+---
+title: Annual and hourly calculations
+---
+
+The ETM answers two different kinds of question. *"How much natural gas does my scenario use in 2050?"* is a question about a whole year. *"Is there enough electricity on a cold, windless January evening?"* is a question about a single hour. The model therefore calculates on two levels: annual energy flows for the entire system, and an hour-by-hour simulation for the parts of the system where timing matters.
+
+## The annual calculation
+
+The [energy graph](introduction.md) works with yearly totals: every flow between nodes is an amount of energy per year. This annual view covers the *entire* energy system — every sector, every carrier — and produces most of the headline results: total energy demand, CO₂ emissions, costs, the share of renewables.
+
+Yearly totals are enough for many parts of the system. A car uses the same amount of fuel per year regardless of when it is driven; a factory's yearly gas consumption tells you what you need to know about its emissions.
+
+## Why hours matter
+
+For electricity and heat, yearly totals hide the real challenge. Solar panels produce nothing at night; heat demand peaks in winter; wind comes and goes. A scenario can have more than enough wind and solar *over the year* and still face shortages on dark, still evenings — or produce more power on sunny afternoons than anyone can use.
+
+To capture this, the ETM simulates parts of the system for all **8,760 hours of the year**:
+
+- **Electricity**: all demand and supply, including flexible technologies such as batteries, interconnectors with neighbouring countries and electrolysers.
+- **Heat**: space heating in houses and buildings hour by hour — including how insulation and heat storage carry warmth from one hour to the next — and district heating networks.
+- **Hydrogen and gas**: hourly balancing of production, consumption and seasonal storage.
+
+The hourly simulations use realistic patterns — called *profiles* or *curves* — for things the model cannot choose: sunshine, wind, outdoor temperature, and the daily rhythm of household electricity use. These profiles come from measured weather and consumption data for your region, and you can test your scenario against different historical [weather years](../weather-conditions.md), including cold, dark winters. See the [profiles documentation](../profiles.md) for the full list.
+
+## How the electricity market is simulated
+
+For every hour, the model must decide which power plants run. It does this the way the real electricity market does, using the **merit order**: cheapest first.
+
+1. Production that costs (almost) nothing to run — solar, wind, hydro — is used first, whenever the weather provides it.
+2. The remaining demand is met by dispatchable plants — gas, coal, nuclear, biomass — in order of their running costs, until demand is met.
+3. The running cost of the most expensive plant needed in that hour sets the **electricity price** for that hour.
+
+Flexible technologies react to these hourly prices. Batteries charge when electricity is cheap and abundant, and sell it back when it is scarce and expensive. Electrolysers make hydrogen from cheap surplus power. Interconnectors import when neighbours are cheaper and export when they are more expensive. If supply still exceeds demand in some hour, the surplus is *curtailed* — thrown away — and if demand cannot be met, the model reports a shortage.
+
+The result is a realistic hourly picture of prices, imports and exports, storage behaviour and curtailment. The [merit order documentation](../merit-order.md) describes this in more detail.
+
+## The two levels feed each other
+
+The annual and hourly calculations are not separate models — they exchange results:
+
+- The annual calculation tells the hourly simulation what to work with: total electricity demand, installed capacities, the heating technologies in houses.
+- The hourly simulation reports back how the year actually played out: how many hours each power plant ran, how much solar and wind power was curtailed, how much electricity was imported and exported, and what it all cost.
+
+Those outcomes then shape the annual results you see. A gas plant that the merit order rarely needs will show high costs per unit of electricity produced; a scenario with much more solar than storage will show rising curtailment instead of rising useful production. This interplay is what makes ETM results more than bookkeeping: your scenario is tested against the hours in which it must actually work.
+
+:::info For modellers and developers
+The hourly calculations are performed by open-source calculation engines — [Merit](https://github.com/quintel/merit) for electricity and [Fever](https://github.com/quintel/fever) for space heating. The [contributor documentation](/contrib/intro) describes how they are configured.
+:::

docs/main/how-the-etm-calculates/from-data-to-scenario.md

@@ -0,0 +1,39 @@
+---
+title: From data to scenario
+---
+
+Every ETM scenario starts from a description of a real energy system in a real year: the Netherlands in 2023, Germany in 2019, a municipality, a province. This page explains where that starting point comes from and what it means for your scenario.
+
+## One dataset per region
+
+The ETM contains datasets for more than 400 regions: European countries, the Netherlands and its municipalities, provinces and RES-regions, and a number of other areas. A dataset is a complete, quantified snapshot of a region's energy system in a particular *start year*: how much energy each sector used, which technologies supplied it, what capacity of power plants, wind and solar was installed, and what was imported and exported.
+
+When you [create a scenario](../user_manual/starting-scenario.md), you pick a region and thereby a dataset. The dataset fills the *present* version of the [energy graph](introduction.md) and becomes the fixed reference point that your future scenario is compared against.
+
+## Where the numbers come from
+
+Datasets are not entered by hand; they are built through a documented, repeatable process:
+
+- **Country datasets** are based primarily on national energy balances — the official statistics that record how much of each energy carrier a country produced, converted, imported and consumed. For European countries these come from Eurostat and the IEA. On top of the energy balance, a series of analyses divides sector totals over technologies: how much of households' gas use goes to space heating versus hot water, which power plants make up the installed capacity, and so on. These analyses, including their sources, are public — see the [ETDataset repository](https://github.com/quintel/etdataset-public).
+- **Dutch municipalities, provinces and RES-regions** are based on regional statistics, principally Klimaatmonitor, supplemented with building registries and emissions data. The [regional data page](../data-sources-local.md) describes the sources and assumptions per sector, and larger regions are built up by combining municipalities.
+- **Technology properties** — the cost, efficiency and lifetime of a heat pump, a wind turbine or a power plant — are researched separately per technology and shared by all regions, so that scenarios for different regions are comparable. Each technology has its own public source analysis in ETDataset.
+
+Not every number a dataset needs is directly available in statistics. Where data is missing, it is estimated from related figures — and those estimates are documented in the same analyses. The model then completes the picture itself: from the data that is provided, it calculates all remaining energy flows in the graph so that everything adds up to a consistent whole.
+
+## Start years and dataset versions
+
+Statistics are published with delay, and building a reliable dataset takes research time. A region's dataset therefore has a start year a few years in the past — for the Netherlands, for example, 2023. Older start years often remain available so that existing scenarios keep working; the web interface offers the most recent one.
+
+This has a practical consequence: your scenario describes the transition *from the start year* to your chosen end year. Anything that happened after the start year — a new wind farm, a closed coal plant — is not in the starting data, but you can add it with sliders.
+
+## Checking the data for your region
+
+You do not have to take the starting data on faith:
+
+- The **[ETM Data Manager](https://data.energytransitionmodel.com/)** lets you select any region and inspect the data behind it, sector by sector.
+- The **[data sources pages](../data-sources-regions.md)** describe which regions exist and which sources are used.
+- For Dutch regions, users with local knowledge can propose corrections; datasets are maintained and improved over time.
+
+:::info For modellers and developers
+How datasets are constructed, and how to create or update one, is described in the [ETDataset repository](https://github.com/quintel/etdataset-public) and the [contributor documentation](/contrib/intro).
+:::

docs/main/how-the-etm-calculates/introduction.md

@@ -0,0 +1,49 @@
+---
+title: How the ETM calculates
+---
+
+The Energy Transition Model looks complex from the outside: over a thousand sliders, hundreds of charts, and results that update the moment you change something. Underneath, the model follows a small number of ideas that are easy to understand. This section explains them in plain language — no programming or modelling background needed.
+
+If you understand these four pages, you will know what the model does with your choices, where its starting data comes from, and what its results do (and do not) mean:
+
+1. **This page** — the energy graph, and what happens when you move a slider.
+2. [From data to scenario](from-data-to-scenario.md) — how real statistics for your country or region become the starting point of a scenario.
+3. [Annual and hourly calculations](annual-and-hourly-calculations.md) — how the model combines a year-total view of all energy with an hour-by-hour simulation of electricity and heat.
+4. [Useful, final and primary energy](useful-final-primary-energy.md) — the three ways of counting energy that explain most of the numbers you see in the model.
+
+## The energy system as a graph
+
+The ETM describes the entire energy system of a country or region as a network — modellers call it a *graph*. The network consists of roughly 1,250 connected **nodes**. Each node represents a recognisable part of the energy system: a technology (wind turbines, gas-fired power plants, heat pumps), a group of consumers (households' demand for hot water, freight transport), or an activity such as importing or extracting fuel.
+
+The connections between nodes carry **energy flows**: so many petajoules of electricity from power plants to households, so much natural gas from import terminals to industrial boilers, and so on. Every flow is labelled with its energy carrier — electricity, natural gas, hydrogen, heat, oil products, biomass, and others.
+
+![A simplified example of an energy graph](/img/docs/Graph.jpg)
+
+Together, the nodes and flows form a complete, closed picture of the energy system: all the energy that is used somewhere must be produced, imported or taken from storage somewhere else. This bookkeeping is what keeps ETM scenarios internally consistent — you cannot create or lose energy by accident.
+
+A second, much smaller network of about 190 nodes tracks *molecules* rather than energy — most importantly CO₂, for [carbon capture, storage and utilisation](../co2-ccus.md). It exchanges information with the energy graph: for instance, how much CO₂ a power plant emits depends on how much that plant runs in the energy graph.
+
+## What happens when you move a slider
+
+Almost every slider in the ETM changes a property of one or more nodes: the number of heat pumps in homes, the installed capacity of offshore wind, the efficiency of a future power plant, the share of electric cars in passenger transport.
+
+When you release a slider, the model recalculates the **whole** graph — every node, every flow — from scratch. This takes a few seconds. The calculation is *demand-driven*: it starts from what people and companies need (a warm home, transport, products from industry) and works step by step towards the supply side, asking at each node how much energy — and which carriers — are required to meet the demand placed on it. At the end of the chain, this determines how much fuel is extracted or imported and how much electricity each type of power plant must produce.
+
+Because the whole system is recalculated every time, a single change can ripple through the entire model. More electric cars means more electricity demand, which means more production from power plants, which — depending on your other choices — can mean more gas consumption, more CO₂, or more curtailed solar power on sunny days. All charts and the dashboard are updated to reflect this.
+
+## Present and future, side by side
+
+Every scenario contains two versions of the graph:
+
+- The **present** graph describes the energy system in your scenario's start year. It is filled with real statistics for your country or region — see [From data to scenario](from-data-to-scenario.md) — and does not change when you move sliders.
+- The **future** graph describes the energy system in the scenario's end year (2050, for example). This is the one your sliders act on.
+
+Most results in the ETM are a comparison between these two: the dashboard's CO₂ reduction, the change in energy demand, the difference in yearly costs. When a chart shows "present" and "future" columns, you are looking at the same node in the two versions of the graph.
+
+## Reading the numbers behind the charts
+
+Every chart, dashboard item and downloadable result in the ETM is a *query*: a stored recipe that reads numbers from the graph and combines them — for example, "add up the CO₂ emissions of all nodes in the transport sector". The model contains thousands of these queries. You do not need to know how they work, but it is useful to know that they exist: every number the ETM shows can be traced back to specific nodes and flows in the graph, and from there to [documented data sources](../data-sources-regions.md).
+
+:::info For modellers and developers
+The technical counterparts of this page — node types, edge types, calculation rules and the query language — are described in the [contributor documentation](/contrib/graph-components).
+:::