Functions
template<int dim, int spacedim, typename number = double>
void	create_interpolation_sparsity_pattern (const DoFHandler< dim, spacedim > &space_dh, const Particles::ParticleHandler< dim, spacedim > &particle_handler, SparsityPatternBase &sparsity, const AffineConstraints< number > &constraints=AffineConstraints< number >(), const ComponentMask &space_comps={})

template<int dim, int spacedim, typename MatrixType >
void	create_interpolation_matrix (const DoFHandler< dim, spacedim > &space_dh, const Particles::ParticleHandler< dim, spacedim > &particle_handler, MatrixType &matrix, const AffineConstraints< typename MatrixType::value_type > &constraints=AffineConstraints< typename MatrixType::value_type >(), const ComponentMask &space_comps={})

template<int dim, int spacedim, typename InputVectorType , typename OutputVectorType >
void	interpolate_field_on_particles (const DoFHandler< dim, spacedim > &field_dh, const Particles::ParticleHandler< dim, spacedim > &particle_handler, const InputVectorType &field_vector, OutputVectorType &interpolated_field, const ComponentMask &field_comps={})

template<int n_components, int dim, int spacedim, typename InputVectorType , typename OutputVectorType >
void	interpolate_field_on_particles (const DoFHandler< dim, spacedim > &field_dh, const Particles::ParticleHandler< dim, spacedim > &particle_handler, const InputVectorType &field_vector, OutputVectorType &interpolated_field, const ComponentMask &field_comps={}, const Mapping< dim, spacedim > &mapping=(ReferenceCells::get_hypercube< dim >() .template get_default_linear_mapping< spacedim >()))

Detailed Description

A namespace for functions offering tools to handle ParticleHandler objects and their coupling with DoFHandler objects.

Function Documentation

◆ create_interpolation_sparsity_pattern()

template<int dim, int spacedim, typename number = double>

void Particles::Utilities::create_interpolation_sparsity_pattern	(	const DoFHandler< dim, spacedim > &	space_dh,
		const Particles::ParticleHandler< dim, spacedim > &	particle_handler,
		SparsityPatternBase &	sparsity,
		const AffineConstraints< number > &	constraints = `AffineConstraints<number>()`,
		const ComponentMask &	space_comps = `{}`
	)

Create an interpolation sparsity pattern for particles.

Given a triangulation representing the domain \(\Omega\), a particle handler of particles in \(\Omega\), and a scalar finite element space \(V(\Omega) = \text{span}\{v_j\}_{j=0}^n\), compute the sparsity pattern that would be necessary to assemble the matrix

\[ M_{i,j} \dealcoloneq v_j(x_i) , \]

where \(V(\Omega)\) is the finite element space associated with the space_dh, and the index i is given by the particle id whose position is x_i.

In the case of vector valued finite element spaces, the components on which interpolation must be performed can be selected using a component mask. Only primitive finite element spaces are supported.

When selecting more than one component, the resulting sparsity will have dimension equal to particle_handler.n_global_particles() * mask.n_selected_components() times space_dh.n_dofs(), and the corresponding matrix entries are given by

\[ M_{(i*n_comps+k),j} \dealcoloneq v_j(x_i) \cdot e_{comp_j}, \]

where comp_j is the only non zero component of the vector valued basis function v_j (equal to fe.system_to_component_index(j).first), k corresponds to its index within the selected components of the mask, and \(e_{comp_j}\) is the unit vector in the direction comp_j.

The sparsity is filled by locating the position of the particle with index i within the particle handler with respect to the embedding triangulation \(\Omega\), and coupling it with all the local degrees of freedom specified in the component mask space_comps, following the ordering in which they are selected in the mask space_comps.

If a particle does not fall within \(\Omega\), it is ignored, and the corresponding rows of the sparsity will be empty.

Constraints of the form supported by the AffineConstraints class may be supplied with the constraints argument. The method AffineConstraints::add_entries_local_to_global() is used to fill the final sparsity pattern.

Definition at line 36 of file utilities.cc.

◆ create_interpolation_matrix()

template<int dim, int spacedim, typename MatrixType >

void Particles::Utilities::create_interpolation_matrix	(	const DoFHandler< dim, spacedim > &	space_dh,
		const Particles::ParticleHandler< dim, spacedim > &	particle_handler,
		MatrixType &	matrix,
		const AffineConstraints< typename MatrixType::value_type > &	constraints = `AffineConstraints<typename MatrixType::value_type>()`,
		const ComponentMask &	space_comps = `{}`
	)

Create an interpolation matrix for particles.

Given a triangulation representing the domains \(\Omega\), a particle handler of particles in \(\Omega\), and a scalar finite element space \(V(\Omega) = \text{span}\{v_j\}_{j=0}^n\), compute the matrix

\[ M_{ij} \dealcoloneq v_j(x_i) , \]

where \(V(\Omega)\) is the finite element space associated with the space_dh, and the index i is given by the particle id whose position is x_i.

In the case of vector valued finite element spaces, the components on which interpolation must be performed can be selected using a component mask. Only primitive finite element spaces are supported.

When selecting more than one component, the resulting sparsity will have dimension equal to particle_handler.n_global_particles() * mask.n_selected_components() times space_dh.n_dofs(), and the corresponding matrix entries are given by

\[ M_{(i*n_comps+k),j} \dealcoloneq v_j(x_i) \cdot e_{comp_j}, \]

where comp_j is the only non zero component of the vector valued basis function v_j (equal to fe.system_to_component_index(j).first), k corresponds to its index within the selected components of the mask, and \(e_{comp_j}\) is the unit vector in the direction comp_j.

The matrix is filled by locating the position of the particle with index i within the particle handler with respect to the embedding triangulation \(\Omega\), and coupling it with all the local degrees of freedom specified in the component mask space_comps, following the ordering in which they are selected in the mask space_comps.

If a particle does not fall within \(\Omega\), it is ignored, and the corresponding rows of the matrix will be zero.

Constraints of the form supported by the AffineConstraints class may be supplied with the constraints argument. The method AffineConstraints::distribute_local_to_global() is used to distribute the entries of the matrix to respect the given constraints.

Definition at line 118 of file utilities.cc.

◆ interpolate_field_on_particles() [1/2]

template<int dim, int spacedim, typename InputVectorType , typename OutputVectorType >

void Particles::Utilities::interpolate_field_on_particles	(	const DoFHandler< dim, spacedim > &	field_dh,
		const Particles::ParticleHandler< dim, spacedim > &	particle_handler,
		const InputVectorType &	field_vector,
		OutputVectorType &	interpolated_field,
		const ComponentMask &	field_comps = `{}`
	)

Given a DoFHandler and a ParticleHandler, interpolate a vector field at the position of the particles. The result is stored in an output vector that is indexed by the global particle id (see the interpolated_field documentation below for the exact layout and size).

Parameters

[in]	field_dh	The DOF Handler which was used to generate the field vector that is to be interpolated.
[in]	particle_handler	The particle handler whose particle serve as the interpolation points.
[in]	field_vector	The vector of the field to be interpolated. This vector must be coherent with the dof_handler provided
[in,out]	interpolated_field	The interpolated value of the field at the position of the particles. The vector is indexed by the global particle id: the value of selected component `k` for the particle with id `i` is stored at entry `i * n_components + k`. Consequently the vector must have size `particle_handler.get_next_free_particle_index() * n_components` (equal to `n_global_particles * n_components` when no particles have been removed), not merely the number of locally owned particles, and the entries are not ordered following the loop over particles. In parallel, this must be a distributed vector whose locally owned rows include the entries for all locally owned particles; the function adds into these entries and calls compress(VectorOperation::add) before returning.
[in]	field_comps	An optional component mask that decides which subset of the vector fields are interpolated

Definition at line 192 of file utilities.h.

◆ interpolate_field_on_particles() [2/2]

template<int n_components, int dim, int spacedim, typename InputVectorType , typename OutputVectorType >

void Particles::Utilities::interpolate_field_on_particles	(	const DoFHandler< dim, spacedim > &	field_dh,
		const Particles::ParticleHandler< dim, spacedim > &	particle_handler,
		const InputVectorType &	field_vector,
		OutputVectorType &	interpolated_field,
		const ComponentMask &	field_comps = `{}`,
		const Mapping< dim, spacedim > &	mapping = `(ReferenceCells::get_hypercube<dim>() .template get_default_linear_mapping<spacedim>() )`
	)

Given a DoFHandler and a ParticleHandler, interpolate a vector field at the position of the particles. The result is stored in an output vector that is indexed by the global particle id (see the interpolated_field documentation below for the exact layout and size). This version relies on FePointEvaluation to interpolate the field at the particle location efficiently. The drawback is that this requires knowledge of the number of components at compile time.