From 34d942d2c1ea980104a12c5ad8c9b25b662936f8 Mon Sep 17 00:00:00 2001
From: Andrew Lee <andrew.lee@netl.doe.gov>
Date: Fri, 8 Dec 2023 11:08:49 -0500
Subject: [PATCH] Adding acknowledgements and test for ok reports

---
 idaes/core/util/model_diagnostics.py          | 18 ++++
 .../core/util/tests/test_model_diagnostics.py | 96 +++++++++++++++++++
 2 files changed, 114 insertions(+)

diff --git a/idaes/core/util/model_diagnostics.py b/idaes/core/util/model_diagnostics.py
index 088d01aceb..0d6e5f3991 100644
--- a/idaes/core/util/model_diagnostics.py
+++ b/idaes/core/util/model_diagnostics.py
@@ -3136,6 +3136,15 @@ def check_parallel_jacobian(model, tolerance: float = 1e-4, direction: str = "ro
     as this means that the associated constraints or variables are (near)
     duplicates of each other.
 
+    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
+
+    We would also like to acknowledge Gurobi Model Analyzer for their implementation
+    of these methods (https://github.com/Gurobi/gurobi-modelanalyzer).
+
     Args:
         model: model to be analysed
         tolerance: tolerance to use to determine if constraints/variables are parallel
@@ -3214,6 +3223,15 @@ def check_ill_conditioning(
     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
+
+    We would also like to acknowledge Gurobi Model Analyzer for their implementation
+    of these methods (https://github.com/Gurobi/gurobi-modelanalyzer).
+
     Args:
         model: model to be analysed
         target_feasibility_tol: target tolerance for solving ill conditioning problem
diff --git a/idaes/core/util/tests/test_model_diagnostics.py b/idaes/core/util/tests/test_model_diagnostics.py
index 178d973082..26fc18f5d2 100644
--- a/idaes/core/util/tests/test_model_diagnostics.py
+++ b/idaes/core/util/tests/test_model_diagnostics.py
@@ -1231,6 +1231,102 @@ def test_report_structural_issues(self, model):
 
     display_components_with_inconsistent_units()
 
+====================================================================================
+"""
+
+        assert stream.getvalue() == expected
+
+    @pytest.mark.component
+    def test_report_structural_issues_ok(self):
+        m = ConcreteModel()
+
+        m.v1 = Var(initialize=1)
+        m.v2 = Var(initialize=2)
+        m.v3 = Var(initialize=3)
+
+        m.c1 = Constraint(expr=2 * m.v1 == m.v2)
+        m.c2 = Constraint(expr=m.v1 + m.v2 == m.v3)
+        m.c3 = Constraint(expr=m.v1 == 1)
+
+        dt = DiagnosticsToolbox(model=m)
+
+        stream = StringIO()
+        dt.report_structural_issues(stream)
+
+        expected = """====================================================================================
+Model Statistics
+
+        Activated Blocks: 1 (Deactivated: 0)
+        Free Variables in Activated Constraints: 3 (External: 0)
+            Free Variables with only lower bounds: 0
+            Free Variables with only upper bounds: 0
+            Free Variables with upper and lower bounds: 0
+        Fixed Variables in Activated Constraints: 0 (External: 0)
+        Activated Equality Constraints: 3 (Deactivated: 0)
+        Activated Inequality Constraints: 0 (Deactivated: 0)
+        Activated Objectives: 0 (Deactivated: 0)
+
+------------------------------------------------------------------------------------
+0 WARNINGS
+
+    No warnings found!
+
+------------------------------------------------------------------------------------
+0 Cautions
+
+    No cautions found!
+
+------------------------------------------------------------------------------------
+Suggested next steps:
+
+    Try to initialize/solve your model and then call report_numerical_issues()
+
+====================================================================================
+"""
+
+        assert stream.getvalue() == expected
+
+    @pytest.mark.component
+    def test_report_numerical_issues_ok(self):
+        m = ConcreteModel()
+
+        m.v1 = Var(initialize=1)
+        m.v2 = Var(initialize=2)
+        m.v3 = Var(initialize=3)
+
+        m.c1 = Constraint(expr=2 * m.v1 == m.v2)
+        m.c2 = Constraint(expr=m.v1 + m.v2 == m.v3)
+        m.c3 = Constraint(expr=m.v1 == 1)
+
+        dt = DiagnosticsToolbox(model=m)
+
+        stream = StringIO()
+        dt.report_numerical_issues(stream)
+
+        expected = """====================================================================================
+Model Statistics
+
+    Jacobian Condition Number: 1.237E+01
+
+------------------------------------------------------------------------------------
+0 WARNINGS
+
+    No warnings found!
+
+------------------------------------------------------------------------------------
+0 Cautions
+
+    No cautions found!
+
+------------------------------------------------------------------------------------
+Suggested next steps:
+
+    If you still have issues converging your model consider:
+        display_near_parallel_constraints()
+        display_near_parallel_variables()
+        prepare_degeneracy_hunter()
+        prepare_svd_toolbox()
+
 ====================================================================================
 """