feat(project): Add external project dependencies to project manifests.

examples/my-model/README.md

@@ -1,7 +1,8 @@
 # Example multi-file project
 
 This example builds several variants of one small model from a shared base model and
-interchangeable network fragments, using a `pywr-project.json` manifest.
+interchangeable network fragments, using a `pywr-project.json` manifest. It also depends on a
+second project, `../neighbour`, which holds a neighbouring supply system.
 
 ## Layout
 
@@ -14,11 +15,16 @@ 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
+
+neighbour/                 # a separate project that my-model depends on
+├── pywr-project.json
+├── supply/                # network set: the neighbour's network
+│   └── base.json
+└── data/
+    └── demand.csv         # the neighbour's demand, read by `supply/base.json`
 ```
 
 The base model has a `Placeholder` node, `supply1`, for the catchment inflow. Each file in
@@ -28,18 +34,22 @@ for the base model node it connects to (`demand1` or `link1`) and adds a new sup
 
 ## Manifest
 
-The manifest has five parts:
+The manifest has six parts:
 
+- **`dependencies`** name other projects whose definitions this one may use, by a path to their
+  manifest. This project depends on `../neighbour/pywr-project.json` under the name
+  `neighbour`, so it refers to the network definition `neighbour` there as
+  `neighbour::neighbour`. A project's own `exports` list what others may use; the neighbour
+  project exports only that network definition.
 - **`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.
+  catchment must select exactly one inflow.
 - **`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. `neighbour`
-  is the `neighbour` sub-network's base network on its own. `option12` extends `option1` and
-  `option2` to combine them.
+  sub-network; a model cannot select from a sub-network's sets unless it is active. `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.
 
@@ -55,8 +65,12 @@ The manifest has five parts:
   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`.
+    - `neighbour`, the `neighbour::neighbour` network definition from the neighbour project. Its
+      `import` node's maximum flow is the transfer `company-link1-flow`, which carries the flow
+      through `link1` in `company`.
+
+  Files from the neighbour project read their data relative to that project, so
+  `data/demand.csv` in `supply/base.json` is read from `../neighbour/data/demand.csv`.
 
 ## Running
 

examples/my-model/pywr-project.json

@@ -1,11 +1,13 @@
 {
   "format": "v1",
   "base_model": "models/base.json",
-  "sub_networks": [
+  "dependencies": [
     {
       "name": "neighbour",
-      "base_network": "base.json"
-    },
+      "manifest": "../neighbour/pywr-project.json"
+    }
+  ],
+  "sub_networks": [
     {
       "name": "catchment",
       "network_sets": [
@@ -73,11 +75,6 @@
         }
       ]
     },
-    {
-      "name": "neighbour",
-      "description": "A neighbouring supply system.",
-      "base": "neighbour"
-    },
     {
       "name": "option12",
       "description": "Both supply options.",
@@ -138,7 +135,7 @@
         {
           "name": "neighbour",
           "network": {
-            "network": "neighbour"
+            "network": "neighbour::neighbour"
           },
           "transfers": [
             {