Add skeleton of mkdocs

docs/_generated/.gitignore

@@ -0,0 +1 @@
+*.md

docs/api_reference.md

@@ -0,0 +1,23 @@
+## Model
+
+::: calliope.Model
+
+## `calliope.backend.backend_model.BackendModel` (methods to interface with the optimisation problem)
+
+::: calliope.backend.backend_model.BackendModel
+
+## `calliope.core.attrdict.AttrDict`
+
+::: calliope.core.attrdict.AttrDict
+
+## `calliope.exceptions`
+
+::: calliope.exceptions
+
+## `calliope.core.util.logging`
+
+::: calliope.core.util.logging
+
+## `calliope.backend.helper_functions` (math formulation helper functions)
+
+::: calliope.backend.helper_functions

docs/cli_reference.md

@@ -0,0 +1,9 @@
+# CLI Reference
+
+This page provides documentation for the `calliope` command line tool.
+
+::: mkdocs-click
+    :module: calliope.cli
+    :command: cli
+    :prog_name: calliope
+    :depth: 1

docs/css/extra.css

@@ -0,0 +1,48 @@
+:root {
+    --md-primary-fg-color:        #98252D;
+    --md-primary-fg-color--light: #ECB7B7;
+    --md-primary-fg-color--dark:  #90030C;
+}
+
+.md-grid {
+    /* max-width: 1340px; */
+}
+
+.md-typeset, .md-nav, .md-tabs__link, .md-typeset .admonition, .md-typeset details, .md-typeset table:not([class]) {
+    font-size: 0.8rem;
+}
+
+.md-typeset h1, .md-typeset h2 {
+    font-weight: normal;
+    color: var(--md-typeset-color);
+}
+
+.doc-function h3 {
+    /* font-size: 1.0rem; */
+    margin-top: 3.0rem;
+}
+
+.bubble {
+    border-radius: 2px;
+    padding: 1px 4px 1px 4px;
+}
+
+.green {
+    background-color: rgba(0, 151, 142, 0.25);
+    color: #00978e;
+}
+
+.blue {
+    background-color: rgba(0, 83, 159, 0.25);
+    color: #00539f;
+}
+
+.red {
+    background-color: rgba(217, 57, 54, 0.25);
+    color: #D93936;
+}
+
+.yellow {
+    background-color: rgba(254, 247, 80, 0.5);
+    color: #757719;
+}

docs/custom_math/annual_energy_balance.yaml

@@ -0,0 +1,63 @@
+# title: Annual energy balance
+
+# description: |
+#   Limit or set the total (e.g. annual) outflow of a technology to a specified absolute value.
+#
+#   New technology-level parameters:
+#
+#   * `annual_flow_max`
+#   * `annual_source_max`
+#
+#   New top-level parameters:
+#
+#   * `annual_flow_max` (if summing over technologies and/or nodes)
+#   * `flow_max_group` (if summing over technologies and/or nodes)
+#
+#   Helper functions used:
+#
+#   * `inheritance` (where)
+#   * `sum` (expression)
+#
+# ---
+
+constraints:
+  annual_energy_balance_per_tech_and_node:
+    description: Limit total technology annual energy production at each possible deployment site.
+    foreach: [nodes, techs]
+    where: annual_flow_max
+    equations:
+      - expression: "sum(flow_out, over=[carriers, timesteps]) <= annual_flow_max"
+
+  annual_energy_balance_global_per_tech:
+    description: Limit total technology annual energy production across all possible deployment sites.
+    foreach: [techs]
+    where: annual_flow_max
+    equations:
+      - expression: "sum(flow_out, over=[nodes, carriers, timesteps]) <= annual_flow_max"
+
+  annual_energy_balance_global_multi_tech:
+    description: Limit total combined technology annual energy production across all possible deployment sites.
+    # To slice a model component with a list of values, we need to use referenced `slices`.
+    where: annual_flow_max AND flow_max_group
+    equations:
+      - expression: "sum(flow_out[techs=$techs], over=[nodes, techs, carriers, timesteps]) <= annual_flow_max"
+    slices:
+      techs:
+        - expression: flow_max_group
+
+  annual_energy_balance_total_source_availability:
+    description: >
+      Limit total flow into the system from a particular source.
+      NOTE: this only works for supply_plus technologies.
+        For `supply` technologies you will need to convert `flow_out` to `flow_in` using `energy_eff` and limit that.
+    foreach: [techs]
+    where: source_use AND annual_source_max
+    equations:
+      - expression: "sum(source_use, over=[nodes, techs, timesteps]) <= annual_source_max"
+
+  annual_energy_balance_total_sink_availability:
+    description: Limit total flow out of the system into a sink that is not pinned by `sink_equals`.
+    foreach: [techs]
+    where: inheritance(demand) AND annual_sink_max
+    equations:
+      - expression: "sum(flow_in, over=[nodes, carriers, timesteps]) <= annual_sink_max"

docs/custom_math/chp_htp.yaml

@@ -0,0 +1,148 @@
+# title: CHP plants
+
+# description: |
+#   Set Combined heat and power (CHP) plant heat to power operational zones.
+#   There are three types of CHP that can be described by the following constraints:
+#   1. CHPs with extraction (condensing) turbines, where some electrical efficiency can be sacrificed by diverting high-temperature steam to provide more heat (following the extraction (cv) line).
+#   At maximum electrical efficiency, some heat can still be generated from the low-temperature steam output (following the backpressure (cb) line).
+#   The following figure shows the 2D plane of electricity and heat generation; there is a third dimension not shown here: fuel consumption.
+#
+#   ```text
+#   Along the cv line, fuel consumption remains constant.
+#   ^
+#   |Electricity
+#   |
+#   |----
+#   |    \-------   Cv
+#   |            \-------
+#   |                    \-------
+#   |                            \------
+#   |                              --/
+#   |    operating region       --/
+#   |                        --/
+#   |                     --/
+#   |                  --/
+#   |               --/
+#   |            --/   Cb
+#   |         --/
+#   |      --/
+#   |   --/
+#   | -/                              Heat
+#   -------------------------------------->
+#   ```
+#
+#   2. CHPs without extraction turbines, but with auxiliary boilers that can be used to divert fuel use for direct heat generation.
+#   At maximum electrical efficiency, some heat can be generated from the low-temperature steam output (following the backpressure (cb) line).
+#   For the same fuel input, electricity output can be sacrificed by diverting some fuel to direct use in a boiler, with its own efficiency.
+#   This leads to two sources of heat output (E = electricity output): H1 = E / cb; H2 / boiler_eff + E / turbine_eff = fuel_consumption. Total heat output H is then H1 + H2.
+#   The following figure shows the 2D plane of electricity and heat generation; there is a third dimension not shown here: fuel consumption.
+#
+#   ```text
+#   ^
+#   |Electricity
+#   |
+#   |                  --/
+#   |         Cb    --/   \-
+#   |            --/        \-
+#   |         --/             \-
+#   |      --/                  \-
+#   |   --/        operating      \-
+#   | -/            region          \-  Heat
+#   ---------------------------------------->
+#   ````
+#
+#   3. CHPs without extraction turbines and without an auxiliary boiler.
+#   Here, there is no operating region; the output must follow the backpressure line.
+#
+#   ```text
+#   ^
+#   |Electricity
+#   |
+#   |                          /--
+#   |                       /--
+#   |               Cb   /--
+#   |                 /--
+#   |               /-
+#   |            /--
+#   |         /--
+#   |      /--
+#   |    /-
+#   | /--                             Heat
+#   -------------------------------------->
+#   ```
+#
+#   New technology-level parameters:
+#
+#   * `turbine_type` (used to group constraints together)
+#   * `power_loss_factor`
+#   * `power_to_heat_ratio`
+#   * `boiler_eff`
+#
+#   Helper functions used:
+#
+#   * `reduce_carrier_dim` (expression)
+#
+# ---
+
+constraints:
+# Extraction turbine constraints
+# ~~
+  chp_extraction_line:
+    description: >
+      Set the extraction line for combined heat and power plants with extraction turbines.
+      `power_loss_factor` is also referred to as simply `cv`.
+    foreach: [nodes, techs, timesteps]
+    where: turbine_type=extraction
+    equations:
+      - expression: >
+          flow_out[carriers=electricity]
+          <= (reduce_carrier_dim(flow_in, carrier_tier=in) * energy_eff)
+             - (flow_out[carriers=heat] * power_loss_factor)
+
+  chp_backpressure_line_min:
+    description: >
+      Set the backpressure line as a lower bound for electricity generation in combined heat and power plants with extraction turbines.
+      `power_to_heat_ratio` is also referred to as the `backpressure ratio` or simply `cb`.
+    foreach: [nodes, techs, timesteps]
+    where: turbine_type=extraction
+    equations:
+      - expression: flow_out[carriers=electricity] >= flow_out[carriers=heat] * power_to_heat_ratio
+# ~~
+
+# Backpressure with direct boiler option
+# ~~
+  chp_backpressure_line_max:
+    description: >
+      Set the backpressure line as a lower bound for heat generation in combined heat and power plants without extraction turbines, but with the option to divert fuel to use in direct heat generation (e.g., via a boiler).
+      `power_to_heat_ratio` is also referred to as the `backpressure ratio` or simply `cb`.
+    foreach: [nodes, techs, timesteps]
+    where: turbine_type=backpressure AND boiler_eff
+    equations:
+      - expression: flow_out[carriers=electricity] <= flow_out[carriers=heat] * power_to_heat_ratio
+
+  chp_divert_fuel_to_boiler:
+    description: >
+      Divert fuel input from use in combined heat and power generation to be used in direct heat generation (e.g., via a boiler).
+      `heat_eff` is the boiler efficiency.
+      `power_to_heat_ratio` is also referred to as the `backpressure ratio` or simply `cb`.
+    foreach: [nodes, techs, timesteps]
+    where: turbine_type=backpressure AND boiler_eff
+    equations:
+      - expression: >
+          flow_out[carriers=heat]
+          <= (reduce_carrier_dim(flow_in, carrier_tier=in) * boiler_eff)
+             - (flow_out[carriers=electricity] * (
+                  (boiler_eff / energy_eff) - (1 / power_to_heat_ratio)
+               )
+          )
+# ~~
+
+# Backpressure only
+  chp_backpressure_line_equals:
+    description: >
+      Fix the backpressure line for combined heat and power plants without extraction turbines.
+      `power_to_heat_ratio` is also referred to as the `backpressure ratio` or simply `cb`.
+    foreach: [nodes, techs, timesteps]
+    where: turbine_type=backpressure AND NOT boiler_eff
+    equations:
+      - expression: flow_out[carriers=electricity] == flow_out[carriers=heat] * power_to_heat_ratio

docs/custom_math/demand_share_per_timestep_decision.yaml

@@ -0,0 +1,78 @@
+# title: Demand share per timestep as decision variable
+
+# description: |
+#   Allows the model to decide on how a fraction of demand for a carrier is met by the given group of technologies, which will each have the same share in each timestep.
+#   Variables and constraints defined here could be extended to iterate over nodes  and over carriers if desired.
+#   If summing over nodes, remove the summation over nodes in the constraints and add it into the list in `demand_share_per_timestep_decision_sum` (if using).
+#   If summing over carriers, the slicing of `sink_equals` will need to change per carrier by using a where statement in `slices: ...`.
+#
+#   The share is relative to the flow `sink` from a specified `demand` technology (or group thereof) only.
+#
+#   Specifying `relaxation` inside the constraint to a non-zero value allows the constraint some flexibility around a given value, making a model easier to solve.
+#
+#   New top-level parameters:
+#
+#   * ``relaxation`` (defined here directly)
+#   * ``demand_share_limit`` (defined here directly)
+#
+#   Helper functions used:
+#
+#   * sum (expression)
+#   * select_from_lookup_arrays (expression)
+#
+# ---
+
+variables:
+  demand_share_per_timestep_decision:
+    description: Relative share of demand that a given technology must meet per node.
+    unit: fraction
+    foreach: [nodes, techs]
+    where: NOT config.mode=operate AND decide_demand_share
+    bounds:
+      min: 0
+      max: .inf
+
+# The two main constraints enforce that the shares are the same in each timestep,
+# with an optional relaxation.
+
+constraints:
+  demand_share_per_timestep_decision_main_min:
+    description: Limit the lower bound of a technology's outflow to the share of demand that the model has decided it will meet.
+    foreach: [nodes, techs, timesteps]
+    where: demand_share_per_timestep_decision
+    equations:
+      - expression: >
+          flow_out[carriers=$carrier] >=
+          (1 - $relaxation) * select_from_lookup_arrays(sink_equals, techs=decide_demand_share) * demand_share_per_timestep_decision
+    sub_expressions:
+      # 0 == no relaxation, 0.01 == 1% relaxation (lhs == rhs -> lhs >= 0.99 * rhs & lhs <= 1.01 * rhs)
+      relaxation: &relaxation_component
+        - where: demand_share_relaxation
+          expression: demand_share_relaxation
+        - where: NOT demand_share_relaxation
+          expression: "0"
+    slices: &slice
+      carrier:
+        - expression: demand_share_carrier  # assigned as a top-level parameter
+
+  demand_share_per_timestep_decision_main_max:
+    description: Limit the upper bound of a technology's outflow to the share of demand that the model has decided it will meet.
+    foreach: [nodes, techs, timesteps]
+    where: demand_share_per_timestep_decision
+    equations:
+      - expression: >
+          flow_out[carriers=$carrier] <=
+          (1 + $relaxation) * select_from_lookup_arrays(sink_equals, techs=decide_demand_share) * demand_share_per_timestep_decision
+    sub_expressions:
+      relaxation: *relaxation_component
+    slices: *slice
+
+# The optional additional sum constraint ensures that all decision shares add up
+# to a specified share of carrier demand (here, 50% = 0.5 of electricity demand).
+
+  demand_share_per_timestep_decision_sum:
+    description: Limit the total share of demand that can be met by technologies controlled by the `demand_share_per_timestep_decision` variable.
+    foreach: [nodes, timesteps]
+    where: demand_share_per_timestep_decision AND demand_share_limit
+    equations:
+      - expression: sum(demand_share_per_timestep_decision, over=[techs]) == demand_share_limit

docs/hooks/changelog_highlight.py

@@ -0,0 +1,17 @@
+REPLACEMENTS = {
+    # Changelog
+    "|new|": "<span class='bubble green'>new</span>",
+    "|fixed|": "<span class='bubble blue'>fixed</span>",
+    "|changed|": "<span class='bubble yellow'>changed</span>",
+    "|backwards-incompatible|": "<span class='bubble red'>backwards-incompatible</span>",
+    # Math documentation
+    "|REMOVED|": "<span class='bubble red'>REMOVED</span>",
+    "|UPDATED|": "<span class='bubble yellow'>UPDATED</span>",
+    "|NEW|": "<span class='bubble green'>NEW</span>",
+}
+
+
+def on_page_markdown(markdown, **kwargs):
+    for old, new in REPLACEMENTS.items():
+        markdown = markdown.replace(old, new)
+    return markdown