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.
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)[source]¶
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 PyomoComponentSet
containing all components which meet a given criteria. These methods are useful for determining where a problem may exist, as theComponentSet
indicates which components may be causing a problem.Generator methods (end with
_generator
) contain Pythongenerators
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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