Debian Codegraph @

include/deal.II/particles/utilities.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2020 - 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_utilities
16 #define dealii_particles_utilities
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/index_set.h>
21 #include <deal.II/base/point.h>
22 #include <deal.II/base/quadrature.h>
23
24 #include <deal.II/dofs/dof_handler.h>
25
26 #include <deal.II/fe/component_mask.h>
27 #include <deal.II/fe/fe.h>
28
29 #include <deal.II/grid/grid_tools_cache.h>
30
31 #include <deal.II/lac/affine_constraints.h>
32 #include <deal.II/lac/sparsity_pattern_base.h>
33
34 #include <deal.II/particles/particle_handler.h>
35
36
37 DEAL_II_NAMESPACE_OPEN
38
39
40
41 namespace Particles
42 {
43 /**
44 * A namespace for functions offering tools to handle ParticleHandler objects
45 * and their coupling with DoFHandler objects.
46 */
47 namespace Utilities
48 {
49 /**
50 * Create an interpolation sparsity pattern for particles.
51 *
52 * Given a triangulation representing the domain $\Omega$, a particle
53 * handler of particles in $\Omega$, and a scalar finite element space
54 * $V(\Omega) = \text{span}\{v_j\}_{j=0}^n$, compute the sparsity pattern
55 * that would be necessary to assemble the matrix
56 * \f[
57 * M_{i,j} \dealcoloneq v_j(x_i) ,
58 * \f]
59 * where $V(\Omega)$ is the finite element space associated with the
60 * `space_dh`, and the index `i` is given by the particle id whose position
61 * is `x_i`.
62 *
63 * In the case of vector valued finite element spaces, the components on
64 * which interpolation must be performed can be selected using a component
65 * mask. Only primitive finite element spaces are supported.
66 *
67 * When selecting more than one component, the resulting sparsity will have
68 * dimension equal to `particle_handler.n_global_particles() *
69 * mask.n_selected_components()` times `space_dh.n_dofs()`, and the
70 * corresponding matrix entries are given by
71 * \f[
72 * M_{(i*n_comps+k),j} \dealcoloneq v_j(x_i) \cdot e_{comp_j},
73 * \f]
74 * where `comp_j` is the only non zero component of the vector valued basis
75 * function `v_j` (equal to `fe.system_to_component_index(j).first`),
76 * `k` corresponds to its index within the selected components of the mask,
77 * and $e_{comp_j}$ is the unit vector in the direction `comp_j`.
78 *
79 * The `sparsity` is filled by locating the position of the particle with
80 * index `i` within the particle handler with respect to the embedding
81 * triangulation $\Omega$, and coupling it with all the local degrees of
82 * freedom specified in the component mask @p space_comps, following the
83 * ordering in which they are selected in the mask @p space_comps.
84 *
85 * If a particle does not fall within $\Omega$, it is ignored, and the
86 * corresponding rows of the sparsity will be empty.
87 *
88 * Constraints of the form supported by the AffineConstraints class may be
89 * supplied with the @p constraints argument. The method
90 * AffineConstraints::add_entries_local_to_global() is used to fill the
91 * final sparsity pattern.
92 */
93 template <int dim, int spacedim, typename number = double>
94 void
95 create_interpolation_sparsity_pattern(
96 const DoFHandler<dim, spacedim> &space_dh,
97 const Particles::ParticleHandler<dim, spacedim> &particle_handler,
98 SparsityPatternBase &sparsity,
99 const AffineConstraints<number> &constraints =
100 AffineConstraints<number>(),
101 const ComponentMask &space_comps = {});
102
103 /**
104 * Create an interpolation matrix for particles.
105 *
106 * Given a triangulation representing the domains $\Omega$, a particle
107 * handler of particles in $\Omega$, and a scalar finite element space
108 * $V(\Omega) = \text{span}\{v_j\}_{j=0}^n$, compute the matrix
109 * \f[
110 * M_{ij} \dealcoloneq v_j(x_i) ,
111 * \f]
112 * where $V(\Omega)$ is the finite element space associated with the
113 * `space_dh`, and the index `i` is given by the particle id whose position
114 * is `x_i`.
115 *
116 * In the case of vector valued finite element spaces, the components on
117 * which interpolation must be performed can be selected using a component
118 * mask. Only primitive finite element spaces are supported.
119 *
120 * When selecting more than one component, the resulting sparsity will have
121 * dimension equal to `particle_handler.n_global_particles() *
122 * mask.n_selected_components()` times `space_dh.n_dofs()`, and the
123 * corresponding matrix entries are given by
124 * \f[
125 * M_{(i*n_comps+k),j} \dealcoloneq v_j(x_i) \cdot e_{comp_j},
126 * \f]
127 * where `comp_j` is the only non zero component of the vector valued basis
128 * function `v_j` (equal to `fe.system_to_component_index(j).first`),
129 * `k` corresponds to its index within the selected components of the mask,
130 * and $e_{comp_j}$ is the unit vector in the direction `comp_j`.
131 *
132 * The matrix is filled by locating the position of the particle with
133 * index `i` within the particle handler with respect to the embedding
134 * triangulation $\Omega$, and coupling it with all the local degrees of
135 * freedom specified in the component mask @p space_comps, following the
136 * ordering in which they are selected in the mask @p space_comps.
137 *
138 * If a particle does not fall within $\Omega$, it is ignored, and the
139 * corresponding rows of the matrix will be zero.
140 *
141 * Constraints of the form supported by the AffineConstraints class may be
142 * supplied with the @p constraints argument. The method
143 * AffineConstraints::distribute_local_to_global() is used to distribute
144 * the entries of the matrix to respect the given constraints.
145 */
146 template <int dim, int spacedim, typename MatrixType>
147 void
148 create_interpolation_matrix(
149 const DoFHandler<dim, spacedim> &space_dh,
150 const Particles::ParticleHandler<dim, spacedim> &particle_handler,
151 MatrixType &matrix,
152 const AffineConstraints<typename MatrixType::value_type> &constraints =
153 AffineConstraints<typename MatrixType::value_type>(),
154 const ComponentMask &space_comps = {});
155
156 /**
157 * Given a DoFHandler and a ParticleHandler, interpolate a vector field
158 * at the position of the particles. The result is stored in an output
159 * vector whose size corresponds to the number of locally owned particles *
160 * number of active components
161 *
162 * @param[in] field_dh The DOF Handler which was used to generate the
163 * field vector that is to be interpolated.
164 *
165 * @param[in] particle_handler The particle handler whose particle serve as
166 * the interpolation points.
167 *
168 * @param[in] field_vector The vector of the field to be interpolated. This
169 * vector must be coherent with the dof_handler provided
170 *
171 * @param[in,out] interpolated_field The interpolated value of the field at
172 * the position of the particles. The size of the vector must be
173 * n_locally_owned_particles times the n_components
174 *
175 * @param[in] field_comps An optional component mask that decides which
176 * subset of the vector fields are interpolated
177 */
178 template <int dim,
179 int spacedim,
180 typename InputVectorType,
181 typename OutputVectorType>
182 void
183 interpolate_field_on_particles(
184 const DoFHandler<dim, spacedim> &field_dh,
185 const Particles::ParticleHandler<dim, spacedim> &particle_handler,
186 const InputVectorType &field_vector,
187 OutputVectorType &interpolated_field,
188 const ComponentMask &field_comps = {})
189 {
190 if (particle_handler.n_locally_owned_particles() == 0)
191 {
192 interpolated_field.compress(VectorOperation::add);
193 return; // nothing else to do here
194 }
195
196 const auto &fe = field_dh.get_fe();
197 auto particle = particle_handler.begin();
198
199 // Take care of components
200 const ComponentMask comps =
201 (field_comps.size() == 0 ? ComponentMask(fe.n_components(), true) :
202 field_comps);
203 AssertDimension(comps.size(), fe.n_components());
204 const auto n_comps = comps.n_selected_components();
205
206 AssertDimension(field_vector.size(), field_dh.n_dofs());
207 AssertDimension(interpolated_field.size(),
208 particle_handler.get_next_free_particle_index() *
209 n_comps);
210
211 // Global to local indices
212 std::vector<unsigned int> space_gtl(fe.n_components(),
213 numbers::invalid_unsigned_int);
214 for (unsigned int i = 0, j = 0; i < space_gtl.size(); ++i)
215 if (comps[i])
216 space_gtl[i] = j++;
217
218 std::vector<types::global_dof_index> dof_indices(fe.n_dofs_per_cell());
219
220 while (particle != particle_handler.end())
221 {
222 const auto &cell = particle->get_surrounding_cell();
223 const auto &dh_cell =
224 typename DoFHandler<dim, spacedim>::cell_iterator(*cell, &field_dh);
225 dh_cell->get_dof_indices(dof_indices);
226 const auto pic = particle_handler.particles_in_cell(cell);
227
228 Assert(pic.begin() == particle, ExcInternalError());
229 for (unsigned int i = 0; particle != pic.end(); ++particle, ++i)
230 {
231 const Point<dim> reference_location =
232 particle->get_reference_location();
233
234 const auto id = particle->get_id();
235
236 for (unsigned int j = 0; j < fe.n_dofs_per_cell(); ++j)
237 {
238 const auto comp_j =
239 space_gtl[fe.system_to_component_index(j).first];
240 if (comp_j != numbers::invalid_unsigned_int)
241 interpolated_field[id * n_comps + comp_j] +=
242 fe.shape_value(j, reference_location) *
243 field_vector(dof_indices[j]);
244 }
245 }
246 }
247 interpolated_field.compress(VectorOperation::add);
248 }
249
250 } // namespace Utilities
251 } // namespace Particles
252 DEAL_II_NAMESPACE_CLOSE
253
254 #endif