Merge branch 'main' into update-math-docs-cross-refs

AUTHORS

@@ -13,3 +13,4 @@ Francesco Lombardi, Politecnico di Milano <[email protected]>
 Adriaan Hilbers, Imperial College London <[email protected]>
 Jann Launer, TU Delft <[email protected]>
 Ivan Ruiz Manuel, TU Delft <[email protected]>
+Stefan Strömer, AIT Austrian Institute of Technology GmbH and TU Delft <[email protected]>

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ### User-facing changes
 
+|changed| `node_groups` and `tech_groups` changed to a general top-level `templates` key,
+accessed via the `template` key (replacing `inherit`) in `nodes` and `techs` (#600).
+
+|fixed| Contribution of `cost_om_annual_investment_fraction` to total investment costs, to not apply to depreciated costs (#645).
+
+|fixed| Math for multi-carrier variable export costs (#663).
+
 |new| Piecewise constraints added to the YAML math with its own unique syntax (#107).
 These constraints will be added to the optimisation problem using Special Ordered Sets of Type 2 (SOS2) variables.
 

docs/advanced/mode.md

@@ -98,9 +98,9 @@ Technologies at locations with higher scores will be penalised in the objective
 In the [national scale example model](../examples/national_scale/index.md), this would look something like:
 
 ```yaml
-tech_groups:
+templates:
   add_spores_score:
-    inherit: cost_dim_setter
+    template: cost_dim_setter
     cost_flow_cap:
       data: [null, null]
       index: ["monetary", "spores_score"]
@@ -112,16 +112,16 @@ tech_groups:
 
 techs:
   ccgt:
-    inherit: add_spores_score
+    template: add_spores_score
     cost_flow_cap.data: [750, 0]
   csp:
-    inherit: add_spores_score
+    template: add_spores_score
     cost_flow_cap.data: [1000, 0]
   battery:
-    inherit: add_spores_score
+    template: add_spores_score
     cost_flow_cap.data: [null, 0]
   region1_to_region2:
-    inherit: add_spores_score
+    template: add_spores_score
     cost_flow_cap.data: [10000, 0]
 ```
 

docs/creating/data_sources.md

@@ -235,7 +235,7 @@ In this section we will show some examples of loading data and provide the equiv
 === "YAML"
 
     ```yaml
-    tech_groups:  # (1)!
+    templates:  # (1)!
       cost_setter:
         cost_interest_rate:
           data: 0.1
@@ -260,7 +260,7 @@ In this section we will show some examples of loading data and provide the equiv
 
     techs:
       tech1:
-        inherit: cost_setter
+        template: cost_setter
         cost_flow_cap.data: 100
         cost_area_use.data: 50
         cost_flow_out.data: 0.2
@@ -269,7 +269,7 @@ In this section we will show some examples of loading data and provide the equiv
         cost_storage_cap.data: 150
     ```
 
-    1. To limit repetition, we have defined [technology groups](groups.md) for our costs.
+    1. To limit repetition, we have defined [templates](templates.md) for our costs.
 
 !!! info "See also"
     Our [data source loading tutorial][loading-tabular-data] has more examples of loading tabular data into your model.

docs/creating/index.md

@@ -35,7 +35,7 @@ We distinguish between:
 - the model **definition** (your representation of a physical system in YAML).
 
 Model configuration is everything under the top-level YAML key [`config`](config.md).
-Model definition is everything else, under the top-level YAML keys [`parameters`](parameters.md), [`techs`](techs.md), [`nodes`](nodes.md), [`tech_groups`](groups.md), [`node_groups`](groups.md), and [`data_sources`](data_sources.md).
+Model definition is everything else, under the top-level YAML keys [`parameters`](parameters.md), [`techs`](techs.md), [`nodes`](nodes.md), [`templates`](templates.md), and [`data_sources`](data_sources.md).
 
 It is possible to define alternatives to the model configuration/definition that you can refer to when you initialise your model.
 These are defined under the top-level YAML keys [`scenarios` and `overrides`](scenarios.md).
@@ -84,5 +84,5 @@ The rest of this section discusses everything you need to know to set up a model
 - An overview of [YAML as it is used in Calliope](yaml.md) - though this comes first here, you can also safely skip it and refer back to it as a reference as questions arise when you go through the model configuration and definition examples.
 - More details on the [model configuration](config.md).
 - The key parts of the model definition, first, the [technologies](techs.md), then, the [nodes](nodes.md), the locations in space where technologies can be placed.
-- How to use [technology and node inheritance](groups.md) to reduce repetition in the model definition.
+- How to use [technology and node templates](templates.md) to reduce repetition in the model definition.
 - Other important features to be aware of when defining your model: defining [indexed parameters](parameters.md), i.e. parameter which are not indexed over technologies and nodes, [loading tabular data](data_sources.md), and defining [scenarios and overrides](scenarios.md).

docs/creating/techs.md

@@ -12,12 +12,13 @@ This establishes the basic characteristics in the optimisation model (decision v
 * `transmission`: Transmits a carrier from one node to another.
 * `conversion`: Converts from one carrier to another.
 
-??? info "Sharing configuration through inheritance"
-    To share definitions between technologies and/or nodes, you can use configuration inheritance (the `inherit` key).
-    This allows a technology/node to inherit definitions from [`tech_group`/`node_group` definitions](groups.md).
-    Note that `inherit` is different to setting a `base_tech`.
-    Setting a base_tech does not entail any configuration options being inherited.
-    It is only used when building the optimisation problem (i.e., in the `math`).
+??? info "Sharing configuration with templates"
+
+    To share definitions between technologies and/or nodes, you can use configuration templates (the `template` key).
+    This allows a technology/node to inherit definitions from [`template` definitions](templates.md).
+    Note that `template` is different to setting a `base_tech`.
+    Setting a base_tech does not entail any configuration options being inherited;
+    `base_tech` is only used when building the optimisation problem (i.e., in the `math`).
 
 The following example shows the definition of a `ccgt` technology, i.e. a combined cycle gas turbine that delivers electricity:
 
@@ -193,4 +194,4 @@ In an [override](scenarios.md) you may want to remove a technology entirely from
 The easiest way to do this is to set `active: false`.
 The resulting input dataset won't feature that technology in any way.
 You can even do this to deactivate technologies at specific [nodes](nodes.md) and to deactivate nodes entirely.
-Conversely, setting `active: true` in an override will lead to the technology reappearing.
+Conversely, setting `active: true` in an override will lead to the technology reappearing.

docs/creating/groups.md → docs/creating/templates.md

@@ -1,43 +1,43 @@
 
-# Inheriting from technology node groups: `tech_groups`, `node_groups`
+# Inheriting from templates: `templates`
 
 For larger models, duplicate entries can start to crop up and become cumbersome.
-To streamline data entry, technologies and nodes can inherit common data from a `tech_group` or `node_group`, respectively.
+To streamline data entry, technologies and nodes can inherit common data from a `template`.
 
 For example, if we want to set interest rate to `0.1` across all our technologies, we could define:
 
 ```yaml
-tech_groups:
+templates:
   interest_rate_setter:
     cost_interest_rate:
       data: 0.1
       index: monetary
       dims: costs
 techs:
   ccgt:
-    inherit: interest_rate_setter
+    template: interest_rate_setter
     ...
   ac_transmission:
-    inherit: interest_rate_setter
+    template: interest_rate_setter
     ...
 ```
 
 Similarly, if we want to allow the same technologies at all our nodes:
 
 ```yaml
-node_groups:
+templates:
   standard_tech_list:
     techs: {ccgt, battery, demand_power}  # (1)!
 nodes:
   region1:
-    inherit: standard_tech_list
+    template: standard_tech_list
     ...
   region2:
-    inherit: standard_tech_list
+    template: standard_tech_list
     ...
   ...
   region100:
-    inherit: standard_tech_list
+    template: standard_tech_list
 ```
 
 1. this YAML syntax is shortform for:
@@ -48,19 +48,19 @@ nodes:
       demand_power:
     ```
 
-Inheritance chains can also be set up.
-That is, groups can inherit from groups.
+Inheritance chains can also be created.
+That is, templates can inherit from other templates.
 E.g.:
 
 ```yaml
-tech_groups:
+templates:
   interest_rate_setter:
     cost_interest_rate:
       data: 0.1
       index: monetary
       dims: costs
   investment_cost_setter:
-    inherit: interest_rate_setter
+    template: interest_rate_setter
     cost_flow_cap:
       data: 100
       index: monetary
@@ -71,25 +71,25 @@ tech_groups:
        dims: costs
 techs:
   ccgt:
-    inherit: investment_cost_setter
+    template: investment_cost_setter
     ...
   ac_transmission:
-    inherit: interest_rate_setter
+    template: interest_rate_setter
     ...
 ```
 
-Finally, inherited properties can always be overridden by the inheriting component.
+Finally, template properties can always be overridden by the inheriting component.
 This can be useful to streamline setting costs, e.g.:
 
 ```yaml
-tech_groups:
+templates:
   interest_rate_setter:
     cost_interest_rate:
       data: 0.1
       index: monetary
       dims: costs
   investment_cost_setter:
-    inherit: interest_rate_setter
+    template: interest_rate_setter
     cost_interest_rate.data: 0.2  # this will replace `0.1` in the `interest_rate_setter`.
     cost_flow_cap:
       data: null
@@ -101,7 +101,7 @@ tech_groups:
       dims: costs
 techs:
   ccgt:
-    inherit: investment_cost_setter
+    template: investment_cost_setter
     cost_flow_cap.data: 100  # this will replace `null` in the `investment_cost_setter`.
     ...
 ```

docs/examples/index.md

@@ -16,6 +16,6 @@ The ["urban scale" example](urban_scale/index.md) builds a model for part of a d
 
 * Use of conversion technologies with singular and multiple output carriers.
 * Revenue generation, by carrier export.
-* Inheriting from technology groups
+* Inheriting from templates
 
 The ["MILP" example](milp/index.md) extends the urban scale example, exhibiting binary and integer decision variable functionality (extended an LP model to a MILP model).

docs/examples/national_scale/index.md

@@ -110,16 +110,16 @@ The costs are more numerous as well, and include monetary costs for all relevant
 * carrier conversion capacity
 * variable operational and maintenance costs
 
-### Interlude: inheriting from technology groups
+### Interlude: inheriting from templates
 
 You will notice that the above technologies _inherit_ `cost_dim_setter`.
-Inheritance allows us to avoid excessive repetition in our model definition.
+Templates allow us to avoid excessive repetition in our model definition.
 In this case, `cost_dim_setter` defines the dimension and index of costs, allowing us to keep our definition of technology costs to only defining `data`.
 By defining `data`, the technologies override the `null` setting applied by `cost_dim_setter`.
 We also use it to set the `interest_rate` for all technologies, which will be used to annualise any investment costs each technology defines.
 
-Technologies can inherit from anything defined in `tech_groups`, while nodes can inherit from anything in `node_groups`.
-items in `[tech/node]_groups` can also inherit from each other, so you can create inheritance chains.
+Technologies and nodes can inherit from anything defined in `templates`.
+items in `templates` can also inherit from each other, so you can create inheritance chains.
 
 `cost_dim_setter` looks like this:
 
@@ -185,7 +185,7 @@ Transmission technologies look different to other technologies, as they link the
 As the name suggests, it applies no cost or efficiency losses to this transmission.
 
 We can see that those technologies which rely on `free_transmission` inherit a lot of this information from elsewhere in the model definition.
-`free_transmission` is defined in `tech_groups`, which makes it inheritable.
+`free_transmission` is defined in `templates`, which makes it inheritable.
 
 ```yaml
 --8<-- "src/calliope/example_models/national_scale/model_config/techs.yaml:free-transmission"
@@ -234,11 +234,11 @@ The remaining nodes look similar:
 ```
 
 `region2` is very similar to `region1`, except that it does not include the `ccgt` technology.
-The three `region1-` locations are defined together using the node group `csp_regions`, except for their geospatial coordinates.
+The three `region1-` locations are defined together using the template `csp_regions`, except for their geospatial coordinates.
 They allow only the `csp` technology, this allows us to model three possible sites for CSP plants.
 
 ```yaml
---8<-- "src/calliope/example_models/national_scale/model_config/locations.yaml:node-groups"
+--8<-- "src/calliope/example_models/national_scale/model_config/locations.yaml:templates"
 ```
 
 ---

docs/examples/urban_scale/index.md

@@ -37,7 +37,7 @@ You can find out more about this user-defined math [below](#interlude-user-defin
 ### Bringing the YAML files together
 
 Technically, you could define everything about your model in the same file as your configuration.
-One file with the top-level keys `config`, `parameters`, `techs`, `nodes`, `tech_groups`, `node_groups`, `scenarios`, `overrides`.
+One file with the top-level keys `config`, `parameters`, `techs`, `nodes`, `templates`, `scenarios`, `overrides`.
 However, this tends to become unwieldy.
 
 Instead, various parts of the model are defined in different files and then we `import` them in the YAML file that we are going to load into calliope (`calliope.Model("my_main_model_file.yaml")`).
@@ -127,14 +127,14 @@ The definition of this technology in the example model's configuration looks as
 --8<-- "src/calliope/example_models/urban_scale/model_config/techs.yaml:pv"
 ```
 
-### Interlude: inheriting from technology groups
+### Interlude: inheriting from templates
 
 You will notice that the above technologies _inherit_ `interest_rate_setter`.
-Inheritance allows us to avoid excessive repetition in our model definition.
+Templates allow us to avoid excessive repetition in our model definition.
 In this case, `interest_rate_setter` defines an interest rate that will be used to annualise any investment costs the technology defines.
 
-Technologies can inherit from anything defined in `tech_groups`, while nodes can inherit from anything in `node_groups`.
-items in `[tech/node]_groups` can also inherit from each other, so you can create inheritance chains.
+Technologies / nodes can inherit from anything defined in `templates`.
+items in `templates` can also inherit from each other, so you can create inheritance chains.
 
 `interest_rate_setter` looks like this:
 
@@ -241,10 +241,10 @@ Gas is made available in each node without consideration of transmission.
 --8<-- "src/calliope/example_models/urban_scale/model_config/techs.yaml:transmission"
 ```
 
-To avoid excessive duplication in model definition, our transmission technologies inherit most of the their parameters from technology _groups_:
+To avoid excessive duplication in model definition, our transmission technologies inherit most of the their parameters from _templates_:
 
 ```yaml
---8<-- "src/calliope/example_models/urban_scale/model_config/techs.yaml:transmission-tech-groups"
+--8<-- "src/calliope/example_models/urban_scale/model_config/techs.yaml:transmission-templates"
 ```
 
 `power_lines` has an efficiency of 0.95, so a loss during transmission of 0.05.
@@ -316,4 +316,4 @@ These revenue possibilities are reflected in the technologies' and locations' de
 ---
 !!! info "Where to go next"
     To try loading and solving the model yourself, move on to the accompanying notebook [here][running-the-urban-scale-example-model].
-    You can also find a list of all the example models available in Calliope [here][calliope.examples].
+    You can also find a list of all the example models available in Calliope [here][calliope.examples].