From 229c0631066c8a51c7337355404db6fd2d4470b0 Mon Sep 17 00:00:00 2001
From: David Wells <drwells@email.unc.edu>
Date: Thu, 15 Aug 2024 14:41:28 -0600
Subject: [PATCH] Improve our 32-bit vs 64-bit PETSc documentation.

---
 cmake/setup_cached_variables.cmake |  2 +-
 doc/developers/packaging.html      |  3 +--
 doc/external-libs/petsc.html       | 13 +++++++++++++
 doc/readme.html                    |  4 +---
 4 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/cmake/setup_cached_variables.cmake b/cmake/setup_cached_variables.cmake
index 52f9cc27f3..59639a1860 100644
--- a/cmake/setup_cached_variables.cmake
+++ b/cmake/setup_cached_variables.cmake
@@ -331,7 +331,7 @@ unset(ENV{NVCCFLAGS})
 ########################################################################
 
 option(DEAL_II_WITH_64BIT_INDICES
-  "If set to ON, then use 64-bit data types to represent global degree of freedom indices. The default is to OFF. You only want to set this to ON if you will solve problems with more than 2^31 (approximately 2 billion) unknowns. If set to ON, you also need to ensure that both Trilinos and/or PETSc support 64-bit indices."
+  "If set to ON, then use 64-bit data types to represent global degree of freedom indices. The default is to OFF. You only want to set this to ON if you will solve problems with more than 2^31 (approximately 2 billion) unknowns."
   OFF
   )
 list(APPEND DEAL_II_FEATURES 64BIT_INDICES)
diff --git a/doc/developers/packaging.html b/doc/developers/packaging.html
index 0e8db8cdab..f2fd58fc5d 100644
--- a/doc/developers/packaging.html
+++ b/doc/developers/packaging.html
@@ -78,8 +78,7 @@
       </li>
       <li>
         The flag <tt>DEAL_II_WITH_64BIT_INDICES</tt> changes an integral type
-        used for indices in the library. This value should be made consistent
-        with the way PETSc is configured.
+        used for indices in the library.
       </li>
       <li>
         <acronym>deal.II</acronym> includes copies of boost, Kokkos, muParser, TBB, and
diff --git a/doc/external-libs/petsc.html b/doc/external-libs/petsc.html
index 8f8064b8f7..d55206d590 100644
--- a/doc/external-libs/petsc.html
+++ b/doc/external-libs/petsc.html
@@ -102,6 +102,19 @@
       another way, installing PETSc with the flag <code>--download-mpich</code>
       often causes problems (such as linking errors or poor performance)
       that may be avoided by using whatever your system provides instead.
+
+      If you want to solve problems which have more than two billion unknowns
+      with PETSc then you should also pass the
+      <code>--with-64-bit-indices=on</code> flag to <code>configure.py</code>.
+      You will also want to configure deal.II with 64-bit indices by
+      providing <code>-DDEAL_II_WITH_64BIT_INDICES=ON</code> to deal.II's cmake
+      configuration run. deal.II will throw an exception if it cannot
+      successfully convert indices between the two libraries, but, as long
+      as the supported index ranges overlap (e.g., when solving problems with
+      less than 2 billion degrees of freedom where either PETSc or deal.II uses
+      32-bit indices and the other uses 64-bit indices) all solvers will work
+      correctly.
+
       <br>
       Now let PETSc check his own sanity:
       <pre>
diff --git a/doc/readme.html b/doc/readme.html
index bf2b5e2d3c..3cb2cfb71b 100644
--- a/doc/readme.html
+++ b/doc/readme.html
@@ -357,9 +357,7 @@
                 cells or unknowns to approximately four billions. If
                 larger problem must be solved, pass the
                 <code>-DDEAL_II_WITH_64BIT_INDICES=ON</code> argument to
-                <code>cmake</code>. To use this option with
-                PETSc, PETSc must be compiled
-                with the option <code>--with-64-bit-indices</code>.
+                <code>cmake</code>.
             </p>
         </li>
     </ul>
-- 
2.39.5