idaes.core.util package

Subpackages

• idaes.core.util.convergence package
  • Submodules
  • idaes.core.util.convergence.convergence module
  • idaes.core.util.convergence.convergence_base module
  • idaes.core.util.convergence.mpi_utils module

Submodules

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_physical_parameter_block(val)

Domain validator for property package attributes

Parameters:val – value to be checked Returns:ConfigurationError if val is not an instance of PhysicalParameterBlock or useDefault

idaes.core.util.config.is_port(arg)

Domain validator for ports

Parameters:arg – argument to be checked as a Port Returns:Port object or Exception

idaes.core.util.config.is_reaction_parameter_block(val)

Domain validator for reaction package attributes

Parameters:val – value to be checked Returns:ConfigurationError if val is not an instance of ReactionParameterBlock

idaes.core.util.config.is_state_block(val)

Domain validator for state block as an argument

Parameters:val – value to be checked Returns:ConfigurationError if val is not an instance of StateBlock or None

idaes.core.util.config.is_time_domain(arg)

Domain validator for time domains

Parameters:

• arg – argument to be checked as a time domain (i.e. Set or
• ContinuousSet) –

Returns:

Set, ContinuousSet or Exception

idaes.core.util.config.is_transformation_method(arg)

Domain validator for transformation methods

Parameters:arg – argument to be checked for membership in recognized strings Returns:Recognised string or Exception

idaes.core.util.config.is_transformation_scheme(arg)

Domain validator for transformation scheme

Parameters:arg – argument to be checked for membership in recognized strings Returns:Recognised string or Exception

idaes.core.util.config.list_of_floats(arg)

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)

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.exceptions module

This module contains custom IDAES exceptions.

exception idaes.core.util.exceptions.BalanceTypeNotSupportedError

IDAES exception to be used when a control volumedoes not support a given type of balance equation.

exception idaes.core.util.exceptions.BurntToast

General exception for when something breaks badly in the core.

exception idaes.core.util.exceptions.ConfigurationError

IDAES exception to be used when configuration arguments are incorrect or inconsistent.

exception idaes.core.util.exceptions.DynamicError

IDAES exception for cases where settings associated with dynamic models are incorrect.

exception idaes.core.util.exceptions.PropertyNotSupportedError

IDAES exception for cases when a models calls for a property which is not supported by the chosen property package.

Needs to inherit from AttributeError for Pyomo interactions.

exception idaes.core.util.exceptions.PropertyPackageError

IDAES exception for generic errors arising from property packages.

Needs to inherit from AttributeError for Pyomo interactions.

idaes.core.util.expr_doc module

class idaes.core.util.expr_doc.Pyomo2SympyVisitor(object_map)

This is based on the class of the same name in pyomo.core.base.symbolic, but it catches ExternalFunctions and does not decend into named expressions.

class idaes.core.util.expr_doc.PyomoSympyBimap

This is based on the class of the same name in pyomo.core.base.symbolic, but it adds mapping latex symbols to the sympy symbols. This will get you pretty equations when using sympy’s LaTeX writer.

idaes.core.util.expr_doc.deduplicate_symbol(x, v, used)

Check if x is a duplicated LaTeX symbol if so add incrementing Di subscript

Parameters:

• x – symbol string
• v – pyomo object
• used – dictionary of pyomo objects with symbols as keys

Returns:

Returns a unique symbol. If x was not in used keys, returns x, otherwise adds exponents to make it unique.

idaes.core.util.expr_doc.document_constraints(comp, doc=True, descend_into=True)

Provides nicely formatted constraint documetntation in markdown format, assuming the $$latex math$$ and $latex math$ syntax is supported.

Parameters:

• comp – A Pyomo component to document in {_ConstraintData, _ExpressionData, _BlockData}.
• doc – True adds a documentation table for each constraint or expression. Due to the way symbols are semi-automatiaclly generated, the exact symbol definitions may be unique to each constraint or expression, if unique LaTeX symbols were not provided everywhere in a block.
• descend_into – If True, look in subblocks for constraints.

Returns:

A string in markdown format with equations in LaTeX form.

idaes.core.util.expr_doc.ipython_document_constraints(comp, doc=True, descend_into=True)

See document_constraints, this just directly displays the markdown instead of returning a string.

idaes.core.util.expr_doc.sympify_expression(expr)

Converts Pyomo expressions to sympy expressions. This is based on the function of the same name in pyomo.core.base.symbolic. The difference between this and the Pymomo is that this one checks if the expr argument is a named expression and expands it anyway. This allows named expressions to only be expanded if they are the top level object.

idaes.core.util.expr_doc.to_latex(expr)

Return a sympy expression for the given Pyomo expression

Parameters:expr (Expression) – Pyomo expression Returns:

keys: sympy_expr, a sympy expression; where, markdown string

with documentation table; latex_expr, a LaTeX string representation of the expression.

Return type:(dict)

idaes.core.util.initialization module

This module contains utility functions for initialization of IDAES models.

idaes.core.util.initialization.solve_indexed_blocks(solver, blocks, **kwds)

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.math module

This module contains utility functions for mathematical operators of use in equation oriented models.

idaes.core.util.math.smooth_abs(a, eps=0.0001)

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

\[|a| = sqrt(a^2 + eps^2)\]

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.math.smooth_max(a, b, eps=0.0001)

Smooth maximum operator, using smooth_abs operator.

\[max(a, b) = 0.5*(a+b + |a-b|)\]

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.math.smooth_min(a, b, eps=0.0001)

Smooth minimum operator, using smooth_abs operator.

\[max(a, b) = 0.5*(a+b - |a-b|)\]

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.math.smooth_minmax(a, b, eps=0.0001, sense='max')

General function for creating an expression for a smooth minimum or maximum. Uses the smooth_abs operator.

\[minmax(a, b) = 0.5*(a+b +- |a-b|)\]

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 module

This module contains miscellaneous utility functions for use in IDAES models.

idaes.core.util.misc.TagReference(s, description='')

Create a Pyomo reference with an added description string attribute to describe the reference. The intended use for these references is to create a time-indexed reference to variables in a model corresponding to plant measurment tags.

Parameters:

• s – Pyomo time slice of a variable or expression
• description (str) – A description the measurment

Returns:

A Pyomo Reference object with an added doc attribute

idaes.core.util.misc.add_object_reference(self, local_name, remote_object)

Method to create a reference in the local model to a remote Pyomo object. This method should only be used where Pyomo Reference objects are not suitable (such as for referencing scalar Pyomo objects where the None index is undesirable).

Parameters:

• local_name – name to use for local reference (str)
• remote_object – object to make a reference to

Returns:

None

idaes.core.util.misc.copy_port_values(destination, source)

Copy the variable values in the source port to the destination port. The ports must containt the same variables.

Parameters:

• (pyomo.Port) – Copy values from this port
• (pyomo.Port) – Copy values to this port

Returns:

None

idaes.core.util.misc.extract_data(data_dict)

General method that returns a rule to extract data from a python dictionary. This method allows the param block to have a database for a parameter but extract a subset of this data to initialize a Pyomo param object.

idaes.core.util.misc.svg_tag(tags, svg, outfile=None, idx=None, tag_map=None, show_tags=False)

Replace text in a SVG with tag values for the model. This works by looking for text elements in the SVG with IDs that match the tags or are in tag_map.

Parameters:

• tags – A dictionary where the key is the tag and the value is a Pyomo Refernce. The refernce could be indexed. In yypical IDAES applications the references would be indexed by time.
• svg – a file pointer or a string continaing svg contents
• outfile – a file name to save the results, if None don’t save
• idx – if None not indexed, otherwise an index in the indexing set of the reference
• tag_map – dictionary with svg id keys and tag values, to map svg ids to tags
• show_tags – Put tag labels of the diagram instead of numbers

Returns:

String for SVG

idaes.core.util.model_serializer module

Functions for saving and loading Pyomo objects to json

class idaes.core.util.model_serializer.Counter

This is a counter object, which is an easy way to pass an interger pointer around between methods.

class idaes.core.util.model_serializer.StoreSpec(classes=((<class 'pyomo.core.base.param.Param'>, ('_mutable', )), (<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 'int'>, ('value', )), (<class 'float'>, ('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)

A StoreSpec object tells the serializer 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 state.

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 or None, an emptry list store the object, but none of its attributes, None will not store objects of this class 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. More specific classes should come before more general classes. For example if an obejct is a HeatExchanger and a UnitModel, and HeatExchanger is listed first, it will follow the HeatExchanger settings. If UnitModel is listed first in the classes list, it will follow the UnitModel settings.
• 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. The use for this is to specifically exclude certain classes that would get caught by more general classes (e.g. UnitModel is in the class list, but you want to exclude HeatExchanger which is derived from UnitModel).
• ignore_missing – If True will ignore a component 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 stored state. Extra items in the stored state will not raise an exception regaurdless of this argument.
• suffix – If True store suffixes and component ids. If false, don’t store suffixes.
• suffix_filter – None to store all siffixes if suffix=True, or a list of suffixes to store if suffix=True

classmethod bound()

Returns a StoreSpec object to store variable bounds only.

get_class_attr_list(o)

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)

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()

Returns a StoreSpec object to store if variables are fixed.

set_read_callback(attr, cb=None)

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

set_write_callback(attr, cb=None)

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

classmethod value()

Returns a StoreSpec object to store variable values only.

classmethod value_isfixed(only_fixed)

Return a StoreSpec object to store variable values and if fixed.

Parameters:only_fixed – Only load fixed variable values

classmethod value_isfixed_isactive(only_fixed)

Retur a StoreSpec object to store variable values, if variables are fixed and if components are active.

Parameters:only_fixed – Only load fixed variable values

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

Component data to a dict.

idaes.core.util.model_serializer.component_data_to_dict(o, wts)

Component data to a dict.

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

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, only used if sd is None
• s – JSON string to load only used if both sd and fname are None
• wts – StoreSpec object specifying what to load
• gz – If True assume the file specified by fname is gzipped. The default is False.

Returns:

Dictionary with some perfomance information. The keys are “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

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

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:

• o – The Pyomo component object to save. Usually a Pyomo model, but could also be a subcomponent of a model (usually a sub-block).
• fname – json file name to save model state, if None only create python dict
• gz – If fname is given and gv is True gzip the json file. The default is False.
• 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
• metadata – A dictionary of addtional metadata to add.
• 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.
• return_dict – default is False if true returns a dictionary representation
• return_json_string – default is False returns a json string

Returns:

If return_dict is True returns a dictionary serialization of the Pyomo component. If return_dict is False and return_json_string is True returns a json string dump of the dict. If fname is given the dictionary is also written to a json file. If gz is True and fname is given, writes a gzipped json file.

idaes.core.util.tables module

idaes.core.util.tables.state_table(m, attributes, heading=None)

Create a Pandas dataframe that shows the material state in every state block.

Parameters:

• m (Block) – Pyomo model or block from which to create a state block table
• attributes (list or tuple of strings) – Attributes to report from a StateBlock, can be a Var, Param, or Expression. If an attribute doesn’t exist or doesn’t have a valid value, it will be treated as missing data.
• heading (list or tuple of srings) – A list of strings that will be used as column headings. If None the attribute names will be used.

Returns:

A Pandas DataFrame with a StateBlock table

Return type:

(DataFrame)

idaes.core.util.tables.stream_table(streams, attributes, heading=None)

Create a Pandas DataFrame that shows the material state in streams.

Parameters:

• streams (dict) – A dictionary with stream name keys and StateBlockData objects for values. The stream names do not need to correspond to Arcs in the flowhseet. Any name can be associated with a state block. Use an OrderedDict to show the streams in a specific order, otherwise the dataframe can be sorted later.
• attributes (list or tuple of strings) – Attributes to report from a StateBlock, can be a Var, Param, or Expression. If an attribute doesn’t exist or doesn’t have a valid value, it will be treated as missing data.
• heading (list or tuple of srings) – A list of strings that will be used as column headings. If None the attribute names will be used.

Returns:

A Pandas dataframe containing a stream table

Return type:

(DataFrame)