The schematic shows the nodes and the edges of your model as a diagram. What you change on it is written to the model file.

Open the schematic

Use any of these while a model is open:

• the schematic button at the top right of the editor
• the schematic button at the top of the Model view
• Ctrl Alt P, then S

Each node is a circle in the colour of its type, with its name below. A virtual node is a square with a dashed border and its name in italic. There is one schematic for each model, and it updates when the JSON file changes.

Find your way

Move around

• Drag the background to move, and scroll to zoom.
• Use the buttons on the left to zoom in, zoom out and fit the whole network in the view.
• The minimap at the bottom right shows where you are in a large network.
• Hover a node to read its JSON. Hover an edge to see the nodes and the slots it connects; turn this off with the pywr.schematic.showEdgeLabelOnHover setting.

The zoom and the position are remembered for each model. To forget them all, run Pywr: Clear Saved Schematic Zoom & Position.

Customise the view

The View button in the toolbar opens a panel with the options to change what the schematic shows:

• Virtual nodes shows or hides the virtual nodes, with the dashed lines to the nodes they refer to.
• Virtual node lines shows or hides only the dashed lines.
• Node names shows or hides the names below the nodes.
• Upstream and downstream of the selected node follows the edges from the node you select: the nodes and edges that can send it water turn green, the ones it feeds turn red, and the rest of the network is dimmed. Select one node to use it.
• Node size makes the nodes, with their icon and name, smaller or larger.

The two options for the virtual nodes are only listed when the model has virtual nodes.

The options are saved in the settings of the workspace (.vscode/settings.json) or, when no workspace is open, in your user settings. See the pywr.schematic.* settings.

Pywr v1 The virtual nodes are the AggregatedNode and AggregatedStorage nodes, and the nodes whose type is, or contains, VirtualStorage (for example AnnualVirtualStorage or a custom MyVirtualStorage node).

Pywr v1 models

Pywr v1 The schematic of a Pywr v1 model uses the position saved with each node, in its editor_position or its schematic key, and keeps the node icons and the edge colours saved in the model. When you move a node, its new position is saved in the editor_position key of the node.

Edit the network

Move a node

Drag a node to its new place. Its position is saved in the model file, so the layout is shared with everyone who opens the model.

Add a node

1. Press Add node in the toolbar at the bottom of the schematic. A panel opens with the types of node.

   

2. Drag a type onto the schematic and drop it where the node should be.

3. Type the name of the node and press Enter.

The node is added to the model with the default values of its type, and its form opens so you can set them. To stop the form opening, turn off the pywr.openFormOnAdd setting.

Connect two nodes

1. Press Add edge in the toolbar. The schematic enters connecting mode and shows the slots of each node: water leaves from a green slot and arrives at a red slot.

   

2. Drag from a green slot of the first node to a red slot of the second node.

3. Add as many edges as you need, then press Exit connecting mode or Esc.

Edit, rename and delete

• Double-click a node to open its form.
• Right-click a node or an edge for Edit, Rename, Find usages, Go to JSON and Delete. Rename and Find usages are for nodes only. See Add, rename and delete for the other places to rename or delete a component.
• Select one or more items, then press Delete item in the toolbar, Delete or Backspace. You are asked to confirm, and told when a node is still used by other components.

Draw shapes

To annotate the schematic, press Add shape in the toolbar and pick Rectangle, Arrow or Text. The shape is added in the middle of the view.

• Drag a shape to move it. Drag the corners of a selected rectangle to resize it, or the two ends of a selected arrow to change where it starts and points.
• Double-click a rectangle or a text shape to edit its text. Enter saves it and Shift+Enter starts a new line.
• Select a shape to change its colours from the toolbar above it: the border (the line of an arrow), the fill of a rectangle and the text. No fill makes a rectangle transparent again.
• Press the bin in the same toolbar, Delete or Backspace to delete a selected shape.

Shapes are drawn under the nodes and edges. They are saved in a top-level shapes list in the model file, which pywr ignores when it runs the model:

"shapes": [
  { "type": "rectangle", "x": 0, "y": 0, "width": 300, "height": 200,
    "border_color": "#2563eb", "text": "Upper catchment" },
  { "type": "arrow", "x": 320, "y": 100, "x2": 420, "y2": 100 },
  { "type": "text", "x": 0, "y": 220, "text": "Draft network", "text_color": "#dc2626" }
]

Shapes are hidden when the schematic draws the network on a map.

Draw the network on a map

When the nodes of a model have geographic coordinates, the schematic is drawn on a map.

To start a new model on a map:

1. Open the schematic of a model with no nodes. You are asked how to draw it.

2. Pick Map.

3. Type the latitude and the longitude of the area of your model, such as 51.48, -3.18, or leave the field empty to start from a map of the world.

4. Add your nodes. They are saved with their latitude and longitude.

Note

The map is drawn with tiles from OpenStreetMap, so it needs an internet connection. The rest of the extension works offline.

Show the results on the network

After a run, the schematic can show the results on the nodes and the edges.

1. Run the model.

2. Open the schematic and press Results in the toolbar. The results of the last run are loaded; when there is none, you are asked for a results file.

   

3. Read the network:

   • Each node shows its value and the attribute it is for.
   • A storage node shows how full it is, with a bar.
   • Pywr v2 Edges get wider as their flow grows, and are dashed when the flow is zero.
   • Pywr v2 When a node saves more than one attribute, pick the one to show from the list on the node.
   • Hover a node to see a small chart of its values, with a marker at the time step shown. Click the chart to open it in the results viewer.

   

4. Use the bar at the top to move through the run:

   • pick the scenario
   • drag the slider to a time step, or press Play to move through them
   • Pywr v2 click a red tick above the slider to jump to a time step where an output node has a deficit (see below)
   • click the file name to show the results of another file
   • press Hide the results to go back to the plain schematic

Pywr v2 The red ticks need the deficit of the output nodes in the results file. Pywr v2 saves only the Inflow of an output node by default: add its Deficit attribute to a metric set of the output, for example

{ "type": "Node", "name": "demand1", "attribute": "Deficit" }

A time step is marked when a deficit is larger than 0.001, in the flow units of the model. Pywr v1 results files do not have the deficit, so their slider has no ticks: use a live run instead. With many time steps, the ticks close to each other are drawn as one, which jumps to the first of them.

When something goes wrong

See The schematic shows no results and The map of the schematic is blank in Troubleshooting.