Diagnostics Toolbox

Contents

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:

  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 (NonNegativeFloat, default=0.0001) – Absolute tolerance for considering a variable to be close to its bounds.

  • variable_bounds_relative_tolerance (NonNegativeFloat, default=0.0001) – Relative tolerance for considering a variable to be close to its bounds.

  • variable_bounds_violation_tolerance (NonNegativeFloat, 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 (NonNegativeFloat, default=1e-05) – Absolute tolerance to use when checking constraint residuals.

  • constraint_term_mismatch_tolerance (NonNegativeFloat, default=1000000.0) – Magnitude difference to use when checking for mismatched additive terms in constraints.

  • constraint_term_cancellation_tolerance (NonNegativeFloat, default=0.0001) – Absolute tolerance to use when checking for canceling additive terms in constraints.

  • max_canceling_terms (NonNegativeInt, default=5) – Maximum number of terms to consider when looking for canceling combinations in expressions.

  • constraint_term_zero_tolerance (NonNegativeFloat, default=1e-10) – Absolute tolerance to use when determining if a constraint term is equal to zero.

  • variable_large_value_tolerance (NonNegativeFloat, default=10000.0) – Absolute tolerance for considering a value to be large.

  • variable_small_value_tolerance (NonNegativeFloat, default=0.0001) – Absolute tolerance for considering a value to be small.

  • variable_zero_value_tolerance (NonNegativeFloat, default=1e-08) – Absolute tolerance for considering a value to be near to zero.

  • jacobian_large_value_caution (NonNegativeFloat, default=10000.0) – Tolerance for raising a caution for large Jacobian values.

  • jacobian_large_value_warning (NonNegativeFloat, default=100000000.0) – Tolerance for raising a warning for large Jacobian values.

  • jacobian_small_value_caution (NonNegativeFloat, default=0.0001) – Tolerance for raising a caution for small Jacobian values.

  • jacobian_small_value_warning (NonNegativeFloat, 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 (NonNegativeFloat, default=1e-08) – Tolerance for identifying near-parallel Jacobian rows/columns

  • absolute_feasibility_tolerance (NonNegativeFloat, default=1e-06) – Feasibility tolerance for identifying infeasible constraints and bounds

assert_no_numerical_warnings(ignore_parallel_components=False)[source]#

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

Parameters:

components (ignore_parallel_components - ignore checks for parallel)

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

compute_infeasibility_explanation(stream=None, solver=None, tee=False)[source]#

This function attempts to determine why a given model is infeasible. It deploys two main algorithms:

  1. Relaxes the constraints of the problem, and reports to the user some sets of constraints and variable bounds, which when relaxed, creates a feasible model.

  2. Uses the information collected from (1) to attempt to compute a Minimal Infeasible System (MIS), which is a set of constraints and variable bounds which appear to be in conflict with each other. It is minimal in the sense that removing any single constraint or variable bound would result in a feasible subsystem.

Parameters:

  • stream – I/O object to write report to (default = stdout)

  • solver – A pyomo solver object or a string for SolverFactory (default = get_solver())

  • tee – Display intermediate solves conducted (False)

Returns:

None

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_canceling_terms(stream=None)[source]#

Display constraints in model which contain additive terms which potentially cancel each other.

Note that this method looks a the current state of the constraint, and will flag terms as cancelling if you have a form A == B + C where C is significantly smaller than A and B. In some cases this behavior is intended, as C is a correction term which happens to be very small at the current state. However, you should review these constraints to determine whether the correction term is important for the situation you are modeling and consider removing the term if it will never be significant.

Parameters:

stream – I/O object to write report 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_constraints_with_mismatched_terms(stream=None)[source]#

Display constraints in model which contain additive terms of significantly different magnitude.

Parameters:

stream – I/O object to write report to (default = stdout)

Returns:

None

display_constraints_with_no_free_variables(stream=None)[source]#

Display constraints in model which contain no free variables.

Parameters:

stream – I/O object to write report 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_problematic_constraint_terms(constraint, max_cancellations=5, stream=None)[source]#

Display a summary of potentially problematic terms in a given constraint.

Note that this method looks a the current state of the constraint, and will flag terms as cancelling if you have a form A == B + C where C is significantly smaller than A and B. In some cases this behavior is intended, as C is a correction term which happens to be very small at the current state. However, you should review these constraints to determine whether the correction term is important for the situation you are modeling and consider removing the term if it will never be significant.

Parameters:

  • constraint – ConstraintData object to be examined

  • max_cancellations (int) – maximum number of cancellations per node before termination. None = find all cancellations.

  • stream – I/O object to write report 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 (NonNegativeFloat, default=100000.0) – Maximum value for nu in MILP models.

  • m_small (NonNegativeFloat, default=1e-05) – Smallest value for nu to be considered non-zero in MILP models.

  • trivial_constraint_tolerance (NonNegativeFloat, 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 0x7fa0fa11e8e0>) – 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 (NonNegativeFloat, default=1e-06) – Tolerance for defining a small singular value

  • size_cutoff_in_singular_vector (NonNegativeFloat, 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

Contents