Pywr for VS Code
Build, explore and run Pywr water resource models
in VS Code. Pywr models are large JSON files. With this extension you can navigate
them, edit them with forms, draw them on a schematic, run them and chart the results.
The extension works with models for Pywr v2 and for Pywr v1.
It recognises which version a model is written for, and the status bar shows it.
Read the documentation for
step-by-step guides, from your first model to charting its results.

Features
Catch mistakes as you type
Your model is checked against the Pywr schema while you edit it. Typos in component
types, missing fields and wrong values are underlined straight away. You also get a
warning when two components share a name, or when a component refers to a node,
parameter or table that doesn't exist.
Pywr v2 models are also checked for mistakes the schema cannot catch. You get a warning
for a node with no edges, an edge using a slot its node does not have, a parameter,
table or timeseries that nothing uses, a metric set that no output saves, lists whose
lengths must match (such as the values and the control curves of a parameter) and a
scenario group whose labels or subset do not match its size.
Pywr v1 models are checked against the rules pywr applies when it loads a model, such as
edges connecting existing nodes and storage nodes having an initial volume. Component types from your own
Python files listed in includes are recognised as custom components.

See your whole model at a glance
The Pywr sidebar lists every node, edge, parameter, metric set, output, timeseries
and table in your model (nodes, edges, parameters, recorders, scenarios and tables for
Pywr v1 models). Click an item to open its form, or use the buttons next to it to
rename it, go to it in the JSON file or delete it. Right-click an item for all its
actions: find where it is used, see its dependencies, show it on the schematic or chart
its results. A summary above the file and each section shows how many components your
model has.
The views follow each other: select a node or an edge on the schematic and it is
selected in the Model tree, select it in the tree and the schematic moves to it.
With the pywr.tree.followCursor setting, the tree also follows the cursor of the JSON
editor.
The sidebar shows the model in the editor. To keep a model in the sidebar while you
work on another file, such as a Python script, make it the primary model of the
workspace: click the star at the top of the Model view, or right-click a JSON file
in the Explorer and choose Set as the Primary Pywr Model. Another model you open
still takes over the sidebar while it is in the editor.
The same tree collects every file your model depends on, such as CSV tables,
timeseries and Python modules. Open any of them in its default app with one click.

Work in the JSON file
The JSON editor knows the components of your model:
- Rename a component with
F2, on its name or anywhere it is used. Every reference
is updated.
- Go to a component from a place that uses it with
F12, and list where a component
is used with Shift+F12.
- Hover a name to see the type and the comment of the component and how many times
it is used, or hover the
type of a component to read what the type does.
- Complete the names of nodes, parameters, tables and the other components where
they can be used, and the component types on
type.
- See the type of a component from the colour of its name: nodes, parameters and the
other components each have their own colour, where they are defined and where they
are used. Turn the colours off with the
pywr.highlightComponentNames setting.
- Find a component in the Outline view or with Go to Symbol in Editor.
- Use the links above each component to open its form, show it on the schematic or
list where it is used. Turn them off for large models with the
pywr.codeLens.componentActions setting. The link above metadata and time
(timestepper in Pywr v1) opens the model settings.
- Fix mistakes with the light bulb. For a name that does not exist, pick the closest
name or create the component. Rename a duplicated component, remove an edge to a
missing node, or browse for a file that cannot be found.
Click a node, parameter, output, metric set, timeseries or table (or recorder and
scenario in Pywr v1 models) in the sidebar to open a form with all its fields. Pick
component names from lists, choose files with a file picker, and switch between
parameter types from a dropdown. When you save, the form is validated and your changes
are written back into the JSON file.
The forms also show you the data you are editing:
- Preview charts draw profiles (monthly, weekly, daily and sub-daily), control
curves, polynomials, interpolation points and reservoir bathymetry as you type.
- File previews show the columns and first rows of a CSV table or timeseries, with a
chart of its numeric columns.
- Column suggestions list the columns of the file, so you can click a column name
instead of typing it.

Add, rename and delete safely
- Add new components from the Command Palette or by dragging nodes onto the
schematic. You get a ready-made template for the type you pick.
- Rename a component and every place that uses it is updated too.
- Delete a component and, if other components still use it, you are shown where
before anything is removed.
- Find where a component is used from the sidebar, to see its impact before you
change it.
- See the dependencies of a component in the Dependencies view: what it uses and
what uses it, level by level. Right-click a component in the sidebar and pick
Show the dependencies, or use the button in its form.

Draw your network on a schematic
Open the schematic from the editor toolbar to see your network as a diagram. Drag nodes
around, connect them to add edges, and add new nodes from the toolbar. Every change is
saved to your model. If your nodes have coordinates, the schematic is drawn on top of a
map. A minimap helps you find your way in large networks, and the zoom and position are
remembered for each model.
When you open the schematic of a model without nodes, you choose between a schematic
and a map. For a map, you can type the latitude and longitude of the area of your model
to start from; the nodes you add are then saved with their coordinates.
For Pywr v1 models, the schematic uses the node positions saved by pywr-editor, or the
schematic position used by pywr, and keeps the node icons and edge colours set in
pywr-editor. When you move a node, its position is saved in the pywr-editor format, so
the model still opens in pywr-editor.
Press Results in the schematic toolbar to show the results of your model on the
network. Each node shows its value and each storage node how full it is. With Pywr v2
results, edges get wider as their flow grows. Pick a scenario, drag the slider to move
through time, or press play.
Press Run live to run the model from the schematic and watch it one time step at a
time, without a results file. Step through the run or play it: a node gets an orange
outline when its flow reaches its maximum flow, and an output node a red outline when
its demand is not met. A node whose maximum flow is zero is grey with the label
blocked.

Search everything
Press the search button of the Model view and type: the tree only keeps the nodes,
edges, parameters, outputs, metric sets, timeseries and tables whose name or type
matches. Type type:reservoir to only search the types. Click a match to open its
form and, when the schematic is open, to show the node or the edge on it.
Run your model
Press the Run button in the editor toolbar. You can follow the progress timestep by
timestep and stop the run at any time. When the run finishes, you can open the results
in the chart viewer, open the folder with the results, or see how long each part of the
model took. Each run saves its results in a new folder named after the date and time,
inside a results folder next to your model.
For Pywr v1 models, the extension runs pywr from the Python environment you selected,
so pywr 1 must be installed in it. Pywr v1 saves the results you choose with the CSV and
tables recorders in your model: when the run finishes, Open output folder opens the
folder of their files.
Pywr v1 only loads the custom nodes, parameters and recorders in the Python files listed
in includes. If yours are in compiled Cython modules (.so or .pyd files),
right-click a module in the Explorer and pick Pywr: Add to the Cython Modules, or run
Pywr: Manage Cython Modules to add and remove them. The modules are saved in the
pywr.v1.cythonModules setting of your workspace (.vscode/settings.json) and are
imported before each run, including the run of the QA report. Their classes are also
recognised as custom components when the model is checked; for this the extension
imports the modules with the selected Python environment.
To change how a model runs without editing it, use Pywr: Run the model with options…
(the gear button next to Run). You can pick the solver, run only some scenarios and
choose the folder where the outputs are saved. The options are remembered for each
model, and the model file is not changed. The model is saved before each run.
For Pywr v1 models, you can also set the solver and the scenario combinations in the
model itself from the Model settings form.

Chart your results
Open a results file to chart it in VS Code. The viewer reads the HDF5 and
CSV outputs of Pywr v2, and the files written by the TablesRecorder, TablesRecorder2
and CSVRecorder of Pywr v1. HDF5 files open in the viewer by default; for a CSV file, right-click it and
pick Pywr: Open results chart. You do not need a Python environment.
- Pick what to plot. Tick metrics and scenarios on the left, filter scenarios by
group, and show or hide lines from the legend. To chart one component, press its
Chart the results button in the sidebar or in its form. For a reservoir whose
cost is set by a control curve parameter, the control curves are drawn too, as
dash-dot lines, when the reservoir volume is saved as relative (the
ProportionalVolume of Pywr v2, or a volume between 0 and 1 in Pywr v1). In Pywr
v1, the curves are multiplied by a constant max_volume to draw them with the
absolute volume. A curve
that is a constant is drawn from the model; a curve that is a parameter is drawn when
it is saved in the file.
- Change the view. Switch between time series, duration curves and percentile bands
across scenarios. Aggregate the values by month or year, and show the statistics of
each line.
- Arrange the charts. Add charts and choose the chart of each metric, for example to
draw flows and volumes on their own axes, then rename and reorder the charts.
- Compare two runs. Load a second results file to draw its lines next to yours, or
plot the difference between the two.
- Zoom and export. Drag to zoom, see the values in a table, and export the chart as
PNG or the values as CSV.
For Pywr v1 results, scenarios are labelled with the ensemble names of your model when
the model is found next to the results file.

Check the behaviour of your model with a QA report
A QA report is a set of charts you define once for a model and draw again after every
change, to check that the model still behaves as you expect. For example, the first
chart shows the volume of a reservoir with the parameters of its control curves, and the
second one the flows downstream.
- Build the charts. Pick Pywr: Open the QA report, add a chart and choose the
nodes, virtual nodes, parameters and edges to draw on it. You can also right-click a
component in the sidebar and pick Add to the QA report…. For a node, choose the
attribute to export or leave the default one. For a Pywr v1 model you can add nodes
and named parameters: a node shows its flow, or its volume if it is a storage node.
- Style the lines. Click a line in the legend of a chart to change its colour,
style (solid, dashed, dotted or dash-dot) and width. The lines you do not change get
the next colour of the chart.
- Run the report. Press Run to run the model and export only the components on
your charts. Your model file is not changed, and the results are saved in
results/qa, next to the model, and replaced at each run. The run uses the solver and
the scenarios of your last run with options. A Pywr v2 model does not write its own
outputs during this run. A Pywr v1 model still runs its recorders, but their files are
saved in results/qa so that your results are not replaced; the components are
exported with a TablesRecorder, which needs PyTables in your Python environment.
- Inspect and share. The charts are drawn as soon as the run finishes. Pick the
scenario to draw, zoom all the charts together, and press Export PDF to save the
charts as a document.
The report is saved in a file next to the model (model.qa.json for model.json), so
you can commit it and share it with the model.
Review pull requests on Azure DevOps
When your model is in a Git repository on Azure DevOps or Azure DevOps Server, connect
the folder once with Pywr: Connect to Azure DevOps and a personal access token. The
token is saved encrypted in the folder, with its key in the keychain of your computer.
- Run Pywr: Show pull requests to list the pull requests waiting for your review,
those you reviewed and those you created. Open their changes, check them out, vote,
link work items, or complete them with a merge strategy the branch policies allow.
- The status bar shows the pull request of the branch you have checked out, with its
approvals and open comments. Its comments are shown on their lines in the editor,
where you can reply, resolve them or start new ones.
- Run Pywr: Create a pull request to push your branch and create a pull request
from it, with the template of the repository.
With branch policies on Azure DevOps, every change to the model is recorded, can be
reverted, and reaches the main branch only after your line manager or another modeller
approves it. See Track and approve model changes,
Connect to Azure DevOps
and Review and create pull requests.
Requirements
- VS Code 1.110 or later.
- Models written for Pywr v2 (2.0.0-rc1 or later)
or Pywr v1. The extension recognises a JSON file as a
Pywr v2 model when it has the
metadata, time and network sections, and as a
Pywr v1 model when it has a timestepper section and a list of nodes.
- To run Pywr v2 models, a Python environment (such as a virtual environment or a
conda environment) with Python 3.10 or later. Pywr runs in a process started by
VS Code and uses this environment for Python parameters and the pandas, polars and Python timeseries
(which need
pyarrow).
- To run Pywr v1 models, a Python environment with pywr 1 installed
(
pip install pywr).
The Pywr: Set up the Python environment command installs the packages each version
needs. It uses the active environment, or creates a .venv in the workspace folder if
there is none, and then checks that every package can be imported.
The Python extension
is installed automatically with this extension.
Getting started
- Open a folder that contains your Pywr model.
- Open the model's JSON file. The Pywr icon appears in the activity bar and the
sidebar fills with your model's components. To start a model from scratch, run
Pywr: New model and pick the Pywr version and a template (an empty model, one
reservoir, or a river with an abstraction).
- Open the schematic with the icon in the editor toolbar, or click a component in the
sidebar to edit it.
- To run the model, select a Python environment with Python: Select Interpreter,
then press the Run button in the editor toolbar. When the run finishes, press
Open results to chart them.
The Get started with Pywr walkthrough (Help > Welcome) guides you through the
same steps.
To read the documentation of Pywr v1, Pywr v2 or this extension without leaving VS Code,
run Pywr: Open the documentation.
Keyboard shortcuts
These shortcuts work when a Pywr model is open. Press the first keys, release them, then
press the letter (with Shift where shown).
| Shortcut |
Command |
Ctrl+Alt+P S |
Open the schematic of the active model |
Ctrl+Alt+P R |
Run the model |
Ctrl+Alt+P Shift+R |
Run the model with options |
Ctrl+Alt+P A |
Add a component |
Settings
| Setting |
Description |
Default |
pywr.expandTreesOnOpen |
Expand the Model tree when you open a model. |
true |
pywr.schematic.openWithModel |
Open the schematic next to a model when you open its JSON file. A model without nodes is skipped. |
false |
pywr.schematic.showEdgeLabelOnHover |
Show the nodes and slots an edge connects when you hover over it. |
true |
pywr.schematic.showVirtualNodes |
Show the virtual nodes on the schematic. Also changed with the View button of the schematic toolbar. |
true |
pywr.schematic.showVirtualLinks |
Show the dashed lines between the virtual nodes and the nodes they refer to. Also changed with the View button. |
true |
pywr.schematic.showNodeNames |
Show the names of the nodes on the schematic. Also changed with the View button. |
true |
pywr.schematic.highlightRoutes |
When a node is selected, colour the nodes and edges that can send it water in green and the ones it feeds in red, and dim the others. Also changed with the View button. |
false |
pywr.schematic.nodeSize |
The scale of the nodes on the schematic, from 0.5 to 2. Also changed with the View button. |
1 |
pywr.runner.threads |
Number of threads to use when running a model. |
3 |
pywr.enableLogging |
Write logs to the Pywr output channel, useful to report a problem. |
false |
pywr.showChangelogOnUpdate |
Open the changelog in a new tab the first time the extension starts after an update. |
true |
pywr.normaliseModelOnOpen |
Offer to rewrite a Pywr v1 model when you open it, so that short type names (such as constant) become the pywr class names (ConstantParameter). |
true |
pywr.codeLens.componentActions |
Show the links to edit a component, show it on the schematic and list where it is used above each component in the JSON file. Turn this off for large models. |
true |
pywr.codeLens.referenceActions |
Show the links to edit, rename or remove a component and go to its definition above each name that refers to it in the JSON file. Turn this off for large models. |
true |
pywr.highlightComponentNames |
Colour the component names, and the places where they are used, in the JSON file with a colour for each component type (for example the nodes in green). Change the colours with the pywr.componentName.* colours of workbench.colorCustomizations. |
true |
pywr.tree.followCursor |
Select in the trees the component at the cursor of the JSON editor. |
false |
pywr.primaryModel |
The model shown in the sidebar when the file in the editor is not a Pywr model, relative to the workspace folder. Set it with the star of the Model view. |
Not set |
pywr.openFormOnAdd |
Open the form of a node, a parameter, a recorder, a timeseries or a table straight after you add it with a command, to edit its default values. |
true |
pywr.v1.cythonModules |
Compiled Cython modules (.so or .pyd files) to import before a Pywr v1 model is loaded and run. Relative paths are relative to the workspace folder. |
[] |
Troubleshooting
The run fails with "No active Python environment" or "is a global interpreter".
Pywr needs a Python environment, not a system-wide Python. Create one with
python -m venv .venv in your model's folder, then select it with
Python: Select Interpreter.
A Pywr v1 run fails with "pywr is not installed". Install pywr 1 in the selected
environment with pip install pywr, or select the environment where it is installed
with Python: Select Interpreter.
Licence
Pywr for VS Code is free for non-commercial use:
- learning and self-education;
- contributions to open-source projects that bring you no commercial benefit;
- content creation, such as tutorials, courses, videos and articles;
- hobby projects.
Any other use, for example modelling for your employer or for a client, needs a licence.
Businesses can try the extension for 30 days. During the trial, a yellow Pywr licence
inactive item in the status bar counts the days left. It turns red when the trial ends.
To buy a licence:
- Click the Pywr licence item in the status bar (or run Pywr: Manage licence)
and choose Buy a licence.
- Choose the number of users and pay by card with Stripe.
- Copy the licence key from the thank-you page.
- Click the status bar item again, choose Enter licence key and paste the key.
Each user of a licence enters the same key, and takes one of its seats. To move a seat
to another user, run Pywr: Show licence seat ID and email the ID to us. To pay by bank
transfer, choose Ask for an invoice or email
support@pywrtools.dev. We send you the key once the
invoice is paid.
If you use the extension only for non-commercial purposes, choose I use Pywr for
non-commercial purposes only, then accept the
licence agreement. The status bar item goes away, and the
extension asks you again in 12 months.
The full terms are in the licence agreement. Read more on
pywrtools.dev.
Support
Email support@pywrtools.dev to report a bug, ask a
question or suggest a feature. See the support policy.