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
- 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:
- 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:
- 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)
- 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
andnlp
arguments may be provided if they are already available. If these are provided, the provided model is not used. If eitherjac
ornlp
is not provided, a Jacobian andPyomoNLP
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:
- 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:
- 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