Model Statistics Methods

The IDAES toolset contains a number of utility functions which are useful for quantifying model statistics such as the number of variable and constraints, and calculating the available degrees of freedom in a model. These methods can be found in idaes.core.util.model_statistics.

The most commonly used methods are degrees_of_freedom and report_statistics, which are described below.

Degrees of Freedom Method

The degrees_of_freedom method calculates the number of degrees of freedom available in a given model. The calculation is based on the number of unfixed variables which appear in active constraints, minus the number of active equality constraints in the model. Users should note that this method does not consider inequality or deactivated constraints, or variables which do not appear in active equality constraints.

idaes.core.util.model_statistics.degrees_of_freedom(block)

Method to return the degrees of freedom of a model.

Parameters:

block – model to be studied

Returns:

Number of degrees of freedom in block.

Report Statistics Method

The report_statistics method provides the user with a summary of the contents of their model, including the degrees of freedom and a break down of the different Variables, Constraints, Objectives, Blocks and Expressions. This method also includes numbers of deactivated components for the user to use in debugging complex models.

Note

This method only considers Pyomo components in activated Blocks. The number of deactivated Blocks is reported, but any components within these Blocks are not included.

Example Output

Model Statistics

Degrees of Freedom: 0

Total No. Variables: 52

No. Fixed Variables: 12

No. Unused Variables: 0 (Fixed: 0)

No. Variables only in Inequalities: 0 (Fixed: 0)

Total No. Constraints: 40

No. Equality Constraints: 40 (Deactivated: 0)

No. Inequality Constraints: 0 (Deactivated: 0)

No. Objectives: 0 (Deactivated: 0)

No. Blocks: 14 (Deactivated: 0)

No. Expressions: 2

idaes.core.util.model_statistics.report_statistics(block, ostream=None)

Method to print a report of the model statistics for a Pyomo Block

Parameters:

• block – the Block object to report statistics from

• ostream – output stream for printing (defaults to sys.stdout)

Returns:

Printed output of the model statistics

Other Statistics Methods

In addition to the methods discussed above, the model_statistics module also contains a number of methods for quantifying model statistics which may be of use to the user in debugging models. These methods come in three types:

• Number methods (start with number_) return the number of components which meet a given criteria, and are useful for quickly quantifying different types of components within a model for determining where problems may exist.

• Set methods (end with _set) return a Pyomo ComponentSet containing all components which meet a given criteria. These methods are useful for determining where a problem may exist, as the ComponentSet indicates which components may be causing a problem.

• Generator methods (end with _generator) contain Python generators which return all components which meet a given criteria.

Available Methods

This module contains utility functions for reporting structural statistics of IDAES models.

idaes.core.util.model_statistics.activated_block_component_generator(block, ctype)

Generator which returns all the components of a given ctype which exist in activated Blocks within a model.

Parameters:

• block – model to be studied

• ctype – type of Pyomo component to be returned by generator.

Returns:

A generator which returns all components of ctype which appear in activated Blocks in block

idaes.core.util.model_statistics.activated_blocks_set(block)

Method to return a ComponentSet of all activated Block components in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all activated Block components in block (including block itself)

idaes.core.util.model_statistics.activated_constraints_generator(block)

Generator which returns all activated Constraint components in a model.

Parameters:

block – model to be studied

Returns:

A generator which returns all activated Constraint components block

idaes.core.util.model_statistics.activated_constraints_set(block)

Method to return a ComponentSet of all activated Constraint components in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all activated Constraint components in block

idaes.core.util.model_statistics.activated_equalities_generator(block)

Generator which returns all activated equality Constraint components in a model.

Parameters:

block – model to be studied

Returns:

A generator which returns all activated equality Constraint components block

idaes.core.util.model_statistics.activated_equalities_set(block)

Method to return a ComponentSet of all activated equality Constraint components in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all activated equality Constraint components in block

idaes.core.util.model_statistics.activated_inequalities_generator(block)

Generator which returns all activated inequality Constraint components in a model.

Parameters:

block – model to be studied

Returns:

A generator which returns all activated inequality Constraint components block

idaes.core.util.model_statistics.activated_inequalities_set(block)

Method to return a ComponentSet of all activated inequality Constraint components in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all activated inequality Constraint components in block

idaes.core.util.model_statistics.activated_objectives_generator(block)

Generator which returns all activated Objective components in a model.

Parameters:

block – model to be studied

Returns:

A generator which returns all activated Objective components block

idaes.core.util.model_statistics.activated_objectives_set(block)

Method to return a ComponentSet of all activated Objective components which appear in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all activated Objective components which appear in block

idaes.core.util.model_statistics.active_variables_in_deactivated_blocks_set(block)

Method to return a ComponentSet of any Var components which appear within an active Constraint but belong to a deactivated Block in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including any Var components which belong to a deactivated Block but appear in an activate Constraint in block

idaes.core.util.model_statistics.deactivated_blocks_set(block)

Method to return a ComponentSet of all deactivated Block components in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all deactivated Block components in block (including block itself)

idaes.core.util.model_statistics.deactivated_constraints_generator(block)

Generator which returns all deactivated Constraint components in a model.

Parameters:

block – model to be studied

Returns:

A generator which returns all deactivated Constraint components block

idaes.core.util.model_statistics.deactivated_constraints_set(block)

Method to return a ComponentSet of all deactivated Constraint components in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all deactivated Constraint components in block

idaes.core.util.model_statistics.deactivated_equalities_generator(block)

Generator which returns all deactivated equality Constraint components in a model.

Parameters:

block – model to be studied

Returns:

A generator which returns all deactivated equality Constraint components block

idaes.core.util.model_statistics.deactivated_equalities_set(block)

Method to return a ComponentSet of all deactivated equality Constraint components in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all deactivated equality Constraint components in block

idaes.core.util.model_statistics.deactivated_inequalities_generator(block)

Generator which returns all deactivated inequality Constraint components in a model.

Parameters:

block – model to be studied

Returns:

A generator which returns all indeactivated equality Constraint components block

idaes.core.util.model_statistics.deactivated_inequalities_set(block)

Method to return a ComponentSet of all deactivated inequality Constraint components in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all deactivated inequality Constraint components in block

idaes.core.util.model_statistics.deactivated_objectives_generator(block)

Generator which returns all deactivated Objective components in a model.

Parameters:

block – model to be studied

Returns:

A generator which returns all deactivated Objective components block

idaes.core.util.model_statistics.deactivated_objectives_set(block)

Method to return a ComponentSet of all deactivated Objective components which appear in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all deactivated Objective components which appear in block

idaes.core.util.model_statistics.derivative_variables_set(block)

Method to return a ComponentSet of all DerivativeVar components which appear in a model. Users should note that DerivativeVars are converted to ordinary Vars when a DAE transformation is applied. Thus, this method is useful for detecting any DerivativeVars which were do transformed.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all DerivativeVar components which appear in block

idaes.core.util.model_statistics.expressions_set(block)

Method to return a ComponentSet of all Expression components which appear in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all Expression components which appear in block

idaes.core.util.model_statistics.fixed_unused_variables_set(block)

Method to return a ComponentSet of all fixed Var components which do not appear within any activated Constraint in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all fixed Var components which do not appear within any Constraints in block

idaes.core.util.model_statistics.fixed_variables_generator(block)

Generator which returns all fixed Var components in a model.

Parameters:

block – model to be studied

Returns:

A generator which returns all fixed Var components block

idaes.core.util.model_statistics.fixed_variables_in_activated_equalities_set(block)

Method to return a ComponentSet of all fixed Var components which appear within an equality Constraint in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all fixed Var components which appear within activated equality Constraints in block

idaes.core.util.model_statistics.fixed_variables_only_in_inequalities(block)

Method to return a ComponentSet of all fixed Var components which appear only within activated inequality Constraints in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all fixed Var components which appear only within activated inequality Constraints in block

idaes.core.util.model_statistics.fixed_variables_set(block)

Method to return a ComponentSet of all fixed Var components in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all fixed Var components in block

idaes.core.util.model_statistics.large_residuals_set(block, tol=1e-05, return_residual_values=False)

Method to return a ComponentSet of all Constraint components with a residual greater than a given threshold which appear in a model.

Parameters:

• block – model to be studied

• tol – residual threshold for inclusion in ComponentSet

• return_residual_values – boolean, if true return dictionary with residual values

Returns:

A ComponentSet including all Constraint components with a residual greater than tol which appear in block (if return_residual_values is false) residual_values: dictionary with constraint as key and residual (float) as value (if return_residual_values is true)

Return type:

large_residual_set

idaes.core.util.model_statistics.number_activated_blocks(block)

Method to return the number of activated Block components in a model.

Parameters:

block – model to be studied

Returns:

Number of activated Block components in block (including block itself)

idaes.core.util.model_statistics.number_activated_constraints(block)

Method to return the number of activated Constraint components in a model.

Parameters:

block – model to be studied

Returns:

Number of activated Constraint components in block

idaes.core.util.model_statistics.number_activated_equalities(block)

Method to return the number of activated equality Constraint components in a model.

Parameters:

block – model to be studied

Returns:

Number of activated equality Constraint components in block

idaes.core.util.model_statistics.number_activated_inequalities(block)

Method to return the number of activated inequality Constraint components in a model.

Parameters:

block – model to be studied

Returns:

Number of activated inequality Constraint components in block

idaes.core.util.model_statistics.number_activated_objectives(block)

Method to return the number of activated Objective components which appear in a model.

Parameters:

block – model to be studied

Returns:

Number of activated Objective components which appear in block

idaes.core.util.model_statistics.number_active_variables_in_deactivated_blocks(block)

Method to return the number of Var components which appear within an active Constraint but belong to a deactivated Block in a model.

Parameters:

block – model to be studied

Returns:

Number of Var components which belong to a deactivated Block but appear in an activate Constraint in block

idaes.core.util.model_statistics.number_deactivated_blocks(block)

Method to return the number of deactivated Block components in a model.

Parameters:

block – model to be studied

Returns:

Number of deactivated Block components in block (including block itself)

idaes.core.util.model_statistics.number_deactivated_constraints(block)

Method to return the number of deactivated Constraint components in a model.

Parameters:

block – model to be studied

Returns:

Number of deactivated Constraint components in block

idaes.core.util.model_statistics.number_deactivated_equalities(block)

Method to return the number of deactivated equality Constraint components in a model.

Parameters:

block – model to be studied

Returns:

Number of deactivated equality Constraint components in block

idaes.core.util.model_statistics.number_deactivated_inequalities(block)

Method to return the number of deactivated inequality Constraint components in a model.

Parameters:

block – model to be studied

Returns:

Number of deactivated inequality Constraint components in block

idaes.core.util.model_statistics.number_deactivated_objectives(block)

Method to return the number of deactivated Objective components which appear in a model.

Parameters:

block – model to be studied

Returns:

Number of deactivated Objective components which appear in block

idaes.core.util.model_statistics.number_derivative_variables(block)

Method to return the number of DerivativeVar components which appear in a model. Users should note that DerivativeVars are converted to ordinary Vars when a DAE transformation is applied. Thus, this method is useful for detecting any DerivativeVars which were do transformed.

Parameters:

block – model to be studied

Returns:

Number of DerivativeVar components which appear in block

idaes.core.util.model_statistics.number_expressions(block)

Method to return the number of Expression components which appear in a model.

Parameters:

block – model to be studied

Returns:

Number of Expression components which appear in block

idaes.core.util.model_statistics.number_fixed_unused_variables(block)

Method to return the number of fixed Var components which do not appear within any activated Constraint in a model.

Parameters:

block – model to be studied

Returns:

Number of fixed Var components which do not appear within any activated Constraints in block

idaes.core.util.model_statistics.number_fixed_variables(block)

Method to return the number of fixed Var components in a model.

Parameters:

block – model to be studied

Returns:

Number of fixed Var components in block

idaes.core.util.model_statistics.number_fixed_variables_in_activated_equalities(block)

Method to return the number of fixed Var components which appear within activated equality Constraints in a model.

Parameters:

block – model to be studied

Returns:

Number of fixed Var components which appear within activated equality Constraints in block

idaes.core.util.model_statistics.number_fixed_variables_only_in_inequalities(block)

Method to return the number of fixed Var components which only appear within activated inequality Constraints in a model.

Parameters:

block – model to be studied

Returns:

Number of fixed Var components which only appear within activated inequality Constraints in block

idaes.core.util.model_statistics.number_large_residuals(block, tol=1e-05)

Method to return the number Constraint components with a residual greater than a given threshold which appear in a model.

Parameters:

• block – model to be studied

• tol – residual threshold for inclusion in ComponentSet

Returns:

Number of Constraint components with a residual greater than tol which appear in block

idaes.core.util.model_statistics.number_total_blocks(block)

Method to return the number of Block components in a model.

Parameters:

block – model to be studied

Returns:

Number of Block components in block (including block itself)

idaes.core.util.model_statistics.number_total_constraints(block)

Method to return the total number of Constraint components in a model.

Parameters:

block – model to be studied

Returns:

Number of Constraint components in block

idaes.core.util.model_statistics.number_total_equalities(block)

Method to return the total number of equality Constraint components in a model.

Parameters:

block – model to be studied

Returns:

Number of equality Constraint components in block

idaes.core.util.model_statistics.number_total_inequalities(block)

Method to return the total number of inequality Constraint components in a model.

Parameters:

block – model to be studied

Returns:

Number of inequality Constraint components in block

idaes.core.util.model_statistics.number_total_objectives(block)

Method to return the number of Objective components which appear in a model

Parameters:

block – model to be studied

Returns:

Number of Objective components which appear in block

idaes.core.util.model_statistics.number_unfixed_variables(block)

Method to return the number of unfixed Var components in a model.

Parameters:

block – model to be studied

Returns:

Number of unfixed Var components in block

idaes.core.util.model_statistics.number_unfixed_variables_in_activated_equalities(block)

Method to return the number of unfixed Var components which appear within activated equality Constraints in a model.

Parameters:

block – model to be studied

Returns:

Number of unfixed Var components which appear within activated equality Constraints in block

idaes.core.util.model_statistics.number_unused_variables(block)

Method to return the number of Var components which do not appear within any activated Constraint in a model.

Parameters:

block – model to be studied

Returns:

Number of Var components which do not appear within any activagted Constraints in block

idaes.core.util.model_statistics.number_variables(block)

Method to return the number of Var components in a model.

Parameters:

block – model to be studied

Returns:

Number of Var components in block

idaes.core.util.model_statistics.number_variables_in_activated_constraints(block)

Method to return the number of Var components that appear within active Constraints in a model.

Parameters:

block – model to be studied

Returns:

Number of Var components which appear within active Constraints in block

idaes.core.util.model_statistics.number_variables_in_activated_equalities(block)

Method to return the number of Var components which appear within activated equality Constraints in a model.

Parameters:

block – model to be studied

Returns:

Number of Var components which appear within activated equality Constraints in block

idaes.core.util.model_statistics.number_variables_in_activated_inequalities(block)

Method to return the number of Var components which appear within activated inequality Constraints in a model.

Parameters:

block – model to be studied

Returns:

Number of Var components which appear within activated inequality Constraints in block

idaes.core.util.model_statistics.number_variables_near_bounds(block, tol=None, abs_tol=0.0001, rel_tol=0.0001)

Method to return the number of all Var components in a model which have a value within tol (relative) of a bound.

Parameters:

• block – model to be studied

• abs_tol – absolute tolerance for inclusion in generator (default = 1e-4)

• rel_tol – relative tolerance for inclusion in generator (default = 1e-4)

Returns:

Number of components block that are close to a bound

idaes.core.util.model_statistics.number_variables_not_in_activated_constraints(block)

Method to return the number of Var components that do not appear within active Constraints in a model.

Parameters:

block – model to be studied

Returns:

Number of Var components which do not appear within active Constraints in block

idaes.core.util.model_statistics.number_variables_only_in_inequalities(block)

Method to return the number of Var components which appear only within activated inequality Constraints in a model.

Parameters:

block – model to be studied

Returns:

Number of Var components which appear only within activated inequality Constraints in block

idaes.core.util.model_statistics.total_blocks_set(block)

Method to return a ComponentSet of all Block components in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all Block components in block (including block itself)

idaes.core.util.model_statistics.total_constraints_set(block)

Method to return a ComponentSet of all Constraint components in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all Constraint components in block

idaes.core.util.model_statistics.total_equalities_generator(block)

Generator which returns all equality Constraint components in a model.

Parameters:

block – model to be studied

Returns:

A generator which returns all equality Constraint components block

idaes.core.util.model_statistics.total_equalities_set(block)

Method to return a ComponentSet of all equality Constraint components in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all equality Constraint components in block

idaes.core.util.model_statistics.total_inequalities_generator(block)

Generator which returns all inequality Constraint components in a model.

Parameters:

block – model to be studied

Returns:

A generator which returns all inequality Constraint components block

idaes.core.util.model_statistics.total_inequalities_set(block)

Method to return a ComponentSet of all inequality Constraint components in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all inequality Constraint components in block

idaes.core.util.model_statistics.total_objectives_generator(block)

Generator which returns all Objective components in a model.

Parameters:

block – model to be studied

Returns:

A generator which returns all Objective components block

idaes.core.util.model_statistics.total_objectives_set(block)

Method to return a ComponentSet of all Objective components which appear in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all Objective components which appear in block

idaes.core.util.model_statistics.unfixed_variables_generator(block)

Generator which returns all unfixed Var components in a model.

Parameters:

block – model to be studied

Returns:

A generator which returns all unfixed Var components block

idaes.core.util.model_statistics.unfixed_variables_in_activated_equalities_set(block)

Method to return a ComponentSet of all unfixed Var components which appear within an activated equality Constraint in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all unfixed Var components which appear within activated equality Constraints in block

idaes.core.util.model_statistics.unfixed_variables_set(block)

Method to return a ComponentSet of all unfixed Var components in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all unfixed Var components in block

idaes.core.util.model_statistics.unused_variables_set(block)

Method to return a ComponentSet of all Var components which do not appear within any activated Constraint in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all Var components which do not appear within any Constraints in block

idaes.core.util.model_statistics.variables_in_activated_constraints_set(block)

Method to return a ComponentSet of all Var components which appear within a Constraint in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all Var components which appear within activated Constraints in block

idaes.core.util.model_statistics.variables_in_activated_equalities_set(block)

Method to return a ComponentSet of all Var components which appear within an equality Constraint in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all Var components which appear within activated equality Constraints in block

idaes.core.util.model_statistics.variables_in_activated_inequalities_set(block)

Method to return a ComponentSet of all Var components which appear within an inequality Constraint in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all Var components which appear within activated inequality Constraints in block

idaes.core.util.model_statistics.variables_near_bounds_generator(block, tol=None, relative=None, skip_lb=False, skip_ub=False, abs_tol=0.0001, rel_tol=0.0001)

Generator which returns all Var components in a model which have a value within tol (default: relative) of a bound.

Parameters:

• block – model to be studied

• abs_tol – absolute tolerance for inclusion in generator (default = 1e-4)

• rel_tol – relative tolerance for inclusion in generator (default = 1e-4)

• skip_lb – Boolean to skip lower bound (default = False)

• skip_ub – Boolean to skip upper bound (default = False)

Returns:

A generator which returns all Var components block that are close to a bound

idaes.core.util.model_statistics.variables_near_bounds_set(block, tol=None, relative=None, skip_lb=False, skip_ub=False, abs_tol=0.0001, rel_tol=0.0001)

Method to return a ComponentSet of all Var components in a model which have a value within tolerance of a bound.

Parameters:

• block – model to be studied

• abs_tol – absolute tolerance for inclusion in generator (default = 1e-4)

• rel_tol – relative tolerance for inclusion in generator (default = 1e-4)

• skip_lb – Boolean to skip lower bound (default = False)

• skip_ub – Boolean to skip upper bound (default = False)

Returns:

A ComponentSet including all Var components block that are close to a bound

idaes.core.util.model_statistics.variables_not_in_activated_constraints_set(block)

Method to return a ComponentSet of all Var components which do not appear within a Constraint in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all Var components which do not appear within activated Constraints in block

idaes.core.util.model_statistics.variables_only_in_inequalities(block)

Method to return a ComponentSet of all Var components which appear only within inequality Constraints in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all Var components which appear only within inequality Constraints in block

idaes.core.util.model_statistics.variables_set(block)

Method to return a ComponentSet of all Var components in a model.

Parameters:

block – model to be studied

Returns:

A ComponentSet including all Var components in block