Debian Codegraph @

include/deal.II/particles/generators.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2019 - 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_particles_particle_generator_h
16 #define dealii_particles_particle_generator_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/function.h>
21 #include <deal.II/base/quadrature.h>
22
23 #include <deal.II/distributed/tria.h>
24
25 #include <deal.II/dofs/dof_handler.h>
26
27 #include <deal.II/fe/mapping.h>
28
29 #include <deal.II/particles/particle.h>
30 #include <deal.II/particles/particle_handler.h>
31
32 #include <random>
33
34 DEAL_II_NAMESPACE_OPEN
35
36 namespace Particles
37 {
38 /**
39 * A namespace that contains all classes that are related to the particle
40 * generation.
41 */
42 namespace Generators
43 {
44 /**
45 * A function that generates particles in every cell at specified @p particle_reference_locations.
46 * The total number of particles that is added to the @p particle_handler object is
47 * the number of locally owned cells of the @p triangulation times the number of
48 * locations in @p particle_reference_locations. An optional @p mapping argument
49 * can be used to map from @p particle_reference_locations to the real particle locations.
50 *
51 * @param triangulation The triangulation associated with the @p particle_handler.
52 *
53 * @param particle_reference_locations A vector of positions in the unit cell.
54 * Particles will be generated in every cell at these locations.
55 *
56 * @param particle_handler The particle handler that will take ownership
57 * of the generated particles.
58 *
59 * @param mapping An optional mapping object that is used to map reference
60 * location in the unit cell to the real cells of the triangulation. If no
61 * mapping is provided a MappingQ1 is assumed.
62 */
63 template <int dim, int spacedim = dim>
64 void
65 regular_reference_locations(
66 const Triangulation<dim, spacedim> &triangulation,
67 const std::vector<Point<dim>> &particle_reference_locations,
68 ParticleHandler<dim, spacedim> &particle_handler,
69 const Mapping<dim, spacedim> &mapping =
70 (ReferenceCells::get_hypercube<dim>()
71 #ifndef _MSC_VER
72 .template get_default_linear_mapping<dim, spacedim>()
73 #else
74 .ReferenceCell::get_default_linear_mapping<dim, spacedim>()
75 #endif
76 ));
77
78 /**
79 * A function that generates one particle at a random location in cell @p cell and with
80 * index @p id. The function expects a random number generator to avoid the expensive generation
81 * and destruction of a generator for every particle and optionally takes
82 * into account a mapping for the cell. The algorithm implemented in the
83 * function is described in @cite GLHPW2018. In short, the algorithm
84 * generates
85 * random locations within the bounding box of the @p cell. It then inverts the mapping
86 * to check if the generated particle is within the cell itself. This makes
87 * sure the algorithm produces statistically random locations even for
88 * nonlinear mappings and distorted cells. However, if the ratio between
89 * bounding box and cell volume becomes very large -- i.e. the cells become
90 * strongly deformed, for example a pencil shaped cell that lies diagonally
91 * in the domain -- then the algorithm can become very inefficient.
92 * Therefore, it only tries to find a location ni the cell a fixed number of
93 * times before throwing an error message.
94 *
95 * @param[in] cell The cell in which a particle is generated.
96 *
97 * @param[in] id The particle index that will be assigned to the new
98 * particle.
99 *
100 * @param[in,out] random_number_generator A random number generator that
101 * will be used for the creation of th particle.
102 *
103 * @param[in] mapping An optional mapping object that is used to map
104 * reference location in the unit cell to the real cell. If no mapping is
105 * provided a MappingQ1 is assumed.
106 */
107 template <int dim, int spacedim = dim>
108 Particle<dim, spacedim>
109 random_particle_in_cell(
110 const typename Triangulation<dim, spacedim>::active_cell_iterator &cell,
111 const types::particle_index id,
112 std::mt19937 &random_number_generator,
113 const Mapping<dim, spacedim> &mapping =
114 (ReferenceCells::get_hypercube<dim>()
115 #ifndef _MSC_VER
116 .template get_default_linear_mapping<dim, spacedim>()
117 #else
118 .ReferenceCell::get_default_linear_mapping<dim, spacedim>()
119 #endif
120 ));
121
122 /**
123 * A function that generates one particle at a random location in cell @p cell and with
124 * index @p id. This version of the function above immediately inserts the generated
125 * particle into the @p particle_handler and returns a iterator to it instead of
126 * a particle object. This avoids unnecessary copies of the particle.
127 */
128 template <int dim, int spacedim = dim>
129 ParticleIterator<dim, spacedim>
130 random_particle_in_cell_insert(
131 const typename Triangulation<dim, spacedim>::active_cell_iterator &cell,
132 const types::particle_index id,
133 std::mt19937 &random_number_generator,
134 ParticleHandler<dim, spacedim> &particle_handler,
135 const Mapping<dim, spacedim> &mapping =
136 (ReferenceCells::get_hypercube<dim>()
137 #ifndef _MSC_VER
138 .template get_default_linear_mapping<dim, spacedim>()
139 #else
140 .ReferenceCell::get_default_linear_mapping<dim, spacedim>()
141 #endif
142 ));
143
144 /**
145 * A function that generates particles randomly in the domain with a
146 * particle density
147 * according to a provided probability density function @p probability_density_function.
148 * The total number of particles that is added to the @p particle_handler object is
149 * @p n_particles_to_create. An optional @p mapping argument
150 * can be used to map from @p particle_reference_locations to the real particle locations.
151 * The function can compute the number of particles per cell either
152 * deterministically by computing the integral of the probability density
153 * function for each cell and creating
154 * particles accordingly (if option @p random_cell_selection set to false), or it can
155 * select cells randomly based on the probability density function and the
156 * cell size
157 * (if option @p random_cell_selection set to true). In either case the position of
158 * individual particles inside the cell is computed randomly.
159 *
160 * The algorithm implemented in the function is described in
161 * @cite GLHPW2018.
162 *
163 * @param[in] triangulation The triangulation associated with the @p particle_handler.
164 *
165 * @param[in] probability_density_function A function with non-negative
166 * values that determines the probability density of a particle to be
167 * generated in this location. The function does not need to be normalized.
168 *
169 * @param[in] random_cell_selection A bool that determines, how the number
170 * of particles per cell is computed (see the description above).
171 *
172 * @param[in] n_particles_to_create The number of particles that will be
173 * created by this function.
174 *
175 * @param[in,out] particle_handler The particle handler that will take
176 * ownership of the generated particles.
177 *
178 * @param[in] mapping An optional mapping object that is used to map
179 * reference location in the unit cell to the real cells of the
180 * triangulation. If no mapping is provided a MappingQ1 is assumed.
181 *
182 * @param[in] random_number_seed An optional seed that determines the
183 * initial state of the random number generator. Use the same number to get
184 * a reproducible particle distribution, or a changing number (e.g. based on
185 * system time) to generate different particle distributions for each call
186 * to this function.
187 */
188 template <int dim, int spacedim = dim>
189 void
190 probabilistic_locations(
191 const Triangulation<dim, spacedim> &triangulation,
192 const Function<spacedim> &probability_density_function,
193 const bool random_cell_selection,
194 const types::particle_index n_particles_to_create,
195 ParticleHandler<dim, spacedim> &particle_handler,
196 const Mapping<dim, spacedim> &mapping =
197 (ReferenceCells::get_hypercube<dim>()
198 #ifndef _MSC_VER
199 .template get_default_linear_mapping<dim, spacedim>()),
200 #else
201 .ReferenceCell::get_default_linear_mapping<dim, spacedim>()),
202 #endif
203 const unsigned int random_number_seed = 5432);
204
205
206 /**
207 * A function that generates particles at the locations of the support
208 * points of a DoFHandler, possibly based on a different Triangulation with
209 * respect to the one used to construct the ParticleHandler.
210 * The total number of particles that is added to the @p particle_handler object is
211 * the number of dofs of the DoFHandler that is passed that are within the
212 * triangulation and whose components are within the ComponentMask.
213 * This function uses insert_global_particles and consequently may induce
214 * considerable mpi communication overhead.
215 *
216 * This function is used in step-70.
217 *
218 * @param[in] dof_handler A DOF handler that may live on another
219 * triangulation that is used to establsh the positions of the particles.
220 *
221 * @param[in] global_bounding_boxes A vector that contains all the bounding
222 * boxes for all processors. This vector can be established by first using
223 * 'GridTools::compute_mesh_predicate_bounding_box()' and gathering all the
224 * bounding boxes using 'Utilities::MPI::all_gather().
225 *
226 * @param[in,out] particle_handler The particle handler that will take
227 * ownership of the generated particles. The particles that are generated
228 * will be appended to the particles currently owned by the particle
229 * handler.
230 *
231 * @param[in] mapping An optional mapping object that is used to map
232 * the DOF locations. If no mapping is provided a MappingQ1 is assumed.
233 *
234 * @param[in] components Component mask that decides which subset of the
235 * support points of the dof_handler are used to generate the particles.
236 *
237 * @param[in] properties An optional vector of vector of properties
238 * for each particle to be inserted.
239 */
240 template <int dim, int spacedim = dim>
241 void
242 dof_support_points(
243 const DoFHandler<dim, spacedim> &dof_handler,
244 const std::vector<std::vector<BoundingBox<spacedim>>>
245 &global_bounding_boxes,
246 ParticleHandler<dim, spacedim> &particle_handler,
247 const Mapping<dim, spacedim> &mapping =
248 (ReferenceCells::get_hypercube<dim>()
249 #ifndef _MSC_VER
250 .template get_default_linear_mapping<dim, spacedim>()),
251 #else
252 .ReferenceCell::get_default_linear_mapping<dim, spacedim>()),
253 #endif
254 const ComponentMask &components = {},
255 const std::vector<std::vector<double>> &properties = {});
256
257 /**
258 * A function that generates particles at the locations of the quadrature
259 * points of a Triangulation. This Triangulation can be different
260 * from the one used to construct the ParticleHandler.
261 * The total number of particles that is added to the @p particle_handler object is the
262 * number of cells multiplied by the number of particle reference locations
263 * which are generally constructed using a quadrature.
264 * This function uses insert_global_particles and consequently may
265 * induce considerable mpi communication overhead.
266 *
267 * @param[in] triangulation The possibly non-matching triangulation which is
268 * used to insert the particles into the domain.
269 *
270 * @param[in] quadrature A quadrature whose reference location are used to
271 * insert the particles within the cells.
272 *
273 * @param[in] global_bounding_boxes A vector that contains all the bounding
274 * boxes for all processors. This vector can be established by first using
275 * 'GridTools::compute_mesh_predicate_bounding_box()' and gathering all the
276 * bounding boxes using 'Utilities::MPI::all_gather. Of course, if you are
277 * applying this function on a sequential triangulation, then this argument
278 * is simply an (outer) vector with just one element, and that one element
279 * would be the result of the function mentioned above.
280 *
281 * @param[in,out] particle_handler The particle handler that will take
282 * ownership of the generated particles.
283 *
284 * @param[in] mapping An optional mapping object that is used to map
285 * the quadrature locations. If no mapping is provided a MappingQ1 is
286 * assumed.
287 *
288 * @param[in] properties An optional vector of vector of properties
289 * for each particle to be inserted.
290 */
291 template <int dim, int spacedim = dim>
292 void
293 quadrature_points(
294 const Triangulation<dim, spacedim> &triangulation,
295 const Quadrature<dim> &quadrature,
296 const std::vector<std::vector<BoundingBox<spacedim>>>
297 &global_bounding_boxes,
298 ParticleHandler<dim, spacedim> &particle_handler,
299 const Mapping<dim, spacedim> &mapping =
300 (ReferenceCells::get_hypercube<dim>()
301 .template get_default_linear_mapping<dim, spacedim>()),
302 const std::vector<std::vector<double>> &properties = {});
303 } // namespace Generators
304 } // namespace Particles
305
306 DEAL_II_NAMESPACE_CLOSE
307
308 #endif