watertap.ui package

Submodules

watertap.ui.fsapi module

Simple flowsheet interface API

class watertap.ui.fsapi.Actions(value)

Bases: str, Enum

Known actions that can be run. Actions that users should not run directly (unless they know what they are doing) are prefixed with an underscore.

watertap.ui.fsapi.FSI

Forward-reference to a FlowsheetInterface type, used in FlowsheetInterface.find()

alias of TypeVar(‘FSI’, bound=FlowsheetInterface)

class watertap.ui.fsapi.FlowsheetExport(*, obj: object = None, name: str = '', description: str = '', model_objects: Dict[str, ModelExport] = {}, version: int = 2, requires_idaes_solver: bool = False)

Bases: BaseModel

A flowsheet and its contained exported model objects.

add(*args, data: Optional[Union[dict, ModelExport]] = None, **kwargs) → object

Add a new variable (or other model object).

There are a few different ways of invoking this function. Users will typically use this form:

add(obj=<pyomo object>, name="My value name", ..etc..)

If these same name/value pairs are already in a dictionary, this form is more convenient:

add(data=my_dict_of_name_value_pairs)

If you have an existing ModelExport object, you can add it more directly with:

add(my_object)
# -- OR --
add(data=my_object)

Parameters

• *args – If present, should be a single non-named argument, which is a ModelExport object. Create by adding it.

• data – If present, create from this argument. If it’s a dict, create from its values just as from the kwargs. Otherwise it should be a ModelExport object, and create by adding it.

• kwargs – Name/value pairs to create a ModelExport object.

Raises

KeyError – If the name of the Pyomo object is the same as an existing one, i.e. refuse to overwrite.

class watertap.ui.fsapi.FlowsheetInterface(fs: Optional[FlowsheetExport] = None, do_build: Optional[Callable] = None, do_export: Optional[Callable] = None, do_solve: Optional[Callable] = None, **kwargs)

Bases: object

Interface between users, UI developers, and flowsheet models.

class MissingObject(key, name)

Bases: tuple

Type of item in list MissingObjectError.missing. key is the unique key assigned to the variable, name is the variable name in the flowsheet

property key

Alias for field number 0

property name

Alias for field number 1

exception MissingObjectError(missing)

Bases: Exception

Error returned if data in load refers to a variable not found in the target object.

Use the .missing attribute of the error object to get the list of MissingObjects.

__init__(missing)

UI_HOOK = 'export_to_ui'

Function to look for in modules. See find().

__init__(fs: Optional[FlowsheetExport] = None, do_build: Optional[Callable] = None, do_export: Optional[Callable] = None, do_solve: Optional[Callable] = None, **kwargs)

Constructor.

Parameters

• fs – An existing wrapper to a flowsheet object. If this is not provided, then one will be constructed by passing the keyword arguments to the built-in pydantic parse_obj() method of FlowsheetExport.

• do_build – Function to call to build the flowsheet. It should build the flowsheet model and return the FlowsheetBlock, which is typically the fs attribute of the model object. Required

• do_export – Function to call to export variables after the model is built. This will be called automatically by build(). Required

• do_solve – Function to solve the model. It should return the result that the solver itself returns. Required

• **kwargs – See fs arg. If the fs arg is provided, these are ignored.

add_action(action_name: str, action_func: Callable)

Add an action for the flowsheet.

Parameters

• action_name – Name of the action to take (see Actions)

• action_func – Function to call for the action

Returns

None

build(**kwargs)

Build flowsheet

Parameters

**kwargs – User-defined values

Returns

None

Raises

RuntimeError – If the build fails

dict() → Dict

Serialize.

Returns

Serialized contained FlowsheetExport object

export_values()

Copy current values in underlying Pyomo model into exported model.

Side-effects:

Attribute fs_exp is modified.

classmethod from_installed_packages(group_name: str = 'watertap.flowsheets') → Dict[str, FlowsheetInterface]

Get all flowsheet interfaces defined as entry points within the Python packages installed in the environment.

This uses the importlib.metadata.entry_points() function to fetch the list of flowsheets declared as part of a Python package distribution’s entry points under the group group_name.

To set up a flowsheet interface for discovery, locate your Python package distribution’s file (normally setup.py, pyproject.toml, or equivalent) and add an entry in the entry_points section.

For example, to add a flowsheet defined in watertap/examples/flowsheets/my_flowsheet.py so that it can be discovered with the name my_flowsheet wherever the watertap package is installed, the following should be added to WaterTAP’s setup.py:

setup(
    name="watertap",
    # other setup() sections
    entry_points={
        "watertap.flowsheets": [
             # other flowsheet entry points
             "my_flowsheet = watertap.examples.flowsheets.my_flowsheet",
        ]
    }
)

Parameters

group_name – The entry_points group from which the flowsheet interface modules will be populated.

Returns

Mapping with keys the module names and values FlowsheetInterface objects

classmethod from_module(module: Union[str, module]) → Optional[FlowsheetInterface]

Get a a flowsheet interface for module.

Parameters

module – The module

Returns

A flowsheet interface or None if it failed

get_action(name: str) → Optional[Callable]

Get the function for an add()-ed action.

Parameters

name – Name of the action (see Actions)

Returns

Function for this action

Raises

KeyError, if no such action is defined –

load(data: Dict)

Load values from the data into corresponding variables in this instance’s FlowsheetObject.

Parameters

data – The input flowsheet (probably deserialized from JSON)

run_action(name, **kwargs)

Run the named action.

solve(**kwargs)

Solve flowsheet.

Parameters

**kwargs – User-defined values

Returns

Return value of the underlying solve function

Raises

RuntimeError – if the solver did not terminate in an optimal solution

class watertap.ui.fsapi.ModelExport(*, obj: Optional[object] = None, name: str = '', value: float = 0.0, ui_units: object = None, display_units: str = '', rounding: float = 0, description: str = '', is_input: bool = True, is_output: bool = True, is_readonly: bool = None, input_category: Optional[str] = None, output_category: Optional[str] = None, obj_key: str = None)

Bases: BaseModel

A variable, expression, or parameter.

exception watertap.ui.fsapi.UnsupportedObjType(obj: Any, supported: Optional = None)

Bases: TypeError

__init__(obj: Any, supported: Optional = None)

Module contents