Add skeleton of mkdocs

.gitignore

@@ -30,3 +30,4 @@ doc/_build/
 doc/_static/notebooks/*.html
 .ipynb_checkpoints
 outputs/
+site/

.readthedocs.yml

@@ -1,9 +1,17 @@
-version: 2 # required
+version: 2
 conda:
-  environment: requirements/docs.yml
+  environment: requirements/base.txt
 build:
-  os: ubuntu-22.04 # required
+  os: ubuntu-22.04
   tools:
     python: mambaforge-4.10
-sphinx:
-  configuration: doc/conf.py
+  jobs:
+    pre_build:
+      - python ./docs/pre_build/generate_math.py
+    post_create_environment:
+      - mamba install python=3.11 --file requirements/docs.txt
+      - pip install --no-deps .
+
+
+mkdocs:
+  configuration: mkdocs.yml

Makefile

@@ -1,9 +1,7 @@
-.PHONY : doc-plots, doc-math
-doc-plots :
-	python doc/helpers/generate_plots.py
+.PHONY : doc-math
 
 doc-math :
-	python doc/helpers/generate_math.py
+	python docs/pre_build/generate_math.py
 
 ###
 # Build package and upload to PyPI

doc/helpers/generate_readable_schema.py

@@ -13,7 +13,7 @@
 from typing import Union
 
 import jsonschema2md
-import yaml
+import ruamel.yaml
 
 
 def schema_to_md(
@@ -28,8 +28,8 @@ def schema_to_md(
     parser = jsonschema2md.Parser()
     parser.tab_size = 2
 
-    with Path(path_to_schema).open("r") as f_schema:
-        schema = yaml.safe_load(f_schema)
+    yaml = ruamel.yaml.YAML(typ="safe")
+    schema = yaml.load(Path(path_to_schema).read_text())
 
     lines = parser.parse_schema(schema)
     lines = customise_markdown(lines)

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.attrdict.AttrDict`
+
+::: calliope.attrdict.AttrDict
+
+## `calliope.exceptions`
+
+::: calliope.exceptions
+
+## `calliope.util.logging`
+
+::: calliope.util.logging
+
+## `calliope.backend.helper_functions` (math formulation helper functions)
+
+::: calliope.backend.helper_functions

docs/cli_reference.md

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

docs/css/extra.css

@@ -0,0 +1,52 @@
+.rst-badge {
+    font-size: 0.7rem;
+}
+
+: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