User guide for commodity graphs

docs/SUMMARY.md

@@ -11,6 +11,7 @@
   - [Output Files](file_formats/output_files.md)
 - [Model Description](model/README.md)
   - [Units and Dimensions](model/units_and_dimensions.md)
+  - [Commodity Graphs](model/commodity_graphs.md)
   - [Dispatch Optimisation](model/dispatch_optimisation.md)
   - [Investment Appraisal](model/investment.md)
   - [Commodity Prices](model/prices.md)

docs/glossary.md

@@ -82,6 +82,10 @@ electricity.
 produced and/or consumed by *Processes* in the model. A *Service Demand* is a type of *Commodity* that
 is defined at the end point of the system.
 
+**Commodity Graph:** A directed graph built by MUSE2 for each *Milestone Year*, in which nodes are
+*Commodity Markets* and edges are *Processes*. It is used to validate the model, determine the
+*Investment Order* and identify *Circular Commodity Dependencies*.
+
 **Commodity Levy:** Represents a tax, levy or other external cost on a *Commodity*. Levies can be
 applied to all *Commodity* production (sum of output of all *Assets* for that *Commodity*), net
 production (sum of output and input for all *Assets*), or all consumption (sum of input for all

docs/images/commodity_graph_example.dot

@@ -0,0 +1,41 @@
+// Example commodity graph for docs/model/commodity_graphs.md
+// Render with: dot -Tsvg commodity_graph_example.dot -o commodity_graph_example.svg
+digraph commodity_graph {
+    rankdir=LR;
+    nodesep=0.4;
+    ranksep=0.8;
+    node [shape=box, style="rounded,filled", fontname="Helvetica", fontsize=12];
+    edge [fontname="Helvetica", fontsize=10];
+
+    SOURCE [shape=ellipse, style=dashed];
+
+    GASPRD [label="GASPRD\n(gas produced)", fillcolor="#B3CDE3"];
+    GASNAT [label="GASNAT\n(natural gas)", fillcolor="#B3CDE3"];
+    ELCTRI [label="ELCTRI\n(electricity)", fillcolor="#B3CDE3"];
+    H2YPRD [label="H2YPRD\n(hydrogen)", fillcolor="#B3CDE3"];
+    RSHEAT [label="RSHEAT\n(residential heat)", fillcolor="#CCEBC5"];
+    TPASKM [label="TPASKM\n(passenger km)", fillcolor="#CCEBC5"];
+    CO2EMT [label="CO2EMT\n(CO₂ emitted)", fillcolor="#FED9A6"];
+
+    SOURCE -> GASPRD [label="GASDRV"];
+    SOURCE -> ELCTRI [label="WNDFRM"];
+    GASPRD -> GASNAT [label="GASPRC"];
+    GASNAT -> ELCTRI [label="GASCGT"];
+    GASNAT -> CO2EMT [label="GASCGT", style=dashed];
+    GASNAT -> RSHEAT [label="RGASBR"];
+    GASNAT -> CO2EMT [label="RGASBR", style=dashed];
+    ELCTRI -> H2YPRD [label="H2YPRO"];
+    H2YPRD -> ELCTRI [label="H2YGEN"];
+    ELCTRI -> RSHEAT [label="RELCHP"];
+    ELCTRI -> TPASKM [label="TELCCR"];
+
+    legend [shape=plain, style="", fontsize=11, label=<
+      <table border="0" cellborder="1" cellspacing="0" cellpadding="4">
+        <tr><td colspan="2"><b>Key</b></td></tr>
+        <tr><td bgcolor="#CCEBC5">SVD</td><td align="left">service demand</td></tr>
+        <tr><td bgcolor="#B3CDE3">SED</td><td align="left">supply equals demand</td></tr>
+        <tr><td bgcolor="#FED9A6">OTH</td><td align="left">other</td></tr>
+        <tr><td>───</td><td align="left">primary output</td></tr>
+        <tr><td>- - -</td><td align="left">secondary output</td></tr>
+      </table>>];
+}

docs/images/investment_order_example.dot

@@ -0,0 +1,36 @@
+// Investment order example for docs/model/commodity_graphs.md
+// Render with: dot -Tsvg investment_order_example.dot -o investment_order_example.svg
+digraph investment_order {
+    rankdir=LR;
+    nodesep=0.4;
+    ranksep=0.8;
+    node [shape=box, style="rounded,filled", fontname="Helvetica", fontsize=12];
+    edge [fontname="Helvetica", fontsize=10];
+    fontname="Helvetica";
+    fontsize=12;
+
+    GASPRD [label="GASPRD\n(invested 4th)", fillcolor="#B3CDE3"];
+    GASNAT [label="GASNAT\n(invested 3rd)", fillcolor="#B3CDE3"];
+
+    subgraph cluster_cycle {
+        label="Circularity (invested 2nd)";
+        style="rounded,dashed";
+        ELCTRI [label="ELCTRI\n(2a)", fillcolor="#B3CDE3"];
+        H2YPRD [label="H2YPRD\n(2b)", fillcolor="#B3CDE3"];
+    }
+
+    subgraph cluster_layer {
+        label="Layer (invested 1st)";
+        style="rounded,dashed";
+        TPASKM [fillcolor="#CCEBC5"];
+        RSHEAT [fillcolor="#CCEBC5"];
+    }
+
+    GASPRD -> GASNAT;
+    GASNAT -> ELCTRI;
+    GASNAT -> RSHEAT;
+    ELCTRI -> H2YPRD;
+    H2YPRD -> ELCTRI;
+    ELCTRI -> RSHEAT;
+    ELCTRI -> TPASKM;
+}