watertap.ui package

Submodules

watertap.ui.api module

This module defines the API for the WaterTAP user interface.

Provides these abilitites:

• Specify which blocks/variables to export the UI

• Save/load/update the state of all exported blocks and variables

• Specify functions to implement standard flowsheet “actions”

• An interface for running these actions that understands simple dependencies (running A requires B must have been run first).

• Add user-specified action names and functions in addition to standard ones

• Load a mapping of names to flowsheet modules from a configuration file

Exchange format for flowsheet data:

{
    "blocks": {
        "Flowsheet": {
            "category": "default" OR "<category-name>",
            "display_name": "<name>",
            "description": "<descriptive text>",
            "variables": {
                "<name>": {
                    "value": <number or string>
                      OR
                    "value": {"index": [[<index list1>], [<index list2>], ..],
                              "value": [<value1>, <value2>, ..]}
                    "display_name": "<name>"
                    "description": "<descriptive text>",
                    "units": "<units for value>",
                    "readonly": <True or False>
                },
                ...
            },
            "blocks": {
               << Same structure as Flowsheet block for each sub-block, which may
                  of course have its own sub-blocks, etc. >>
            },
            "meta": {
                << block-level metadata (see ``meta`` below) >>
            }
        }
    }
    "meta": {
        "parameters": {
           "<name>": {
             "choices": [<value1>, <value2>, ..],
              "range": (<min>, <max>),
              "type": "str" OR "int" OR "float",
              "val": <value>
            },
            ...
         }
        << other user-defined metadata >>
    }
}

class watertap.ui.api.BlockInterface(block: Optional[Block], info: Optional[Dict] = None)

Bases: object

User interface for a Pyomo/IDAES block.

add_parameter(name: str, choices=None, vrange=None, vtype: Optional[Union[type, str]] = None)

Add a constrained parameter type. Initial value of parameter will be None.

Parameters

• name – Parameter name

• choices – List of possible values

• vrange – Range for numeric values (min <= x <= max)

• vtype – Expected type for value. Can be inferred from choices/vrange, but must be present if neither of those options are given. One of ‘str’, ‘int’, ‘float’, either as string or builtin type.

Raises

ValueError – conflicting or incorrect arguments

property block

Get block that is being interfaced to.

dict() → Dict

Return current state serialized as a dictionary.

Returns

Dictionary with all the UI-exported blocks and variables.

get_parameter(name: str) → Union[float, int, str]

Get the value of a flowsheet parameter.

Parameters

name – Name of parameter to get

Returns

Value for parameter. Will be None if not set.

Raises

KeyError – unknown parameter

classmethod get_schema() → Dict

Get a schema that can validate the exported JSON representation from dict() or, equivalently, save().

Returns

The schema

get_var_extra() → Dict[str, List[str]]

After a load(), these are the variables that were in some BlockInterface object, but not found in the input data for the corresponding block.

e.g.: {'Flowsheet': ['new1'], 'Flowsheet.Component': ['new2']}

Returns

Dict that maps a block name to a list of variable names

Raises

KeyError – if load() has not been called.

get_var_missing() → Dict[str, List[str]]

After a load(), these are the variables that were present in the input, but not found in the BlockInterface object for the corresponding block.

e.g., {'Flowsheet': ['foo', 'bar'], 'Flowsheet.Component': ['baz']}

Returns

Dict that maps a block name to a list of variable names

Raises

KeyError – if load() has not been called.

load(file_or_stream: Union[str, Path, TextIO])

Load from file or stream into this FlowsheetInterface.

Parameters

file_or_stream – File to load from

Raises

ValueError – Improper input data

classmethod load_from(file_or_stream: Union[str, Path, TextIO], fs: Optional[Union[Block, FlowsheetInterface]]) → FlowsheetInterface

Load from saved state in a file to modify a FlowsheetInterface.

Parameters

• file_or_stream – File to load from

• fs – Flowsheet which will be updated with values and units from saved data

Returns

Updated flowsheet interface

Raises

ValueError – Improper input data

property meta: Dict

Block metadata.

save(file_or_stream: Union[str, Path, TextIO])

Save the current state of this instance to a file.

Parameters

file_or_stream – File specified as filename, Path object, or stream object

Returns

None

Raises

• IOError – Could not open or use the output file

• TypeError – Unable to serialize as JSON

set_parameter(name: str, val: Union[float, int, str])

Set the value for a flowsheet parameter.

Parameters

• name – Name of parameter to set

• val – Value for parameter

Raises

• KeyError – unknown parameter

• TypeError – wrong type for this parameter

• ValueError – invalid value for this parameter

update(data: Dict)

Update values in blocks in and under this interface, from data.

Any variables in the file that were not found in the hierarchy of block interfaces under this object, or any variables in that hierarchy that were not present in the input file, are recorded and can be retrieved after this function returnns with get_var_missing() and get_var_extra().

Args:

data: Data in the expected schema (see get_schema())

Raises

ValueError – Problem with structure in the data

class watertap.ui.api.FlowsheetInterface(info)

Bases: BlockInterface

Interface to the UI for a flowsheet.

add_action_type(action_type: str, deps: Optional[List[str]] = None)

Add a new action type to this interface.

Parameters

• action_type – Name of the action

• deps – List of (names of) actions on which this action depends. These actions are automatically run before this one is run.

Returns

None

Raises

• KeyError – An action listed in ‘deps’ is not a standard action defined in WorkflowActions, or a user action.

• ValueError – A circular dependency was created

get_action(name)

Get the action that was set with set_action().

run_action(name)

Run the named action’s function.

set_action(name, func, **kwargs)

Set a function to call for a named action on the flowsheet.

update(data: Dict)

Update values in blocks in and under this interface, from data.

Any variables in the file that were not found in the hierarchy of block interfaces under this object, or any variables in that hierarchy that were not present in the input file, are recorded and can be retrieved after this function returnns with get_var_missing() and get_var_extra().

Args:

data: Data in the expected schema (see get_schema())

Raises

ValueError – Problem with structure in the data

watertap.ui.api.export_variables(block, variables=None, name='', desc='', category='') → BlockInterface

Export variables from the given block, optionally providing metadata for the block itself. This method is really a simplified way to create BlockInterface instances for models (a.k.a., blocks).

Parameters

• block – IDAES model block

• variables –

  List of variable names, or dict, of variable data to export. If it is a dict, the following fields may be present:

  valuescalar

  <number or string>

  valueindexed

  {“index”: [[<index list1>], [<index list2>], ..],

  ”value”: [<value1>, <value2>, ..]}

  display_name

  Name to display for the variable (default name in the model)

  description

  Description of the variable (default is .doc of the variable, or nothing)

  units

  Units for the variable, in a standard string generated by Pyomo units.

  readonly

  If False (the default), the variable can be modified in the UI. If True, it should not be. Note that this is not known to the model, i.e., setting this to True does not change the variable to an (IDAES) parameter.

• name – Name to give this block (default=``block.name``)

• desc – Description of the block (default=``block.doc``)

• category – User-defined category for this block, such as “costing”, that can be used by the UI to group things visually. (default=”default”)

Returns

An initialized BlockInterface object.

Raises

ValueError – bad form for an input value

watertap.ui.api.find_flowsheet_interfaces(config: Union[str, Path, Dict] = {'packages': ['watertap']})

Find flowsheets in Python packages/modules.

watertap.ui.api.get_block_interface(block: Block) → Optional[BlockInterface]

Retrieve attached block interface, if any. Use with set_block_interface().

Parameters

block – The block to access.

Returns

The interface, or None.

watertap.ui.api.set_block_interface(block, data: Union[BlockInterface, Dict])

Set the interface information to a block.

Parameters

• block – Block to wrap

• data – The interface info to set, either as a BlockInterface object or as the config dict needed to create one.

Returns

None

watertap.ui.api_model module

Model for the data that is created and consumed by the user interface API.

watertap.ui.api_util module

Utility functions for the api module.

watertap.ui.api_util.flatten_tree(tree: Dict, tuple_keys: bool = False, copy_value: bool = True, sort: bool = True) → List[Tuple[Union[List[str], str], Dict]]

Flatten a tree of blocks.

Parameters

• tree – The tree of blocks. See watertap.ui.api for details on the format. Should start like: { "blocks": { "Flowsheet": { ... } } }

• tuple_keys – Controls whether the flattened keys should be a tuple of strings or a single dotted string.

• copy_value – If True, make a copy of the value and remove the “blocks” from it. Otherwise, the values are references to the input.

• sort – If True, sort the result by keys before returning it.

Returns

List of tuples of (key, value), where key is the full path to the block and the value is the value of the block.

watertap.ui.api_util.open_file_or_stream(fos, attr='tell', **kwargs) → IO

Open a file or use the existing stream. Avoids adding this logic to every

function that wants to provide multiple ways of specifying a file.

Parameters

• fos – File or stream

• attr – Attribute to check on the fos object to see if it is a stream

• kwargs – Additional keywords passed to the open call. Ignored if the input is a stream.

Returns

Opened stream object

Module contents