idaes.core.util package¶
Subpackages¶
Submodules¶
idaes.core.util.compare module¶
Provides a utility function for comparing two models
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.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.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.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.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.initialization module¶
Library of utility functions for initialization
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_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.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:
- frequent
- nightly
- expensive
- 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.
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
-
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
-
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.
-
idaes.core.util.model_serializer.
component_data_from_dict
(sd, 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.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. If a attribute is requested that is not a port avriable, this will attempt to find the property package accociated with the source and search there. This handles variables and expressions.
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.
lb
(expr, block_bounds=(None, None))[source]¶ Returns the lower bound of the expression or variable
-
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_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