Diagnostics Toolbox#

The IDAES Diagnostics Toolbox is intended to provide a comprehensive collection of tools for identifying potential modeling issues, and guiding the user through the model diagnosis workflow. For more in-depth discussion of the model diagnosis workflow see the Model Diagnostics Workflow documentation.

class idaes.core.util.model_diagnostics.DiagnosticsToolbox(model, **kwargs)[source]#

The IDAES Model DiagnosticsToolbox.

To get started:

Create an instance of your model (this does not need to be initialized yet).

Fix variables until you have 0 degrees of freedom. Many of these tools presume a square model, and a square model should always be the foundation of any more advanced model.

Create an instance of the DiagnosticsToolbox and provide the model to debug as the model argument.

Call the report_structural_issues() method.

Model diagnostics is an iterative process and you will likely need to run these tools multiple times to resolve all issues. After making a change to your model, you should always start from the beginning again to ensure the change did not introduce any new issues; i.e., always start from the report_structural_issues() method.

Note that structural checks do not require the model to be initialized, thus users should start with these. Numerical checks require at least a partial solution to the model and should only be run once all structural issues have been resolved.

Report methods will print a summary containing three parts:

Warnings - these are critical issues that should be resolved before continuing. For each warning, a method will be suggested in the Next Steps section to get additional information.
Cautions - these are things that could be correct but could also be the source of solver issues. Not all cautions need to be addressed, but users should investigate each one to ensure that the behavior is correct and that they will not be the source of difficulties later. Methods exist to provide more information on all cautions, but these will not appear in the Next Steps section.
Next Steps - these are recommended methods to call from the DiagnosticsToolbox to get further information on warnings. If no warnings are found, this will suggest the next report method to call.

Parameters:

model (_BlockData) – model to be diagnosed. The DiagnosticsToolbox does not support indexed Blocks.

Keyword Arguments:

variable_bounds_absolute_tolerance (float, default=0.0001) – Absolute tolerance for considering a variable to be close to its bounds.
variable_bounds_relative_tolerance (float, default=0.0001) – Relative tolerance for considering a variable to be close to its bounds.
variable_bounds_violation_tolerance (float, default=0) – Absolute tolerance for considering a variable to violate its bounds. Some solvers relax bounds on variables thus allowing a small violation to be considered acceptable.
constraint_residual_tolerance (float, default=1e-05) – Absolute tolerance to use when checking constraint residuals.
variable_large_value_tolerance (float, default=10000.0) – Absolute tolerance for considering a value to be large.
variable_small_value_tolerance (float, default=0.0001) – Absolute tolerance for considering a value to be small.
variable_zero_value_tolerance (float, default=1e-08) – Absolute tolerance for considering a value to be near to zero.
jacobian_large_value_caution (float, default=10000.0) – Tolerance for raising a caution for large Jacobian values.
jacobian_large_value_warning (float, default=100000000.0) – Tolerance for raising a warning for large Jacobian values.
jacobian_small_value_caution (float, default=0.0001) – Tolerance for raising a caution for small Jacobian values.
jacobian_small_value_warning (float, default=1e-08) – Tolerance for raising a warning for small Jacobian values.
warn_for_evaluation_error_at_bounds (bool, default=True) – If False, warnings will not be generated for things like log(x) with x >= 0
parallel_component_tolerance (float, default=0.0001) – Tolerance for identifying near-parallel Jacobian rows/columns

assert_no_numerical_warnings()[source]#

Checks for numerical warnings in the model and raises an AssertionError if any are found.

Raises:: AssertionError if any warnings are identified by numerical analysis. –

assert_no_structural_warnings(ignore_evaluation_errors=False, ignore_unit_consistency=False)[source]#

Checks for structural warnings in the model and raises an AssertionError if any are found.

Parameters:

warnings (ignore_unit_consistency - ignore unit consistency) –
warnings –
ignore_evaluation_errors (bool) –
ignore_unit_consistency (bool) –

Raises:

AssertionError if any warnings are identified by structural analysis. –

display_components_with_inconsistent_units(stream=None)[source]#

Prints a list of all Constraints, Expressions and Objectives in the model with inconsistent units of measurement.

Parameters:: stream – an I/O object to write the list to (default = stdout)
Returns:: None

display_constraints_with_extreme_jacobians(stream=None)[source]#

Prints the constraints associated with rows in the Jacobian with extreme L2 norms. This often indicates poorly scaled constraints.

Tolerances can be set via the DiagnosticsToolbox config.

Parameters:: stream – an I/O object to write the output to (default = stdout)
Returns:: None

display_constraints_with_large_residuals(stream=None)[source]#

Prints a list of Constraints with residuals greater than a specified tolerance. Tolerance can be set in the class configuration options.

Parameters:: stream – an I/O object to write the list to (default = stdout)
Returns:: None

display_external_variables(stream=None)[source]#

Prints a list of variables that appear within activated Constraints in the model but are not contained within the model themselves.

Parameters:: stream – an I/O object to write the list to (default = stdout)
Returns:: None

display_extreme_jacobian_entries(stream=None)[source]#

Prints variables and constraints associated with entries in the Jacobian with extreme values. This can be indicative of poor scaling, especially for isolated terms (e.g. variables which appear only in one term of a single constraint).

Tolerances can be set via the DiagnosticsToolbox config.

Parameters:: stream – an I/O object to write the output to (default = stdout)
Returns:: None

display_near_parallel_constraints(stream=None)[source]#

Display near-parallel (duplicate) constraints in model.

Parameters:: stream – I/O object to write report to (default = stdout)
Returns:: None

display_near_parallel_variables(stream=None)[source]#

Display near-parallel (duplicate) variables in model.

Parameters:: stream – I/O object to write report to (default = stdout)
Returns:: None

display_overconstrained_set(stream=None)[source]#

Prints the variables and constraints in the over-constrained sub-problem from a Dulmage-Mendelsohn partitioning.

This can be used to identify the over-defined part of a model and thus where constraints must be removed or variables unfixed.

Parameters:: stream – an I/O object to write the list to (default = stdout)
Returns:: None

display_potential_evaluation_errors(stream=None)[source]#

Prints constraints that may be prone to evaluation errors (e.g., log of a negative number) based on variable bounds.

Parameters:: stream – an I/O object to write the output to (default = stdout)
Returns:: None

display_underconstrained_set(stream=None)[source]#

Prints the variables and constraints in the under-constrained sub-problem from a Dulmage-Mendelsohn partitioning.

This can be used to identify the under-defined part of a model and thus where additional information (fixed variables or constraints) are required.

Parameters:: stream – an I/O object to write the list to (default = stdout)
Returns:: None

display_unused_variables(stream=None)[source]#

Prints a list of variables that do not appear in any activated Constraints.

Parameters:: stream – an I/O object to write the list to (default = stdout)
Returns:: None

display_variables_at_or_outside_bounds(stream=None)[source]#

Prints a list of variables with values that fall at or outside the bounds on the variable.

Parameters:: stream – an I/O object to write the list to (default = stdout)
Returns:: None

display_variables_fixed_to_zero(stream=None)[source]#

Prints a list of variables that are fixed to an absolute value of 0.

Parameters:: stream – an I/O object to write the list to (default = stdout)
Returns:: None

display_variables_near_bounds(stream=None)[source]#

Prints a list of variables with values close to their bounds. Tolerance can be set in the class configuration options.

Parameters:: stream – an I/O object to write the list to (default = stdout)
Returns:: None

display_variables_with_extreme_jacobians(stream=None)[source]#

Prints the variables associated with columns in the Jacobian with extreme L2 norms. This often indicates poorly scaled variables.

Tolerances can be set via the DiagnosticsToolbox config.

Parameters:: stream – an I/O object to write the output to (default = stdout)
Returns:: None

display_variables_with_extreme_values(stream=None)[source]#

Prints a list of variables with extreme values.

Tolerances can be set in the class configuration options.

Parameters:: stream – an I/O object to write the list to (default = stdout)
Returns:: None

display_variables_with_none_value(stream=None)[source]#

Prints a list of variables with a value of None.

Parameters:: stream – an I/O object to write the list to (default = stdout)
Returns:: None

display_variables_with_value_near_zero(stream=None)[source]#

Prints a list of variables with a value close to zero. The tolerance for determining what is close to zero can be set in the class configuration options.

Parameters:: stream – an I/O object to write the list to (default = stdout)
Returns:: None

get_dulmage_mendelsohn_partition()[source]#

Performs a Dulmage-Mendelsohn partitioning on the model and returns the over- and under-constrained sub-problems.

Returns:: list-of-lists variables in each independent block of the under-constrained set list-of-lists constraints in each independent block of the under-constrained set list-of-lists variables in each independent block of the over-constrained set list-of-lists constraints in each independent block of the over-constrained set

property model#: Model currently being diagnosed.

prepare_degeneracy_hunter(**kwargs)[source]#

Create an instance of the DegeneracyHunter and store as self.degeneracy_hunter.

After creating an instance of the toolbox, call report_irreducible_degenerate_sets.

Returns:

Instance of DegeneracyHunter

Keyword Arguments:

solver (str, default='scip') – MILP solver to use for finding irreducible degenerate sets.
solver_options (optional) – Options to pass to MILP solver.
M (float, default=100000.0) – Maximum value for nu in MILP models.
m_small (float, default=1e-05) – Smallest value for nu to be considered non-zero in MILP models.
trivial_constraint_tolerance (float, default=1e-06) – Tolerance for identifying non-zero rows in Jacobian.

prepare_svd_toolbox(**kwargs)[source]#

Create an instance of the SVDToolbox and store as self.svd_toolbox.

After creating an instance of the toolbox, call display_underdetermined_variables_and_constraints().

Returns:

Instance of SVDToolbox

Keyword Arguments:

number_of_smallest_singular_values (PositiveInt, optional) – Number of smallest singular values to compute
svd_callback (svd_callback_validator, default=<function svd_dense at 0x7fa217de6980>) – Callback to SVD method of choice (default = svd_dense). Callbacks should take the Jacobian and number of singular values to compute as options, plus any method specific arguments, and should return the u, s and v matrices as numpy arrays.
svd_callback_arguments (dict, optional) – Optional arguments to pass to SVD callback (default = None)
singular_value_tolerance (float, default=1e-06) – Tolerance for defining a small singular value
size_cutoff_in_singular_vector (float, default=0.1) – Size below which to ignore constraints and variables in the singular vector

report_numerical_issues(stream=None)[source]#

Generates a summary report of any numerical issues identified in the model provided and suggest next steps for debugging model.

Numerical checks should only be performed once all structural issues have been resolved, and require that at least a partial solution to the model is available.

Parameters:: stream – I/O object to write report to (default = stdout)
Returns:: None

report_structural_issues(stream=None)[source]#

Generates a summary report of any structural issues identified in the model provided and suggests next steps for debugging the model.

This should be the first method called when debugging a model and after any change is made to the model. These checks can be run before trying to initialize and solve the model.

Parameters:: stream – I/O object to write report to (default = stdout)
Returns:: None