IDAES Flowsheet Visualizer

Introduction

The IDAES Flowsheet Visualizer, or IFV for short, is a web-based user interface (UI) that lets you:

  • View any IDAES flowsheet as a process engineering diagram

  • Export flowsheet diagrams as images (SVG format)

  • View and export the “stream table” for the flowsheet

  • Rearrange the flowsheet diagram to your taste and save the arrangement for next time

  • Dynamically refresh the displayed values to reflect changes in the underlying IDAES model

To use the IFV, first install IDAES. The IFV can be invoked from a Jupyter Notebook or a Python script. It does not require that you run any other application. Currently the IFV is only for viewing the flowsheet on your own computer. 1

Starting and stopping the IFV is fast and does not consume many resources.

1 But, since it is a web application, a shared service for viewing flowsheets stored remotely is definitely possible.

Guide

This guide describes how to invoke (i.e., start) and use the IFV.

Invocation

The IFV visualizes flowsheets. To get started with creating a flowsheet with IDAES, see the Flowsheet models documentation page. Once you have created your flowsheet, simply call the visualize method on that object, passing some parameters to give it a name and optional file for saving changes:

# First, create your IDAES model, "m", which has an attribute ".fs" for the flowsheet
# Then, invoke the `visualize` method
m.fs.visualize("My Flowsheet")

The invocation of the visualize method will pop up a browser tab or window with the UI, displaying the flowsheet and, if the information is available, the stream table.

Note

In contrast to notebooks, invoking the visualize method as above in a script will have the background process terminate when the script finishes processing. In order to keep the process running, the loop_forever option must be set to True:

m.fs.visualize("My Flowsheet", loop_forever=True)

You can continue to run more code and the UI will continue to work in the background. You can close the UI at any time. If you exit the notebook while the UI is running, you can still manipulate the diagram and stream table, but you will not be able to save or refresh, since these require communication with the Python process that no longer exists.

There are three ways to invoke the visualize functionality, which in the end do the same thing and have the same arguments.

  1. Use the visualize method of a flowsheet (as above)

  2. Call the visualize function from the package idaes.core.ui.fsvis, passing it a flowsheet object

  3. Call the same visualize function from the module idaes.core.ui.fsvis.fsvis, passing it a flowsheet object

In all cases, the arguments and behavior are the same. See the visualize function documentation for details on parameters to this function.

Note

You can continue to modify and use your model and flowsheet after calling visualize(). This may update the visualization, but nothing you do in the IFV will affect the Python model; it is read-only.

User Interface

This section describes how to use the graphical web user interface. We start with a screenshot of the UI, with the main areas highlighted. Then we zoom in on each area and describe how to use it.

In the screenshot of the IFV UI below, you can click on one of the indicated areas to jump to the associated description.

Top bar Diagram Controls Diagram/Flowsheet Stream Table

Top bar

../../_images/ifv_screenshot_topbar.png

Screenshot of the top bar of the IFV UI

The top bar has a title bar, which contains the IDAES logo and the name of the flowsheet being visualized, and a menu. The menu items are:

  • Refresh: Update the view with any changes made to the flowsheet from the Python side. This also has the effect of saving the current layout.

  • Save: Save the current layout to the data store that was specified with the visualization was launched. Note that this does not update with any changes made to the flowsheet in Python (use Refresh for that). Neither does it have any effect on the Python flowsheet values, as the IFV cannot modify the underlying flowsheet.

  • Export: Save the flowsheet or stream table as a file.

    • Flowsheet: Save the flowsheet as a Scalable Vector Graphics (SVG) file, a common format for images that consist of “vector” elements like boxes, lines, and text. SVG files can be viewed like images by most programs that allow image viewing, and even edited with a program like Inkscape. You will get a preview of the image and a “Download” button that will save in a file named for the flowsheet, with a “.svg” extension.

    • Stream table: Save the flowsheet as comma-separated values. The result will be a text file, called “export.csv”, that contains the data.

  • View: Toggle the visibility of the flowsheet (diagram) area and the stream table area.

  • Help: Load this documentation page.

Back to main window screenshot

Diagram

../../_images/ifv_screenshot_diagram.png

Screenshot of the main diagram (or flowsheet) area of the IFV UI

The diagram (or flowsheet) area lets you rearrange the flowsheet as you need and zoom in on particular sections. You can interact with the components on the diagram:

Shapes

Geometric shapes on the flowsheet represent unit models, inlets and outlets, and other IDAES components. They are connected by lines, and each has a name. All shapes can be moved by clicking and dragging them. If you right-click on a shape, it will rotate 90 degrees.

Lines

The lines connecting units can be manipulated by clicking and dragging. You can click on a line to create a new segment that can be used for routing the line around objects. You can eliminate a segment by clicking on the dot that appears as you hover over the line. There are also pill-shaped handles that appear on the lines for moving them. The endpoints of the lines are determined by the flowsheet and cannot be changed. For the same reason, you also cannot add or remove lines.

Labels

Both the shapes and lines have associated values that can be shown, which pop up over the lines if you toggle the “Show labels” control. See the Diagram Controls section for details.

More details on mouse and keyboard actions for the diagram are available in the documentation of the underlying Rappid toolkit.

Back to main window screenshot

Diagram Controls

../../_images/ifv_screenshot_diagramcontrols.png

Screenshot of the diagram controls area of the IFV UI

The diagram controls allow you to affect some global properties of the diagram/flowsheet area.

View actions
  • Labels: Toggle visibility of the information (labels) shown for each stream. This is the same information that appears in the Stream Table.

  • Grid: Toggle a background “grid”

  • zoomin: Zoom in by 25%

  • zoomout: Zoom out by 25%

  • zoomfit: Fit the diagram into the current area

Back to main window screenshot

Stream Table

The IFV will show a stream table with variables and their units defined for each stream in the flowsheet, if these values exist and the flowsheet adheres to the IDAES conventions for naming the inlet and outlet streams. In case the variables are unit-less, their units would be replaced with ‘–’. An example of a stream table is shown below.

../../_images/ifv_screenshot_streamtable.png

Screenshot of an example stream table

There are a number of ways of manipulating this table:

  • The “Hide Fields” pull-down menu provides a list of stream names. Select a name to hide/show that column in the table.

  • Click on the column header and drag it left or right to change its order in the table.

  • Resize a column by hovering over a column border until you see the mouse pointer change, then drag it to resize.

You can also export the entire table as a file of comma-separated values. See the Export documentation for details.

Back to main window screenshot

Reference

idaes.core.ui.fsvis.visualize(flowsheet, name='flowsheet', save=None, load_from_saved=True, save_dir=None, save_time_interval=5000, overwrite=False, browser=True, port=None, log_level=30, quiet=False, loop_forever=False)[source]

Visualize the flowsheet in a web application.

The web application is started in a separate thread and this function returns immediately.

Also open a browser window to display the visualization app. The URL is printed unless quiet is True.

Parameters
  • flowsheet – IDAES flowsheet to visualize

  • name (str) – Name of flowsheet to display as the title of the visualization

  • load_from_saved (bool) – If True load from saved file if any. Otherwise create a new file or overwrite it (depending on ‘overwrite’ flag).

  • save (Optional[Union[pathlib.Path, str, bool]]) – Where to save the current flowsheet layout and values. If this argument is not specified, “name.json” will be used (if this file already exists, a “-<version>” number will be added between the name and the extension). If the value given is the boolean ‘False’, then nothing will be saved. The boolean ‘True’ value is treated the same as unspecified.

  • save_dir (Optional[pathlib.Path]) – If this argument is given, and save is not given or a relative path, then it will be used as the directory to save the default or given file. The current working directory is the default. If save is given and an absolute path, this argument is ignored.

  • save_time_interval – The time interval that the UI application checks if any changes has occurred in the graph for it to save the model. Default is 5 seconds

  • overwrite (bool) – If True, and the file given by save exists, overwrite instead of creating a new numbered file.

  • browser (bool) – If true, open a browser

  • port (Optional[int]) – Start listening on this port. If not given, find an open port.

  • log_level (int) – An IDAES logging level, which is a superset of the built-in logging module levels. See the idaes.logger module for details

  • quiet (bool) – If True, suppress printing any messages to standard output (console)

  • loop_forever (bool) – If True, don’t return but instead loop until a Control-C is received. Useful when invoking this function at the end of a script.

Returns

See VisualizeResult

Raises
  • idaes.core.ui.fsvis.errors.VisualizerSaveError – if the data storage at ‘save_as’ can’t be opened

  • idaes.core.ui.fsvis.errors.VisualizerError – Any other errors

  • RuntimeError – If too many versions of the save file already exist. See MAX_SAVED_VERSIONS.

Return type

idaes.core.ui.fsvis.fsvis.VisualizeResult

idaes.core.ui.fsvis.VisualizeResult = <class 'idaes.core.ui.fsvis.fsvis.VisualizeResult'>

VisualizeResult(store, port, server)

Software notes

This section provides some additional details for developers or users more interested in the programming details.

Client/server architecture

The visualize() command works by starting an HTTP server in a separate thread, and serving requests from the UI (or any other requester). The server only responds to requests from your computer, not the internet. When you exit the script or Jupyter Notebook that called visualize then you will also stop the server – and the associated IFV page will no longer be able to save or refresh the flowsheet. The architecture diagram is shown below.

+-------------------+                        +--------------------+
|                   |                        |    Web browser     |
|  'Python script'  |                        +--------------------+
|  'or Jupyter'     |    +---------------+   | IFV web interface  |
|  'Notebook'       |    | 'HTTP server' |   +--------------------+
|                   |    | 'running in'  |   |    +--+            |
|                   |    | 'a separate'  |   |    +--+            |
|                   |    | 'thread'      |   |      |      +--+   |
|                   |    |               <--->      +----> +--+   |
|  m.fs.visualize   +---->  Load/Save    |   |                    |
|                   |    |               |   |                    |
+-------------------+    +-----^---------+   +--------------------+
                               |
                               |
                        +------v--------------+
                        |   Local Storage     |
                        +---------------------+

Persistence architecture

The saving of the model uses the the module idaes.core.ui.fsvis.persist. This module implements the well-known “factory pattern”, which makes it easy to extend by adding a new DataStore sub-class and updating the logic in the factory method, create(), to create and return instances of that class for a given input type. The input in this case comes from the save_as argument to the visualize() method.