Debian Codegraph @

dune/istl/paamg/parameters.hh

raw
1 // SPDX-FileCopyrightText: Copyright © DUNE Project contributors, see file LICENSE.md in module root
2 // SPDX-License-Identifier: LicenseRef-GPL-2.0-only-with-DUNE-exception
3 // -*- tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
4 // vi: set et ts=4 sw=2 sts=2:
5 #ifndef DUNE_AMG_PARAMETERS_HH
6 #define DUNE_AMG_PARAMETERS_HH
7
8 #include <cstddef>
9
10 namespace Dune
11 {
12 namespace Amg
13 {
14 /**
15 * @addtogroup ISTL_PAAMG
16 *
17 * @{
18 */
19 /** @file
20 * @author Markus Blatt
21 * @brief Parameter classes for customizing AMG
22 *
23 * All parameters of the AMG can be set by using the class Parameter, which
24 * can be provided to CoarsenCriterion via its constructor.
25 */
26
27 /**
28 * @brief Parameters needed to check whether a node depends on another.
29 */
30 class DependencyParameters
31 {
32 public:
33 /** @brief Constructor */
34 DependencyParameters()
35 : alpha_(1.0/3.0), beta_(1.0E-5)
36 {}
37
38 /**
39 * @brief Set threshold for marking nodes as isolated.
40 * The default value is 1.0E-5.
41 */
42 void setBeta(double b)
43 {
44 beta_ = b;
45 }
46
47 /**
48 * @brief Get the threshold for marking nodes as isolated.
49 * The default value is 1.0E-5.
50 * @return beta
51 */
52 double beta() const
53 {
54 return beta_;
55 }
56
57 /**
58 * @brief Set the scaling value for marking connections as strong.
59 * Default value is 1/3
60 */
61 void setAlpha(double a)
62 {
63 alpha_ = a;
64 }
65
66 /**
67 * @brief Get the scaling value for marking connections as strong.
68 * Default value is 1/3
69 */
70 double alpha() const
71 {
72 return alpha_;
73 }
74
75 private:
76 double alpha_, beta_;
77 };
78
79 /**
80 * @brief Parameters needed for the aggregation process
81 */
82 class AggregationParameters :
83 public DependencyParameters
84 {
85 public:
86 /**
87 * @brief Constructor.
88 *
89 * The parameters will be initialized with default values suitable
90 * for 2D isotropic problems.
91 *
92 * If that does not fit your needs either use setDefaultValuesIsotropic
93 * setDefaultValuesAnisotropic or setup the values by hand
94 */
95 AggregationParameters()
96 : maxDistance_(2), minAggregateSize_(4), maxAggregateSize_(6),
97 connectivity_(15), skipiso_(false)
98 {}
99
100 /**
101 * @brief Sets reasonable default values for an isotropic problem.
102 *
103 * Reasonable means that we should end up with cube aggregates of
104 * diameter 2.
105 *
106 * @param dim The dimension of the problem.
107 * @param diameter The preferred diameter for the aggregation.
108 */
109 void setDefaultValuesIsotropic(std::size_t dim, std::size_t diameter=2)
110 {
111 maxDistance_=diameter-1;
112 std::size_t csize=1;
113
114 for(; dim>0; dim--) {
115 csize*=diameter;
116 maxDistance_+=diameter-1;
117 }
118 minAggregateSize_=csize;
119 maxAggregateSize_=static_cast<std::size_t>(csize*1.5);
120 }
121
122 /**
123 * @brief Sets reasonable default values for an anisotropic problem.
124 *
125 * Reasonable means that we should end up with cube aggregates with
126 * sides of diameter 2 and sides in one dimension that are longer
127 * (e.g. for 3D: 2x2x3).
128 *
129 * @param dim The dimension of the problem.
130 * @param diameter The preferred diameter for the aggregation.
131 */
132 void setDefaultValuesAnisotropic(std::size_t dim,std::size_t diameter=2)
133 {
134 setDefaultValuesIsotropic(dim, diameter);
135 maxDistance_+=dim-1;
136 }
137 /**
138 * @brief Get the maximal distance allowed between two nodes in a aggregate.
139 *
140 * The distance between two nodes in a aggregate is the minimal number of edges
141 * it takes to travel from one node to the other without leaving the aggregate.
142 * @return The maximum distance allowed.
143 */
144 std::size_t maxDistance() const { return maxDistance_;}
145
146 /**
147 * @brief Set the maximal distance allowed between two nodes in a aggregate.
148 *
149 * The distance between two nodes in a aggregate is the minimal number of edges
150 * it takes to travel from one node to the other without leaving the aggregate.
151 * The default value is 2.
152 * @param distance The maximum distance allowed.
153 */
154 void setMaxDistance(std::size_t distance) { maxDistance_ = distance;}
155
156 /**
157 * @brief Whether isolated aggregates will not be represented on
158 * the coarse level.
159 * @return True if these aggregates will be skipped.
160 */
161 bool skipIsolated() const
162 {
163 return skipiso_;
164 }
165
166 /**
167 * @brief Set whether isolated aggregates will not be represented on
168 * the coarse level.
169 * @param skip True if these aggregates will be skipped.
170 */
171 void setSkipIsolated(bool skip)
172 {
173 skipiso_=skip;
174 }
175
176 /**
177 * @brief Get the minimum number of nodes a aggregate has to consist of.
178 * @return The minimum number of nodes.
179 */
180 std::size_t minAggregateSize() const { return minAggregateSize_;}
181
182 /**
183 * @brief Set the minimum number of nodes a aggregate has to consist of.
184 *
185 * the default value is 4.
186 */
187 void setMinAggregateSize(std::size_t size){ minAggregateSize_=size;}
188
189 /**
190 * @brief Get the maximum number of nodes a aggregate is allowed to have.
191 * @return The maximum number of nodes.
192 */
193 std::size_t maxAggregateSize() const { return maxAggregateSize_;}
194
195 /**
196 * @brief Set the maximum number of nodes a aggregate is allowed to have.
197 *
198 * The default values is 6.
199 * @param size The maximum number of nodes.
200 */
201 void setMaxAggregateSize(std::size_t size){ maxAggregateSize_ = size;}
202
203 /**
204 * @brief Get the maximum number of connections a aggregate is allowed to have.
205 *
206 * This limit exists to achieve sparsity of the coarse matrix. the default value is 15.
207 *
208 * @return The maximum number of connections a aggregate is allowed to have.
209 */
210 std::size_t maxConnectivity() const { return connectivity_;}
211
212 /**
213 * @brief Set the maximum number of connections a aggregate is allowed to have.
214 *
215 * This limit exists to achieve sparsity of the coarse matrix. the default value is 15.
216 *
217 * @param connectivity The maximum number of connections a aggregate is allowed to have.
218 */
219 void setMaxConnectivity(std::size_t connectivity){ connectivity_ = connectivity;}
220
221 private:
222 std::size_t maxDistance_, minAggregateSize_, maxAggregateSize_, connectivity_;
223 bool skipiso_;
224
225 };
226
227
228 /**
229 * @brief Identifiers for the different accumulation modes.
230 */
231 enum AccumulationMode {
232 /**
233 * @brief No data accumulution.
234 *
235 * The coarse level data will be distributed to all processes.
236 */
237 noAccu = 0,
238 /**
239 * @brief Accumulate data to one process at once
240 *
241 * Once no further coarsening is possible all data will be accumulated to one process
242 */
243 atOnceAccu=1,
244 /**
245 * @brief Successively accumulate to fewer processes.
246 */
247 successiveAccu=2
248 };
249
250
251
252
253 /**
254 * @brief Parameters for the complete coarsening process.
255 */
256 class CoarseningParameters : public AggregationParameters
257 {
258 public:
259 /**
260 * @brief Set the maximum number of levels allowed in the hierarchy.
261 */
262 void setMaxLevel(int l)
263 {
264 maxLevel_ = l;
265 }
266 /**
267 * @brief Get the maximum number of levels allowed in the hierarchy.
268 */
269 int maxLevel() const
270 {
271 return maxLevel_;
272 }
273
274 /**
275 * @brief Set the maximum number of unknowns allowed on the coarsest level.
276 */
277 void setCoarsenTarget(int nodes)
278 {
279 coarsenTarget_ = nodes;
280 }
281
282 /**
283 * @brief Get the maximum number of unknowns allowed on the coarsest level.
284 */
285 int coarsenTarget() const
286 {
287 return coarsenTarget_;
288 }
289
290 /**
291 * @brief Set the minimum coarsening rate to be achieved in each coarsening.
292 *
293 * The default value is 1.2
294 */
295 void setMinCoarsenRate(double rate)
296 {
297 minCoarsenRate_ = rate;
298 }
299
300 /**
301 * @brief Get the minimum coarsening rate to be achieved.
302 */
303 double minCoarsenRate() const
304 {
305 return minCoarsenRate_;
306 }
307
308 /**
309 * @brief Whether the data should be accumulated on fewer processes on coarser levels.
310 */
311 AccumulationMode accumulate() const
312 {
313 return accumulate_;
314 }
315 /**
316 * @brief Set whether the data should be accumulated on fewer processes on coarser levels.
317 */
318 void setAccumulate(AccumulationMode accu)
319 {
320 accumulate_=accu;
321 }
322
323 void setAccumulate(bool accu){
324 accumulate_=accu ? successiveAccu : noAccu;
325 }
326
327 /**
328 * @brief Check if the indices for the coarser levels should be created in a fixed order.
329 */
330 bool useFixedOrder() const
331 {
332 return useFixedOrder_;
333 }
334
335 void setUseFixedOrder(bool useFixedOrder)
336 {
337 useFixedOrder_ = useFixedOrder;
338 }
339
340 /**
341 * @brief Set the damping factor for the prolongation.
342 *
343 * @param d The new damping factor.
344 */
345 void setProlongationDampingFactor(double d)
346 {
347 dampingFactor_ = d;
348 }
349
350 /**
351 * @brief Get the damping factor for the prolongation.
352 *
353 * @return d The damping factor.
354 */
355 double getProlongationDampingFactor() const
356 {
357 return dampingFactor_;
358 }
359 /**
360 * @brief Constructor
361 * @param maxLevel The maximum number of levels allowed in the matrix hierarchy (default: 100).
362 * @param coarsenTarget If the number of nodes in the matrix is below this threshold the
363 * coarsening will stop (default: 1000).
364 * @param minCoarsenRate If the coarsening rate falls below this threshold the
365 * coarsening will stop (default: 1.2)
366 * @param prolongDamp The damping factor to apply to the prolongated update (default: 1.6)
367 * @param accumulate Whether to accumulate the data onto fewer processors on coarser levels.
368 * @param useFixedOrder Flag indicating if creating indices for the coarser level
369 * should be done in a fixed order, i.e., the order in which the rows were sent.
370 * If set to true, this makes the runs reproducible but it might slow down performance.
371 */
372 CoarseningParameters(int maxLevel=100, int coarsenTarget=1000, double minCoarsenRate=1.2,
373 double prolongDamp=1.6, AccumulationMode accumulate=successiveAccu,
374 bool useFixedOrder = false)
375 : maxLevel_(maxLevel), coarsenTarget_(coarsenTarget), minCoarsenRate_(minCoarsenRate),
376 dampingFactor_(prolongDamp), accumulate_( accumulate), useFixedOrder_(useFixedOrder)
377 {}
378
379 private:
380 /**
381 * @brief The maximum number of levels allowed in the hierarchy.
382 */
383 int maxLevel_;
384 /**
385 * @brief The maximum number of unknowns allowed on the coarsest level.
386 */
387 int coarsenTarget_;
388 /**
389 * @brief The minimum coarsening rate to be achieved.
390 */
391 double minCoarsenRate_;
392 /**
393 * @brief The damping factor to apply to the prologated correction.
394 */
395 double dampingFactor_;
396 /**
397 * @brief Whether the data should be agglomerated to fewer processor on
398 * coarser levels.
399 */
400 AccumulationMode accumulate_;
401 /**
402 * @brief useFixedOrder Flag indicating if creating indices for the coarser
403 * level should be done in a fixed order. If set to true, this makes the runs reproducible
404 * but it might slow down performance.
405 */
406 bool useFixedOrder_;
407 };
408
409 /**
410 * @brief All parameters for AMG.
411 *
412 * Instances of this class can be provided to CoarsenCriterion via its
413 * constructor.
414 */
415 class Parameters : public CoarseningParameters
416 {
417 public:
418 /**
419 * @brief Set the debugging level.
420 *
421 * @param level If 0 no debugging output will be generated.
422 * @warning In parallel the level has to be consistent over all procceses.
423 */
424 void setDebugLevel(int level)
425 {
426 debugLevel_ = level;
427 }
428
429 /**
430 * @brief Get the debugging Level.
431 *
432 * @return 0 if no debugging output will be generated.
433 */
434 int debugLevel() const
435 {
436 return debugLevel_;
437 }
438
439 /**
440 * @brief Set the number of presmoothing steps to apply
441 * @param steps The number of steps:
442 */
443 void setNoPreSmoothSteps(std::size_t steps)
444 {
445 preSmoothSteps_=steps;
446 }
447 /**
448 * @brief Get the number of presmoothing steps to apply
449 * @return The number of steps:
450 */
451 std::size_t getNoPreSmoothSteps() const
452 {
453 return preSmoothSteps_;
454 }
455
456 /**
457 * @brief Set the number of postsmoothing steps to apply
458 * @param steps The number of steps:
459 */
460 void setNoPostSmoothSteps(std::size_t steps)
461 {
462 postSmoothSteps_=steps;
463 }
464 /**
465 * @brief Get the number of postsmoothing steps to apply
466 * @return The number of steps:
467 */
468 std::size_t getNoPostSmoothSteps() const
469 {
470 return postSmoothSteps_;
471 }
472
473 /**
474 * @brief Set the value of gamma; 1 for V-cycle, 2 for W-cycle
475 */
476 void setGamma(std::size_t gamma)
477 {
478 gamma_=gamma;
479 }
480 /**
481 * @brief Get the value of gamma; 1 for V-cycle, 2 for W-cycle
482 */
483 std::size_t getGamma() const
484 {
485 return gamma_;
486 }
487
488 /**
489 * @brief Set whether to use additive multigrid.
490 * @param additive True if multigrid should be additive.
491 */
492 void setAdditive(bool additive)
493 {
494 additive_=additive;
495 }
496
497 /**
498 * @brief Get whether to use additive multigrid.
499 * @return True if multigrid should be additive.
500 */
501 bool getAdditive() const
502 {
503 return additive_;
504 }
505
506 /**
507 * @brief Constructor
508 * @param maxLevel The maximum number of levels allowed in the matrix hierarchy (default: 100).
509 * @param coarsenTarget If the number of nodes in the matrix is below this threshold the
510 * coarsening will stop (default: 1000).
511 * @param minCoarsenRate If the coarsening rate falls below this threshold the
512 * coarsening will stop (default: 1.2)
513 * @param prolongDamp The damping factor to apply to the prolongated update (default: 1.6)
514 * @param accumulate Whether to accumulate the data onto fewer processors on coarser levels.
515 */
516 Parameters(int maxLevel=100, int coarsenTarget=1000, double minCoarsenRate=1.2,
517 double prolongDamp=1.6, AccumulationMode accumulate=successiveAccu, bool useFixedOrder = false)
518 : CoarseningParameters(maxLevel, coarsenTarget, minCoarsenRate, prolongDamp, accumulate, useFixedOrder)
519 , debugLevel_(2), preSmoothSteps_(2), postSmoothSteps_(2), gamma_(1),
520 additive_(false)
521 {}
522 private:
523 int debugLevel_;
524 std::size_t preSmoothSteps_;
525 std::size_t postSmoothSteps_;
526 std::size_t gamma_;
527 bool additive_;
528 };
529
530 } //namespace AMG
531
532 } //namespace Dune
533 #endif