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)

The IDAES Model DiagnosticsToolbox.

To get started:

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

2. 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.

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

4. 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:

1. 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.

2. 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.

3. 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.

assert_no_numerical_warnings()

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

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

Raises

AssertionError if any warnings are identified by structural analysis. –

display_components_with_inconsistent_units(stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

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=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

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=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

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=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

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=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

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_overconstrained_set(stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

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_underconstrained_set(stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

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=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

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=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

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=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

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=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

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=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

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=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

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=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

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=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

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

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.

report_numerical_issues(stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

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=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

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