Rename SVDToolbox to JacobianAnalysisToolbox

[andrewlee94]

Fixes None

Summary/Motivation:

In preparation for adding some additional diagnostics tools, this PR renamed the SVDToolbox to the more generic JacobianAnalysisToolbox. Seeing as the SVDToolbox was added after the v2.2 release, this should not cause any backward compatibility issues.

Examples tests will fail until IDAES/examples#82 is merged.

Changes proposed in this PR:

• Rename SVDToolbox
• Update docs accordingly
• Fix a minor bug in Degeneracy Hunter related to avoid an edge case with trivial constraints.

Legal Acknowledgement

By contributing to this software project, I agree to the following terms and conditions for my contribution:

1. I agree my contributions are submitted under the license terms described in the LICENSE.txt file at the top level of this directory.
2. I represent I am authorized to make the contributions and grant the license. If my employer has rights to intellectual property that includes these contributions, I represent that I have received permission to make contributions and grant the required license on behalf of that employer.

[codecov]

Codecov Report

Attention: 4 lines in your changes are missing coverage. Please review.

Comparison is base (41bb3c9) 77.41% compared to head (c41bab2) 77.40%.

Files	Patch %	Lines
idaes/core/util/model_diagnostics.py	73.33%	3 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1297      +/-   ##
==========================================
- Coverage   77.41%   77.40%   -0.01%     
==========================================
  Files         390      390              
  Lines       63402    63404       +2     
  Branches    11658    11659       +1     
==========================================
- Hits        49080    49077       -3     
- Misses      11793    11798       +5     
  Partials     2529     2529              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[Robbybp]

I think this name might be general enough to be somewhat confusing. DiagnosticsToolbox already does a significant amount of Jacobian analysis. Also, my interpretation of the purpose of SVDToolbox is to cache the result of the SVD, then call useful methods on it. I worry that if we turn it into a general Jacobian analysis toolbox, we will end up with too much state to easily keep track of. Additionally, we may run into conflicting method definitions. For instance, if we add a QR factorization method, then display_rank_of_equality_constraints will need to decide whether to use the result of SVD or the result of QR.

If we go the route of a general Jacobian analysis toolbox, I would like to start with a well-defined idea of what we are caching and how we specify the method to use for a particular analysis.

[andrewlee94]

@Robbybp Would your suggestion be to leave this as-is and put the new ill-conditioning tools into DiagnosticsToolbox then?

[dallan-keylogic]

@Robbybp It'd be my preference that the Jacobian analysis tools in the normal diagnostics toolbox get merged over here, rather than the other way around. Some example workflow ended up in my FOCAPD paper, where you determine that something is a problematic Var using the DiagnosticsToolbox then you have to use the SVDToolbox to figure out which Constraints it appears in. The other option is adding those methods to the normal diagnostics toolbox.

[Robbybp]

@Robbybp Would your suggestion be to leave this as-is and put the new ill-conditioning tools into DiagnosticsToolbox then?

That is my current recommendation, at least for the parallel row/col identifier. There is nothing that stops us from adding JacobianAnalysisToolbox later as a pure addition if we want a single class that is in charge of caching expensive linear algebra operations.

I am less confident about what to do with the optimization-based analysis tool. I still think this is very similar to Degeneracy Hunter:

• Both solve optimization problems where the result is a vector of weights that prove (almost) linear dependence
• Degeneracy Hunter minimizes the 0-norm of the weight vector. Whereas the ModelAnalyzer tool minimizes the parameter that relaxes the linear dependence constraint, with an option to add a 1-norm penalty to the objective as regularization.
• Degeneracy Hunter normalizes with y[i].fix(1), while ModelAnalyzer normalizes with sum(y[:]) == 1 (or maybe it enforces that the 1-norm is 1, I forget).

I think the right option medium-term is probably to combine these into a more general formulation, so we don't have multiple LP/MIP-based ill-conditioning/degeneracy analyzers lying around. For now I think I advocating putting the analyzer into a stand-alone function.

[Robbybp]

@Robbybp It'd be my preference that the Jacobian analysis tools in the normal diagnostics toolbox get merged over here, rather than the other way around. Some example workflow ended up in my FOCAPD paper, where you determine that something is a problematic Var using the DiagnosticsToolbox then you have to use the SVDToolbox to figure out which Constraints it appears in. The other option is adding those methods to the normal diagnostics toolbox.

I would like to keep as much functionality accessible from the main DiagnosticsToolbox as possible. The barriers to adding SVD to DiagnosticsToolbox are the same as those to expanding SVD: keeping track of state and method selection when something can be done multiple ways (e.g. checking rank). Neither of these are insurmountable.

Our current approach is something like:

dt = DiagnosticsToolbox(m)
dt.report_numeric_issues()
dt.prepare_svd_toolbox()
dt.svd_toolbox.get_rank_of_equality_constraints()

which I think is not bad.

[bknueven]

I am less confident about what to do with the optimization-based analysis tool. I still think this is very similar to Degeneracy Hunter:

* Both solve optimization problems where the result is a vector of weights that prove (almost) linear dependence

* Degeneracy Hunter minimizes the 0-norm of the weight vector. Whereas the ModelAnalyzer tool minimizes the parameter that relaxes the linear dependence constraint, with an option to add a 1-norm penalty to the objective as regularization.

* Degeneracy Hunter normalizes with `y[i].fix(1)`, while ModelAnalyzer normalizes with `sum(y[:]) == 1` (or maybe it enforces that the 1-norm is 1, I forget).

I think the right option medium-term is probably to combine these into a more general formulation, so we don't have multiple LP/MIP-based ill-conditioning/degeneracy analyzers lying around. For now I think I advocating putting the analyzer into a stand-alone function.

I agree - I think the ModelAnalyzer should eventually be rolled into Degeneracy Hunter. ModelAnalyzer uses a LASSO approach as compared to Degeneracy Hunter's best subset selection approach.

For very degenerate problems I think the ModelAnalzyer could benefit from an implementation which is more integrated with a specific LP code. In either case the LP or MIP ends up sharing some of the same issues as the original NLP.

[andrewlee94]

@Robbybp @bknueven I'll close this PR as unneeded then.