IDAES Flowsheet Visualizer¶
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.
This guide describes how to invoke (i.e., start) and use the IFV.
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.
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
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.
Use the visualize method of a flowsheet (as above)
Call the visualize function from the package idaes.core.ui.fsvis, passing it a flowsheet object
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.
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.
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.
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:
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:
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.
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.
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.
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”
: Zoom in by 25%
: Zoom out by 25%
: Fit the diagram into the current area
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.
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.
- 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
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[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[Path]) – If this argument is given, and
saveis 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
saveis 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
saveexists, 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
loggingmodule levels. See the
idaes.loggermodule 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.
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
- Return type
- idaes.core.ui.fsvis.VisualizeResult = <class 'idaes.core.ui.fsvis.fsvis.VisualizeResult'>¶
VisualizeResult(store, port, server)
This section provides some additional details for developers or users more interested in the programming details.
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 | +---------------------+
The saving of the model uses the the module
This module implements the well-known “factory pattern”, which makes it easy to extend by adding
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.