Debian Codegraph @

include/deal.II/distributed/grid_refinement.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2010 - 2023 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_distributed_grid_refinement_h
16 #define dealii_distributed_grid_refinement_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22
23 #include <deal.II/distributed/tria.h>
24
25 #include <deal.II/numerics/vector_tools_common.h>
26
27 #include <limits>
28 #include <vector>
29
30 DEAL_II_NAMESPACE_OPEN
31
32 namespace internal
33 {
34 namespace parallel
35 {
36 namespace distributed
37 {
38 namespace GridRefinement
39 {
40 /**
41 * Compute the global max and min of the criteria vector. These are
42 * returned only on the processor with rank zero, all others get a pair
43 * of zeros.
44 */
45 template <typename number>
46 std::pair<number, number>
47 compute_global_min_and_max_at_root(
48 const dealii::Vector<number> &criteria,
49 const MPI_Comm mpi_communicator);
50
51 namespace RefineAndCoarsenFixedNumber
52 {
53 /**
54 * Compute a threshold value so that exactly n_target_cells have a
55 * value that is larger.
56 */
57 template <typename number>
58 number
59 compute_threshold(const dealii::Vector<number> &criteria,
60 const std::pair<double, double> &global_min_and_max,
61 const types::global_cell_index n_target_cells,
62 const MPI_Comm mpi_communicator);
63 } // namespace RefineAndCoarsenFixedNumber
64
65 namespace RefineAndCoarsenFixedFraction
66 {
67 /**
68 * Compute a threshold value so that the error accumulated over all
69 * criteria[i] so that
70 * @code
71 * criteria[i] > threshold
72 * @endcode
73 * is larger than target_error.
74 */
75 template <typename number>
76 number
77 compute_threshold(const dealii::Vector<number> &criteria,
78 const std::pair<double, double> &global_min_and_max,
79 const double target_error,
80 const MPI_Comm mpi_communicator);
81 } // namespace RefineAndCoarsenFixedFraction
82 } // namespace GridRefinement
83 } // namespace distributed
84 } // namespace parallel
85 } // namespace internal
86
87
88
89 namespace parallel
90 {
91 namespace distributed
92 {
93 /**
94 * This namespace provides a collection of functions that aid in refinement
95 * and coarsening of triangulations. Despite the name of the namespace, the
96 * functions do not actually <i>refine</i> the triangulation, but only
97 * <i>mark cells for refinement or coarsening</i>. In other words, they
98 * perform the "mark" part of the typical "solve-estimate-mark-refine"
99 * cycle of the adaptive finite element loop.
100 *
101 * In contrast to the functions in namespace dealii::GridRefinement,
102 * the functions in the current namespace are intended for parallel
103 * computations, i.e., computations, e.g., on objects of type
104 * parallel::distributed::Triangulation.
105 *
106 * @ingroup grid
107 */
108 namespace GridRefinement
109 {
110 /**
111 * Like dealii::GridRefinement::refine_and_coarsen_fixed_number, but
112 * designed for parallel computations, where each process has only
113 * information about locally owned cells.
114 *
115 * The vector of criteria needs to be a vector of refinement criteria
116 * for all cells active on the current triangulation, i.e.,
117 * it needs to be of length <code>tria.n_active_cells()</code> (and not
118 * <code>tria.n_locally_owned_active_cells()</code>). In other words,
119 * the vector needs to include entries for ghost and artificial
120 * cells. However, the current
121 * function will only look at the indicators that correspond to those
122 * cells that are actually locally owned, and ignore the indicators for
123 * all other cells. The function will then coordinate among all
124 * processors that store part of the triangulation so that at the end
125 * a fraction @p top_fraction_of_cells of all Triangulation::n_global_active_cells()
126 * active cells are refined, rather than a fraction of the
127 * Triangulation::n_locally_active_cells on each processor individually.
128 * In other words, it may be that on some processors, no cells are
129 * refined at all.
130 *
131 * The same is true for the fraction of cells that is coarsened.
132 *
133 * @param[in,out] tria The triangulation whose cells this function is
134 * supposed to mark for coarsening and refinement.
135 *
136 * @param[in] criteria The refinement criterion for each mesh cell active
137 * on the current triangulation. Entries may not be negative.
138 *
139 * @param[in] top_fraction_of_cells The fraction of cells to be refined.
140 * If this number is zero, no cells will be refined. If it equals one,
141 * the result will be flagging for global refinement.
142 *
143 * @param[in] bottom_fraction_of_cells The fraction of cells to be
144 * coarsened. If this number is zero, no cells will be coarsened.
145 *
146 * @param[in] max_n_cells This argument can be used to specify a maximal
147 * number of cells. If this number is going to be exceeded upon
148 * refinement, then refinement and coarsening fractions are going to be
149 * adjusted in an attempt to reach the maximum number of cells. Be aware
150 * though that through proliferation of refinement due to
151 * Triangulation::MeshSmoothing, this number is only an indicator. The
152 * default value of this argument is to impose no limit on the number of
153 * cells.
154 */
155 template <int dim, typename Number, int spacedim>
156 void
157 refine_and_coarsen_fixed_number(
158 dealii::Triangulation<dim, spacedim> &tria,
159 const dealii::Vector<Number> &criteria,
160 const double top_fraction_of_cells,
161 const double bottom_fraction_of_cells,
162 const types::global_cell_index max_n_cells =
163 std::numeric_limits<types::global_cell_index>::max());
164
165 /**
166 * Like dealii::GridRefinement::refine_and_coarsen_fixed_fraction, but
167 * designed for parallel computations, where each process only has
168 * information about locally owned cells.
169 *
170 * The vector of criteria needs to be a vector of refinement criteria
171 * for all cells active on the current triangulation, i.e.,
172 * it needs to be of length <code>tria.n_active_cells()</code> (and not
173 * <code>tria.n_locally_owned_active_cells()</code>). In other words,
174 * the vector needs to include entries for ghost and artificial
175 * cells. However, the current
176 * function will only look at the indicators that correspond to those
177 * cells that are actually locally owned, and ignore the indicators for
178 * all other cells. The function will then coordinate among all
179 * processors that store part of the triangulation so that at the end
180 * the smallest fraction of Triangulation::n_global_active_cells (not
181 * Triangulation::n_locally_owned_active_cells() on each processor
182 * individually)
183 * is refined that together make up a total of @p top_fraction_of_error
184 * of the total error. In other words, it may be that on some
185 * processors, no cells are refined at all.
186 *
187 * The same is true for the fraction of cells that is coarsened.
188 *
189 * @param[in,out] tria The triangulation whose cells this function is
190 * supposed to mark for coarsening and refinement.
191 *
192 * @param[in] criteria The refinement criterion computed on each mesh cell
193 * active on the current triangulation. Entries may not be negative.
194 *
195 * @param[in] top_fraction_of_error The fraction of the total estimate
196 * which should be refined. If this number is zero, no cells will be
197 * refined. If it equals one, the result will be flagging for global
198 * refinement.
199 *
200 * @param[in] bottom_fraction_of_error The fraction of the estimate
201 * coarsened. If this number is zero, no cells will be coarsened.
202 *
203 * @param[in] norm_type To determine thresholds, combined errors on
204 * subsets of cells are calculated as norms of the criteria on these
205 * cells. Different types of norms can be used for this purpose, from
206 * which VectorTools::L1_norm and
207 * VectorTools::L2_norm are currently supported.
208 */
209 template <int dim, typename Number, int spacedim>
210 void
211 refine_and_coarsen_fixed_fraction(
212 dealii::Triangulation<dim, spacedim> &tria,
213 const dealii::Vector<Number> &criteria,
214 const double top_fraction_of_error,
215 const double bottom_fraction_of_error,
216 const VectorTools::NormType norm_type = VectorTools::L1_norm);
217 } // namespace GridRefinement
218 } // namespace distributed
219 } // namespace parallel
220
221
222 DEAL_II_NAMESPACE_CLOSE
223
224 #endif // dealii_distributed_grid_refinement_h