Merge pull request #434 from DrTimothyAldenDavis/dev2

add comment about UMFPACK strategy
DrTimothyAldenDavis · Oct 8, 2023 · c30a408 · c30a408
2 parents a68ff27 + 13a7859
commit c30a408
Show file tree

Hide file tree

Showing 6 changed files with 28 additions and 4 deletions.
diff --git a/UMFPACK/Config/umfpack.h.in b/UMFPACK/Config/umfpack.h.in
@@ -568,7 +568,13 @@ Arguments:
 
         Control [UMFPACK_STRATEGY]:  This is the most important control
             parameter.  It determines what kind of ordering and pivoting
-            strategy that UMFPACK should use.  There are 4 options:
+            strategy that UMFPACK should use.
+
+            NOTE: the interaction of numerical and fill-reducing pivoting is
+            a delicate balance, and a perfect hueristic is not possible because
+            sparsity-preserving pivoting is an NP-hard problem.  Selecting the
+            wrong strategy can lead to catastrophic fill-in and/or numerical
+            inaccuracy.
 
             UMFPACK_STRATEGY_AUTO:  This is the default.  The input matrix is
                 analyzed to determine how symmetric the nonzero pattern is, and

diff --git a/UMFPACK/Doc/UMFPACK_QuickStart.pdf b/UMFPACK/Doc/UMFPACK_QuickStart.pdf
diff --git a/UMFPACK/Doc/UMFPACK_QuickStart.tex b/UMFPACK/Doc/UMFPACK_QuickStart.tex
@@ -494,7 +494,13 @@ \subsection{umfpack\_di\_symbolic}
 
         Control [UMFPACK_STRATEGY]:  This is the most important control
             parameter.  It determines what kind of ordering and pivoting
-            strategy that UMFPACK should use.  There are 4 options:
+            strategy that UMFPACK should use.
+
+            NOTE: the interaction of numerical and fill-reducing pivoting is
+            a delicate balance, and a perfect hueristic is not possible because
+            sparsity-preserving pivoting is an NP-hard problem.  Selecting the
+            wrong strategy can lead to catastrophic fill-in and/or numerical
+            inaccuracy.
 
             UMFPACK_STRATEGY_AUTO:  This is the default.  The input matrix is
                 analyzed to determine how symmetric the nonzero pattern is, and

diff --git a/UMFPACK/Doc/UMFPACK_UserGuide.pdf b/UMFPACK/Doc/UMFPACK_UserGuide.pdf
diff --git a/UMFPACK/Doc/UMFPACK_UserGuide.tex b/UMFPACK/Doc/UMFPACK_UserGuide.tex
@@ -2534,7 +2534,13 @@ \subsection{umfpack\_*\_symbolic}
 
         Control [UMFPACK_STRATEGY]:  This is the most important control
             parameter.  It determines what kind of ordering and pivoting
-            strategy that UMFPACK should use.  There are 4 options:
+            strategy that UMFPACK should use.
+
+            NOTE: the interaction of numerical and fill-reducing pivoting is
+            a delicate balance, and a perfect hueristic is not possible because
+            sparsity-preserving pivoting is an NP-hard problem.  Selecting the
+            wrong strategy can lead to catastrophic fill-in and/or numerical
+            inaccuracy.
 
             UMFPACK_STRATEGY_AUTO:  This is the default.  The input matrix is
                 analyzed to determine how symmetric the nonzero pattern is, and

diff --git a/UMFPACK/Include/umfpack.h b/UMFPACK/Include/umfpack.h
@@ -568,7 +568,13 @@ packed complex Syntax:
 
         Control [UMFPACK_STRATEGY]:  This is the most important control
             parameter.  It determines what kind of ordering and pivoting
-            strategy that UMFPACK should use.  There are 4 options:
+            strategy that UMFPACK should use.
+
+            NOTE: the interaction of numerical and fill-reducing pivoting is
+            a delicate balance, and a perfect hueristic is not possible because
+            sparsity-preserving pivoting is an NP-hard problem.  Selecting the
+            wrong strategy can lead to catastrophic fill-in and/or numerical
+            inaccuracy.
 
             UMFPACK_STRATEGY_AUTO:  This is the default.  The input matrix is
                 analyzed to determine how symmetric the nonzero pattern is, and