| 1 |
// ------------------------------------------------------------------------ |
| 2 |
// |
| 3 |
// SPDX-License-Identifier: LGPL-2.1-or-later |
| 4 |
// Copyright (C) 2002 - 2025 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_filtered_iterator_h |
| 16 |
#define dealii_filtered_iterator_h |
| 17 |
|
| 18 |
|
| 19 |
#include <deal.II/base/config.h> |
| 20 |
|
| 21 |
#include <deal.II/base/exceptions.h> |
| 22 |
#include <deal.II/base/iterator_range.h> |
| 23 |
#include <deal.II/base/types.h> |
| 24 |
|
| 25 |
#include <deal.II/grid/tria_iterator_base.h> |
| 26 |
|
| 27 |
#include <memory> |
| 28 |
#include <set> |
| 29 |
#include <tuple> |
| 30 |
|
| 31 |
#ifdef DEAL_II_HAVE_CXX20 |
| 32 |
# include <concepts> |
| 33 |
#endif |
| 34 |
|
| 35 |
|
| 36 |
DEAL_II_NAMESPACE_OPEN |
| 37 |
|
| 38 |
|
| 39 |
/** |
| 40 |
* In this namespace a number of classes is declared that may be used as |
| 41 |
* filters in the FilteredIterator class. The filters either check for binary |
| 42 |
* information (for example, the IteratorFilters::Active filter class checks |
| 43 |
* whether the object pointed to is active), or for valued information by |
| 44 |
* comparison with prescribed values (for example, the LevelEqualTo filter |
| 45 |
* class checks whether the level of the object pointed to by the iterator |
| 46 |
* under consideration is equal to a value that was given to the filter upon |
| 47 |
* construction. |
| 48 |
* |
| 49 |
* For examples of use of these classes as well as requirements on filters see |
| 50 |
* the general description of the FilteredIterator class. |
| 51 |
* |
| 52 |
* @ingroup Iterators |
| 53 |
*/ |
| 54 |
namespace IteratorFilters |
| 55 |
{ |
| 56 |
/** |
| 57 |
* Filter that evaluates to true if either the iterator points to an active |
| 58 |
* object or an iterator past the end. |
| 59 |
* |
| 60 |
* @ingroup Iterators |
| 61 |
*/ |
| 62 |
class Active |
| 63 |
{ |
| 64 |
public: |
| 65 |
/** |
| 66 |
* Evaluate the iterator and return true if the object is active or past |
| 67 |
* the end. |
| 68 |
*/ |
| 69 |
template <class Iterator> |
| 70 |
bool |
| 71 |
operator()(const Iterator &i) const; |
| 72 |
}; |
| 73 |
|
| 74 |
/** |
| 75 |
* Filter that evaluates to true if either the iterator points to an object |
| 76 |
* for which the user flag is set or an iterator past the end. See |
| 77 |
* @ref GlossUserFlags |
| 78 |
* for information about user flags. |
| 79 |
* |
| 80 |
* @ingroup Iterators |
| 81 |
*/ |
| 82 |
class UserFlagSet |
| 83 |
{ |
| 84 |
public: |
| 85 |
/** |
| 86 |
* Evaluate the iterator and return true if the object has a set user flag |
| 87 |
* or past the end. |
| 88 |
*/ |
| 89 |
template <class Iterator> |
| 90 |
bool |
| 91 |
operator()(const Iterator &i) const; |
| 92 |
}; |
| 93 |
|
| 94 |
|
| 95 |
/** |
| 96 |
* Filter that evaluates to true if either the iterator points to an object |
| 97 |
* for which the user flag is not set or an iterator past the end. Inverse |
| 98 |
* filter to the previous class. |
| 99 |
* |
| 100 |
* @ingroup Iterators |
| 101 |
*/ |
| 102 |
class UserFlagNotSet |
| 103 |
{ |
| 104 |
public: |
| 105 |
/** |
| 106 |
* Evaluate the iterator and return true if the object has an unset user |
| 107 |
* flag or past the end. |
| 108 |
*/ |
| 109 |
template <class Iterator> |
| 110 |
bool |
| 111 |
operator()(const Iterator &i) const; |
| 112 |
}; |
| 113 |
|
| 114 |
|
| 115 |
/** |
| 116 |
* Filter for iterators that evaluates to true if either the iterator is |
| 117 |
* past the end or the level of the object pointed to is equal to a value |
| 118 |
* given to the constructor. |
| 119 |
* |
| 120 |
* @ingroup Iterators |
| 121 |
*/ |
| 122 |
class LevelEqualTo |
| 123 |
{ |
| 124 |
public: |
| 125 |
/** |
| 126 |
* Constructor. Store the level which iterators shall have to be evaluated |
| 127 |
* to true. |
| 128 |
*/ |
| 129 |
LevelEqualTo(const unsigned int level); |
| 130 |
|
| 131 |
/** |
| 132 |
* Evaluation operator. Returns true if either the level of the object |
| 133 |
* pointed to is equal to the stored value or the iterator is past the |
| 134 |
* end. |
| 135 |
*/ |
| 136 |
template <class Iterator> |
| 137 |
bool |
| 138 |
operator()(const Iterator &i) const; |
| 139 |
|
| 140 |
protected: |
| 141 |
/** |
| 142 |
* Stored value to compare the level with. |
| 143 |
*/ |
| 144 |
const unsigned int level; |
| 145 |
}; |
| 146 |
|
| 147 |
|
| 148 |
|
| 149 |
/** |
| 150 |
* Filter for iterators that evaluates to true if either the iterator is |
| 151 |
* past the end or the subdomain id of the object pointed to is equal to a |
| 152 |
* value given to the constructor, assuming that the iterator allows |
| 153 |
* querying for a subdomain id. |
| 154 |
* |
| 155 |
* @ingroup Iterators |
| 156 |
*/ |
| 157 |
class SubdomainEqualTo |
| 158 |
{ |
| 159 |
public: |
| 160 |
/** |
| 161 |
* Constructor. Store the subdomain which iterators shall have to be |
| 162 |
* evaluated to true. |
| 163 |
*/ |
| 164 |
SubdomainEqualTo(const types::subdomain_id subdomain_id); |
| 165 |
|
| 166 |
/** |
| 167 |
* Evaluation operator. Returns true if either the subdomain of the object |
| 168 |
* pointed to is equal to the stored value or the iterator is past the |
| 169 |
* end. |
| 170 |
*/ |
| 171 |
template <class Iterator> |
| 172 |
bool |
| 173 |
operator()(const Iterator &i) const; |
| 174 |
|
| 175 |
protected: |
| 176 |
/** |
| 177 |
* Stored value to compare the subdomain with. |
| 178 |
*/ |
| 179 |
const types::subdomain_id subdomain_id; |
| 180 |
}; |
| 181 |
|
| 182 |
|
| 183 |
|
| 184 |
/** |
| 185 |
* Filter for iterators that evaluates to true if a cell is owned by the |
| 186 |
* current processor, i.e., if it is a |
| 187 |
* @ref GlossLocallyOwnedCell "locally owned cell". |
| 188 |
* |
| 189 |
* This class is used in step-32, in connection with the methods of the |
| 190 |
* @ref distributed |
| 191 |
* topic. |
| 192 |
* |
| 193 |
* @ingroup Iterators |
| 194 |
*/ |
| 195 |
class LocallyOwnedCell |
| 196 |
{ |
| 197 |
public: |
| 198 |
/** |
| 199 |
* Evaluation operator. Returns true if the cell is locally owned. |
| 200 |
*/ |
| 201 |
template <class Iterator> |
| 202 |
bool |
| 203 |
operator()(const Iterator &i) const; |
| 204 |
}; |
| 205 |
|
| 206 |
|
| 207 |
|
| 208 |
/** |
| 209 |
* Filter for iterators that evaluates to true if the level subdomain id of |
| 210 |
* a cell is equal to the current processor id. |
| 211 |
* |
| 212 |
* @ingroup Iterators |
| 213 |
*/ |
| 214 |
class LocallyOwnedLevelCell |
| 215 |
{ |
| 216 |
public: |
| 217 |
/** |
| 218 |
* Evaluation operator. Returns true if the level subdomain id of the cell |
| 219 |
* is equal to the current processor id. |
| 220 |
*/ |
| 221 |
template <class Iterator> |
| 222 |
bool |
| 223 |
operator()(const Iterator &i) const; |
| 224 |
}; |
| 225 |
|
| 226 |
|
| 227 |
/** |
| 228 |
* Filter for iterators that evaluates to true if the iterator of the object |
| 229 |
* pointed to is equal to a value or set of values given to the constructor, |
| 230 |
* assuming that the iterator allows querying for a material id. |
| 231 |
* |
| 232 |
* |
| 233 |
* @ingroup Iterators |
| 234 |
*/ |
| 235 |
class MaterialIdEqualTo |
| 236 |
{ |
| 237 |
public: |
| 238 |
/** |
| 239 |
* Constructor. Store the material id which iterators shall have to be |
| 240 |
* evaluated to true and state if the iterator must be locally owned. |
| 241 |
*/ |
| 242 |
MaterialIdEqualTo(const types::material_id material_id, |
| 243 |
const bool only_locally_owned = false); |
| 244 |
|
| 245 |
/** |
| 246 |
* Constructor. Store a collection of material ids which iterators shall |
| 247 |
* have to be evaluated to true and state if the iterator must be locally |
| 248 |
* owned. |
| 249 |
*/ |
| 250 |
MaterialIdEqualTo(const std::set<types::material_id> &material_ids, |
| 251 |
const bool only_locally_owned = false); |
| 252 |
|
| 253 |
/** |
| 254 |
* Evaluation operator. Returns true if the material id of the object |
| 255 |
* pointed to is equal within the stored set of value allowable values |
| 256 |
* and, if required, if the cell is locally owned. |
| 257 |
*/ |
| 258 |
template <class Iterator> |
| 259 |
bool |
| 260 |
operator()(const Iterator &i) const; |
| 261 |
|
| 262 |
protected: |
| 263 |
/** |
| 264 |
* Stored value to compare the material id with. |
| 265 |
*/ |
| 266 |
const std::set<types::material_id> material_ids; |
| 267 |
/** |
| 268 |
* Flag stating whether only locally owned cells must return true. |
| 269 |
*/ |
| 270 |
const bool only_locally_owned; |
| 271 |
}; |
| 272 |
|
| 273 |
/** |
| 274 |
* Filter for iterators that evaluates to true if the iterator of the object |
| 275 |
* pointed to is equal to a value or set of values given to the constructor, |
| 276 |
* assuming that the iterator allows querying for an active FE index. |
| 277 |
* |
| 278 |
* |
| 279 |
* @ingroup Iterators |
| 280 |
*/ |
| 281 |
class ActiveFEIndexEqualTo |
| 282 |
{ |
| 283 |
public: |
| 284 |
/** |
| 285 |
* Constructor. Store the active FE index which iterators shall have to be |
| 286 |
* evaluated to true and state if the iterator must be locally owned. |
| 287 |
*/ |
| 288 |
ActiveFEIndexEqualTo(const unsigned int active_fe_index, |
| 289 |
const bool only_locally_owned = false); |
| 290 |
|
| 291 |
/** |
| 292 |
* Constructor. Store a collection of active FE indices which iterators |
| 293 |
* shall have to be evaluated to true and state if the iterator must be |
| 294 |
* locally owned. |
| 295 |
*/ |
| 296 |
ActiveFEIndexEqualTo(const std::set<unsigned int> &active_fe_indices, |
| 297 |
const bool only_locally_owned = false); |
| 298 |
|
| 299 |
/** |
| 300 |
* Evaluation operator. Returns true if the active FE index of the object |
| 301 |
* pointed to is equal within the stored set of value allowable values |
| 302 |
* and, if required, if the cell is locally owned. |
| 303 |
*/ |
| 304 |
template <class Iterator> |
| 305 |
bool |
| 306 |
operator()(const Iterator &i) const; |
| 307 |
|
| 308 |
protected: |
| 309 |
/** |
| 310 |
* Stored value to compare the material id with. |
| 311 |
*/ |
| 312 |
const std::set<unsigned int> active_fe_indices; |
| 313 |
/** |
| 314 |
* Flag stating whether only locally owned cells must return true. |
| 315 |
*/ |
| 316 |
const bool only_locally_owned; |
| 317 |
}; |
| 318 |
|
| 319 |
/** |
| 320 |
* Filter for iterators that evaluates to true if the iterator of the object |
| 321 |
* pointed to is on the boundary. |
| 322 |
* |
| 323 |
* |
| 324 |
* @ingroup Iterators |
| 325 |
*/ |
| 326 |
class AtBoundary |
| 327 |
{ |
| 328 |
public: |
| 329 |
/** |
| 330 |
* Evaluate the iterator and return true if the object at the boundary. |
| 331 |
*/ |
| 332 |
template <class Iterator> |
| 333 |
bool |
| 334 |
operator()(const Iterator &i) const; |
| 335 |
}; |
| 336 |
|
| 337 |
|
| 338 |
/** |
| 339 |
* Filter for iterators that evaluates to true if the iterator of the object |
| 340 |
* pointed to is equal to a value or set of values given to the constructor, |
| 341 |
* assuming that the iterator allows querying for a boundary id. |
| 342 |
* |
| 343 |
* @ingroup Iterators |
| 344 |
*/ |
| 345 |
class BoundaryIdEqualTo |
| 346 |
{ |
| 347 |
public: |
| 348 |
/** |
| 349 |
* Constructor. Store the boundary id which iterators shall have to be |
| 350 |
* evaluated to true. |
| 351 |
*/ |
| 352 |
BoundaryIdEqualTo(const types::boundary_id boundary_id); |
| 353 |
|
| 354 |
/** |
| 355 |
* Constructor. Store a collection of boundary ids which iterators shall |
| 356 |
* have to be evaluated to true. |
| 357 |
*/ |
| 358 |
BoundaryIdEqualTo(const std::set<types::boundary_id> &boundary_ids); |
| 359 |
|
| 360 |
/** |
| 361 |
* Evaluation operator. Returns true if the boundary id of the object |
| 362 |
* pointed to is equal within the stored set of value allowable values. |
| 363 |
*/ |
| 364 |
template <class Iterator> |
| 365 |
bool |
| 366 |
operator()(const Iterator &i) const; |
| 367 |
|
| 368 |
protected: |
| 369 |
/** |
| 370 |
* Stored value to compare the material id with. |
| 371 |
*/ |
| 372 |
const std::set<types::boundary_id> boundary_ids; |
| 373 |
}; |
| 374 |
|
| 375 |
|
| 376 |
/** |
| 377 |
* Filter for iterators that evaluates to true if the iterator of the object |
| 378 |
* pointed to is equal to a value or set of values given to the constructor, |
| 379 |
* assuming that the iterator allows querying for a manifold id. |
| 380 |
* |
| 381 |
* @ingroup Iterators |
| 382 |
*/ |
| 383 |
class ManifoldIdEqualTo |
| 384 |
{ |
| 385 |
public: |
| 386 |
/** |
| 387 |
* Constructor. Store the boundary id which iterators shall have to be |
| 388 |
* evaluated to true. |
| 389 |
*/ |
| 390 |
ManifoldIdEqualTo(const types::manifold_id manifold_id); |
| 391 |
|
| 392 |
/** |
| 393 |
* Constructor. Store a collection of boundary ids which iterators shall |
| 394 |
* have to be evaluated to true. |
| 395 |
*/ |
| 396 |
ManifoldIdEqualTo(const std::set<types::manifold_id> &manifold_ids); |
| 397 |
|
| 398 |
/** |
| 399 |
* Evaluation operator. Returns true if the boundary id of the object |
| 400 |
* pointed to is equal within the stored set of value allowable values. |
| 401 |
*/ |
| 402 |
template <class Iterator> |
| 403 |
bool |
| 404 |
operator()(const Iterator &i) const; |
| 405 |
|
| 406 |
protected: |
| 407 |
/** |
| 408 |
* Stored value to compare the material id with. |
| 409 |
*/ |
| 410 |
const std::set<types::manifold_id> manifold_ids; |
| 411 |
}; |
| 412 |
} // namespace IteratorFilters |
| 413 |
|
| 414 |
|
| 415 |
/** |
| 416 |
* This class provides a certain view on a range of triangulation or |
| 417 |
* DoFHandler iterators by only iterating over elements that satisfy a given |
| 418 |
* filter (called a <em>predicate</em>, following the notation of the C++ |
| 419 |
* standard library). Once initialized with a predicate and a value for the |
| 420 |
* iterator, a filtered iterator advances to the next or previous element that |
| 421 |
* satisfies the predicate if operators ++ or \-- are invoked. Intermediate |
| 422 |
* iterator values that lie in between but do not satisfy the predicate are |
| 423 |
* skipped. It is thus very simple to write loops over a certain class of |
| 424 |
* objects without the need to explicitly write down the condition they have |
| 425 |
* to satisfy in each loop iteration. This in particular is helpful if |
| 426 |
* functions are called with a pair of iterators denoting a range on which |
| 427 |
* they shall act, by choosing a filtered iterator instead of usual ones. |
| 428 |
* The use of this class is particularly useful when writing "ranged-based" |
| 429 |
* `for` loops of the form |
| 430 |
* @code |
| 431 |
* for (const auto &cell : <some FilteredIterator object>) |
| 432 |
* { ... } |
| 433 |
* @endcode |
| 434 |
* An example is to write |
| 435 |
* @code |
| 436 |
* DoFHandler<dim> dof_handler; |
| 437 |
* ... |
| 438 |
* for (const auto &cell : |
| 439 |
* dof_handler.active_cell_iterators() |
| 440 |
* | IteratorFilters::LocallyOwnedCell() |
| 441 |
* | IteratorFilters::AtBoundary()) |
| 442 |
* { |
| 443 |
* fe_values.reinit (cell); |
| 444 |
* ...do the local integration on 'cell'...; |
| 445 |
* } |
| 446 |
* @endcode |
| 447 |
* where the resulting loop iterates over all active cells that are also |
| 448 |
* locally owned and that point to cells that are at the boundary of the |
| 449 |
* domain. |
| 450 |
* |
| 451 |
* This class implements functionality comparable to what was added to C++20 |
| 452 |
* in the form of |
| 453 |
* [range adaptors](https://en.cppreference.com/w/cpp/ranges/filter_view) |
| 454 |
* and the filters and filter views that represent them. |
| 455 |
* |
| 456 |
* This class is used in step-32. |
| 457 |
* |
| 458 |
* |
| 459 |
* <h3>Predicates</h3> |
| 460 |
* |
| 461 |
* The object that represent the condition an iterator has to satisfy only |
| 462 |
* has to provide an interface that allows to call the evaluation operator, |
| 463 |
* i.e. <code>bool operator() (const BaseIterator&)</code>. This includes |
| 464 |
* function pointers as well as classes that implement an <code>bool operator |
| 465 |
* ()(const BaseIterator&)</code>. Then, the FilteredIterator will skip all |
| 466 |
* objects where the return value of this function is <code>false</code>. |
| 467 |
* |
| 468 |
* |
| 469 |
* An example of a simple valid predicate is the following: given the function |
| 470 |
* @code |
| 471 |
* template <typename BIterator> |
| 472 |
* bool level_equal_to_3 (const BIterator& c) |
| 473 |
* { |
| 474 |
* return (static_cast<unsigned int>(c->level()) == 3); |
| 475 |
* }; |
| 476 |
* @endcode |
| 477 |
* then |
| 478 |
* @code |
| 479 |
* &level_equal_to_3<typename Triangulation<dim>::active_cell_iterator> |
| 480 |
* @endcode |
| 481 |
* is a valid predicate. |
| 482 |
* |
| 483 |
* Likewise, given the following binary function |
| 484 |
* @code |
| 485 |
* template <typename BIterator> |
| 486 |
* bool level_equal_to (const BIterator& c, |
| 487 |
* const unsigned int level) |
| 488 |
* { |
| 489 |
* return (static_cast<unsigned int>(c->level()) == level); |
| 490 |
* }; |
| 491 |
* @endcode |
| 492 |
* then the lambda function |
| 493 |
* @code |
| 494 |
* [](const BIterator& c) { return level_equal_to<active_cell_iterator>(c, |
| 495 |
* 3);} |
| 496 |
* @endcode |
| 497 |
* is another valid predicate (here: a function that returns true if either |
| 498 |
* the iterator is past the end or the level is equal to the second argument; |
| 499 |
* this second argument is taken considered fixed when creating the lambda |
| 500 |
* function). |
| 501 |
* |
| 502 |
* Finally, classes can be predicates. The following class is one: |
| 503 |
* @code |
| 504 |
* class Active |
| 505 |
* { |
| 506 |
* public: |
| 507 |
* template <class Iterator> |
| 508 |
* bool operator () (const Iterator &i) const |
| 509 |
* { |
| 510 |
* return i->is_active(); |
| 511 |
* } |
| 512 |
* }; |
| 513 |
* @endcode |
| 514 |
* and objects of this type can be used as predicates. Likewise, this more |
| 515 |
* complicated one can also be used: |
| 516 |
* @code |
| 517 |
* class SubdomainEqualTo |
| 518 |
* { |
| 519 |
* public: |
| 520 |
* SubdomainEqualTo (const types::subdomain_id subdomain_id) |
| 521 |
* : subdomain_id (subdomain_id) |
| 522 |
* {}; |
| 523 |
* |
| 524 |
* template <class Iterator> |
| 525 |
* bool operator () (const Iterator &i) const |
| 526 |
* { |
| 527 |
* return (i->subdomain_id() == subdomain_id); |
| 528 |
* } |
| 529 |
* |
| 530 |
* private: |
| 531 |
* const types::subdomain_id subdomain_id; |
| 532 |
* }; |
| 533 |
* @endcode |
| 534 |
* Objects like <code>SubdomainEqualTo(3)</code> can then be used as |
| 535 |
* predicates. |
| 536 |
* |
| 537 |
* Since whenever a predicate is evaluated it is checked that the iterator |
| 538 |
* checked is actually valid (i.e. not past the end), no checks for this case |
| 539 |
* have to be performed inside predicates. |
| 540 |
* |
| 541 |
* A number of filter classes are already implemented in the IteratorFilters |
| 542 |
* namespace, but writing different ones is simple following the examples |
| 543 |
* above. |
| 544 |
* |
| 545 |
* |
| 546 |
* <h3>Initialization of filtered iterators</h3> |
| 547 |
* |
| 548 |
* Filtered iterators are given a predicate at construction time which cannot |
| 549 |
* be changed any more. This behavior would be expected if the predicate |
| 550 |
* would have been given as a template parameter to the class, but since that |
| 551 |
* would make the declaration of filtered iterators a nightmare, we rather |
| 552 |
* give the predicate as an unchangeable entity to the constructor. Note that |
| 553 |
* one can assign a filtered iterator with one predicate to another filtered |
| 554 |
* iterator with another type; yet, this does <em>not</em> change the |
| 555 |
* predicate of the assigned-to iterator, only the pointer indicating the |
| 556 |
* iterator is changed. |
| 557 |
* |
| 558 |
* If a filtered iterator is not assigned a value of the underlying |
| 559 |
* (unfiltered) iterator type, the default value is taken. If, however, a |
| 560 |
* value is given to the constructor, that value has either to be past the |
| 561 |
* end, or has to satisfy the predicate. For example, if the predicate only |
| 562 |
* evaluates to true if the level of an object is equal to three, then |
| 563 |
* <code>tria.begin_active(3)</code> would be a valid choice while |
| 564 |
* <code>tria.begin()</code> would not since the latter also returns iterators |
| 565 |
* to non-active cells which always start at level 0. |
| 566 |
* |
| 567 |
* Since one often only has some iterator and wants to set a filtered iterator |
| 568 |
* to the first one that satisfies a predicate (for example, the first one for |
| 569 |
* which the user flag is set, or the first one with a given subdomain id), |
| 570 |
* there are assignment functions #set_to_next_positive and |
| 571 |
* #set_to_previous_positive that assign the next or last previous iterator |
| 572 |
* that satisfies the predicate, i.e. they follow the list of iterators in |
| 573 |
* either direction until they find a matching one (or the past-the-end |
| 574 |
* iterator). Like the <code>operator=</code> they return the resulting value |
| 575 |
* of the filtered iterator. |
| 576 |
* |
| 577 |
* |
| 578 |
* <h3>Examples</h3> |
| 579 |
* |
| 580 |
* The following call counts the number of active cells that have a set user |
| 581 |
* flag: |
| 582 |
* @code |
| 583 |
* FilteredIterator<typename Triangulation<dim>::active_cell_iterator> |
| 584 |
* begin (IteratorFilters::UserFlagSet()), |
| 585 |
* end (IteratorFilters::UserFlagSet()); |
| 586 |
* begin.set_to_next_positive(tria.begin_active()); |
| 587 |
* end = tria.end(); |
| 588 |
* n_flagged_cells = std::distance (begin, end); |
| 589 |
* @endcode |
| 590 |
* Note that by the @p set_to_next_positive call the first cell with a set |
| 591 |
* user flag was assigned to the @p begin iterator. For the end iterator, no |
| 592 |
* such call was necessary, since the past-the-end iterator always satisfies |
| 593 |
* all predicates. |
| 594 |
* |
| 595 |
* The same can be achieved by the following snippet, though harder to read: |
| 596 |
* @code |
| 597 |
* using FI = |
| 598 |
* FilteredIterator<typename Triangulation<dim>::active_cell_iterator>; |
| 599 |
* n_flagged_cells = |
| 600 |
* std::distance ( |
| 601 |
* FI(IteratorFilters::UserFlagSet()).set_to_next_positive( |
| 602 |
* tria.begin_active()), |
| 603 |
* FI(IteratorFilters::UserFlagSet(), tria.end())); |
| 604 |
* @endcode |
| 605 |
* It relies on the fact that if we create an unnamed filtered iterator with a |
| 606 |
* given predicate but no iterator value and assign it the next positive value |
| 607 |
* with respect to this predicate, it returns itself which is then used as the |
| 608 |
* first parameter to the @p std::distance function. This procedure is not |
| 609 |
* necessary for the end element to this function here, since the past-the-end |
| 610 |
* iterator always satisfies the predicate so that we can assign this value to |
| 611 |
* the filtered iterator directly in the constructor. |
| 612 |
* |
| 613 |
* Finally, the following loop only assembles the matrix on cells with |
| 614 |
* subdomain id equal to three: |
| 615 |
* @code |
| 616 |
* FilteredIterator<typename Triangulation<dim>::active_cell_iterator> |
| 617 |
* cell (IteratorFilters::SubdomainEqualTo(3)), |
| 618 |
* endc (IteratorFilters::SubdomainEqualTo(3), tria.end()); |
| 619 |
* cell.set_to_next_positive (tria.begin_active()); |
| 620 |
* for (; cell!=endc; ++cell) |
| 621 |
* assemble_local_matrix (cell); |
| 622 |
* @endcode |
| 623 |
* |
| 624 |
* Since comparison between filtered and unfiltered iterators is defined, we |
| 625 |
* could as well have let the @p endc variable in the last example be of type |
| 626 |
* Triangulation::active_cell_iterator since it is unchanged and its value |
| 627 |
* does not depend on the filter. |
| 628 |
* |
| 629 |
* @ingroup grid |
| 630 |
* @ingroup Iterators |
| 631 |
*/ |
| 632 |
template <typename BaseIterator> |
| 633 |
class FilteredIterator : public BaseIterator |
| 634 |
{ |
| 635 |
public: |
| 636 |
/** |
| 637 |
* Typedef to the accessor type of the underlying iterator. |
| 638 |
*/ |
| 639 |
using AccessorType = typename BaseIterator::AccessorType; |
| 640 |
|
| 641 |
/** |
| 642 |
* Constructor. Set the iterator to the default state and use the given |
| 643 |
* predicate for filtering subsequent assignment and iteration. |
| 644 |
* |
| 645 |
* @dealiiConceptRequires{(std::predicate<Predicate, BaseIterator>)} |
| 646 |
*/ |
| 647 |
template <typename Predicate> |
| 648 |
DEAL_II_CXX20_REQUIRES((std::predicate<Predicate, BaseIterator>)) |
| 649 |
FilteredIterator(Predicate p); |
| 650 |
|
| 651 |
/** |
| 652 |
* Constructor. Use the given predicate for filtering and initialize the |
| 653 |
* iterator with the given value. |
| 654 |
* |
| 655 |
* If the initial value @p bi does not satisfy the predicate @p p then it is |
| 656 |
* advanced until we either hit the past-the-end iterator, or the |
| 657 |
* predicate is satisfied. This allows, for example, to write code like |
| 658 |
* @code |
| 659 |
* FilteredIterator<typename Triangulation<dim>::active_cell_iterator> |
| 660 |
* cell (IteratorFilters::SubdomainEqualTo(13), |
| 661 |
* triangulation.begin_active()); |
| 662 |
* @endcode |
| 663 |
* |
| 664 |
* If the cell <code>triangulation.begin_active()</code> does not have a |
| 665 |
* subdomain_id equal to 13, then the iterator will automatically be |
| 666 |
* advanced to the first cell that has. |
| 667 |
* |
| 668 |
* @dealiiConceptRequires{(std::predicate<Predicate, BaseIterator>)} |
| 669 |
*/ |
| 670 |
template <typename Predicate> |
| 671 |
DEAL_II_CXX20_REQUIRES((std::predicate<Predicate, BaseIterator>)) |
| 672 |
FilteredIterator(Predicate p, const BaseIterator &bi); |
| 673 |
|
| 674 |
/** |
| 675 |
* Copy constructor. Copy the predicate and iterator value of the given |
| 676 |
* argument. |
| 677 |
*/ |
| 678 |
FilteredIterator(const FilteredIterator &fi); |
| 679 |
|
| 680 |
/** |
| 681 |
* Assignment operator. Copy the iterator value of the argument, but as |
| 682 |
* discussed in the class documentation, the predicate of the argument is |
| 683 |
* not copied. The iterator value underlying the argument has to satisfy the |
| 684 |
* predicate of the object assigned to, as given at its construction time. |
| 685 |
*/ |
| 686 |
FilteredIterator & |
| 687 |
operator=(const FilteredIterator &fi); |
| 688 |
|
| 689 |
/** |
| 690 |
* Assignment operator. Copy the iterator value of the argument, and keep |
| 691 |
* the predicate of this object. The given iterator value has to satisfy the |
| 692 |
* predicate of the object assigned to, as given at its construction time. |
| 693 |
*/ |
| 694 |
FilteredIterator & |
| 695 |
operator=(const BaseIterator &fi); |
| 696 |
|
| 697 |
/** |
| 698 |
* Search for the next iterator from @p bi onwards that satisfies the |
| 699 |
* predicate of this object and assign it to this object. |
| 700 |
* |
| 701 |
* Since filtered iterators are automatically converted to the underlying |
| 702 |
* base iterator type, you can also give a filtered iterator as argument to |
| 703 |
* this function. |
| 704 |
*/ |
| 705 |
FilteredIterator & |
| 706 |
set_to_next_positive(const BaseIterator &bi); |
| 707 |
|
| 708 |
/** |
| 709 |
* As above, but search for the previous iterator from @p bi backwards that |
| 710 |
* satisfies the predicate of this object and assign it to this object. |
| 711 |
* |
| 712 |
* Since filtered iterators are automatically converted to the underlying |
| 713 |
* base iterator type, you can also give a filtered iterator as argument to |
| 714 |
* this function. |
| 715 |
*/ |
| 716 |
FilteredIterator & |
| 717 |
set_to_previous_positive(const BaseIterator &bi); |
| 718 |
|
| 719 |
/** |
| 720 |
* Compare for equality of the underlying iterator values of this and the |
| 721 |
* given object. |
| 722 |
* |
| 723 |
* We do not compare for equality of the predicates. |
| 724 |
*/ |
| 725 |
bool |
| 726 |
operator==(const FilteredIterator &fi) const; |
| 727 |
|
| 728 |
/** |
| 729 |
* Compare for equality of the underlying iterator value of this object with |
| 730 |
* the given object. |
| 731 |
* |
| 732 |
* The predicate of this object is irrelevant for this operation. |
| 733 |
*/ |
| 734 |
bool |
| 735 |
operator==(const BaseIterator &fi) const; |
| 736 |
|
| 737 |
/** |
| 738 |
* Compare for inequality of the underlying iterator values of this and the |
| 739 |
* given object. |
| 740 |
* |
| 741 |
* We do not compare for equality of the predicates. |
| 742 |
*/ |
| 743 |
bool |
| 744 |
operator!=(const FilteredIterator &fi) const; |
| 745 |
|
| 746 |
/** |
| 747 |
* Compare for inequality of the underlying iterator value of this object |
| 748 |
* with the given object. |
| 749 |
* |
| 750 |
* The predicate of this object is irrelevant for this operation. |
| 751 |
*/ |
| 752 |
bool |
| 753 |
operator!=(const BaseIterator &fi) const; |
| 754 |
|
| 755 |
/** |
| 756 |
* Compare for ordering of the underlying iterator values of this and the |
| 757 |
* given object. |
| 758 |
* |
| 759 |
* We do not compare the predicates. |
| 760 |
*/ |
| 761 |
bool |
| 762 |
operator<(const FilteredIterator &fi) const; |
| 763 |
|
| 764 |
/** |
| 765 |
* Compare for ordering of the underlying iterator value of this object with |
| 766 |
* the given object. |
| 767 |
* |
| 768 |
* The predicate of this object is irrelevant for this operation. |
| 769 |
*/ |
| 770 |
bool |
| 771 |
operator<(const BaseIterator &fi) const; |
| 772 |
|
| 773 |
/** |
| 774 |
* Prefix advancement operator: move to the next iterator value satisfying |
| 775 |
* the predicate and return the new iterator value. |
| 776 |
*/ |
| 777 |
FilteredIterator & |
| 778 |
operator++(); |
| 779 |
|
| 780 |
/** |
| 781 |
* Postfix advancement operator: move to the next iterator value satisfying |
| 782 |
* the predicate and return the old iterator value. |
| 783 |
*/ |
| 784 |
FilteredIterator |
| 785 |
operator++(int); |
| 786 |
|
| 787 |
/** |
| 788 |
* Prefix decrement operator: move to the previous iterator value satisfying |
| 789 |
* the predicate and return the new iterator value. |
| 790 |
*/ |
| 791 |
FilteredIterator & |
| 792 |
operator--(); |
| 793 |
|
| 794 |
/** |
| 795 |
* Postfix advancement operator: move to the previous iterator value |
| 796 |
* satisfying the predicate and return the old iterator value. |
| 797 |
*/ |
| 798 |
FilteredIterator |
| 799 |
operator--(int); |
| 800 |
|
| 801 |
/** |
| 802 |
* Exception. |
| 803 |
*/ |
| 804 |
DeclException1( |
| 805 |
ExcInvalidElement, |
| 806 |
BaseIterator, |
| 807 |
<< "The element " << arg1 |
| 808 |
<< " with which you want to compare or which you want to" |
| 809 |
<< " assign from is invalid since it does not satisfy the predicate."); |
| 810 |
|
| 811 |
private: |
| 812 |
/** |
| 813 |
* Base class to encapsulate a predicate object. Since predicates can be of |
| 814 |
* different types and we do not want to code these types into the template |
| 815 |
* parameter list of the filtered iterator class, we use a base class with |
| 816 |
* an abstract function and templatized derived classes that implement the |
| 817 |
* use of actual predicate types through the virtual function. |
| 818 |
* |
| 819 |
* @ingroup Iterators |
| 820 |
*/ |
| 821 |
class PredicateBase |
| 822 |
{ |
| 823 |
public: |
| 824 |
/** |
| 825 |
* Mark the destructor virtual to allow destruction through pointers to |
| 826 |
* the base class. |
| 827 |
*/ |
| 828 |
virtual ~PredicateBase() = default; |
| 829 |
|
| 830 |
/** |
| 831 |
* Abstract function which in derived classes denotes the evaluation of |
| 832 |
* the predicate on the given iterator. |
| 833 |
*/ |
| 834 |
virtual bool |
| 835 |
operator()(const BaseIterator &bi) const = 0; |
| 836 |
|
| 837 |
/** |
| 838 |
* Generate a copy of this object, i.e. of the actual type of this |
| 839 |
* pointer. |
| 840 |
*/ |
| 841 |
virtual std::unique_ptr<PredicateBase> |
| 842 |
clone() const = 0; |
| 843 |
}; |
| 844 |
|
| 845 |
|
| 846 |
/** |
| 847 |
* Actual implementation of the above abstract base class. Use a template |
| 848 |
* parameter to denote the actual type of the predicate and store a copy of |
| 849 |
* it. When the virtual function is called evaluate the given iterator with |
| 850 |
* the stored copy of the predicate. |
| 851 |
* |
| 852 |
* @ingroup Iterators |
| 853 |
*/ |
| 854 |
template <typename Predicate> |
| 855 |
class PredicateTemplate : public PredicateBase |
| 856 |
{ |
| 857 |
public: |
| 858 |
/** |
| 859 |
* Constructor. Take a predicate and store a copy of it. |
| 860 |
*/ |
| 861 |
PredicateTemplate(const Predicate &predicate); |
| 862 |
|
| 863 |
/** |
| 864 |
* Evaluate the iterator with the stored copy of the predicate. |
| 865 |
*/ |
| 866 |
virtual bool |
| 867 |
operator()(const BaseIterator &bi) const override; |
| 868 |
|
| 869 |
/** |
| 870 |
* Generate a copy of this object, i.e. of the actual type of this |
| 871 |
* pointer. |
| 872 |
*/ |
| 873 |
virtual std::unique_ptr<PredicateBase> |
| 874 |
clone() const override; |
| 875 |
|
| 876 |
private: |
| 877 |
/** |
| 878 |
* Copy of the predicate. |
| 879 |
*/ |
| 880 |
const Predicate predicate; |
| 881 |
}; |
| 882 |
|
| 883 |
/** |
| 884 |
* Pointer to an object that encapsulated the actual data type of the |
| 885 |
* predicate given to the constructor. |
| 886 |
*/ |
| 887 |
std::unique_ptr<const PredicateBase> predicate; |
| 888 |
}; |
| 889 |
|
| 890 |
|
| 891 |
|
| 892 |
/** |
| 893 |
* Create an object of type FilteredIterator given the base iterator and |
| 894 |
* predicate. This function makes the creation of temporary objects (for |
| 895 |
* example as function arguments) a lot simpler because one does not have to |
| 896 |
* explicitly specify the type of the base iterator by hand -- it is deduced |
| 897 |
* automatically here. |
| 898 |
* |
| 899 |
* @relatesalso FilteredIterator |
| 900 |
* |
| 901 |
* @dealiiConceptRequires{(std::predicate<Predicate, BaseIterator>)} |
| 902 |
*/ |
| 903 |
template <typename BaseIterator, typename Predicate> |
| 904 |
DEAL_II_CXX20_REQUIRES((std::predicate<Predicate, BaseIterator>)) |
| 905 |
FilteredIterator<BaseIterator> make_filtered_iterator(const BaseIterator &i, |
| 906 |
const Predicate &p) |
| 907 |
{ |
| 908 |
FilteredIterator<BaseIterator> fi(p); |
| 909 |
fi.set_to_next_positive(i); |
| 910 |
return fi; |
| 911 |
} |
| 912 |
|
| 913 |
|
| 914 |
|
| 915 |
namespace internal |
| 916 |
{ |
| 917 |
namespace FilteredIteratorImplementation |
| 918 |
{ |
| 919 |
// The following classes create a nested sequence of |
| 920 |
// FilteredIterator<FilteredIterator<...<BaseIterator>...>> with as many |
| 921 |
// levels of FilteredIterator classes as there are elements in the TypeList |
| 922 |
// if the latter is given as a std::tuple<Args...>. |
| 923 |
template <typename BaseIterator, typename TypeList> |
| 924 |
struct NestFilteredIterators; |
| 925 |
|
| 926 |
template <typename BaseIterator, typename Predicate> |
| 927 |
struct NestFilteredIterators<BaseIterator, std::tuple<Predicate>> |
| 928 |
{ |
| 929 |
using type = ::dealii::FilteredIterator<BaseIterator>; |
| 930 |
}; |
| 931 |
|
| 932 |
template <typename BaseIterator, typename Predicate, typename... Targs> |
| 933 |
struct NestFilteredIterators<BaseIterator, std::tuple<Predicate, Targs...>> |
| 934 |
{ |
| 935 |
using type = ::dealii::FilteredIterator< |
| 936 |
typename NestFilteredIterators<BaseIterator, |
| 937 |
std::tuple<Targs...>>::type>; |
| 938 |
}; |
| 939 |
} // namespace FilteredIteratorImplementation |
| 940 |
} // namespace internal |
| 941 |
|
| 942 |
|
| 943 |
|
| 944 |
/** |
| 945 |
* Filter the given range of iterators using a Predicate. This allows to |
| 946 |
* replace: |
| 947 |
* @code |
| 948 |
* DoFHandler<dim> dof_handler; |
| 949 |
* ... |
| 950 |
* for (const auto &cell : dof_handler.active_cell_iterators()) |
| 951 |
* { |
| 952 |
* if (cell->is_locally_owned()) |
| 953 |
* { |
| 954 |
* fe_values.reinit (cell); |
| 955 |
* ...do the local integration on 'cell'...; |
| 956 |
* } |
| 957 |
* } |
| 958 |
* @endcode |
| 959 |
* by: |
| 960 |
* @code |
| 961 |
* DoFHandler<dim> dof_handler; |
| 962 |
* ... |
| 963 |
* const auto filtered_iterators_range = |
| 964 |
* filter_iterators(dof_handler.active_cell_iterators(), |
| 965 |
* IteratorFilters::LocallyOwnedCell()); |
| 966 |
* for (const auto &cell : filtered_iterators_range) |
| 967 |
* { |
| 968 |
* fe_values.reinit (cell); |
| 969 |
* ...do the local integration on 'cell'...; |
| 970 |
* } |
| 971 |
* @endcode |
| 972 |
* |
| 973 |
* @note This function is obsolete and should be replaced by calling |
| 974 |
* `operator|` instead. The latter is certainly more in the |
| 975 |
* spirit of |
| 976 |
* [C++20 range |
| 977 |
* adaptors](https://en.cppreference.com/w/cpp/ranges/filter_view) and results |
| 978 |
* in the following code instead of the one shown above: |
| 979 |
* @code |
| 980 |
* DoFHandler<dim> dof_handler; |
| 981 |
* ... |
| 982 |
* for (const auto &cell : |
| 983 |
* dof_handler.active_cell_iterators() |
| 984 |
* | IteratorFilters::LocallyOwnedCell()) |
| 985 |
* { |
| 986 |
* fe_values.reinit (cell); |
| 987 |
* ...do the local integration on 'cell'...; |
| 988 |
* } |
| 989 |
* @endcode |
| 990 |
* |
| 991 |
* @relatesalso FilteredIterator |
| 992 |
* @ingroup CPP11 |
| 993 |
* |
| 994 |
* @dealiiConceptRequires{(std::predicate<Predicate, BaseIterator>)} |
| 995 |
*/ |
| 996 |
template <typename BaseIterator, typename Predicate> |
| 997 |
DEAL_II_CXX20_REQUIRES((std::predicate<Predicate, BaseIterator>)) |
| 998 |
inline IteratorRange<FilteredIterator<BaseIterator>> filter_iterators( |
| 999 |
IteratorRange<BaseIterator> i, |
| 1000 |
const Predicate &p) |
| 1001 |
{ |
| 1002 |
FilteredIterator<BaseIterator> fi(p, *(i.begin())); |
| 1003 |
FilteredIterator<BaseIterator> fi_end(p, *(i.end())); |
| 1004 |
|
| 1005 |
return IteratorRange<FilteredIterator<BaseIterator>>(fi, fi_end); |
| 1006 |
} |
| 1007 |
|
| 1008 |
|
| 1009 |
|
| 1010 |
/** |
| 1011 |
* Filter the given range of iterators through an arbitrary number of |
| 1012 |
* Predicates. This allows to replace: |
| 1013 |
* @code |
| 1014 |
* DoFHandler<dim> dof_handler; |
| 1015 |
* ... |
| 1016 |
* for (const auto &cell : dof_handler.active_cell_iterators()) |
| 1017 |
* { |
| 1018 |
* if (cell->is_locally_owned()) |
| 1019 |
* { |
| 1020 |
* if (cell->at_boundary()) |
| 1021 |
* { |
| 1022 |
* fe_values.reinit (cell); |
| 1023 |
* ...do the local integration on 'cell'...; |
| 1024 |
* } |
| 1025 |
* } |
| 1026 |
* } |
| 1027 |
* @endcode |
| 1028 |
* by: |
| 1029 |
* @code |
| 1030 |
* DoFHandler<dim> dof_handler; |
| 1031 |
* ... |
| 1032 |
* const auto filtered_iterators_range = |
| 1033 |
* filter_iterators(dof_handler.active_cell_iterators(), |
| 1034 |
* IteratorFilters::LocallyOwnedCell(), |
| 1035 |
* IteratorFilters::AtBoundary()); |
| 1036 |
* for (const auto &cell : filter_iterators_range) |
| 1037 |
* { |
| 1038 |
* fe_values.reinit (cell); |
| 1039 |
* ...do the local integration on 'cell'...; |
| 1040 |
* } |
| 1041 |
* @endcode |
| 1042 |
* |
| 1043 |
* @note This function is obsolete and should be replaced by calling |
| 1044 |
* `operator|` once or multiple times instead. |
| 1045 |
* The latter is certainly more in the spirit of |
| 1046 |
* [C++20 range |
| 1047 |
* adaptors](https://en.cppreference.com/w/cpp/ranges/filter_view) and results |
| 1048 |
* in the following code instead of the one shown above: |
| 1049 |
* @code |
| 1050 |
* DoFHandler<dim> dof_handler; |
| 1051 |
* ... |
| 1052 |
* for (const auto &cell : |
| 1053 |
* dof_handler.active_cell_iterators() |
| 1054 |
* | IteratorFilters::LocallyOwnedCell() |
| 1055 |
* | IteratorFilters::AtBoundary()) |
| 1056 |
* { |
| 1057 |
* fe_values.reinit (cell); |
| 1058 |
* ...do the local integration on 'cell'...; |
| 1059 |
* } |
| 1060 |
* @endcode |
| 1061 |
* |
| 1062 |
* @relatesalso FilteredIterator |
| 1063 |
* @ingroup CPP11 |
| 1064 |
* |
| 1065 |
* @dealiiConceptRequires{(std::predicate<Predicate, BaseIterator>)} |
| 1066 |
*/ |
| 1067 |
template <typename BaseIterator, typename Predicate, typename... Targs> |
| 1068 |
DEAL_II_CXX20_REQUIRES((std::predicate<Predicate, BaseIterator>)) |
| 1069 |
IteratorRange< |
| 1070 |
typename internal::FilteredIteratorImplementation:: |
| 1071 |
NestFilteredIterators<BaseIterator, std::tuple<Predicate, Targs...>>:: |
| 1072 |
type> filter_iterators(IteratorRange<BaseIterator> i, |
| 1073 |
const Predicate &p, |
| 1074 |
const Targs... args) |
| 1075 |
{ |
| 1076 |
// Recursively create filtered iterators, one predicate at a time |
| 1077 |
auto fi = filter_iterators(i, p); |
| 1078 |
return filter_iterators(fi, args...); |
| 1079 |
} |
| 1080 |
|
| 1081 |
|
| 1082 |
|
| 1083 |
/** |
| 1084 |
* Filter the given range of iterators using a predicate. This allows to |
| 1085 |
* replace: |
| 1086 |
* @code |
| 1087 |
* DoFHandler<dim> dof_handler; |
| 1088 |
* ... |
| 1089 |
* for (const auto &cell : dof_handler.active_cell_iterators()) |
| 1090 |
* { |
| 1091 |
* if (cell->is_locally_owned()) |
| 1092 |
* { |
| 1093 |
* fe_values.reinit (cell); |
| 1094 |
* ...do the local integration on 'cell'...; |
| 1095 |
* } |
| 1096 |
* } |
| 1097 |
* @endcode |
| 1098 |
* by: |
| 1099 |
* @code |
| 1100 |
* DoFHandler<dim> dof_handler; |
| 1101 |
* ... |
| 1102 |
* const auto filtered_iterators_range = |
| 1103 |
* filter_iterators(); |
| 1104 |
* for (const auto &cell : |
| 1105 |
* dof_handler.active_cell_iterators() | IteratorFilters::LocallyOwnedCell()) |
| 1106 |
* { |
| 1107 |
* fe_values.reinit (cell); |
| 1108 |
* ...do the local integration on 'cell'...; |
| 1109 |
* } |
| 1110 |
* @endcode |
| 1111 |
* Here, the `operator|` is to be interpreted in the same way as is done in |
| 1112 |
* the [range adaptors](https://en.cppreference.com/w/cpp/ranges) feature |
| 1113 |
* that is part of [C++20](https://en.wikipedia.org/wiki/C%2B%2B20). It has |
| 1114 |
* the same meaning as the `|` symbol on the command line: It takes what is |
| 1115 |
* on its left as its inputs, and filters and transforms to produce some |
| 1116 |
* output. In the example above, it "filters" all of the active cell iterators |
| 1117 |
* and removes those that do not satisfy the predicate -- that is, it produces |
| 1118 |
* a range of iterators that only contains those cells that are both active |
| 1119 |
* and locally owned. |
| 1120 |
* |
| 1121 |
* @note The `|` operator can be applied more than once. This results in code |
| 1122 |
* such as the following: |
| 1123 |
* @code |
| 1124 |
* DoFHandler<dim> dof_handler; |
| 1125 |
* ... |
| 1126 |
* for (const auto &cell : |
| 1127 |
* dof_handler.active_cell_iterators() |
| 1128 |
* | IteratorFilters::LocallyOwnedCell() |
| 1129 |
* | IteratorFilters::AtBoundary()) |
| 1130 |
* { |
| 1131 |
* fe_values.reinit (cell); |
| 1132 |
* ...do the local integration on 'cell'...; |
| 1133 |
* } |
| 1134 |
* @endcode |
| 1135 |
* In this code, the loop executes over all active cells that are both |
| 1136 |
* locally owned and located at the boundary. |
| 1137 |
* |
| 1138 |
* @relatesalso FilteredIterator |
| 1139 |
* @ingroup CPP11 |
| 1140 |
* |
| 1141 |
* @dealiiConceptRequires{(std::predicate<Predicate, BaseIterator>)} |
| 1142 |
*/ |
| 1143 |
template <typename BaseIterator, typename Predicate> |
| 1144 |
DEAL_II_CXX20_REQUIRES((std::predicate<Predicate, BaseIterator>)) |
| 1145 |
inline IteratorRange<FilteredIterator<BaseIterator>> |
| 1146 |
operator|(IteratorRange<BaseIterator> i, const Predicate &p) |
| 1147 |
{ |
| 1148 |
return filter_iterators(i, p); |
| 1149 |
} |
| 1150 |
|
| 1151 |
|
| 1152 |
|
| 1153 |
/* ------------------ Inline functions and templates ------------ */ |
| 1154 |
|
| 1155 |
|
| 1156 |
template <typename BaseIterator> |
| 1157 |
template <typename Predicate> |
| 1158 |
DEAL_II_CXX20_REQUIRES((std::predicate<Predicate, BaseIterator>)) |
| 1159 |
inline FilteredIterator<BaseIterator>::FilteredIterator(Predicate p) |
| 1160 |
: predicate(new PredicateTemplate<Predicate>(p)) |
| 1161 |
{} |
| 1162 |
|
| 1163 |
|
| 1164 |
|
| 1165 |
template <typename BaseIterator> |
| 1166 |
template <typename Predicate> |
| 1167 |
DEAL_II_CXX20_REQUIRES((std::predicate<Predicate, BaseIterator>)) |
| 1168 |
inline FilteredIterator<BaseIterator>::FilteredIterator(Predicate p, |
| 1169 |
const BaseIterator &bi) |
| 1170 |
: BaseIterator(bi) |
| 1171 |
, predicate(new PredicateTemplate<Predicate>(p)) |
| 1172 |
{ |
| 1173 |
if ((this->state() == IteratorState::valid) && !(*predicate)(*this)) |
| 1174 |
set_to_next_positive(bi); |
| 1175 |
} |
| 1176 |
|
| 1177 |
|
| 1178 |
|
| 1179 |
template <typename BaseIterator> |
| 1180 |
inline FilteredIterator<BaseIterator>::FilteredIterator( |
| 1181 |
const FilteredIterator &fi) |
| 1182 |
: // this construction looks strange, but without going through the |
| 1183 |
// address of fi, GCC would not cast fi to the base class of type |
| 1184 |
// BaseIterator but tries to go through constructing a new |
| 1185 |
// BaseIterator with an Accessor. |
| 1186 |
BaseIterator(*static_cast<const BaseIterator *>(&fi)) |
| 1187 |
, predicate(fi.predicate->clone()) |
| 1188 |
{} |
| 1189 |
|
| 1190 |
|
| 1191 |
|
| 1192 |
template <typename BaseIterator> |
| 1193 |
inline FilteredIterator<BaseIterator> & |
| 1194 |
FilteredIterator<BaseIterator>::operator=(const FilteredIterator &fi) |
| 1195 |
{ |
| 1196 |
// Using equivalent code to the one for 'operator=(const BaseIterator &bi)' |
| 1197 |
// below, some compiler would not cast fi to the base class of type |
| 1198 |
// BaseIterator but try to go through constructing a new Accessor from fi |
| 1199 |
// which fails. Hence, we just use an explicit upcast and call the above- |
| 1200 |
// mentioned method. |
| 1201 |
const BaseIterator &bi = fi; |
| 1202 |
return operator=(bi); |
| 1203 |
} |
| 1204 |
|
| 1205 |
|
| 1206 |
|
| 1207 |
template <typename BaseIterator> |
| 1208 |
inline FilteredIterator<BaseIterator> & |
| 1209 |
FilteredIterator<BaseIterator>::operator=(const BaseIterator &bi) |
| 1210 |
{ |
| 1211 |
Assert((bi.state() != IteratorState::valid) || (*predicate)(bi), |
| 1212 |
ExcInvalidElement(bi)); |
| 1213 |
BaseIterator::operator=(bi); |
| 1214 |
return *this; |
| 1215 |
} |
| 1216 |
|
| 1217 |
|
| 1218 |
|
| 1219 |
template <typename BaseIterator> |
| 1220 |
inline FilteredIterator<BaseIterator> & |
| 1221 |
FilteredIterator<BaseIterator>::set_to_next_positive(const BaseIterator &bi) |
| 1222 |
{ |
| 1223 |
BaseIterator::operator=(bi); |
| 1224 |
while ((this->state() == IteratorState::valid) && (!(*predicate)(*this))) |
| 1225 |
BaseIterator::operator++(); |
| 1226 |
|
| 1227 |
return *this; |
| 1228 |
} |
| 1229 |
|
| 1230 |
|
| 1231 |
|
| 1232 |
template <typename BaseIterator> |
| 1233 |
inline FilteredIterator<BaseIterator> & |
| 1234 |
FilteredIterator<BaseIterator>::set_to_previous_positive(const BaseIterator &bi) |
| 1235 |
{ |
| 1236 |
BaseIterator::operator=(bi); |
| 1237 |
while ((this->state() == IteratorState::valid) && (!(*predicate)(*this))) |
| 1238 |
BaseIterator::operator--(); |
| 1239 |
|
| 1240 |
return *this; |
| 1241 |
} |
| 1242 |
|
| 1243 |
|
| 1244 |
|
| 1245 |
template <typename BaseIterator> |
| 1246 |
inline bool |
| 1247 |
FilteredIterator<BaseIterator>::operator==(const FilteredIterator &fi) const |
| 1248 |
{ |
| 1249 |
return (static_cast<const BaseIterator &>(*this) == |
| 1250 |
static_cast<const BaseIterator &>(fi)); |
| 1251 |
} |
| 1252 |
|
| 1253 |
|
| 1254 |
|
| 1255 |
template <typename BaseIterator> |
| 1256 |
inline bool |
| 1257 |
FilteredIterator<BaseIterator>::operator!=(const FilteredIterator &fi) const |
| 1258 |
{ |
| 1259 |
return (static_cast<const BaseIterator &>(*this) != |
| 1260 |
static_cast<const BaseIterator &>(fi)); |
| 1261 |
} |
| 1262 |
|
| 1263 |
|
| 1264 |
|
| 1265 |
template <typename BaseIterator> |
| 1266 |
inline bool |
| 1267 |
FilteredIterator<BaseIterator>::operator<(const FilteredIterator &fi) const |
| 1268 |
{ |
| 1269 |
return (static_cast<const BaseIterator &>(*this) < |
| 1270 |
static_cast<const BaseIterator &>(fi)); |
| 1271 |
} |
| 1272 |
|
| 1273 |
|
| 1274 |
|
| 1275 |
template <typename BaseIterator> |
| 1276 |
inline bool |
| 1277 |
FilteredIterator<BaseIterator>::operator==(const BaseIterator &bi) const |
| 1278 |
{ |
| 1279 |
return (static_cast<const BaseIterator &>(*this) == bi); |
| 1280 |
} |
| 1281 |
|
| 1282 |
|
| 1283 |
|
| 1284 |
template <typename BaseIterator> |
| 1285 |
inline bool |
| 1286 |
FilteredIterator<BaseIterator>::operator!=(const BaseIterator &bi) const |
| 1287 |
{ |
| 1288 |
return (static_cast<const BaseIterator &>(*this) != bi); |
| 1289 |
} |
| 1290 |
|
| 1291 |
|
| 1292 |
|
| 1293 |
template <typename BaseIterator> |
| 1294 |
inline bool |
| 1295 |
FilteredIterator<BaseIterator>::operator<(const BaseIterator &bi) const |
| 1296 |
{ |
| 1297 |
return (static_cast<const BaseIterator &>(*this) < bi); |
| 1298 |
} |
| 1299 |
|
| 1300 |
|
| 1301 |
template <typename BaseIterator> |
| 1302 |
inline FilteredIterator<BaseIterator> & |
| 1303 |
FilteredIterator<BaseIterator>::operator++() |
| 1304 |
{ |
| 1305 |
if (this->state() == IteratorState::valid) |
| 1306 |
do |
| 1307 |
BaseIterator::operator++(); |
| 1308 |
while ((this->state() == IteratorState::valid) && !(*predicate)(*this)); |
| 1309 |
return *this; |
| 1310 |
} |
| 1311 |
|
| 1312 |
|
| 1313 |
|
| 1314 |
template <typename BaseIterator> |
| 1315 |
inline FilteredIterator<BaseIterator> |
| 1316 |
FilteredIterator<BaseIterator>::operator++(int) |
| 1317 |
{ |
| 1318 |
const FilteredIterator old_state = *this; |
| 1319 |
|
| 1320 |
if (this->state() == IteratorState::valid) |
| 1321 |
do |
| 1322 |
BaseIterator::operator++(); |
| 1323 |
while ((this->state() == IteratorState::valid) && !(*predicate)(*this)); |
| 1324 |
return old_state; |
| 1325 |
} |
| 1326 |
|
| 1327 |
|
| 1328 |
|
| 1329 |
template <typename BaseIterator> |
| 1330 |
inline FilteredIterator<BaseIterator> & |
| 1331 |
FilteredIterator<BaseIterator>::operator--() |
| 1332 |
{ |
| 1333 |
if (this->state() == IteratorState::valid) |
| 1334 |
do |
| 1335 |
BaseIterator::operator--(); |
| 1336 |
while ((this->state() == IteratorState::valid) && !(*predicate)(*this)); |
| 1337 |
return *this; |
| 1338 |
} |
| 1339 |
|
| 1340 |
|
| 1341 |
|
| 1342 |
template <typename BaseIterator> |
| 1343 |
inline FilteredIterator<BaseIterator> |
| 1344 |
FilteredIterator<BaseIterator>::operator--(int) |
| 1345 |
{ |
| 1346 |
const FilteredIterator old_state = *this; |
| 1347 |
|
| 1348 |
if (this->state() == IteratorState::valid) |
| 1349 |
do |
| 1350 |
BaseIterator::operator--(); |
| 1351 |
while ((this->state() == IteratorState::valid) && !(*predicate)(*this)); |
| 1352 |
return old_state; |
| 1353 |
} |
| 1354 |
|
| 1355 |
|
| 1356 |
|
| 1357 |
template <typename BaseIterator> |
| 1358 |
template <typename Predicate> |
| 1359 |
inline FilteredIterator<BaseIterator>::PredicateTemplate< |
| 1360 |
Predicate>::PredicateTemplate(const Predicate &predicate) |
| 1361 |
: predicate(predicate) |
| 1362 |
{} |
| 1363 |
|
| 1364 |
|
| 1365 |
|
| 1366 |
template <typename BaseIterator> |
| 1367 |
template <typename Predicate> |
| 1368 |
bool |
| 1369 |
FilteredIterator<BaseIterator>::PredicateTemplate<Predicate>::operator()( |
| 1370 |
const BaseIterator &bi) const |
| 1371 |
{ |
| 1372 |
return predicate(bi); |
| 1373 |
} |
| 1374 |
|
| 1375 |
|
| 1376 |
|
| 1377 |
template <typename BaseIterator> |
| 1378 |
template <typename Predicate> |
| 1379 |
std::unique_ptr<typename FilteredIterator<BaseIterator>::PredicateBase> |
| 1380 |
FilteredIterator<BaseIterator>::PredicateTemplate<Predicate>::clone() const |
| 1381 |
{ |
| 1382 |
return std::make_unique<PredicateTemplate>(predicate); |
| 1383 |
} |
| 1384 |
|
| 1385 |
|
| 1386 |
|
| 1387 |
namespace IteratorFilters |
| 1388 |
{ |
| 1389 |
// ---------------- IteratorFilters::Active --------- |
| 1390 |
|
| 1391 |
template <class Iterator> |
| 1392 |
inline bool |
| 1393 |
Active::operator()(const Iterator &i) const |
| 1394 |
{ |
| 1395 |
return i->is_active(); |
| 1396 |
} |
| 1397 |
|
| 1398 |
|
| 1399 |
// ---------------- IteratorFilters::UserFlagSet --------- |
| 1400 |
|
| 1401 |
template <class Iterator> |
| 1402 |
inline bool |
| 1403 |
UserFlagSet::operator()(const Iterator &i) const |
| 1404 |
{ |
| 1405 |
return (i->user_flag_set()); |
| 1406 |
} |
| 1407 |
|
| 1408 |
|
| 1409 |
// ---------------- IteratorFilters::UserFlagNotSet --------- |
| 1410 |
|
| 1411 |
template <class Iterator> |
| 1412 |
inline bool |
| 1413 |
UserFlagNotSet::operator()(const Iterator &i) const |
| 1414 |
{ |
| 1415 |
return (!i->user_flag_set()); |
| 1416 |
} |
| 1417 |
|
| 1418 |
|
| 1419 |
// ---------------- IteratorFilters::LevelEqualTo --------- |
| 1420 |
inline LevelEqualTo::LevelEqualTo(const unsigned int level) |
| 1421 |
: level(level) |
| 1422 |
{} |
| 1423 |
|
| 1424 |
|
| 1425 |
|
| 1426 |
template <class Iterator> |
| 1427 |
inline bool |
| 1428 |
LevelEqualTo::operator()(const Iterator &i) const |
| 1429 |
{ |
| 1430 |
return (static_cast<unsigned int>(i->level()) == level); |
| 1431 |
} |
| 1432 |
|
| 1433 |
|
| 1434 |
|
| 1435 |
// ---------------- IteratorFilters::SubdomainEqualTo --------- |
| 1436 |
inline SubdomainEqualTo::SubdomainEqualTo( |
| 1437 |
const types::subdomain_id subdomain_id) |
| 1438 |
: subdomain_id(subdomain_id) |
| 1439 |
{} |
| 1440 |
|
| 1441 |
|
| 1442 |
|
| 1443 |
template <class Iterator> |
| 1444 |
inline bool |
| 1445 |
SubdomainEqualTo::operator()(const Iterator &i) const |
| 1446 |
{ |
| 1447 |
return (i->subdomain_id() == subdomain_id); |
| 1448 |
} |
| 1449 |
|
| 1450 |
|
| 1451 |
|
| 1452 |
// ---------------- IteratorFilters::LocallyOwnedCell --------- |
| 1453 |
|
| 1454 |
template <class Iterator> |
| 1455 |
inline bool |
| 1456 |
LocallyOwnedCell::operator()(const Iterator &i) const |
| 1457 |
{ |
| 1458 |
return (i->is_locally_owned()); |
| 1459 |
} |
| 1460 |
|
| 1461 |
|
| 1462 |
// ---------------- IteratorFilters::LocallyOwnedLevelCell --------- |
| 1463 |
|
| 1464 |
template <class Iterator> |
| 1465 |
inline bool |
| 1466 |
LocallyOwnedLevelCell::operator()(const Iterator &i) const |
| 1467 |
{ |
| 1468 |
return (i->is_locally_owned_on_level()); |
| 1469 |
} |
| 1470 |
|
| 1471 |
|
| 1472 |
|
| 1473 |
// ---------------- IteratorFilters::MaterialIdEqualTo --------- |
| 1474 |
inline MaterialIdEqualTo::MaterialIdEqualTo( |
| 1475 |
const types::material_id material_id, |
| 1476 |
const bool only_locally_owned) |
| 1477 |
: material_ids{material_id} |
| 1478 |
, only_locally_owned(only_locally_owned) |
| 1479 |
{} |
| 1480 |
|
| 1481 |
|
| 1482 |
|
| 1483 |
inline MaterialIdEqualTo::MaterialIdEqualTo( |
| 1484 |
const std::set<types::material_id> &material_ids, |
| 1485 |
const bool only_locally_owned) |
| 1486 |
: material_ids(material_ids) |
| 1487 |
, only_locally_owned(only_locally_owned) |
| 1488 |
{} |
| 1489 |
|
| 1490 |
|
| 1491 |
|
| 1492 |
template <class Iterator> |
| 1493 |
inline bool |
| 1494 |
MaterialIdEqualTo::operator()(const Iterator &i) const |
| 1495 |
{ |
| 1496 |
return only_locally_owned == true ? |
| 1497 |
(material_ids.find(i->material_id()) != material_ids.end() && |
| 1498 |
i->is_locally_owned()) : |
| 1499 |
material_ids.find(i->material_id()) != material_ids.end(); |
| 1500 |
} |
| 1501 |
|
| 1502 |
|
| 1503 |
|
| 1504 |
// ---------------- IteratorFilters::ActiveFEIndexEqualTo --------- |
| 1505 |
inline ActiveFEIndexEqualTo::ActiveFEIndexEqualTo( |
| 1506 |
const unsigned int active_fe_index, |
| 1507 |
const bool only_locally_owned) |
| 1508 |
: active_fe_indices{active_fe_index} |
| 1509 |
, only_locally_owned(only_locally_owned) |
| 1510 |
{} |
| 1511 |
|
| 1512 |
|
| 1513 |
|
| 1514 |
inline ActiveFEIndexEqualTo::ActiveFEIndexEqualTo( |
| 1515 |
const std::set<unsigned int> &active_fe_indices, |
| 1516 |
const bool only_locally_owned) |
| 1517 |
: active_fe_indices(active_fe_indices) |
| 1518 |
, only_locally_owned(only_locally_owned) |
| 1519 |
{} |
| 1520 |
|
| 1521 |
|
| 1522 |
|
| 1523 |
template <class Iterator> |
| 1524 |
inline bool |
| 1525 |
ActiveFEIndexEqualTo::operator()(const Iterator &i) const |
| 1526 |
{ |
| 1527 |
return only_locally_owned == true ? |
| 1528 |
(i->is_locally_owned() && |
| 1529 |
active_fe_indices.find(i->active_fe_index()) != |
| 1530 |
active_fe_indices.end()) : |
| 1531 |
active_fe_indices.find(i->active_fe_index()) != |
| 1532 |
active_fe_indices.end(); |
| 1533 |
} |
| 1534 |
|
| 1535 |
|
| 1536 |
|
| 1537 |
// ---------------- IteratorFilters::AtBoundary --------- |
| 1538 |
|
| 1539 |
template <class Iterator> |
| 1540 |
inline bool |
| 1541 |
AtBoundary::operator()(const Iterator &i) const |
| 1542 |
{ |
| 1543 |
return (i->at_boundary()); |
| 1544 |
} |
| 1545 |
|
| 1546 |
|
| 1547 |
|
| 1548 |
// ---------------- IteratorFilters::BoundaryIdEqualTo --------- |
| 1549 |
inline BoundaryIdEqualTo::BoundaryIdEqualTo( |
| 1550 |
const types::boundary_id boundary_id) |
| 1551 |
: boundary_ids{boundary_id} |
| 1552 |
{} |
| 1553 |
|
| 1554 |
|
| 1555 |
|
| 1556 |
inline BoundaryIdEqualTo::BoundaryIdEqualTo( |
| 1557 |
const std::set<types::boundary_id> &boundary_ids) |
| 1558 |
: boundary_ids(boundary_ids) |
| 1559 |
{} |
| 1560 |
|
| 1561 |
|
| 1562 |
|
| 1563 |
template <class Iterator> |
| 1564 |
inline bool |
| 1565 |
BoundaryIdEqualTo::operator()(const Iterator &i) const |
| 1566 |
{ |
| 1567 |
return boundary_ids.find(i->boundary_id()) != boundary_ids.end(); |
| 1568 |
} |
| 1569 |
|
| 1570 |
|
| 1571 |
|
| 1572 |
// ---------------- IteratorFilters::ManifoldIdEqualTo --------- |
| 1573 |
inline ManifoldIdEqualTo::ManifoldIdEqualTo( |
| 1574 |
const types::manifold_id manifold_id) |
| 1575 |
: manifold_ids{manifold_id} |
| 1576 |
{} |
| 1577 |
|
| 1578 |
|
| 1579 |
|
| 1580 |
inline ManifoldIdEqualTo::ManifoldIdEqualTo( |
| 1581 |
const std::set<types::manifold_id> &manifold_ids) |
| 1582 |
: manifold_ids(manifold_ids) |
| 1583 |
{} |
| 1584 |
|
| 1585 |
|
| 1586 |
|
| 1587 |
template <class Iterator> |
| 1588 |
inline bool |
| 1589 |
ManifoldIdEqualTo::operator()(const Iterator &i) const |
| 1590 |
{ |
| 1591 |
return manifold_ids.find(i->manifold_id()) != manifold_ids.end(); |
| 1592 |
} |
| 1593 |
} // namespace IteratorFilters |
| 1594 |
|
| 1595 |
|
| 1596 |
DEAL_II_NAMESPACE_CLOSE |
| 1597 |
|
| 1598 |
#endif |