From: bangerth Date: Mon, 14 Oct 2013 12:19:27 +0000 (+0000) Subject: Clarify a couple of items. X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c519a5c49c181327f3a8616e517a095cc7f85ec6;p=dealii-svn.git Clarify a couple of items. git-svn-id: https://svn.dealii.org/trunk@31224 0785d39b-7218-0410-832d-ea1e28bc413d --- 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 #ifdefs is types::global_dof_index. + * If deal.II is configured as normal, this type is unsigned int, + * but can be switched to unsigned long long int 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: * *
* @@ -35,15 +47,18 @@ * *
@anchor GlobalDoFIndexCell Cell
*
- * 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. *
* *
@anchor GlobalDoFIndexDoFHandler * DoFHandler
*
- * 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. *
* @@ -52,7 +67,8 @@ *
* 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. *
@@ -60,11 +76,13 @@ *
@anchor GlobalDoFIndexSparseMatrix * SparseMatrix
*
- * 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. *
* *
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