Communicate values between a mesh and arbitrary points. More...

#include <deal.II/base/mpi_remote_point_evaluation.h>

Detailed Description

template<int dim, int spacedim = dim>
class Utilities::MPI::RemotePointEvaluation< dim, spacedim >

Communicate values between a mesh and arbitrary points.

This class enables evaluation of finite element functions defined on a Triangulation at arbitrary points inside the mesh. The underlying finite element mesh can be distributed among processes, which makes the operations more involved due to communication.

Once initialized, the data exchange is handled by the functions process_and_evaluate(), that transfers data from the Triangulation to the set of points, and evaluate_and_process(), that performs the inverse operation (taking data defined at each point and making it available in the corresponding cell of the Triangulation).

The helper functions VectorTools::point_values() and VectorTools::point_gradients (the overloads taking an instance of RemotePointEvaluation) can be used in place of process_and_evaluate() and perform the evaluation of a finite element function.

The template argument DataType of the process_and_evaluate() and evaluate_and_process() functions can be a scalar (float, double), Tensor<rank,dim>, or Point<dim>. Additionally, one can specify the number of components (in case DataType is a scalar).

Note: Usage and implementation details of this class and the helper functions above are explained in detail in step-87.; The name of the fields are chosen with the method evaluate_and_process() in mind. Here, quantities are computed at specified arbitrary positioned points (and even on remote processes in the MPI universe) cell by cell and these values are sent to requesting processes, which receive the result and resort the result according to the points.

Definition at line 83 of file mpi_remote_point_evaluation.h.

Inheritance diagram for Utilities::MPI::RemotePointEvaluation< dim, spacedim >:

[legend]

Classes
struct	AdditionalData
class	CellData

Public Member Functions
	RemotePointEvaluation (const AdditionalData &additional_data=AdditionalData())
	RemotePointEvaluation (const double tolerance, const bool enforce_unique_mapping=false, const unsigned int rtree_level=0, const std::function< std::vector< bool >()> &marked_vertices={})
	~RemotePointEvaluation ()
void	reinit (const std::vector< Point< spacedim > > &points, const Triangulation< dim, spacedim > &tria, const Mapping< dim, spacedim > &mapping)
void	reinit (const GridTools::Cache< dim, spacedim > &cache, const std::vector< Point< spacedim > > &points)
void	reinit (const GridTools::internal::DistributedComputePointLocationsInternal< dim, spacedim > &data, const Triangulation< dim, spacedim > &tria, const Mapping< dim, spacedim > &mapping)
const CellData &	get_cell_data () const
template<typename DataType, unsigned int n_components = 1>
void	evaluate_and_process (std::vector< DataType > &output, std::vector< DataType > &buffer, const std::function< void(const ArrayView< DataType > &, const CellData &)> &evaluation_function, const bool sort_data=true) const
template<typename DataType, unsigned int n_components = 1>
std::vector< DataType >	evaluate_and_process (const std::function< void(const ArrayView< DataType > &, const CellData &)> &evaluation_function, const bool sort_data=true) const
template<typename DataType, unsigned int n_components = 1>
void	process_and_evaluate (const std::vector< DataType > &input, std::vector< DataType > &buffer, const std::function< void(const ArrayView< const DataType > &, const CellData &)> &evaluation_function, const bool sort_data=true) const
template<typename DataType, unsigned int n_components = 1>
void	process_and_evaluate (const std::vector< DataType > &input, const std::function< void(const ArrayView< const DataType > &, const CellData &)> &evaluation_function, const bool sort_data=true) const
const std::vector< unsigned int > &	get_point_ptrs () const
bool	is_map_unique () const
bool	all_points_found () const
bool	point_found (const unsigned int i) const
const Triangulation< dim, spacedim > &	get_triangulation () const
const Mapping< dim, spacedim > &	get_mapping () const
bool	is_ready () const
const std::vector< unsigned int > &	get_send_permutation () const
const std::vector< unsigned int > &	get_inverse_recv_permutation () const

Private Attributes
const AdditionalData	additional_data
boost::signals2::connection	tria_signal
bool	ready_flag
ObserverPointer< const Triangulation< dim, spacedim > >	tria
ObserverPointer< const Mapping< dim, spacedim > >	mapping
bool	unique_mapping
bool	all_points_found_flag
std::vector< unsigned int >	point_ptrs
std::vector< unsigned int >	recv_permutation
std::vector< unsigned int >	recv_permutation_inv
std::vector< unsigned int >	recv_ptrs
std::vector< unsigned int >	recv_ranks
std::unique_ptr< CellData >	cell_data
std::vector< unsigned int >	send_permutation
std::vector< unsigned int >	send_permutation_inv
std::vector< unsigned int >	send_ranks
std::vector< unsigned int >	send_ptrs
unsigned int	buffer_size_with_sorting
unsigned int	buffer_size_without_sorting

Constructor & Destructor Documentation

◆ RemotePointEvaluation() [1/2]

template<int dim, int spacedim>

Utilities::MPI::RemotePointEvaluation< dim, spacedim >::RemotePointEvaluation ( const AdditionalData & additional_data = AdditionalData() )

Constructor.

Parameters

additional_data Configure options for RemotePointEvaluation.

Definition at line 52 of file mpi_remote_point_evaluation.cc.

◆ RemotePointEvaluation() [2/2]

template<int dim, int spacedim>

Utilities::MPI::RemotePointEvaluation< dim, spacedim >::RemotePointEvaluation	(	const double	tolerance,
		const bool	enforce_unique_mapping = false,
		const unsigned int	rtree_level = 0,
		const std::function< std::vector< bool >()> &	marked_vertices = {} )

Constructor. This constructor is deprecated. Use the other constructor taking AdditionalData instead.

Parameters

tolerance	Tolerance in terms of unit cell coordinates for determining all cells around a point passed to the class during reinit(). Depending on the problem, it might be necessary to adjust the tolerance in order to be able to identify a cell. Floating point arithmetic implies that a point will, in general, not lie exactly on a vertex, edge, or face.
enforce_unique_mapping	Enforce unique mapping, i.e., (one-to-one) relation of points and cells.
rtree_level	RTree level to be used during the construction of the bounding boxes.
marked_vertices	Function that marks relevant vertices to make search of active cells around point more efficient.

Deprecated

Definition at line 61 of file mpi_remote_point_evaluation.cc.

◆ ~RemotePointEvaluation()

template<int dim, int spacedim>

Utilities::MPI::RemotePointEvaluation< dim, spacedim >::~RemotePointEvaluation ( )

Destructor.

Definition at line 76 of file mpi_remote_point_evaluation.cc.

Member Function Documentation

◆ reinit() [1/3]

template<int dim, int spacedim>

void Utilities::MPI::RemotePointEvaluation< dim, spacedim >::reinit	(	const std::vector< Point< spacedim > > &	points,
		const Triangulation< dim, spacedim > &	tria,
		const Mapping< dim, spacedim > &	mapping )

Set up internal data structures and communication pattern based on a list of points points and mesh description (tria and mapping).

Warning: This is a collective call that needs to be executed by all processors in the communicator.

Note: If you want to be sure that all points have been found, call all_points_found() after calling this function.

Definition at line 86 of file mpi_remote_point_evaluation.cc.

◆ reinit() [2/3]

template<int dim, int spacedim>

void Utilities::MPI::RemotePointEvaluation< dim, spacedim >::reinit	(	const GridTools::Cache< dim, spacedim > &	cache,
		const std::vector< Point< spacedim > > &	points )

Set up internal data structures and communication pattern based on an existing Cache and a list of points points.

Warning: This is a collective call that needs to be executed by all processors in the communicator.

Note: If you want to be sure that all points have been found, call all_points_found() after calling this function.

Definition at line 100 of file mpi_remote_point_evaluation.cc.

◆ reinit() [3/3]

template<int dim, int spacedim>

void Utilities::MPI::RemotePointEvaluation< dim, spacedim >::reinit	(	const GridTools::internal::DistributedComputePointLocationsInternal< dim, spacedim > &	data,
		const Triangulation< dim, spacedim > &	tria,
		const Mapping< dim, spacedim > &	mapping )

Set up internal data structures and communication pattern based on GridTools::internal::DistributedComputePointLocationsInternal.

This function is called internally by the reinit() function above. Having it as a separate function makes it possible to set up the class if it is known in which cells corresponding reference points are located (e.g. if intersections of cells are known).

Definition at line 140 of file mpi_remote_point_evaluation.cc.

◆ get_cell_data()

template<int dim, int spacedim>

const RemotePointEvaluation< dim, spacedim >::CellData & Utilities::MPI::RemotePointEvaluation< dim, spacedim >::get_cell_data ( ) const

Return internal data structure storing the data of points positioned in cells.

Definition at line 312 of file mpi_remote_point_evaluation.cc.

◆ evaluate_and_process() [1/2]

template<int dim, int spacedim>

template<typename DataType, unsigned int n_components>

void Utilities::MPI::RemotePointEvaluation< dim, spacedim >::evaluate_and_process	(	std::vector< DataType > &	output,
		std::vector< DataType > &	buffer,
		const std::function< void(const ArrayView< DataType > &, const CellData &)> &	evaluation_function,
		const bool	sort_data = true ) const

Evaluate function evaluation_function in the given points and triangulation. The result is stored in output.

buffer is a temporary buffer than can be used to avoid extra allocations.

Note: If the map of points to cells is not a one-to-one relation (is_map_unique()==false), the result needs to be processed with the help of get_point_ptrs(). This might be the case if a point coincides with a geometric entity (e.g., vertex) that is shared by multiple cells or a point is outside of the computational domain.

Warning: This is a collective call that needs to be executed by all processors in the communicator.

Note: This function can handle arbitrary types including scalar and Tensor objects. In the case that scalar types are used, one can specify the number of components n_components. This allows to provide unrolled tensors, which is useful, e.g., if its dimension and its rank is not known at compile time.

Definition at line 740 of file mpi_remote_point_evaluation.h.

◆ evaluate_and_process() [2/2]

template<int dim, int spacedim>

template<typename DataType, unsigned int n_components>

std::vector< DataType > Utilities::MPI::RemotePointEvaluation< dim, spacedim >::evaluate_and_process	(	const std::function< void(const ArrayView< DataType > &, const CellData &)> &	evaluation_function,
		const bool	sort_data = true ) const

Same as above but with the result provided as return value and without external allocation of a user-provided buffer.

Definition at line 930 of file mpi_remote_point_evaluation.h.

◆ process_and_evaluate() [1/2]

template<int dim, int spacedim>

template<typename DataType, unsigned int n_components>

void Utilities::MPI::RemotePointEvaluation< dim, spacedim >::process_and_evaluate	(	const std::vector< DataType > &	input,
		std::vector< DataType > &	buffer,
		const std::function< void(const ArrayView< const DataType > &, const CellData &)> &	evaluation_function,
		const bool	sort_data = true ) const

This method is the inverse of the method evaluate_and_process(). It makes the data at the points, provided by input, available in the function evaluation_function.

Warning: This is a collective call that needs to be executed by all processors in the communicator.

Note: This function can handle arbitrary types including scalar and Tensor objects. In the case that scalar types are used, one can specify the number of components n_components. This allows to provide unrolled tensors, which is useful, e.g., if its dimension and its rank is not known at compile time.

Definition at line 951 of file mpi_remote_point_evaluation.h.

◆ process_and_evaluate() [2/2]

template<int dim, int spacedim>

template<typename DataType, unsigned int n_components>

void Utilities::MPI::RemotePointEvaluation< dim, spacedim >::process_and_evaluate	(	const std::vector< DataType > &	input,
		const std::function< void(const ArrayView< const DataType > &, const CellData &)> &	evaluation_function,
		const bool	sort_data = true ) const

Same as above but without external allocation of a user-provided buffer.

Definition at line 1153 of file mpi_remote_point_evaluation.h.

◆ get_point_ptrs()

template<int dim, int spacedim>

const std::vector< unsigned int > & Utilities::MPI::RemotePointEvaluation< dim, spacedim >::get_point_ptrs ( ) const

Return a CRS-like data structure to determine the position of the result corresponding a point and the amount.

Definition at line 321 of file mpi_remote_point_evaluation.cc.

◆ is_map_unique()

template<int dim, int spacedim>

bool Utilities::MPI::RemotePointEvaluation< dim, spacedim >::is_map_unique ( ) const

Return if points and cells have a one-to-one relation. This is not the case if a point is not owned by any cell (the point is outside of the domain) or if multiple cells own the point (the point is positioned on a geometric entity shared by neighboring cells).

Definition at line 330 of file mpi_remote_point_evaluation.cc.

◆ all_points_found()

template<int dim, int spacedim>

bool Utilities::MPI::RemotePointEvaluation< dim, spacedim >::all_points_found ( ) const

Return if all points could be found in the domain.

Definition at line 339 of file mpi_remote_point_evaluation.cc.

◆ point_found()

template<int dim, int spacedim>

bool Utilities::MPI::RemotePointEvaluation< dim, spacedim >::point_found ( const unsigned int i ) const

Return if point i could be found in the domain.

Definition at line 348 of file mpi_remote_point_evaluation.cc.

◆ get_triangulation()

template<int dim, int spacedim>

const Triangulation< dim, spacedim > & Utilities::MPI::RemotePointEvaluation< dim, spacedim >::get_triangulation ( ) const

Return the Triangulation object used during reinit().

Definition at line 363 of file mpi_remote_point_evaluation.cc.

◆ get_mapping()

template<int dim, int spacedim>

const Mapping< dim, spacedim > & Utilities::MPI::RemotePointEvaluation< dim, spacedim >::get_mapping ( ) const

Return the Mapping object used during reinit().

Definition at line 372 of file mpi_remote_point_evaluation.cc.

◆ is_ready()

template<int dim, int spacedim>

bool Utilities::MPI::RemotePointEvaluation< dim, spacedim >::is_ready ( ) const

Return if the internal data structures have been set up and if yes whether they are still valid (and not invalidated due to changes of the Triangulation).

Definition at line 381 of file mpi_remote_point_evaluation.cc.

◆ get_send_permutation()

template<int dim, int spacedim>

const std::vector< unsigned int > & Utilities::MPI::RemotePointEvaluation< dim, spacedim >::get_send_permutation ( ) const

Return permutation needed for sending. If this is applied, evaluation results do not have to be sorted according to the receiving ranks during evaluate_and_process().

Definition at line 390 of file mpi_remote_point_evaluation.cc.

◆ get_inverse_recv_permutation()

template<int dim, int spacedim>

const std::vector< unsigned int > & Utilities::MPI::RemotePointEvaluation< dim, spacedim >::get_inverse_recv_permutation ( ) const

Data is contiguous rank by rank directly after MPI communication. If no sorting is requested during evaluate_and_process(), this permutation allows to access all values corresponding to an evaluation point (sorted into different cells).

Definition at line 399 of file mpi_remote_point_evaluation.cc.

Member Data Documentation

◆ additional_data

template<int dim, int spacedim = dim>

const AdditionalData Utilities::MPI::RemotePointEvaluation< dim, spacedim >::additional_data

private

Additional data with basic settings.

Definition at line 455 of file mpi_remote_point_evaluation.h.

◆ tria_signal

template<int dim, int spacedim = dim>

boost::signals2::connection Utilities::MPI::RemotePointEvaluation< dim, spacedim >::tria_signal

private

Storage for the status of the triangulation signal.

Definition at line 460 of file mpi_remote_point_evaluation.h.

◆ ready_flag

template<int dim, int spacedim = dim>

bool Utilities::MPI::RemotePointEvaluation< dim, spacedim >::ready_flag

private

Flag indicating if the reinit() function has been called and if yes the triangulation has not been modified since then (potentially invalidating the communication pattern).

Definition at line 467 of file mpi_remote_point_evaluation.h.

◆ tria

template<int dim, int spacedim = dim>

ObserverPointer<const Triangulation<dim, spacedim> > Utilities::MPI::RemotePointEvaluation< dim, spacedim >::tria

private

Reference to the Triangulation object used during reinit().

Definition at line 472 of file mpi_remote_point_evaluation.h.

◆ mapping

template<int dim, int spacedim = dim>

ObserverPointer<const Mapping<dim, spacedim> > Utilities::MPI::RemotePointEvaluation< dim, spacedim >::mapping

private

Reference to the Mapping object used during reinit().

Definition at line 477 of file mpi_remote_point_evaluation.h.

◆ unique_mapping

template<int dim, int spacedim = dim>

bool Utilities::MPI::RemotePointEvaluation< dim, spacedim >::unique_mapping

private

(One-to-one) relation of points and cells.

Definition at line 482 of file mpi_remote_point_evaluation.h.

◆ all_points_found_flag

template<int dim, int spacedim = dim>

bool Utilities::MPI::RemotePointEvaluation< dim, spacedim >::all_points_found_flag

private

Cache if all points passed in during reinit() have been found.

Definition at line 487 of file mpi_remote_point_evaluation.h.

◆ point_ptrs

template<int dim, int spacedim = dim>

std::vector<unsigned int> Utilities::MPI::RemotePointEvaluation< dim, spacedim >::point_ptrs

private

Since for each point multiple or no results can be available, the pointers in this vector indicate the first and last entry associated with a point in a CRS-like fashion.

Definition at line 494 of file mpi_remote_point_evaluation.h.

◆ recv_permutation

template<int dim, int spacedim = dim>

std::vector<unsigned int> Utilities::MPI::RemotePointEvaluation< dim, spacedim >::recv_permutation

private

Permutation index within a recv buffer.

Definition at line 499 of file mpi_remote_point_evaluation.h.

◆ recv_permutation_inv

template<int dim, int spacedim = dim>

std::vector<unsigned int> Utilities::MPI::RemotePointEvaluation< dim, spacedim >::recv_permutation_inv

private

Inverse of permutation index within a recv buffer.

Definition at line 504 of file mpi_remote_point_evaluation.h.

◆ recv_ptrs

template<int dim, int spacedim = dim>

std::vector<unsigned int> Utilities::MPI::RemotePointEvaluation< dim, spacedim >::recv_ptrs

private

Pointers of ranges within a receive buffer that are filled by ranks specified by recv_ranks.

Definition at line 510 of file mpi_remote_point_evaluation.h.

◆ recv_ranks

template<int dim, int spacedim = dim>

std::vector<unsigned int> Utilities::MPI::RemotePointEvaluation< dim, spacedim >::recv_ranks

private

Ranks from where data is received.

Definition at line 515 of file mpi_remote_point_evaluation.h.

◆ cell_data

template<int dim, int spacedim = dim>

std::unique_ptr<CellData> Utilities::MPI::RemotePointEvaluation< dim, spacedim >::cell_data

private

Point data sorted according to cells so that evaluation (incl. reading of degrees of freedoms) needs to be performed only once per cell.

Definition at line 521 of file mpi_remote_point_evaluation.h.

◆ send_permutation

template<int dim, int spacedim = dim>

std::vector<unsigned int> Utilities::MPI::RemotePointEvaluation< dim, spacedim >::send_permutation

private

Permutation index within a send buffer.

Definition at line 526 of file mpi_remote_point_evaluation.h.

◆ send_permutation_inv

template<int dim, int spacedim = dim>

std::vector<unsigned int> Utilities::MPI::RemotePointEvaluation< dim, spacedim >::send_permutation_inv

private

Inverse of permutation index within a send buffer.

Definition at line 531 of file mpi_remote_point_evaluation.h.

◆ send_ranks

template<int dim, int spacedim = dim>

std::vector<unsigned int> Utilities::MPI::RemotePointEvaluation< dim, spacedim >::send_ranks

private

Ranks to send to.

Definition at line 536 of file mpi_remote_point_evaluation.h.

◆ send_ptrs

template<int dim, int spacedim = dim>

std::vector<unsigned int> Utilities::MPI::RemotePointEvaluation< dim, spacedim >::send_ptrs

private

Pointers of ranges within a send buffer to be sent to the ranks specified by send_ranks.

Definition at line 542 of file mpi_remote_point_evaluation.h.

◆ buffer_size_with_sorting

template<int dim, int spacedim = dim>

unsigned int Utilities::MPI::RemotePointEvaluation< dim, spacedim >::buffer_size_with_sorting

private

Buffer size (if internal sorting is requested) determined as max of:

needed during evaluate_and_process()

point data (sorted according to cells) -> input from cell loop
point data (sorted according to ranks) -> to be sent
memory for receiving data (by one process at a time)

needed during process_and_evaluate()

point data (sorted according to cells) -> output to cell loop
point data (sorted according to ranks) -> to be sent
memory for receiving data (by one process at a time)

Definition at line 557 of file mpi_remote_point_evaluation.h.

◆ buffer_size_without_sorting

template<int dim, int spacedim = dim>

unsigned int Utilities::MPI::RemotePointEvaluation< dim, spacedim >::buffer_size_without_sorting

private

Buffer size (if sorting is not requested); corresponds to the number of evaluation points.

Definition at line 563 of file mpi_remote_point_evaluation.h.

The documentation for this class was generated from the following files:

include/deal.II/base/mpi_remote_point_evaluation.h
source/base/mpi_remote_point_evaluation.cc

Detailed Description

Classes

Public Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ RemotePointEvaluation() [1/2]

◆ RemotePointEvaluation() [2/2]

◆ ~RemotePointEvaluation()

Member Function Documentation

◆ reinit() [1/3]

◆ reinit() [2/3]

◆ reinit() [3/3]

◆ get_cell_data()

◆ evaluate_and_process() [1/2]

◆ evaluate_and_process() [2/2]

◆ process_and_evaluate() [1/2]

◆ process_and_evaluate() [2/2]

◆ get_point_ptrs()

◆ is_map_unique()

◆ all_points_found()

◆ point_found()

◆ get_triangulation()

◆ get_mapping()

◆ is_ready()

◆ get_send_permutation()

◆ get_inverse_recv_permutation()

Member Data Documentation

◆ additional_data

◆ tria_signal

◆ ready_flag

◆ tria

◆ mapping

◆ unique_mapping

◆ all_points_found_flag

◆ point_ptrs

◆ recv_permutation

◆ recv_permutation_inv

◆ recv_ptrs

◆ recv_ranks

◆ cell_data

◆ send_permutation

◆ send_permutation_inv

◆ send_ranks

◆ send_ptrs

◆ buffer_size_with_sorting

◆ buffer_size_without_sorting