Pywr for VS Code

Build, explore and run Pywr water resource models without leaving your editor. Pywr models are large JSON files, and this extension turns them into something you can navigate, edit with forms, draw on a schematic, run with one click and chart the results of.

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.

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 v1 has no official schema, so the extension uses one built from the forms of pywr-editor. It also checks the rules pywr v1 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 Network tree, select it in the tree and the schematic moves to it. With the pywr.tree.followCursor setting, the trees also follow the cursor of the JSON editor.

The External data view 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.
• 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 timestepper 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.

Edit with forms

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.

The schematic also supports geographical node coordinates and all nodes are displayed on a map.

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.

Search everything

Use the Search view to find any node, edge, parameter, output, metric set, timeseries or table by name or by type, and jump straight to it. Type type:reservoir to only search the types. Click a result to open its form or, when the schematic has the focus, to show the node or the edge on the schematic.

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.

Chart your results

Open a results file to chart it without leaving VS Code. The viewer reads the HDF5 and CSV outputs of Pywr v2, and the files written by the TablesRecorder 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. No Python environment is needed.

• 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.
• 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.
• 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.

Requirements

• VS Code 1.110 or later.
• Models written for Pywr v2 or Pywr v1. The extension recognises a JSON file as a Pywr v2 model when it has the metadata, timestepper 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 inside VS Code and uses this environment for Python parameters and pandas timeseries.
• To run Pywr v1 models, a Python environment with pywr 1 installed (pip install pywr).

The Python extension is installed automatically with this extension.

Getting started

1. Open a folder that contains your Pywr model.
2. 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).
3. Open the schematic with the icon in the editor toolbar, or click a component in the sidebar to edit it.
4. 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.

Keyboard shortcuts

These shortcuts work when a Pywr model is open. Press the first keys, release them, then press the letter.

Settings

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.

The run uses the wrong environment. Once a Pywr v2 model has run, Pywr keeps using the same Python environment until VS Code is restarted. After you change environment, run Developer: Reload Window. Pywr v1 models always use the selected environment.

Feedback

Found a bug or have an idea? Open a ticket or start a new discussion.

Licence

Pywr for VS Code is proprietary software. All rights reserved. You may install and use the extension, but you may not copy, modify, redistribute or sell it, in whole or in part, without written permission. See LICENSE.md for the full terms.