From c519a5c49c181327f3a8616e517a095cc7f85ec6 Mon Sep 17 00:00:00 2001
From: bangerth <bangerth@0785d39b-7218-0410-832d-ea1e28bc413d>
Date: Mon, 14 Oct 2013 12:19:27 +0000
Subject: [PATCH] Clarify a couple of items.

git-svn-id: https://svn.dealii.org/trunk@31224 0785d39b-7218-0410-832d-ea1e28bc413d
---
 .../doc/doxygen/headers/global_dof_index.h    | 44 +++++++++++++------
 deal.II/include/deal.II/base/types.h          |  3 ++
 2 files changed, 34 insertions(+), 13 deletions(-)

diff --git a/deal.II/doc/doxygen/headers/global_dof_index.h b/deal.II/doc/doxygen/headers/global_dof_index.h
index 51ebce36d7..2b5d84bddd 100644
--- a/deal.II/doc/doxygen/headers/global_dof_index.h
+++ b/deal.II/doc/doxygen/headers/global_dof_index.h
@@ -18,10 +18,22 @@
 /**
  * @page GlobalDoFIndex When to use types::global_dof_index instead of unsigned int
  *
- * When the 64-bits version of deal.II is used, it becomes necessary to
- * declare as types::global_dof_index (unsigned long long int) instead of
- * unsigned int. Here, we want to clarify when types::global_dof_index must be
- * used.
+ * deal.II can be configured to use 64-bit indices for degrees of freedom,
+ * rather than the usual unsigned integers that default to 32-bit on most
+ * current systems. This is necessary since we want to be able to solve
+ * problems with more than 4 billion unknowns (the limit of what can be
+ * represented with 32-bit unsigned integers). At the same time, we do not
+ * want to indiscriminately replace all integers in deal.II with 64-bit
+ * versions, since this would increase memory use in many places where we
+ * represent quantities that will most definitely not be larger than 4 billion.
+ *
+ * The data type we define for these indices to keep the bulk
+ * of the code base free of <code>#ifdef</code>s is types::global_dof_index.
+ * If deal.II is configured as normal, this type is <code>unsigned int</code>,
+ * but can be switched to <code>unsigned long long int</code> if the right
+ * flag is provided (see the ReadMe file). This page is intended to clarify
+ * when types::global_dof_index must be used and when one can use a regular
+ * unsigned integer:
  *
  * <dl>
  *
@@ -35,15 +47,18 @@
  *
  * <dt class="glossary">@anchor GlobalDoFIndexCell <b>Cell</b></dt>
  * <dd>
- * The ID of cell is not unique. Cells with different levels of refinement
+ * The ID of cell is not unique: Cells with different levels of refinement
  * and/or on different processors can have the same ID. Thus, all the data
- * associated to cells can be unsigned int.
+ * associated to cells can be unsigned int because on a single processor,
+ * one one mesh level, there will definitely not be more than 4 billion
+ * cells.
  * </dd>
  *
  * <dt class="glossary">@anchor GlobalDoFIndexDoFHandler
  * <b>DoFHandler</b></dt>
  * <dd>
- * The ID of each degree of freedom is unique. Therefore, degrees of freedom
+ * The ID of each degree of freedom is unique in a parallel computation.
+ * Therefore, degrees of freedom
  * are types::global_dof_index.
  * </dd>
  *
@@ -52,7 +67,8 @@
  * <dd>
  * The numbers of row and column are types::global_dof_index even if it is not
  * expected that someone will create a FullMatrix with so many entries.
- * However, ConstraintMatrix is templated on the matrix type and thus, the
+ * However, some functions of ConstraintMatrix are templated on the matrix
+ * type and thus, the
  * size of a FullMatrix has to be of the same type than the size of
  * SparseMatrix.
  * </dd>
@@ -60,11 +76,13 @@
  * <dt class="glossary">@anchor GlobalDoFIndexSparseMatrix
  * <b>SparseMatrix</b></dt>
  * <dd>
- * The size of SparseMatrix can be arbitrary large therefore,
- * types::global_do_index is used. However, even for a large complex problem we
- * can solve now, there is no reason for the number of non-zero entries in a 
- * sparse matrix to go over four billions. Thus, we still use unsigned int
- * for, e.g., row_lengths in the object.
+ * The size of SparseMatrix can be arbitrary large and it is conceivable that
+ * with sufficient memory on a single node, one may generate a matrix with
+ * more than 4 billion rows or columns. Therefore, types::global_dof_index is
+ * used. However, even for a large complex problem we can solve now, it is not
+ * reasonable to expect the number of non-zero entries in a sparse matrix to
+ * go over four billion. Thus, we still use unsigned int for, e.g.,
+ * SparsityPattern::row_lengths and similar functions.
  * </dd>
  *
  * </dl>
diff --git a/deal.II/include/deal.II/base/types.h b/deal.II/include/deal.II/base/types.h
index c01ec8609d..7d873a7e5e 100644
--- a/deal.II/include/deal.II/base/types.h
+++ b/deal.II/include/deal.II/base/types.h
@@ -70,6 +70,9 @@ namespace types
    *
    * The data type always indicates an
    * unsigned integer type.
+   *
+   * See the @ref GlobalDoFIndex page for guidance on when this
+   * type should or should not be used.
    */
   // TODO: we should check that unsigned long long int
   // has the same size as uint64_t
-- 
2.39.5