Updated documentation on housing and building sliders

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
   },
   ...

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
     }

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
     }
   }

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_<housing_type>`
+
+   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_<construction_period>`
+   * `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_<construction_period>`
+   * `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.

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/m<sup>2</sup> (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,13 +42,11 @@ _Example_: 1000 terraced houses with a typical heat demand of 350 kWh/m<sup>2</s
 * Total per residence: €23,910
 * *Total insulation costs: €23,910,000*
 
-For new housing stock, insulation costs are only incurred when the typical heat demand is further reduced compared to the default value. In that case, the insulation costs are calculated using the higher costs category. For new terraced houses, for example, that would be €157 per kWh / further typical heat demand reduction.
-
 ## Buildings
 The insulation costs for buildings follow the same procedure as described above for households. The costs figure for buildings are based on the _tussenwoning_ figures from the Ecofys report, i.e.:
 
 |   | **Insulation costs from low to medium in €/(kWh/m<sup>2</sup>)**  | **Insulation from medium to high in €/(kWh/m<sup>2</sup>)** |
 |---|---|---|
 | Existing building stock | 39 | 157 |
 
-For new building stock insulation costs of €157/(kWh/m<sup>2</sup>) are used for additional insulation.
+For new building stock insulation costs of €157/(kWh/m<sup>2</sup>) are used for additional insulation.

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.