feat(project): Add multi-models to project manifests.

examples/my-model/README.md

@@ -14,6 +14,8 @@ my-model/
 │   └── inflows/           # network set `catchment::inflows`: one inflow per model
 │       ├── historical.json
 │       └── stochastic.json
+├── neighbour/             # sub-network: a neighbouring supply system
+│   └── base.json
 └── options/               # network set: optional supply schemes
     ├── option1.json
     └── option2.json
@@ -26,17 +28,18 @@ for the base model node it connects to (`demand1` or `link1`) and adds a new sup
 
 ## Manifest
 
-The manifest has four parts:
+The manifest has five parts:
 
-- **`sub_networks`** declare directories that hold part of the model, each with its own network
-  sets. The `catchment` sub-network has one set, `inflows`, referred to as `catchment::inflows`.
-  It sets `min` and `max` to 1, so every model that uses the catchment must select exactly one
-  inflow.
+- **`sub_networks`** declare directories that hold part of the model, each with an optional base
+  network and its own network sets. The `catchment` sub-network has one set, `inflows`, referred
+  to as `catchment::inflows`. It sets `min` and `max` to 1, so every model that uses the
+  catchment must select exactly one inflow. The `neighbour` sub-network has only a base network.
 - **`network_sets`** name the project's own directories of fragments.
 - **`networks`** are reusable network definitions. Each selects files from the network sets.
   `historical` and `stochastic` name `catchment` as their `base`, which activates the
-  sub-network; a model cannot select from a sub-network's sets unless it is active. `option12`
-  extends `option1` and `option2` to combine them.
+  sub-network; a model cannot select from a sub-network's sets unless it is active. `neighbour`
+  is the `neighbour` sub-network's base network on its own. `option12` extends `option1` and
+  `option2` to combine them.
 - **`models`** are the runnable model definitions. Each starts from `base_model` and merges the
   networks it lists, in order.
 
@@ -48,6 +51,13 @@ The manifest has four parts:
 | `baseline-option2`    | `historical`, `option2`  | Adds supply option 2           |
 | `baseline-option12`   | `historical`, `option12` | Adds both supply options       |
 
+- **`multi_models`** are runnable multi-network models, whose networks run together and pass
+  values to each other through transfers. `joint-historical` takes its time domain from the
+  `baseline-historical` model and has two networks:
+    - `company`, the network of the `baseline-historical` model;
+    - `neighbour`, the `neighbour` network definition. Its `import` node's maximum flow is the
+      transfer `company-link1-flow`, which carries the flow through `link1` in `company`.
+
 ## Running
 
 From the repository root:
@@ -57,6 +67,8 @@ cargo run -p pywr-cli -- run-project examples/my-model/pywr-project.json \
     --definition baseline-option1 --output-path /tmp/my-model
 ```
 
+`--definition` takes the name of a model or a multi-model.
+
 The base model writes its results to `outputs.h5` in the output path.
 
 

examples/my-model/neighbour/base.json

@@ -0,0 +1,34 @@
+{
+  "nodes": [
+    {
+      "type": "Input",
+      "meta": {
+        "name": "import"
+      },
+      "max_flow": {
+        "type": "InterNetworkTransfer",
+        "name": "company-link1-flow"
+      }
+    },
+    {
+      "type": "Output",
+      "meta": {
+        "name": "demand2"
+      },
+      "max_flow": {
+        "type": "Literal",
+        "value": 5.0
+      },
+      "cost": {
+        "type": "Literal",
+        "value": -10.0
+      }
+    }
+  ],
+  "edges": [
+    {
+      "from_node": "import",
+      "to_node": "demand2"
+    }
+  ]
+}

examples/my-model/pywr-project.json

@@ -2,6 +2,10 @@
   "format": "v1",
   "base_model": "models/base.json",
   "sub_networks": [
+    {
+      "name": "neighbour",
+      "base_network": "base.json"
+    },
     {
       "name": "catchment",
       "network_sets": [
@@ -69,6 +73,11 @@
         }
       ]
     },
+    {
+      "name": "neighbour",
+      "description": "A neighbouring supply system.",
+      "base": "neighbour"
+    },
     {
       "name": "option12",
       "description": "Both supply options.",
@@ -112,5 +121,38 @@
         "option12"
       ]
     }
+  ],
+  "multi_models": [
+    {
+      "name": "joint-historical",
+      "domain": {
+        "model": "baseline-historical"
+      },
+      "networks": [
+        {
+          "name": "company",
+          "network": {
+            "model": "baseline-historical"
+          }
+        },
+        {
+          "name": "neighbour",
+          "network": {
+            "network": "neighbour"
+          },
+          "transfers": [
+            {
+              "from_network": "company",
+              "metric": {
+                "type": "Node",
+                "name": "link1"
+              },
+              "name": "company-link1-flow",
+              "initial_value": 0.0
+            }
+          ]
+        }
+      ]
+    }
   ]
 }