Skip to content
| Marketplace
Sign in
Visual Studio Code>Data Science>Pywr for VS CodeNew to Visual Studio Code? Get it now.
Pywr for VS Code

Pywr for VS Code

Stefano Simoncelli

|
17 installs
| (1) | Free Trial
Build, explore and run Pywr water resource models without leaving your editor. Compatible with the pywr-1 and pywr-2 packages
Installation
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.
Copied to clipboard
More Info

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.

Pywr for VS Code

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.

Validation

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.

Model overview

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.

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.

Edit form

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.

Add a component

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.

Schematic

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.

Run a model

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.

Results chart

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

  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.

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:

  1. Click the Pywr licence item in the status bar (or run Pywr: Manage licence) and choose Buy a licence.
  2. Choose the number of users and pay by card with Stripe.
  3. Copy the licence key from the thank-you page.
  4. 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.

  • Contact us
  • Jobs
  • Privacy
  • Manage cookies
  • Terms of use
  • Trademarks
  • Your Privacy Choices
  • Consumer Health Privacy
© 2026 Microsoft