Model Diagnostic Functions

Model Diagnostic Functions#

The IDAES toolset contains a number of utility functions which can be useful for identifying modeling issues and debugging solver issues.

Other Methods#

This module contains a collection of tools for diagnosing modeling issues.

class idaes.core.util.model_diagnostics.ConstraintTermAnalysisVisitor(term_mismatch_tolerance=1000000.0, term_cancellation_tolerance=0.0001, term_zero_tolerance=1e-10, max_canceling_terms=4, max_cancellations_per_node=5)[source]#

Expression walker for checking Constraints for problematic terms.

This walker will walk the expression and look for summation terms with mismatched magnitudes or potential cancellations.

Parameters:

  • term_mismatch_tolerance (float) – tolerance to use when determining mismatched terms

  • term_cancellation_tolerance (float) – tolerance to use when identifying possible cancellation of terms

  • term_zero_tolerance (float) – tolerance for considering terms equal to zero

  • max_canceling_terms (int) – maximum number of terms to consider when looking for canceling combinations (None = consider all possible combinations)

  • max_cancellations_per_node (int) – maximum number of cancellations to collect for a single node. Collection will terminate when this many cancellations have been identified (None = collect all cancellations)

Returns:

list of values for top-level summation terms list of terms with mismatched magnitudes list of terms with potential cancellations bool indicating whether expression is a constant

exitNode(node, data)[source]#

Method to call when exiting node to check for potential issues.

walk_expression(expr)[source]#

Main method to call to walk an expression and return analysis.

Parameters:

analyzed (expr - expression to be)

Returns:

list of values of top-level additive terms ComponentSet containing any mismatched terms ComponentSet containing any canceling terms Bool indicating whether expression is a constant

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

Tool to perform a parameter sweep of model checking for numerical issues and convergence characteristics. Users may specify an IDAES ParameterSweep class to perform the sweep (default is SequentialSweepRunner).

assert_baseline_comparison(filename, rel_tol=0.1, abs_tol=1)[source]#

Run convergence analysis and assert no differences in results to those defined in baseline file.

Parameters:

  • filename (str) – name of baseline file to load specification from as string

  • rel_tol (float) – relative tolerance to use for comparing number of iterations

  • abs_tol (float) – absolute tolerance to use for comparing number of iterations

Raises:

AssertionError if results of convergence analysis do not match baseline –

compare_convergence_to_baseline(filename, rel_tol=0.1, abs_tol=1)[source]#

Run convergence analysis and compare results to those defined in baseline file.

Parameters:

  • filename (str) – name of baseline file to load specification from as string

  • rel_tol (float) – relative tolerance to use for comparing number of iterations

  • abs_tol (float) – absolute tolerance to use for comparing number of iterations

Returns:

dict containing lists of differences between convergence analysis run and baseline

from_dict(input_dict)[source]#

Load specification and results from dict.

Parameters:

input_dict – dict to load from

Returns:

None

from_json_file(filename)[source]#

Load specification and results from json file.

Parameters:

filename – name of file to load from as string

Returns:

None

report_convergence_summary(stream=None)[source]#

Reports a brief summary of the model convergence run.

Parameters:

stream – Optional output stream to print results to.

Returns:

None

property results#

Returns the results of the IpoptConvergenceAnalysis run

run_convergence_analysis()[source]#

Execute convergence analysis sweep by calling execute_parameter_sweep method in specified runner.

Returns:

dict of results from parameter sweep

run_convergence_analysis_from_dict(input_dict)[source]#

Execute convergence analysis sweep using specification defined in dict.

Parameters:

input_dict (dict) – dict to load specification from

Returns:

dict of results from parameter sweep

run_convergence_analysis_from_file(filename)[source]#

Execute convergence analysis sweep using specification defined in json file.

Parameters:

filename (str) – name of file to load specification from as string

Returns:

dict of results from parameter sweep

property samples#

Returns the set of input samples for convergence analysis (pandas DataFrame)

to_dict()[source]#

Serialize specification and current results to dict form

Returns:

dict

to_json_file(filename)[source]#

Write specification and results to json file.

Parameters:

filename – name of file to write to as string

Returns:

None

idaes.core.util.model_diagnostics.check_parallel_jacobian(model, tolerance=0.0001, direction='row', jac=None, nlp=None)[source]#

Check for near-parallel rows or columns in the Jacobian.

Near-parallel rows or columns indicate a potential degeneracy in the model, as this means that the associated constraints or variables are (near) duplicates of each other.

For efficiency, the jac and nlp arguments may be provided if they are already available. If these are provided, the provided model is not used. If either jac or nlp is not provided, a Jacobian and PyomoNLP are computed using the model.

This method is based on work published in:

Klotz, E., Identification, Assessment, and Correction of Ill-Conditioning and Numerical Instability in Linear and Integer Programs, Informs 2014, pgs. 54-108 https://pubsonline.informs.org/doi/epdf/10.1287/educ.2014.0130

Parameters:

  • model – model to be analysed

  • tolerance (float) – tolerance to use to determine if constraints/variables are parallel

  • direction (str) – ‘row’ (default, constraints) or ‘column’ (variables)

  • jac – model Jacobian as a scipy.sparse.coo_matrix, optional

  • nlp – PyomoNLP of model, optional

Returns:

list of 2-tuples containing parallel Pyomo components

idaes.core.util.model_diagnostics.compute_ill_conditioning_certificate(model, target_feasibility_tol=1e-06, ratio_cutoff=0.0001, direction='row')[source]#

Finds constraints (rows) or variables (columns) in the model Jacobian that may be contributing to ill conditioning.

This method is based on work published in:

Klotz, E., Identification, Assessment, and Correction of Ill-Conditioning and Numerical Instability in Linear and Integer Programs, Informs 2014, pgs. 54-108 https://pubsonline.informs.org/doi/epdf/10.1287/educ.2014.0130

Parameters:

  • model – model to be analysed

  • target_feasibility_tol (float) – target tolerance for solving ill conditioning problem

  • ratio_cutoff (float) – cut-off for reporting ill conditioning

  • direction (str) – ‘row’ (default, constraints) or ‘column’ (variables)

Returns:

list of strings reporting ill-conditioned variables/constraints and their associated y values

idaes.core.util.model_diagnostics.get_valid_range_of_component(component)[source]#

Return the valid range for a component as specified in the model metadata.

Parameters:

component – Pyomo component to get valid range for

Returns:

valid range for component if found. This will either be a 2-tuple (low, high) or None.

Raises:

AttributeError if metadata object not found –

idaes.core.util.model_diagnostics.ipopt_solve_halt_on_error(model, options=None)[source]#

Run IPOPT to solve model with debugging output enabled.

This function calls IPOPT to solve the model provided with settings to halt on AMPL evaluation errors and report these with symbolic names.

Parameters:

  • model – Pyomo model to be solved.

  • options – solver options to be passed to IPOPT

Returns:

Pyomo solver results dict

idaes.core.util.model_diagnostics.list_components_with_values_outside_valid_range(component, descend_into=True)[source]#

Return a list of component objects with values outside the valid range specified in the model metadata.

This function will iterate over component data objects in Blocks and indexed components.

Parameters:

  • component – Pyomo component to search for component outside of range on. This can be a Block, Var or Param.

  • descend_into – (optional) Whether to descend into components on child Blocks (default=True)

Returns:

list of component objects found with values outside the valid range.

idaes.core.util.model_diagnostics.psweep_runner_validator(val)[source]#

Domain validator for Parameter Sweep runners

Parameters:

val – value to be checked

Returns:

TypeError if val is not a valid callback

idaes.core.util.model_diagnostics.set_bounds_from_valid_range(component, descend_into=True)[source]#

Set bounds on Pyomo components based on valid range recorded in model metadata. WARNING - this function will overwrite any bounds already set on the component/model.

This function will iterate over component data objects in Blocks and indexed components.

Parameters:

  • component – Pyomo component to set bounds on. This can be a Block, Var or Param.

  • descend_into – (optional) Whether to descend into components on child Blocks (default=True)

Returns:

None

idaes.core.util.model_diagnostics.svd_callback_validator(val)[source]#

Domain validator for SVD callbacks

Parameters:

val – value to be checked

Returns:

TypeError if val is not a valid callback