idaes_flowsheet_processor.api

Simple flowsheet interface API

Module Contents

Classes

ModelExport	A variable, expression, or parameter.
KPI	Key Performance Indicator
ModelOption	An option for building/running the model.
FlowsheetExport	A flowsheet and its contained exported model objects.
Actions	Known actions that can be run.
FlowsheetCategory	Flowsheet Categories
FlowsheetReport	Abstract base class for flowsheet reports.
FlowsheetInterface	Interface between users, UI developers, and flowsheet models.
FlowsheetKPIReport	Report of the Key Performance Indicators (KPIs) for a flowsheet.
Layout	Translate a simple layout specification into an HTML flex layout.

Functions

ensure_supported(→ None)

Raise UnsupportedObjType if object type is not supported as an input/output

Attributes

FSI
WAFFLE
DONUT

idaes_flowsheet_processor.api.FSI

exception idaes_flowsheet_processor.api.UnsupportedObjType(obj: Any, supported=None)

Inappropriate argument type.

idaes_flowsheet_processor.api.ensure_supported(obj: object) → None

Raise UnsupportedObjType if object type is not supported as an input/output

class idaes_flowsheet_processor.api.ModelExport(/, **data: Any)

A variable, expression, or parameter.

obj: object | None

name: str = ''

value: float = 0.0

ui_units: object

display_units: str = ''

rounding: float = 0

description: str = ''

is_input: bool = True

is_output: bool = True

is_readonly: None | bool

input_category: str | None

output_category: str | None

chart_type: str | None

chart_group: str | None

obj_key: None | str

fixed: bool = True

lb: None | float = 0.0

ub: None | float = 0.0

num_samples: int = 2

has_bounds: bool = True

is_sweep: bool = False

model_config

classmethod validate_obj(v: object) → object

classmethod validate_value(v: float, info: pydantic.ValidationInfo) → float

classmethod validate_units(v: str, info: pydantic.ValidationInfo) → str

classmethod validate_name(v: str, info: pydantic.ValidationInfo) → str

classmethod set_readonly_default(v: bool | None, info: pydantic.ValidationInfo) → bool

classmethod set_obj_key_default(v: str | None, info: pydantic.ValidationInfo) → str

class idaes_flowsheet_processor.api.KPI(/, **data: Any)

Key Performance Indicator

is_table: bool

has_total: bool

name: str

title: str

units: List[str] = []

values: List[float] = []

labels: List[str] = []

xlab: str = ''

ylab: str = ''

total: float = 0.0

total_label: str = ''

class idaes_flowsheet_processor.api.ModelOption(/, **data: Any)

An option for building/running the model.

name: str

category: str = 'Build Options'

display_name: None | str

description: None | str

display_values: List[Any] = []

values_allowed: str | List[Any]

min_val: None | int | float

max_val: None | int | float

value: Any

classmethod validate_display_name(v: str | None, info: pydantic.ValidationInfo) → str

classmethod validate_description(v: str | None, info: pydantic.ValidationInfo) → str

classmethod validate_value(v: Any, info: pydantic.ValidationInfo) → Any

class idaes_flowsheet_processor.api.FlowsheetExport(/, **data: Any)

A flowsheet and its contained exported model objects.

property dof: int

m: object

obj: object

name: None | str

description: None | str

exports: Dict[str, ModelExport]

kpis: Dict[str, KPI]

kpi_order: list[str] = []

kpi_options: Dict

kpi_figures: Dict

version: int = 2

requires_idaes_solver: bool = False

sweep_results: None | dict

build_options: Dict[str, ModelOption]

classmethod validate_name(v: str, info: pydantic.ValidationInfo) → str

classmethod validate_description(v: str, info: pydantic.ValidationInfo) → str

add(*args: object, data: dict | ModelExport = None, **kwargs: object) → 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..)

where the keywords after obj match the non-computed names in ModelExport.

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. Accepted names and default values are in the ModelExport.

Raises:

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

clear_kpis() → None

add_kpi_values(name: str, values: List[float], labels: List[str], units: List[str] | None, title: str = '') → None

Add a Key Performance Indicator (KPI) for a table of names and values.

Parameters:

• name – Name of the KPI

• values – Numeric values

• labels – Labels corresponding to values

• title – Overall description

• units – Descriptive units for the values (optional)

add_kpi_barchart(name: str, values: List[float], labels: List[str], title: str, xlab: str | None = None, ylab: str | None = None, units: SyntaxWarning = 'none') → None

Add a KeyPerformance Indicator (KPI) vector for a barchart.

Parameters:

• name – Name of the KPI

• values – Numeric values

• labels – Labels corresponding to values

• title – Chart title

• xlab – Label for x axis

• ylab – Label for y axis

• units – Units for the values, e.g., “%” if they are percentages adding to 100

add_kpi_total(name: str, values: List[float], labels: List[str], title: str, total_label: str, units: str = '%') → None

Add a Key Performance Indicator (KPI) vector with multiple values and a total

Parameters:

• name – Name of the KPI

• values – Numeric values

• labels – Labels corresponding to values

• total_label – Label for the ‘total’ to which the values sum.

• units – Units for the values, e.g., “%” if they are percentages adding to 100

set_kpi_default_options(**options: object) → None

from_csv(file: str | pathlib.Path, flowsheet: object) → int

Load multiple exports from the given CSV file.

CSV file format rules:

• Always use a header row. The names are case-insensitive, order is not important. The ‘name’, ‘obj’, and ‘ui_units’ columns are required.

• Columns names should match the non-computed names in ModelExport. See .add() for a list.

• The object to export should be in a column named ‘obj’, prefixed with ‘fs.’

• For units, use Pyomo units module as ‘units’, e.g., ‘mg/L’ is units.mg / units.L

For example:

name,obj,description,ui_units,display_units,rounding,is_input,input_category,is_output,output_category
Leach liquid feed rate,fs.leach_liquid_feed.flow_vol[0],Leach liquid feed volumetric flow rate,units.L/units.hour,L/h,2,TRUE,Liquid feed,FALSE,
Leach liquid feed H,"fs.leach_liquid_feed.conc_mass_comp[0,'H']",Leach liquid feed hydrogen mass composition,units.mg/units.L,mg/L,3,TRUE,Liquid feed,FALSE,
.......etc.......

Parameters:

• file – Filename or path. If not an absolute path, start from the directory of the caller’s file.

• flowsheet – Flowsheet used to evaluate the exported objects.

Returns:

Number of exports added

Return type:

int

Raises:

• IOError – if input file doesn’t exist

• ValueError – Invalid data in input file (error message will have details)

to_csv(output: io.TextIOBase | pathlib.Path | str = None) → int

Write wrapped objects as CSV.

Parameters:

output – Where to write CSV file. Can be a stream, path, or filename.

Returns:

Number of objects written into file.

Raises:

IOError – If path is given, and not writable

add_option(name: str, **kwargs: object) → ModelOption

Add an ‘option’ to the flowsheet that can be displayed and manipulated from the UI.

Constructs a ModelOption instance with provided args and adds it to the dict of options, keyed by its name.

Parameters:

• name – Name of option (internal, for accessing the option)

• kwargs – Fields of ModelOption

class idaes_flowsheet_processor.api.Actions

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.

build = 'build'

solve = 'solve'

export = '_export'

diagram = 'diagram'

initialize = 'initialize'

kpis = 'kpis'

class idaes_flowsheet_processor.api.FlowsheetCategory

Flowsheet Categories

wastewater = 'Wasterwater Recovery'

desalination = 'Desalination'

class idaes_flowsheet_processor.api.FlowsheetReport

Abstract base class for flowsheet reports.

This class defines the interface for generating reports from a flowsheet. Subclasses should implement the to_html method to generate the report in HTML format.

abstract to_html(**kwargs: object) → str

Return report as an HTML string.

class idaes_flowsheet_processor.api.FlowsheetInterface(fs: FlowsheetExport | None = None, do_build: Callable | None = None, do_export: Callable | None = None, do_solve: Callable | None = None, do_initialize: Callable | None = None, do_kpis: Callable | None = None, get_diagram: Callable | None = None, category: FlowsheetCategory | None = None, custom_do_param_sweep_kwargs: Dict | None = None, **kwargs: object)

Interface between users, UI developers, and flowsheet models.

UI_HOOK = 'export_to_ui'

MissingObject

build(quiet=False, **kwargs: object) → None

Build flowsheet

Parameters:

• quiet – If true, suppress output from the build function

• **kwargs – User-defined values

Returns:

None

Raises:

RuntimeError – If the build fails

solve(**kwargs: object) → Any

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

get_diagram(**kwargs: object) → Any | None

Return diagram image name.

Parameters:

**kwargs – User-defined values

Returns:

Return image file name if get_diagram function is callable. Otherwise, return none

initialize(*args: object, **kwargs: object) → Any

Run initialize function.

Parameters:

**kwargs – User-defined values

Returns:

Return value of the underlying initialization function. Otherwise, return none

dict() → Dict

Serialize.

Returns:

Serialized contained FlowsheetExport object

load(data: Dict) → None

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

Parameters:

data – The input flowsheet (probably deserialized from JSON)

select_option(option_name: str, new_option: str) → None

Update flowsheet with selected option.

Parameters:

• data – The input flowsheet

• option_name – Name of selected option

Returns:

None

add_action(action_name: str, action_func: Callable) → None

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

get_action(name: str) → Callable | None

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 –

run_action(name: str, *args: object, **kwargs: object) → Any

Run the named action.

export_values() → None

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/flowsheets/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.flowsheets.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: str | types.ModuleType) → FlowsheetInterface | None

Get a a flowsheet interface for module.

Parameters:

module – The module

Returns:

A flowsheet interface or None if it failed

report(rtype=_KPI_REPORT, **kwargs: object) → FlowsheetReport

Generate and return a report for the flowsheet.

Parameters:

• report_type – Type of report to generate (any unique prefix of the report type).

• kwargs – Additional keywords passed to the given report type.

Raises:

ValueError – If a report argument is invalid

Returns:

A flowsheet report, which will display automatically in Jupyter Notebooks.

Return type:

FlowsheetReport

idaes_flowsheet_processor.api.WAFFLE

idaes_flowsheet_processor.api.DONUT

class idaes_flowsheet_processor.api.FlowsheetKPIReport(flowsheet_export: FlowsheetExport, total_type: _ChartTypes | None = None, bgcolor: str = '#ffffff', **kwargs: object)

Report of the Key Performance Indicators (KPIs) for a flowsheet.

The specification of the report is extracted from the FlowsheetExport object that is passed to the class constructor.

VALUE_FONT_NAME_SIZE = '150%'

VALUE_FONT_VAL_SIZE = '180%'

VALUE_FONT_NAME_COLOR = '#666'

VALUE_FONT_VAL_COLOR = '#66F'

VALUE_SEP_WIDTH = '7px'

to_html(layout: Any | None = None, **kwargs: object) → str

Build the report and return as a complete <HTML> element.

Parameters:

• layout – Layout specification. See Layout for format. If not given, lay out in one column.

• kwargs – Options for the create_* methods.

Returns:

HTML for the report

get_kpi_figures(**kwargs: object) → dict[str, plotly.graph_objects.Figure]

“Get figures for each KPI.

Parameters:

kwargs – Options for the create_* methods.

Returns:

classmethod create_kpi_values(kpi, font_size: int = 24, width: int = 800, margin: int | None = None, **ignore: object) → plotly.graph_objects.Figure

Create a table with values for each KPI.

Parameters:

• kpi

• font_size – Font size for the table, in points

• width – Width of the table in pixels

• margin – Margin around the table, as a dict with keys ‘t’, ‘b’, ‘l’, ‘r’. Values in pixels.

Returns:

Plotly Figure object with values in a table

classmethod create_kpi_barchart(kpi: KPI, **ignore: object) → plotly.graph_objects.Figure

Create a barchart from a vector of values

Parameters:

kpi – Key performance indicator

Returns:

Plotly Figure object with the bar chart

classmethod create_kpi_total(kpi: KPI, total_type: _ChartTypes = WAFFLE, **ignore: object) → plotly.graph_objects.Figure

Create diagram for a vector that should be represented as parts of a total. This will be either a pie (donut) chart or waffle chart.

Parameters:

kpi – Key performance indicator

Returns:

Plotly Figure object with the pie or waffle chart

class idaes_flowsheet_processor.api.Layout(spec, kpis: dict[str, str])

Translate a simple layout specification into an HTML flex layout.

The specification takes the form of a (possibly nested) list of names of the KPIs to display, where the outer list is a single column and the next level are rows, then columns within each row, etc.

Some examples:

• [ “kpi_one”, “kpi_two”, “kpi_three” ] will display 4 rows, each the full column width.

• [[“kpi_one”, “kpi_two”, “kpi_three”]] will display 1 row with items laid out horizontally

• [[“kpi_one”, “kpi_two”], [“kpi_three”, “kpi_four”]] will display a 2x2 grid

property body

property css