diff --git a/docs/api/interpolation.md b/docs/api/interpolation.md index fe740b2a..fd98f5dc 100644 --- a/docs/api/interpolation.md +++ b/docs/api/interpolation.md @@ -86,7 +86,7 @@ Authorization: Bearer YOUR_TOKEN "end_year": 2040, "url": "https://engine.energytransitionmodel.com/api/v3/scenarios/123456", "user_values": { - "buildings_insulation_level": 40.3, + "buildings_insulation_new_buildings": 40.3, "capacity_of_energy_power_hydro_river": 39.0 }, ... diff --git a/docs/api/saved-scenarios.md b/docs/api/saved-scenarios.md index 60a81f15..7a2cc130 100644 --- a/docs/api/saved-scenarios.md +++ b/docs/api/saved-scenarios.md @@ -566,7 +566,7 @@ Authorization: Bearer YOUR_TOKEN { "scenario": { "user_values": { - "buildings_insulation_level": 35.7 + "buildings_insulation_new_buildings": 35.7 } } } @@ -648,7 +648,7 @@ Authorization: Bearer YOUR_TOKEN "start_year": 2019, "end_year": 2050, "user_values": { - "buildings_insulation_level": 35.7 + "buildings_insulation_new_buildings": 35.7 } // ... } @@ -673,7 +673,7 @@ Authorization: Bearer YOUR_TOKEN { "scenario": { "user_values": { - "buildings_insulation_level": 42.0, + "buildings_insulation_new_buildings": 42.0, "households_number_of_inhabitants": 18.3, "households_solar_pv_solar_radiation_market_penetration": 21.0 } diff --git a/docs/api/scenarios.md b/docs/api/scenarios.md index d2da4d64..f415a3cb 100644 --- a/docs/api/scenarios.md +++ b/docs/api/scenarios.md @@ -100,7 +100,7 @@ Authorization: Bearer YOUR_TOKEN "active_couplings": [], "inactive_couplings": [], "user_values": { - "buildings_insulation_level": 40.3, + "buildings_insulation_new_buildings": 40.3, "capacity_of_energy_power_hydro_river": 39.0 }, "metadata": { @@ -224,7 +224,7 @@ Authorization: Bearer YOUR_TOKEN "area_code": "UKNI01_northern_ireland", "end_year": "2040" "user_values": { - "buildings_insulation_level": 40.3, + "buildings_insulation_new_buildings": 40.3, "capacity_of_energy_power_hydro_river": 39.0 } } @@ -239,7 +239,7 @@ Authorization: Bearer YOUR_TOKEN "end_year": 2040, ... "user_values": { - "buildings_insulation_level": 40.3, + "buildings_insulation_new_buildings": 40.3, "capacity_of_energy_power_hydro_river": 39.0 } } @@ -281,7 +281,7 @@ Authorization: Bearer YOUR_TOKEN "template": 11111, ... "user_values": { - "buildings_insulation_level": 40.3, + "buildings_insulation_new_buildings": 40.3, "capacity_of_energy_power_hydro_river": 39.0 } } @@ -307,7 +307,7 @@ Authorization: Bearer YOUR_TOKEN { "scenario": { "user_values": { - "buildings_insulation_level": 35.7 + "buildings_insulation_new_buildings": 35.7 } } } @@ -319,7 +319,7 @@ Authorization: Bearer YOUR_TOKEN "id": 12345, ... "user_values": { - "buildings_insulation_level": 35.7, + "buildings_insulation_new_buildings": 35.7, "capacity_of_energy_power_hydro_river": 39.0 } } diff --git a/docs/contrib/built-environment-inputs-priority.md b/docs/contrib/built-environment-inputs-priority.md new file mode 100644 index 00000000..319940b6 --- /dev/null +++ b/docs/contrib/built-environment-inputs-priority.md @@ -0,0 +1,62 @@ +--- +title: Built environment inputs priority +--- + +The housing and building stock, insulation, behaviour and weather inputs all influence the heat demand. +Because ETEngine applies inputs one after another (see [Priority](inputs#priority) for the general mechanism), the **order** in which these inputs run matters. +Running them in the wrong order silently produces incorrect results rather than an error. + +This page documents the priority order used for these inputs, and the reasoning behind it, so that future additions or changes respect the same ordering. +These priorities order is also documented as a comment at the top of each of the relevant `.ad` files in etsource, so it stays visible to anyone editing them directly. + +## Priorities + +Recall that **a higher `priority` number runs earlier**. The building/housing inputs use the following order (highest to lowest): + +#### 4. Shares of new residences + + * `households_share_of_` + + These inputs don't update anything themselves; they only need to have a value available (as a [share group](inputs#share-groups), summing to 100%) before the total number of new residences is distributed across housing types. + + +#### 3. Building and housing stock + + * `households_number_of_residences_new` + * `households_demolished_` + * `buildings_number_of_buildings_new` + * `buildings_number_of_buildings_demolished` + + These read the shares set using priority 4 (via `INPUT_VALUE(...)`) to calculate, per housing type, the number of units added or removed, and update the number of units and useful demand per building type and construction period accordingly. These inputs also update the total roof area available for PV, and the total cooling demand as they are dependant on the total number of buildings. + + #### 2. Weather years + + * `settings_weather_curve_set` + + If the user selects a non-default weather year, this scales `preset_demand` for space heating and cooling using temperature/degree-day factors derived from that weather year, and marks `AREA(weather_curve_set)` as non-default. This must run after stock changes so it scales correctly. + +:::info Weather years override temperature input + +If the user selects a non-default weather year (`settings_weather_curve_set`), the `flexibility_outdoor_temperature` slider has **no effect at all**, even though the temperature with priority 0 is set after the weather years with priority 2. This happens because temperature input explicitly checks whether a weather year has been selected, and does nothing when this is the case +::: + +#### 1. Insulation + + * `households_insulation_` + * `buildings_insulation_existing_buildings` + * `buildings_insulation_new_buildings` + + These reduce the typical heat demand (`AREA()`) and `preset_demand` by the entered percentage, and use the resulting typical heat demand to (re)calculate insulation costs. This runs after the stock and weather updates so that insulation is applied to the correct, final number of units and to demand that has already been adjusted for the weather year. + +#### 0. Behaviour, temperature and batteries + + * `households_space_heating_behaviour` + * `buildings_space_heating_behaviour` + * `flexibility_outdoor_temperature` + * `households_flexibility_p2p_electricity_market_penetration` + + These are the last things to run, applying a final factor to the heat demands. Their relative execution order doesn't matter. The total number of households batteries is also calculated based on the market penetration and the total number of households. + +:::info Custom profiles for air temperature + +When a user uploads a custom temperature profile in the [Modify profiles](https://energytransitionmodel.com/scenario/flexibility/curve_upload/upload-curves) section, this profile sets the outdoor temperature input in the backend and deactivates the slider in the front-end. diff --git a/docs/main/cost-insulation-costs.md b/docs/main/cost-insulation-costs.md index ba329c14..4aabd2c1 100644 --- a/docs/main/cost-insulation-costs.md +++ b/docs/main/cost-insulation-costs.md @@ -2,9 +2,11 @@ title: Insulation costs --- -There are no dedicated sliders in the ETM to set the level of insulation for the housing or the building stock. Instead, users can lower the typical heat demand of a house or building category (see the [Heat in the built environment](heat-built-environment) section). The corresponding reduction in typical heat demand compared to the starting year is interpreted as an increase in the level of insulation. +In the ETM interface, insulation is set using a single slider per construction period for houses and buildings. This slider only shows a percentage, from 0% (no additional insulation) up to 100%. To calculate the insulation costs, the ETM keeps track of a **typical heat demand** for each housing or building category, expressed in kWh/m2 (see the [Heat in the built environment](heat-built-environment) section). The insulation slider reduces this typical heat demand by the percentage entered, compared to its value in the starting year: a slider set to 20% reduces the typical heat demand for that category by 20%. -In line with the greenfield approach for costs, the ETM only assumes costs for investments required in the future. Insulation costs are therefore added when the typical heat demand is reduced compared to the current situation; if not, then the insulation costs are zero. Increases in typical heat demand do not lead to a change in costs. +It is this resulting, reduced typical heat demand that is used to calculate insulation costs, as described below. + +In line with the greenfield approach for costs, the ETM only assumes costs for investments required in the future. Insulation costs are therefore added when the insulation is increased and with that the heat demand is reduced compared to the current situation; if not, then the insulation costs are zero. ## Households The insulation costs for houses are based on the Ecofys report ['De systeemkosten van warmte voor woningen (2015)'](https://refman.energytransitionmodel.com/publications/2063). This report distinguishes three levels of insulation – low, medium, and high – and specifies the investment costs for transitioning from one level to another. The table below shows the insulation costs for existing housing stock of different categories. The ETM uses the 2020 costs for the four different housing types. @@ -40,8 +42,6 @@ _Example_: 1000 terraced houses with a typical heat demand of 350 kWh/m22) are used for additional insulation. \ No newline at end of file +For new building stock insulation costs of €157/(kWh/m2) are used for additional insulation. diff --git a/docs/main/demand.md b/docs/main/demand.md index 64b05e33..07edfce2 100644 --- a/docs/main/demand.md +++ b/docs/main/demand.md @@ -16,7 +16,7 @@ Demand consists of a number of domestic demand sectors and export: For each of the demand sectors shown in the Demand tab in the ETM, a percentage is displayed. This indicates primary energy used to supply the energy use of that particular sector, as a share in the total primary energy use for domestic demand. ## Households -In the [Households](https://energytransitionmodel.com/scenario/demand/households/overview) section the demand for energy in households is specified. The demand growth of energy and the technology mix that uses this energy can be specified. The focus is on technologies used for heating, insulation, cooking, cooling, lighting and appliances. Additionally, you can specify the number and typical heat demand of residences per type and construction period. +In the [Households](https://energytransitionmodel.com/scenario/demand/households/overview) section the demand for energy in households is specified. The demand growth of energy and the technology mix that uses this energy can be specified. The focus is on technologies used for heating, insulation, cooking, cooling, lighting and appliances. Additionally, you can specify the number of residences demolished and newly built per construction period, and the reduction in heat demand due to insulation. ## Buildings The [Buildings](https://energytransitionmodel.com/scenario/demand/buildings/overview) section contains all non-residential buildings in the services sector. This includes office buildings, schools and hospitals. Similar to the Households section, the focus lies on heating, cooling, ventilation, insulation, lighting and roof top solar PV. diff --git a/docs/main/heat-built-environment.md b/docs/main/heat-built-environment.md index 40c81d3c..37e6f50a 100644 --- a/docs/main/heat-built-environment.md +++ b/docs/main/heat-built-environment.md @@ -23,6 +23,11 @@ Each housing type is then split into construction periods: The sources used for the existing housing stock data can be found in the [ETM Dataset Manager](https://data.energytransitionmodel.com/). +Changes to the housing stock between the start and end year are set as follows in the [Population & housing stock](https://energytransitionmodel.com/scenario/demand/households/population-and-housing-stock) section: +* A single slider sets the **total number of new residences** built between the start and end year. +* Four **share sliders** (one per housing type) distribute the total number of new residences across apartments, detached, semi-detached and terraced houses. These four shares always add up to 100%. +* For each of the five existing construction-period categories, a slider sets the **number of residences demolished** in that category (up to the number of residences present in the start year). This number is distributed across the four housing types in proportion to their share of the existing stock within that period. + ### Buildings (non-residential) The building stock within the buildings sector is used to provide a wide range of services, from hospitals to offices or swimming pools, making it difficult to capture the sector in a limited number of categories. Therefore, no different building types are distinguished. @@ -32,32 +37,37 @@ There is limited reliable data available about construction periods for building The sources used for the existing building stock data can be found in the [ETM Dataset Manager](https://data.energytransitionmodel.com/). +Changes to the building stock are set in the [Building stock](https://energytransitionmodel.com/scenario/demand/buildings/building-stock) section using a slider for the **number of buildings demolished** and a slider for the **number of new buildings**. + ## Heat demand -### Space heating demand and insulation -Insulation can be used to reduce the amount of heating needed for houses and buildings. The ETM allows you to alter the heat demand for various types of residences and non-residential buildings separately in the [Household](https://energytransitionmodel.com/scenario/demand/households/overview) or [Buildings](https://energytransitionmodel.com/scenario/demand/buildings/overview) sections. +### Insulation +Insulation can be used to reduce the amount of heating needed for houses and buildings. The ETM allows you to reduce the heat demand for space heating in the [Insulation](https://energytransitionmodel.com/scenario/demand/households/insulation) section under Households, and the corresponding [Insulation](https://energytransitionmodel.com/scenario/demand/buildings/insulation) section under Buildings. -For the **start year**, the heat demand for space heating follows from the region’s dataset. The sources for these data can be found in the [ETM Dataset Manager](https://data.energytransitionmodel.com/). This data is translated to the slider settings for space heating and hot water. +For the **start year**, the heat demand for space heating follows from the region's dataset. The sources for these data can be found in the [ETM Dataset Manager](https://data.energytransitionmodel.com/). -For the **future year**, the ETM uses the typical heat demand sliders to recalculate the heat demand for space heating. The typical heat demand in the ETM reflects the average insulation level of a house or building category and is expressed in kWh/m2. The source for the typical heat demands in the starting year can also be found in the [ETM Dataset Manager](https://data.energytransitionmodel.com/). +For the **future year**, each insulation slider directly sets a **percentage reduction in the typical heat demand** for space heating, relative to its start year (or, for new stock, default new-build) value. Internally, the ETM keeps track of the typical heat demand per housing/building category, expressed in kWh/m2. The sliders scale these values down by the percentage entered. The source for the typical heat demands in the starting year can be found in the [ETM Dataset Manager](https://data.energytransitionmodel.com/). -![](/img/docs/20240506_typical_heat_demand_sliders.png) +![](/img/docs/20260821_insulation_sliders.png) + +Households have six insulation sliders: one per construction-period category. Each slider applies the same percentage reduction to all four housing types within that period simultaneously. Buildings have two insulation sliders: one for existing buildings and one for new buildings. The ETM uses these sliders in two different ways: -1. For **existing** housing/building stock, the slider value is used to scale the heat demand for space heating from the start year. In other words, adjusting the slider value results in a relative change of heat demand for space heating compared to its starting value. -_Example: In the image above, the typical heat demand for apartments built between 1985-2004 has a starting value of 155 kWh/m2. Reducing the typical heat demand to 124 kWh/m2 (a reduction of 20%) means that the heat demand for space heating is decreased by 20% in the simulated future year._ +* For **existing** housing/building stock, the percentage reduction is applied to the heat demand for space heating from the start year. + * _Example:_ setting the "1985 - 2004" insulation slider to 20% reduces the total heat demand for all building types from this construction period by 20%. It also reduces the typical heat demand of all building types by 20%, which is used to calculate insulation costs. + +* For **new** housing/building stock, the percentage reduction is applied to a default typical heat demand for newly built residences/buildings, before that value is multiplied by the number of new units and an average surface area per unit to determine the future heat demand for space heating. + * _Example: the default typical heat demand for space heating for new apartments is 65 kWh/m2. Setting the "new residences" insulation slider to 10% reduces this to 58.5 kWh/m2. If the number of new apartments is set to 100,000, the heat demand for space heating from new apartments increases by 100,000 apartments x 58.5 kWh/m2 x 84 m2/apartment._ -2. For **new** housing/building stock, the actual slider value is used to calculate the future heat demand for space heating, based on an average surface area per newly built unit. -_Example: In the image above, the typical heat demand for space heating for new apartments is set at 65 kWh/m2. The starting value of the number of new residences is set to 0 by definition. If the number of new residences is set at 100,000, the heat demand for space heating increases by 100,000 apartments x 65 kWh/m2 x 84 m2/apartment._ +Note that, for existing stock, the typical heat demand and the actual heat demand for space heating are not directly related: the total heat demand is calculated top-down from the region's dataset, while the typical heat demand is only a bottom-up reference value, scaled by the insulation slider. The resulting typical heat demand values are used to calculate insulation costs. See the [Costs](cost-insulation-costs) section for details on this topic. For new stock, the typical heat demand is actually used to calculate the total heat demand. -Please note that, the **typical heat demand slider values _cannot_ be used to calculate the useful heat demand for existing building stock**. There are two reasons for this: -1. The starting year values for the typical heat demand values are typically not derived from the actual heat demand for space heating data. In fact, they are often derived from different sources entirely. -2. As mentioned above, the future year values of the typical heat demand sliders are only used as a scaling factor. Unlike for new residences/buildings, the actual slider value is not used to calculate heat demand in the future year. +### Behavioural change in space heating demand +The heat demand for space heating can also be changed due to behaviour, using the corresponding slider under the [Behaviour](https://energytransitionmodel.com/scenario/demand/households/behaviour) section for Households, or the equivalent [Behaviour](https://energytransitionmodel.com/scenario/demand/buildings/behaviour) section for Buildings. This slider sets a percentage change, from -50% to +50%, which is applied uniformly to the heat demand for space heating of all housing types and construction periods, including new stock. -Additionally, the typical heat demand sliders are used to calculate insulation costs. See the [Costs](cost-insulation-costs) section for details on this topic. +The behaviour slider is applied on top of, and independently from, the insulation sliders: it changes the actual heat demand for space heating for the simulated future year, but does not affect the typical heat demand values used to calculate insulation costs. For example, insulating a housing category by 20% and additionally setting the behaviour slider to +10% results in a heat demand for space heating of 0.8 x 1.1 = 88% of its start year value, but insulation costs are still calculated based on the 20% reduction in typical heat demand alone. ### Hot water -The demand for hot water is only defined for households. Residences of all housing types and build years are assumed to have the same hot water demand, since it is assumed to depend mostly on human behavior. The behavioral impact on hot water demand can be altered using the corresponding slider under the [Development of demand](https://energytransitionmodel.com/scenario/demand/households/development-of-demand) section. +The demand for hot water is only defined for households. Residences of all housing types and build years are assumed to have the same hot water demand, since it is assumed to depend mostly on human behavior. The behavioral impact on hot water demand can be altered using the corresponding slider under the [Behaviour](https://energytransitionmodel.com/scenario/demand/households/behaviour) section. ### Solar thermal panels Solar thermal panels in households are only used to meet hot water demand. They can be used to meet up to 100% of demand using the corresponding slider. The remaining demand is then met using the specified mix of technologies for space heating and hot water. @@ -66,12 +76,12 @@ Solar thermal panels in buildings are used to meet space heating demand, but onl ### Technologies for space heating and hot water A wide range of technologies is available to meet the space heating and hot water demand. Each slider sets the share of the total housing or building stock that is supplied by a particular technology. -* For **households**, a single technology is assumed to provide both space heating and hot water in a residence. +* For **households**, a single technology is assumed to provide both space heating and hot water in a residence. * For **buildings**, a technology only provides space heating, since the ETM does not specify hot water demand for buildings. It is not possible to directly specify the technology mix for each housing or building category. Instead, technologies are assigned to housing/building categories through a so-called **merit order**. A prioritized mix of technologies is assigned to housing/building stock first by build year, and for housing stock subsequently by housing type: first apartments, then terraced houses, semi-detached and finally detached houses. This order roughly follows the useful heat demand in increasing order, i.e. new apartments have a lower useful heat demand than detached houses from before 1945. The _consumer order_ is therefore fixed as follows: -| Housing stock | Building stock | +| Housing stock | Building stock | |------------------------|----------| | New apartments | New buildings | | New terraced houses | Existing buildings | @@ -83,7 +93,7 @@ It is not possible to directly specify the technology mix for each housing or bu The prioritized mix of technologies is called the _producer order_. Although it is fixed for buildings, the producer order for space heating in households can be adjusted by the user under the [Households merit order](https://energytransitionmodel.com/scenario/demand/households_heating_order/merit-order) section. -The merit order then works by assigning the first technology in the producer order to the first consumer in the consumer order (i.e. new apartments for households), then to the next consumer, and so on. This process continues until the specified share of residences for the first technology has been reached. The ETM then continues this process with the second technology in the producer order, until ultimately all housing/building stock is assigned a technology based on the specified technology shares. +The merit order then works by assigning the first technology in the producer order to the first consumer in the consumer order (i.e. new apartments for households), then to the next consumer, and so on. This process continues until the specified share of residences for the first technology has been reached. The ETM then continues this process with the second technology in the producer order, until ultimately all housing/building stock is assigned a technology based on the specified technology shares. A chart is available that visualizes the resulting number of residences per space heating technology. @@ -92,7 +102,7 @@ A chart is available that visualizes the resulting number of residences per spac Note that a housing category can be matched with more than one heating technology. In the chart above, the housing construction period 1985-2004 is split between air heat pumps and ground heat pumps, whereas newer residences have only been assigned air heat pumps. The reason for this is that the specified share of residences with an air heat pump was reached sometime during the 1985-2004 category, upon which the ETM switched to the next technology in the merit order, that is, ground heat pumps. ### Matching heat demand with supply -The ETM matches demand for space heating and hot water with supply on an hourly basis. It does this for both the **starting year** and the **simulated end year**. +The ETM matches demand for space heating and hot water with supply on an hourly basis. It does this for both the **starting year** and the **simulated end year**. How this proces works for the **starting year** can be found in the section [Built environment heat initialization](../contrib/fever-heat-initialization.md). Below the process for the **simulated end year** is described. @@ -101,8 +111,8 @@ Below the process for the **simulated end year** is described. * **Households water heating**: one water heating demand profile for households; * **Households space heating**: for each housing type (apartments / terraced / semi-detached / detached), the ETM contains a demand profile for high, medium and low levels of insulation. These are matched with build year categories as follows: * _high insulation_: 'new' and '2005-present' residences; - * _medium insulation_: '1965-1984' and '1985-2004' residences - * _low insulation_: '1945-1964' and 'before 1945' residences. + * _medium insulation_: '1965-1984' and '1985-2004' residences + * _low insulation_: '1945-1964' and 'before 1945' residences. The ETM thus contains 12 heat demand profiles in all. See [the ETDataset repository](https://github.com/quintel/etdataset-public/tree/master/curves/demand/) for details on these profiles. @@ -110,10 +120,10 @@ The ETM thus contains 12 heat demand profiles in all. See [the ETDataset reposit To **match demand with supply**, the ETM compares the heat demand profile of each housing/building category with the heat capacities of the assigned technologies: * If supply exceeds demand for an hourly interval, the given technology / technologies have sufficient capacity to provide the required heat. -* If not, the ETM allows for a slight shift in demand through buffering and time shifting. In practice, this means that the ETM can delay demand by four hours. +* If not, the ETM allows for a slight shift in demand through buffering and time shifting. In practice, this means that the ETM can delay demand by four hours. * If demand then still exceeds supply, a heat deficit is registered. -For households, there is a table available that lists the total annual heat deficits per housing category. +For households, there is a table available that lists the total annual heat deficits per housing category. ![](/img/docs/20240506_deficits_in_space_heating_per_residence_type_and_construction_period.png) diff --git a/sidebars.js b/sidebars.js index 4a370954..80ac72d2 100644 --- a/sidebars.js +++ b/sidebars.js @@ -152,6 +152,7 @@ module.exports = { items: [ "contrib/graph-components", "contrib/inputs", + "contrib/built-environment-inputs-priority", "contrib/molecules", "contrib/waste-outputs", "contrib/gql", diff --git a/static/img/docs/20240506_typical_heat_demand_sliders.png b/static/img/docs/20240506_typical_heat_demand_sliders.png deleted file mode 100644 index d6af5d4f..00000000 Binary files a/static/img/docs/20240506_typical_heat_demand_sliders.png and /dev/null differ diff --git a/static/img/docs/20260821_insulation_sliders.png b/static/img/docs/20260821_insulation_sliders.png new file mode 100644 index 00000000..31d93430 Binary files /dev/null and b/static/img/docs/20260821_insulation_sliders.png differ