idaes.core.util package

Submodules

idaes.core.util.compare module

Provides a utility function for comparing two models

idaes.core.util.compare.compare(m1, m2, **kwargs)[source]

The idea here is to go block by block through these two models, printing out the differences in the variables. Some recursion to be expected. If m1name and/or m2name is assigned, the corresponding model will be renamed to the given string

idaes.core.util.compare.compare_block(b1, b2, **kwargs)[source]
idaes.core.util.compare.compare_var(v1, v2, p1names, p2names, **kwargs)[source]

idaes.core.util.concave module

Utility functions for implementing piecewise linear underestimators for concave univariate expressions.

Implementation of the delta formulation from: Bergamini, M. L., Grossmann, I., Scenna, N., & Aguirre, P. (2008).

An improved piecewise outer-approximation algorithm for the global optimization of MINLP models involving concave and bilinear terms. Computers and Chemical Engineering, 32, 477–493. http://doi.org/10.1016/j.compchemeng.2007.03.011
idaes.core.util.concave.add_concave_linear_underest(b, name, nsegs, x, f, f_expr, *sets, **kwargs)[source]
idaes.core.util.concave.add_concave_relaxation(b, z, x, f_expr, df_expr, nsegs, indx, exists, block_bounds=(None, None), bound_contract=None)[source]
idaes.core.util.concave.try_eval(f, x)[source]

idaes.core.util.config module

This module contains utility functions useful for validating arguments to IDAES modeling classes. These functions are primarily designed to be used as the domain argument in ConfigBlocks.

idaes.core.util.config.is_parameter_block(val)[source]

Domain validator for property package attributes

Parameters:val – value to be checked
Returns:TypeError if val is not an instance of PropertyParameterBase, ‘use_parameter_block’ or None
idaes.core.util.config.is_port(arg)[source]

Domain validator for ports

Parameters:arg – argument to be checked as a Port
Returns:Port object or Exception
idaes.core.util.config.list_of_floats(arg)[source]

Domain validator for lists of floats

Parameters:arg – argument to be cast to list of floats and validated
Returns:List of strings
idaes.core.util.config.list_of_strings(arg)[source]

Domain validator for lists of strings

Parameters:arg – argument to be cast to list of strings and validated
Returns:List of strings

idaes.core.util.convex module

Utility functions for generating envelopes for convex nonlinear functions

idaes.core.util.convex.add_convex_relaxation(b, z, x, f_expr, df_expr, nsegs, indx, exists, block_bounds=(None, None), bound_contract=None)[source]

Constructs a linear relaxation to bound a convex equality function

Parameters:
  • b (Block) – PyOMO block in which to generate variables and constraints
  • z (Expression) – PyOMO expression for the convex function output
  • x (Expression) – PyOMO expression for the convex function input
  • f_expr (function) – convex function
  • df_expr (function) – function giving first derivative of convex function with respect to x
  • exists (_VarData) – Variable corresponding to existence of unit
  • block_bounds (dict, optional) – dictionary describing disjunctive bounds present for variables associated with current block
Returns:

None

idaes.core.util.convex.try_eval(f, x)[source]

idaes.core.util.cut_gen module

This module provides utility functions for cut generation.

idaes.core.util.cut_gen.clone_block(old_block, new_block, var_set, lbda)[source]

This function acts similarly to the built-in Pyomo clone function, but excludes entries that are undesired for this platform.

idaes.core.util.cut_gen.clone_block_constraints(old_block, new_block, var_set)[source]
idaes.core.util.cut_gen.clone_block_params(old_block, new_block)[source]
idaes.core.util.cut_gen.clone_block_sets(old_block, new_block)[source]
idaes.core.util.cut_gen.clone_block_vars(old_block, new_block, var_set, lbda)[source]
idaes.core.util.cut_gen.copy_var_data(new_var_data, old_var_data)[source]
idaes.core.util.cut_gen.count_vars(old_block)[source]

Count the number of non-fixed variables to clone

idaes.core.util.cut_gen.get_sum_sq_diff(old_block, new_block)[source]
idaes.core.util.cut_gen.self_proj_var_rule(main_var, disagg_var, var_set, lbda)[source]

idaes.core.util.debug module

Debugging utility functions.

idaes.core.util.debug.display_infeasible_bounds(m, tol=1e-06)[source]

Print the infeasible variable bounds in the model.

Parameters:
  • m (Block) – Pyomo block or model to check
  • tol (float) – feasibility tolerance
idaes.core.util.debug.display_infeasible_constraints(m, tol=1e-06)[source]

Print the infeasible constraints in the model.

Uses the current model state. Prints to standard out.

Parameters:
  • m (Block) – Pyomo block or model to check
  • tol (float) – feasibility tolerance
idaes.core.util.debug.log_disjunct_values(m, integer_tolerance=0.001, logger=<Logger idaes.debug (INFO)>, selected_only=False)[source]

Display logical value of model disjuncts.

Parameters:
  • integer_tolerance (float) – tolerance on integrality test.
  • logger – logger to use for output. Otherwise, default debug module logger is used.
  • selected_only – only log the selected disjuncts

idaes.core.util.expr module

Utility functions for working with Pyomo expressions.

idaes.core.util.expr.is_linear(expr)[source]

Check if the Pyomo expression is linear.

TODO: There is the possibility for false negatives (if there is a nonlinear expression of a mutable parameter). Need to test this.

Parameters:expr (Expression) – Pyomo expression
Returns:True if expression is linear; False otherwise.
Return type:bool
Raises:ValueError – if polynomial degree is negative
idaes.core.util.expr.log_active_nonlinear_constraints(model, logger=<RootLogger root (WARNING)>)[source]

Log names of the active nonlinear constraints.

idaes.core.util.initialization module

Library of utility functions for initialization

idaes.core.util.initialization.get_port_value(port, port_idx=None)[source]

idaes.core.util.mccormick module

Utility functions for implementing piecewise (or standard) McCormick envelopes

Implementation of the McCormick envelope formulation given in: Misener, R., Thompson, J. P., & Floudas, C. A. (2011). Apogee:

Global optimization of standard, generalized, and extended pooling problems via linear and logarithmic partitioning schemes. Computers and Chemical Engineering, 35(5), 876–892. http://doi.org/10.1016/j.compchemeng.2011.01.026
idaes.core.util.mccormick.add_mccormick_cut(b, name, indx, z, x, y, exists, **kwargs)[source]
idaes.core.util.mccormick.add_mccormick_relaxation(b, z, x, y, nsegs, indx, exists, block_bounds=(None, None))[source]

Adds McCormick envelopes for a bilinear term z = x * y

Parameters:
  • b (Block) – PyOMO block in which to put constraints and helper variables
  • z (Expression) – PyOMO expression for the bilinear product
  • x (Expression) – expression for the bilinear operand to be divided into segments for the piecewise case
  • y (Expression) – expression for the other bilinear operand
  • nsegs (integer) – number of piecewise segments (normal is 1)
  • indx (tuple or singleton) – index for an indexed bilinear term
  • exists (Var) – variable corresponding to equipment existence
  • block_bounds (dict, optional) – dictionary describing disjunctive bounds present for variables associated with current block
Returns:

None

idaes.core.util.mccormick.setup_mccormick_cuts(b, name, nsegs, *sets)[source]
idaes.core.util.mccormick.squish(tup)[source]

Squishes a singleton tuple (‘A’,) to ‘A’

If tup is a singleton tuple, return the underlying singleton. Otherwise, return the original tuple.

Parameters:tup (tuple) – Tuple to squish
idaes.core.util.mccormick.squish_concat(a, *b)[source]

idaes.core.util.misc module

This module contains miscellaneous utility functions that of general use in IDAES models.

idaes.core.util.misc.add_object_ref(local_block, local_name, external_component)[source]

Add a reference in a model to non-local Pyomo component. This is used when one Block needs to make use of a component in another Block as if it were part of the local block.

Parameters:
  • local_block – Block in which to add reference
  • local_name – str name for referenced object to use in local_block
  • external_component – external component being referenced
Returns:

None

idaes.core.util.misc.category(*args)[source]

Decorate tests to enable tiered testing.

Suggested categories:
  1. frequent
  2. nightly
  3. expensive
  4. research
Parameters:*args (tuple of strings) – categories to which the test belongs
Returns:Either the original test function or skip
Return type:function
idaes.core.util.misc.dict_set(v, d, pre_idx=None, post_idx=None, fix=False)[source]

Set the values of array variables based on the values stored in a dictionary. There may already be a better way to do this. Should look into it.

The value of Pyomo variable element with index key is set to d[key]

Arguments: v: Indexed Pyomo variable d: dictonary to set the variable values from, keys should match a subset

of Pyomo variable indexes.

pre_idx: fixed indexes before elements to be set or None post_idx: fixed indexes after elements to be set or None fix: bool, fix the variables (otional)

idaes.core.util.misc.doNothing(*args, **kwargs)[source]

Do nothing.

This function is useful for instances when you want to call a function, if it exists. For example: getattr(unit, ‘possibly_defined_function’, getNothing)()

Parameters:
  • *args (anything) – accepts any argument
  • **kwargs (anything) – accepts any keyword arguments
Returns:

None

idaes.core.util.misc.fix_port(port, var, comp=None, value=None, port_idx=None)[source]

Method for fixing Vars in Ports.

Parameters:
  • port – Port object in which to fix Vars
  • var – variable name to be fixed (as str)
  • comp – index of var to be fixed (if applicable, default = None)
  • value – value to use when fixing var (default = None)
  • port_idx – list of Port elements at which to fix var. Must be list of valid indices,
Returns:

None

idaes.core.util.misc.get_pyomo_tmp_files()[source]

Make Pyomo write it’s temporary files to the current working directory, useful for checking nl, sol, and log files for ASL solvers without needing to track down the temporary file location.

idaes.core.util.misc.get_time(results)[source]

Retrieve the solver-reported elapsed time, if available.

idaes.core.util.misc.hhmmss(sec_in)[source]

Convert elapsed time in seconds to “d days hh:mm:ss.ss” format. This is nice for things that take a long time.

idaes.core.util.misc.requires_solver(solver)[source]

Decorate test to skip if a solver isn’t available.

idaes.core.util.misc.round_(n, *args, **kwargs)[source]

Round the number.

This function duplicates the functionality of round, but when passed positive or negative infinity, simply returns the argument.

idaes.core.util.misc.smooth_abs(a, eps=0.0001)[source]

General function for creating an expression for a smooth minimum or maximum.

Parameters:
  • a – term to get absolute value from (Pyomo component, float or int)
  • eps – smoothing parameter (Param, float or int) (default=1e-4)
Returns:

An expression for the smoothed absolute value operation.

idaes.core.util.misc.smooth_max(a, b, eps=0.0001)[source]

Smooth maximum operator.

Parameters:
  • a – first term in max function
  • b – second term in max function
  • eps – smoothing parameter (Param or float, default = 1e-4)
Returns:

An expression for the smoothed maximum operation.

idaes.core.util.misc.smooth_min(a, b, eps=0.0001)[source]

Smooth minimum operator.

Parameters:
  • a – first term in min function
  • b – second term in min function
  • eps – smoothing parameter (Param or float, default = 1e-4)
Returns:

An expression for the smoothed minimum operation.

idaes.core.util.misc.smooth_minmax(a, b, eps=0.0001, sense='max')[source]

General function for creating an expression for a smooth minimum or maximum.

Parameters:
  • a – first term in mix or max function (Pyomo component, float or int)
  • b – second term in min or max function (Pyomo component, float or int)
  • eps – smoothing parameter (Param, float or int) (default=1e-4)
  • sense – ‘mim’ or ‘max’ (default = ‘max’)
Returns:

An expression for the smoothed minimum or maximum operation.

idaes.core.util.misc.solve_indexed_blocks(solver, blocks, **kwds)[source]

This method allows for solving of Indexed Block components as if they were a single Block. A temporary Block object is created which is populated with the contents of the objects in the blocks argument and then solved.

Parameters:
  • solve – a Pyomo solver object to use when solving the Indexed Block
  • blocks – an object which inherits from Block, or a list of Blocks
  • kwds – a dict of argumnets to be passed to the solver
Returns:

A Pyomo solver results object

idaes.core.util.misc.unfix_port(port, var, comp=None, port_idx=None)[source]

Method for unfixing Vars in Ports.

Parameters:
  • port – Port object in which to unfix Vars
  • var – variable name to be unfixed (as str)
  • comp – index of var to be unfixed (if applicable, default = None)
  • port_idx – list of Port elements at which to unfix var. Must be list of valid indices,
Returns:

None

idaes.core.util.model_serializer module

Functions for saving and loading Pyomo objects to json

class idaes.core.util.model_serializer.Counter[source]

Bases: object

class idaes.core.util.model_serializer.StoreSpec(classes=((<class 'pyomo.core.base.param.Param'>, ()), (<class 'pyomo.core.base.var.Var'>, ()), (<class 'pyomo.core.base.component.Component'>, ('active', ))), data_classes=((<class 'pyomo.core.base.var._VarData'>, ('fixed', 'stale', 'value', 'lb', 'ub')), (<class 'pyomo.core.base.param._ParamData'>, ('value', )), (<class 'pyomo.core.base.component.ComponentData'>, ('active', ))), skip_classes=(<class 'pyomo.core.base.external.ExternalFunction'>, <class 'pyomo.core.base.sets.Set'>, <class 'pyomo.network.port.Port'>, <class 'pyomo.core.base.expression.Expression'>, <class 'pyomo.core.base.rangeset.RangeSet'>), ignore_missing=True, suffix=True, suffix_filter=None)[source]

Bases: object

A StoreSpec object tells the load/save JSON functions what to read or write. The default settings will produce a StoreSpec configured to load/save the typical attributes required to load/save a model.

Initialize an object to specify what parts of a model are saved. Classes and data classes are checked in order. So the more specific classes should go first and fallback cases should go last. Since classes like component catch pretty muh everything, you can also specify classes to skip by adding classes to the skip class list. Classes and data classes can also be skipped by setting there attribute list to None.

Parameters:
  • classes – A list of classes to save. Each class is represented by a list (or tupple) containing the following elements (1) class (compared using isinstance) (2) attribute list an empty list is okay. If none skip this type. (3) optional load filter function. The load filter function returns a list of attributes to read based on the state of an object and its saved state. The allows, for example, loading values for unfixed variables, or only loading values whoes current value is less than one. The filter function only applies to load not save. Filter functions take two arguments (a) the object (current state) and (b) the dictionary containing the saved state of an object.
  • data_classes – This takes the same form as the classes argument. This is for component data classes.
  • skip_classes – This is a list of classes to skip. If a class appears in the skip list, but also appears in the classes argument, the classes argument will override skip_classes.
  • ignore_missing – If True will ignore a componet or attribute that exists in the model, but not in the stored state. If false an excpetion will be raised for things in the model that should be loaded but aren’t in the saced state. Extra items in the saved state will not raise an exception regaurdless of this arguments
  • suffix – If True store suffixes an component ids. If false, don’t stored suffixes, also don’t store the compoent ids because they are only needed to read back suffixes.
  • suffix_filter – None to store all siffixes if suffix=True, or a list of suffixes to store if suffix=True
classmethod bound()[source]

Returns a StoreSpec object to store variable bounds only.

get_class_attr_list(o)[source]

Look up what attributes to save/load for an Component object. :param o: Object to look up attribute list for.

Returns:A list of attributes and a filter function for object type
get_data_class_attr_list(o)[source]

Look up what attributes to save/load for an ComponentData object. :param o: Object to look up attribute list for.

Returns:A list of attributes and a filter function for object type
classmethod isfixed()[source]

Returns a StoreSpec object to store is variables are fixed.

set_read_callback(attr, cb=None)[source]

Set a callback to set an attribute, when reading from json or dict.

set_write_callback(attr, cb=None)[source]

Set a callback to get an attribute, when writing to json or dict.

classmethod suffix(suffix_filter=None)[source]
classmethod value()[source]

Returns a StoreSpec object to store variable values only.

classmethod value_isfixed(only_fixed)[source]

Retur a StoreSpec object to store variable values and if fixed. :param only_fixed: Only load fixed variable values

classmethod value_isfixed_isactive(only_fixed)[source]

Retur a StoreSpec object to store variable values, if variables are fixed and if components are active. :param only_fixed: Only load fixed variable values

idaes.core.util.model_serializer.component_data_from_dict(sd, o, wts)[source]

Component data to a dict.

idaes.core.util.model_serializer.component_data_to_dict(o, wts)[source]

Component data to a dict.

idaes.core.util.model_serializer.from_json(o, sd=None, fname=None, s=None, wts=None, gz=False)[source]

Load the state of a Pyomo component state from a dictionary, json file, or json string. Must only specify one of sd, fname, or s as a non-None value. This works by going through the model and loading the state of each sub-compoent of o. If the saved state contains extra information, it is ignored. If the save state doesn’t contain an enetry for a model component that is to be loaded an error will be raised, unless ignore_missing = True.

Parameters:
  • o – Pyomo component to for which to load state
  • sd – State dictionary to load, if None, check fname and s
  • fname – JSON file to load, if None, check for s
  • s – JSON string to load
  • wts – StoreSpec object specifying what to load
Returns:

  • etime_load_file: how long in seconds it took to load the json file
  • etime_read_dict: how long in seconds it took to read models state
  • etime_read_suffixes: how long in seconds it took to read suffixes

Return type:

Dictionary with some perfomance information. The keys are

idaes.core.util.model_serializer.load_json(*args, **kwargs)[source]

Deprecated function will add warning soon. See from_json.

idaes.core.util.model_serializer.save_json(*args, **kwargs)[source]

Deprecated function will add warning eventually. See to_json.

idaes.core.util.model_serializer.to_json(o, fname=None, human_read=False, wts=None, metadata={}, gz=False)[source]

Save the state of a model to a Python dictionary, and optionally dump it to a json file. To load a model state, a model with the same structure must exist. The model itself cannot be recreated from this.

Parameters:
  • fname – json file name to save model state, if None only create python dict
  • human_read – if True, add indents and spacing to make the json file more readable, if false cut out whitespace and make as compact as possilbe
  • wts – is What To Save, this is a StoreSpec object that specifies what object types and attributes to save. If None, the default is used which saves the state of the compelte model state.
  • metadata – addtional metadata to save beyond the standard format_version, date, and time.
Returns:

A Python dictionary containing the state of the model. If fname is given this dictionary is also dumped to a json file.

idaes.core.util.mpdisagg module

Utility functions for implementing multi-parametric disaggregation lower bounds

Implementation of lower-bounding formulation given in: Kolodziej, S., Castro, P. M., & Grossmann, I. E. (2013). Global

optimization of bilinear programs with a multiparametric disaggregation technique. Journal of Global Optimization, 57(4), 1039–1063. http://doi.org/10.1007/s10898-012-0022-1
idaes.core.util.mpdisagg.add_mpDisagg_cut(b, name, indx, w, x, y, exists)[source]
idaes.core.util.mpdisagg.setup_multiparametric_disagg(b, name, minPow, maxPow, *sets)[source]

idaes.core.util.oa module

idaes.core.util.partial_surrogate module

idaes.core.util.stream module

Stream Utilities

idaes.core.util.stream.make_stream_table(model, attrs, t=0, idx={}, streams=None, ignore_missing=False)[source]

This function makes a stream table contained in a Pandas data frame.

Parameters:
  • model – Pyomo block to search for streams in.
  • attrs – Pyomo port components to add to stream table
  • t – Time index for the stream table data
  • idx – Dictionary of index lists for indexed attributes
  • streams – Explicit list of steam objects to include. If this is None all streams in model will be included
  • ignore_missing – If this is True and streams do not have all the attributes requested, the steam will be included anyway with missing data. If this option is false, streams that do not contain all required information will be excluded.
Returns:

A pandas data frame with port variables in columns and streams in rows.

Examples

table = make_stream_table(
model=model, attrs=[“flow_component”, “temperature”, “pressure”], idx={“flow_component”:[“CO2”, “H2O”, “N2”, “O2”, “Ar”]}, t=0, ignore_missing=False)

idaes.core.util.var module

This module provides utility functions and classes related to Pyomo variables

class idaes.core.util.var.SliceVar(var, slices)[source]

Bases: object

This class provides a way to pass sliced variables into other utility functions

class idaes.core.util.var.Wrapper(obj)[source]

Bases: object

This class provides a wrapper around a Pyomo Component so that a Block does not try to attach and construct it.

TODO: this might be a good place for a weakref implementation

idaes.core.util.var.is_fixed_by_bounds(expr, block_bounds=(None, None), tol=1e-14)[source]
idaes.core.util.var.lb(expr, block_bounds=(None, None))[source]

Returns the lower bound of the expression or variable

idaes.core.util.var.max_ub(expr1, expr2)[source]
idaes.core.util.var.max_ubb(expr1, expr2, block_bounds)[source]
idaes.core.util.var.min_lb(expr1, expr2)[source]
idaes.core.util.var.min_lbb(expr1, expr2, block_bounds)[source]
idaes.core.util.var.none_if_empty(tup)[source]

Returns None if passed an empty tuple This is helpful since a SimpleVar is actually an IndexedVar with a single index of None rather than the more intuitive empty tuple.

idaes.core.util.var.tighten_block_bound(var, newbound, block_bounds)[source]
idaes.core.util.var.tighten_mc_var(vardata, x_expr, y_expr, block_bounds)[source]
idaes.core.util.var.tighten_var_bound(var, newbound)[source]

Tightens the variable bounds for one variable

This function does not blindly apply the bounds passed in. Rather, it evaluates whether the new proposed bounds are better than the existing variable bounds.

Parameters:
  • var (_VarData) – single Pyomo variable object (not indexed like Var)
  • newbound (tuple) – a tuple of (new lower bound, new upper bound)
Returns:

None

idaes.core.util.var.ub(expr, block_bounds=(None, None))[source]

Returns the upper bound of the expression or variable

idaes.core.util.var.unwrap(obj)[source]

Unwraps the wrapper, if one exists.

idaes.core.util.var.wrap_var(obj)[source]

Provides a Wrapper around the obj if it is not a constant value; otherwise, returns the constant value.

idaes.core.util.var_test module

idaes.core.util.var_test.assert_var_equal(test_case, var, expected_val, tolerance)[source]
idaes.core.util.var_test.value_correct(var, expected_val, tolerance)[source]