From: Peter Munch Date: Wed, 15 Mar 2023 15:10:34 +0000 (+0100) Subject: Make comments more consistent X-Git-Tag: v9.5.0-rc1~470^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F14900%2Fhead;p=dealii.git Make comments more consistent --- diff --git a/include/deal.II/matrix_free/dof_info.h b/include/deal.II/matrix_free/dof_info.h index 1e45a1bac8..df340bb72b 100644 --- a/include/deal.II/matrix_free/dof_info.h +++ b/include/deal.II/matrix_free/dof_info.h @@ -289,7 +289,7 @@ namespace internal /** * Given @p cell_indices_contiguous_sm containing the local index of - * cells of macro faces (inner/outer) and macro faces compute + * cells of face batches (inner/outer) and cell batches compute * dof_indices_contiguous_sm. */ void diff --git a/include/deal.II/matrix_free/face_info.h b/include/deal.II/matrix_free/face_info.h index 0ed76703f8..1fc018fe95 100644 --- a/include/deal.II/matrix_free/face_info.h +++ b/include/deal.II/matrix_free/face_info.h @@ -165,8 +165,9 @@ namespace internal std::vector> faces; /** - * This table translates a triple of the macro cell number, the index of a - * face within a cell and the index within the cell batch of vectorization + * This table translates a triple of the cell-batch number number, the + * index of a face within a cell and the index within the cell batch of + * vectorization * into the index within the @p faces array. */ ::dealii::Table<3, unsigned int> cell_and_face_to_plain_faces; diff --git a/include/deal.II/matrix_free/fe_evaluation.h b/include/deal.II/matrix_free/fe_evaluation.h index bef5801163..3a9245ce56 100644 --- a/include/deal.II/matrix_free/fe_evaluation.h +++ b/include/deal.II/matrix_free/fe_evaluation.h @@ -295,7 +295,7 @@ public: * corresponds to the value of the integrated function with the test * function of the given index. * - * Note that the derived class FEEvaluationAccess overloads this operation + * @note The derived class FEEvaluationAccess overloads this operation * with specializations for the scalar case (n_components == 1) and for the * vector-valued case (n_components == dim). */ @@ -308,7 +308,7 @@ public: * get_dof_value. Therefore, the original data that was read from a vector * is overwritten as soon as a value is submitted. * - * Note that the derived class FEEvaluationAccess overloads this operation + * @note The derived class FEEvaluationAccess overloads this operation * with specializations for the scalar case (n_components == 1) and for the * vector-valued case (n_components == dim). */ @@ -323,7 +323,7 @@ public: * vector-valued, a vector-valued return argument is given. Note that when * vectorization is enabled, values from several cells are grouped together. * - * Note that the derived class FEEvaluationAccess overloads this operation + * @note The derived class FEEvaluationAccess overloads this operation * with specializations for the scalar case (n_components == 1) and for the * vector-valued case (n_components == dim). */ @@ -338,7 +338,7 @@ public: * which is tested by all basis function on the current cell and integrated * over. * - * Note that the derived class FEEvaluationAccess overloads this operation + * @note The derived class FEEvaluationAccess overloads this operation * with specializations for the scalar case (n_components == 1) and for the * vector-valued case (n_components == dim). */ @@ -351,7 +351,7 @@ public: * EvaluationFlags::gradients, or the value that has been stored there with * a call to FEEvaluationBase::submit_gradient(). * - * Note that the derived class FEEvaluationAccess overloads this operation + * @note The derived class FEEvaluationAccess overloads this operation * with specializations for the scalar case (n_components == 1) and for the * vector-valued case (n_components == dim). */ @@ -368,7 +368,7 @@ public: * This call is equivalent to calling get_gradient() * get_normal_vector() * but will use a more efficient internal representation of data. * - * Note that the derived class FEEvaluationAccess overloads this operation + * @note The derived class FEEvaluationAccess overloads this operation * with specializations for the scalar case (n_components == 1) and for the * vector-valued case (n_components == dim). */ @@ -383,7 +383,7 @@ public: * this specifies what is tested by all basis function gradients on the * current cell and integrated over. * - * Note that the derived class FEEvaluationAccess overloads this operation + * @note The derived class FEEvaluationAccess overloads this operation * with specializations for the scalar case (n_components == 1) and for the * vector-valued case (n_components == dim). */ @@ -420,7 +420,7 @@ public: * this specifies what is tested by the Hessians of all basis functions on the * current cell and integrated over. * - * Note that the derived class FEEvaluationAccess overloads this operation + * @note The derived class FEEvaluationAccess overloads this operation * with specializations for the scalar case (n_components == 1) and for the * vector-valued case (n_components == dim). */ @@ -434,7 +434,7 @@ public: * or even the trace of the Hessian, the Laplacian, is needed, use the other * functions below. * - * Note that the derived class FEEvaluationAccess overloads this operation + * @note The derived class FEEvaluationAccess overloads this operation * with specializations for the scalar case (n_components == 1) and for the * vector-valued case (n_components == dim). */ @@ -446,7 +446,7 @@ public: * quadrature point number @p q_point after a call to * FEEvaluation::evaluate(EvaluationFlags::hessians). * - * Note that the derived class FEEvaluationAccess overloads this operation + * @note The derived class FEEvaluationAccess overloads this operation * with specializations for the scalar case (n_components == 1) and for the * vector-valued case (n_components == dim). */ @@ -460,7 +460,7 @@ public: * when computing the full Hessian, some operations can be saved when only * the Laplacian is requested. * - * Note that the derived class FEEvaluationAccess overloads this operation + * @note The derived class FEEvaluationAccess overloads this operation * with specializations for the scalar case (n_components == 1) and for the * vector-valued case (n_components == dim). */ @@ -476,7 +476,7 @@ public: * Return the divergence of a vector-valued finite element at quadrature * point number @p q_point after a call to @p evaluate(...,true,...). * - * @note Only available for n_components_==dim. + * @note Only available for the vector-valued case (n_components == dim). */ VectorizedArrayType get_divergence(const unsigned int q_point) const; @@ -487,7 +487,7 @@ public: * evaluate(...,true,...). It corresponds to 0.5 * (grad+gradT). * - * @note Only available for n_components_==dim. + * @note Only available for the vector-valued case (n_components == dim). */ SymmetricTensor<2, dim, VectorizedArrayType> get_symmetric_gradient(const unsigned int q_point) const; @@ -496,7 +496,7 @@ public: * Return the curl of the vector field, $\nabla \times v$ after a call to @p * evaluate(...,true,...). * - * @note Only available for n_components_==dim. + * @note Only available for the vector-valued case (n_components == dim). */ Tensor<1, (dim == 2 ? 1 : dim), VectorizedArrayType> get_curl(const unsigned int q_point) const; @@ -509,7 +509,7 @@ public: * tested by all basis function gradients on the current cell and integrated * over. * - * @note Only available for n_components_==dim. + * @note Only available for the vector-valued case (n_components == dim). * * @note This operation writes the data to the same field as * submit_gradient(). As a consequence, only one of these two can be @@ -528,7 +528,7 @@ public: * symmetric gradient which is tested by all basis function symmetric * gradients on the current cell and integrated over. * - * @note Only available for n_components_==dim. + * @note Only available for the vector-valued case (n_components == dim). * * @note This operation writes the data to the same field as * submit_gradient(). As a consequence, only one of these two can be @@ -545,7 +545,7 @@ public: * Write the components of a curl containing the values on quadrature point * @p q_point. Access to the same data field as through @p get_gradient. * - * @note Only available for n_components_==dim. + * @note Only available for the vector-valued case (n_components == dim). * * @note This operation writes the data to the same field as * submit_gradient(). As a consequence, only one of these two can be @@ -1949,7 +1949,9 @@ public: /** * The static number of quadrature points determined from the given template - * argument `n_q_points_1d`. Note that the actual number of quadrature + * argument `n_q_points_1d`. + * + * @note The actual number of quadrature * points, `n_q_points`, can be different if `fe_degree=-1` is given and * run-time loop lengths are used rather than compile time ones. */ @@ -1958,7 +1960,9 @@ public: /** * The static number of degrees of freedom of a scalar component determined - * from the given template argument `fe_degree`. Note that the actual number + * from the given template argument `fe_degree`. + * + * @note The actual number * of degrees of freedom `dofs_per_component` can be different if * `fe_degree=-1` is given or if the underlying is of more complicated type * than the usual FE_Q or FE_DGQ ones, such as FE_DGP. @@ -1968,7 +1972,9 @@ public: /** * The static number of degrees of freedom of all components determined from - * the given template argument `fe_degree`. Note that the actual number of + * the given template argument `fe_degree`. + * + * @note The actual number of * degrees of freedom `dofs_per_cell` can be different if `fe_degree=-1` is * given or if the underlying is of more complicated type than the usual * FE_Q or FE_DGQ ones, such as FE_DGP. @@ -1978,7 +1984,9 @@ public: /** * The static number of degrees of freedom of all components determined from - * the given template argument `fe_degree`. Note that the actual number of + * the given template argument `fe_degree`. + * + * @note The actual number of * degrees of freedom `dofs_per_cell` can be different if `fe_degree=-1` is * given or if the underlying is of more complicated type than the usual * FE_Q or FE_DGQ ones, such as FE_DGP. @@ -2452,7 +2460,9 @@ public: /** * The static number of quadrature points determined from the given template - * argument `n_q_points_1d` taken to the power of dim-1. Note that the actual + * argument `n_q_points_1d` taken to the power of dim-1. + * + * @note The actual * number of quadrature points, `n_q_points`, can be different if * `fe_degree=-1` is given and run-time loop lengths are used rather than * compile time ones. @@ -2462,7 +2472,9 @@ public: /** * The static number of quadrature points on a cell with the same quadrature - * formula. Note that this value is only present for simpler comparison with + * formula. + * + * @note This value is only present for simpler comparison with * the cell quadrature, as the actual number of points is given to a face by * the `static_n_q_points` variable. */ @@ -2471,7 +2483,9 @@ public: /** * The static number of degrees of freedom of a scalar component determined - * from the given template argument `fe_degree`. Note that the actual number + * from the given template argument `fe_degree`. + * + * @note The actual number * of degrees of freedom `dofs_per_component` can be different if * `fe_degree=-1` is given. */ @@ -2480,7 +2494,9 @@ public: /** * The static number of degrees of freedom of all components determined from - * the given template argument `fe_degree`. Note that the actual number of + * the given template argument `fe_degree`. + * + * @note The actual number of * degrees of freedom `dofs_per_cell` can be different if `fe_degree=-1` is * given. */ @@ -2489,7 +2505,9 @@ public: /** * The static number of degrees of freedom of all components determined from - * the given template argument `fe_degree`. Note that the actual number of + * the given template argument `fe_degree`. + * + * @note The actual number of * degrees of freedom `dofs_per_cell` can be different if `fe_degree=-1` is * given. */ diff --git a/include/deal.II/matrix_free/matrix_free.h b/include/deal.II/matrix_free/matrix_free.h index 4f2d4750c1..c33b4c6285 100644 --- a/include/deal.II/matrix_free/matrix_free.h +++ b/include/deal.II/matrix_free/matrix_free.h @@ -95,7 +95,7 @@ DEAL_II_NAMESPACE_OPEN * parallelization in shared memory and vectorization. * * Vectorization is implemented by merging several topological cells into one - * so-called macro cell. This enables the application of all cell-related + * so-called `cell batch`. This enables the application of all cell-related * operations for several cells with one CPU instruction and is one of the * main features of this framework. * @@ -130,25 +130,27 @@ public: /** * Collects the options for initialization of the MatrixFree class. The - * first parameter specifies the MPI communicator to be used, the second the + * parameter @p tasks_parallel_scheme specifies the * parallelization options in shared memory (task-based parallelism, where * one can choose between no parallelism and three schemes that avoid that * cells with access to the same vector entries are accessed - * simultaneously), the third with the block size for task parallel - * scheduling, the fourth the update flags that should be stored by this - * class. + * simultaneously), and the parameter @p tasks_block_size the block size for + * task parallel scheduling. The parameters @p mapping_update_flags, + * @p mapping_update_flags_boundary_faces, @p mapping_update_flags_inner_faces, + * and @p mapping_update_flags_faces_by_cells specify the update flags that + * should be stored by this class. * - * The fifth parameter specifies the level in the triangulation from which + * The parameter @p mg_level specifies the level in the triangulation from which * the indices are to be used. If the level is set to - * numbers::invalid_unsigned_int, the active cells are traversed, and + * `numbers::invalid_unsigned_int`, the active cells are traversed, and * otherwise the cells in the given level. This option has no effect in case * a DoFHandler is given. * - * The parameter @p initialize_plain_indices indicates whether the DoFInfo + * The parameter @p store_plain_indices indicates whether the DoFInfo * class should also allow for access to vectors without resolving * constraints. * - * The two parameters `initialize_indices` and `initialize_mapping` allow + * The two parameters @p initialize_indices and @p initialize_mapping allow * the user to disable some of the initialization processes. For example, if * only the scheduling that avoids touching the same vector/matrix indices * simultaneously is to be found, the mapping needs not be @@ -156,23 +158,27 @@ public: * the next but the topology has not (like when using a deforming mesh with * MappingQEulerian), it suffices to initialize the mapping only. * - * The two parameters `cell_vectorization_categories` and - * `cell_vectorization_categories_strict` control the formation of batches + * The two parameters @p cell_vectorization_categories and + * @p cell_vectorization_categories_strict control the formation of batches * for vectorization over several cells. It is used implicitly when working * with hp-adaptivity but can also be useful in other contexts, such as in * local time stepping where one would like to control which elements - * together form a batch of cells. The array `cell_vectorization_categories` + * together form a batch of cells. The array @p cell_vectorization_categories * is accessed by the number given by cell->active_cell_index() when working - * on the active cells with `mg_level` set to `numbers::invalid_unsigned_int` + * on the active cells with @p mg_level set to `numbers::invalid_unsigned_int` * and by cell->index() for the level cells. By default, the different - * categories in `cell_vectorization_category` can be mixed and the algorithm + * categories in @p cell_vectorization_category can be mixed and the algorithm * is allowed to merge lower category numbers with the next higher categories * if it is necessary inside the algorithm, in order to avoid partially * filled SIMD lanes as much as possible. This gives a better utilization of * the vectorization but might need special treatment, in particular for - * face integrals. If set to @p true, the algorithm will instead keep + * face integrals. If set to `true', the algorithm will instead keep * different categories separate and not mix them in a single vectorized * array. + * + * Finally, @p allow_ghosted_vectors_in_loops allows to enable and disable + * checks and @p communicator_sm gives the MPI communicator to be used + * if MPI-3.0 shared-memory features should be used. */ struct AdditionalData { @@ -341,12 +347,12 @@ public: TasksParallelScheme tasks_parallel_scheme; /** - * Set the number of so-called macro cells that should form one + * Set the number of so-called cell batches that should form one * partition. If zero size is given, the class tries to find a good size * for the blocks based on MultithreadInfo::n_threads() and the number of * cells present. Otherwise, the given number is used. If the given number * is larger than one third of the number of total cells, this means no - * parallelism. Note that in the case vectorization is used, a macro cell + * parallelism. Note that in the case vectorization is used, a cell batch * consists of more than one physical cell. */ unsigned int tasks_block_size; @@ -2152,7 +2158,7 @@ public: /** - * Return the table that translates a triple of the macro cell number, + * Return the table that translates a triple of the cell-batch number, * the index of a face within a cell and the index within the cell batch of * vectorization into the index within the faces array. */ diff --git a/include/deal.II/matrix_free/task_info.h b/include/deal.II/matrix_free/task_info.h index 1f334b718f..bfd3ade2e5 100644 --- a/include/deal.II/matrix_free/task_info.h +++ b/include/deal.II/matrix_free/task_info.h @@ -223,7 +223,7 @@ namespace internal * This helper function determines a block size if the user decided not * to force a block size through MatrixFree::AdditionalData. This is * computed based on the number of hardware threads on the system and - * the number of macro cells that we should work on. + * the number of cell batches that we should work on. */ void guess_block_size(const unsigned int dofs_per_cell);