NearestPoint< dim, number > Class Template Reference

Developer Documentation: MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number > Class Template Reference
Developer Documentation
MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number > Class Template Reference

Compute nearest points to the isocontour of a level set function. More...

#include <nearest_point.hpp>

Public Member Functions

 NearestPoint (const dealii::Mapping< dim > &mapping, const dealii::DoFHandler< dim > &dof_handler_signed_distance, const VectorType &signed_distance, const BlockVectorType &normal_vector, dealii::Utilities::MPI::RemotePointEvaluation< dim, dim > &remote_point_evaluation, const NearestPointData< number > &nearest_point_data, std::optional< std::reference_wrapper< dealii::TimerOutput > > timer_output={})
 Constructor.
 
void reinit (const dealii::DoFHandler< dim > *dof_handler_src_in, const dealii::DoFHandler< dim > *dof_handler_dst_in=nullptr)
 Initialize projection by computing nearest points for each DoF in the given DoFHandler.
 
template<int n_components = 1>
void extend_interface_values (VectorType &solution_out, const VectorType &solution_in, const bool zero_out=true, const std::function< number(const number)> &operation={}) const
 Populate a DoF vector with values from the interface.
 
const std::vector< dealii::Point< dim > > & get_projected_points () const
 Get the computed nearest points corresponding to the nodal locations.
 
const std::vector< std::vector< dealii::types::global_dof_index > > & get_projected_points_dof_indices () const
 Get the global DoF indices associated with each nearest point.
 
void write_to_file (const std::string filename_without_ending) const
 Write the computed nearest points to a file.
 

Public Attributes

std::vector< dealii::Point< dim > > points_not_found
 List of points where the projection failed or did not converge (for debug purposes).
 

Private Types

using VectorType = dealii::LinearAlgebra::distributed::Vector< number >
 
using BlockVectorType = dealii::LinearAlgebra::distributed::BlockVector< number >
 

Private Member Functions

template<int n_components = 1>
void extend_interface_values_nearest_point_fast (VectorType &solution_out, const VectorType &solution_in, const bool zero_out=true, const std::function< number(const number)> &operation={}) const
 Populate a DoF vector with values from the interface using ArborX acceleration.
 
void clear_cached_data ()
 Clear all internally cached data.
 
void register_dof_handlers (const dealii::DoFHandler< dim > *dof_handler_src_in, const dealii::DoFHandler< dim > *dof_handler_dst_in)
 Register DoFHandler objects for source and destination spaces.
 
void collect_narrow_band_support_points ()
 Collect support points from the source DoFHandler near the level set interface.
 
void run_projection_algorithm ()
 Run the projection algorithm to determine nearest points on the interface.
 
bool local_compute_normal_correction (std::vector< dealii::Point< dim > > &y)
 
bool local_compute_normal_and_tangential_correction_coquerelle (std::vector< dealii::Point< dim > > &y)
 
bool local_compute_normal_and_tangential_correction (std::vector< dealii::Point< dim > > &y)
 
void local_compute_nearest_point ()
 
void local_compute_nearest_point_fast ()
 

Private Attributes

const dealii::Mapping< dim > & mapping
 Mapping.
 
const dealii::DoFHandler< dim > & dof_handler_ls
 DoFHandler associated with the level set function (signed distance field)
 
const VectorTypesigned_distance
 Level set / signed distance function used to define the interface.
 
const BlockVectorTypenormal_vector
 
const NearestPointData< number > & nearest_point_data
 
dealii::Utilities::MPI::RemotePointEvaluation< dim, dim > & remote_point_evaluation
 
const number tol_distance
 
const number narrow_band_threshold
 
const number tolerance_normal_vector
 Tolerance for accuracy of the normal vector, if used in projection.
 
const MPI_Comm mpi_comm
 Communicator associated with this projection process.
 
dealii::ConditionalOStream pcout
 
std::optional< std::reference_wrapper< dealii::TimerOutput > > timer_output
 Optional scoped timer for profiling different stages of projection.
 
const dealii::DoFHandler< dim > * dof_handler_src = nullptr
 Source DoFHandler: values are projected from this FE space.
 
const dealii::DoFHandler< dim > * dof_handler_dst = nullptr
 
std::vector< dealii::Point< dim > > projected_points_at_interface
 Projected physical coordinates on the interface, corresponding to each DoF in the stencil.
 
std::vector< std::vector< dealii::types::global_dof_index > > dof_indices
 Global DoF indices (per stencil point) — maps each stencil entry to its target DoFs.
 
std::vector< dealii::Point< dim > > stencil
 Coordinates (physical space) of the stencil points used as nearest point queries.
 
int total_points_rpe = 0
 Temporary variable used to count total projected points in RPE or partitioning.
 
bool is_reinit_called = false
 Tracks whether the reinit() function has been called, to prevent misuse.
 
bool input_vector_is_cut = false
 
dealii::Utilities::MPI::NoncontiguousPartitioner partitioner
 Noncontiguous partitioner used to communicate surface point values across MPI ranks.
 
std::vector< dealii::types::global_dof_index > locally_owned_surface_indices
 Global indices of surface/interface points owned by this MPI rank.
 
std::vector< dealii::types::global_dof_index > ghost_surface_indices
 
std::vector< std::pair< std::pair< unsigned int, unsigned int >, std::vector< dealii::Point< dim > > > > surface_cells_and_unit_points
 

Detailed Description

template<int dim, typename number>
class MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >

Compute nearest points to the isocontour of a level set function.

This class provides methods to compute nearest points from a cloud of query points (typically nodal locations from a DoFHandler) to an implicitly defined interface represented by a level set (signed distance) function.

The interface is approximated using a discrete representation, and the nearest points are determined using one of several algorithms specified via NearestPointType.

Supported methods:

  • nearest_point: Discretizes the surface using the marching cubes algorithm and returns the closest point from the input cloud.
  • nearest_point_fast: Same as nearest_point, but uses ArborX for efficient distributed nearest neighbor search.
  • closest_point_normal: Iteratively refines the nearest point using gradient descent along the normal direction of the level set.
  • closest_point_normal_collinear: Variant of the above that ensures the correction is collinear to the interface.
  • closest_point_normal_collinear_coquerelle: Variant using the algorithm from Coquerelle and Glockner (2014), designed to preserve collinearity.

Member Typedef Documentation

◆ BlockVectorType

template<int dim, typename number >
using MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::BlockVectorType = dealii::LinearAlgebra::distributed::BlockVector<number>
private

◆ VectorType

template<int dim, typename number >
using MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::VectorType = dealii::LinearAlgebra::distributed::Vector<number>
private

Constructor & Destructor Documentation

◆ NearestPoint()

template<int dim, typename number >
MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::NearestPoint ( const dealii::Mapping< dim > &  mapping,
const dealii::DoFHandler< dim > &  dof_handler_signed_distance,
const VectorType signed_distance,
const BlockVectorType normal_vector,
dealii::Utilities::MPI::RemotePointEvaluation< dim, dim > &  remote_point_evaluation,
const NearestPointData< number > &  nearest_point_data,
std::optional< std::reference_wrapper< dealii::TimerOutput > >  timer_output = {} 
)

Constructor.

Initializes the nearest point projection utility.

Parameters
mappingMapping used for geometry transformation.
dof_handler_signed_distanceDoFHandler associated with the signed distance (level set) field.
signed_distanceVector containing the signed distance values.
normal_vectorNormal vectors at the interface. Not needed for nearest_point and nearest_point_fast.
remote_point_evaluationObject used for evaluating points across MPI ranks.
nearest_point_dataStruct containing configuration parameters for the projection.
timer_outputOptional timer for profiling.

Member Function Documentation

◆ clear_cached_data()

template<int dim, typename number >
void MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::clear_cached_data ( )
private

Clear all internally cached data.

This is typically called during reinitialization to ensure that outdated or invalid cached data structures (e.g., support points, DoF indices) are properly reset before reuse.

◆ collect_narrow_band_support_points()

template<int dim, typename number >
void MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::collect_narrow_band_support_points ( )
private

Collect support points from the source DoFHandler near the level set interface.

Identifies and stores support points within a narrow band around the level set interface. The width of this band is determined by an internal parameter narrow_band_threshold. These points are used in the projection step to determine closest points.

◆ extend_interface_values()

template<int dim, typename number >
template<int n_components>
template void MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::extend_interface_values< 3 > ( VectorType solution_out,
const VectorType solution_in,
const bool  zero_out = true,
const std::function< number(const number)> &  operation = {} 
) const

Populate a DoF vector with values from the interface.

This function takes a DoF vector solution_in and interpolates its values at the previously projected points on the interface. These values are then inserted into solution_out at the corresponding DoFs.

You can optionally apply a unary operation (e.g. scaling, filtering) to each value before insertion. If zero_out is true, solution_out is reset to zero before writing.

Template Parameters
n_componentsNumber of components (default is 1).
Parameters
solution_outOutput vector to write interface values into.
solution_inInput vector from which values are sampled.
zero_outWhether to zero the output vector before writing.
operationOptional function applied to each sampled value.

◆ extend_interface_values_nearest_point_fast()

template<int dim, typename number >
template<int n_components>
void MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::extend_interface_values_nearest_point_fast ( VectorType solution_out,
const VectorType solution_in,
const bool  zero_out = true,
const std::function< number(const number)> &  operation = {} 
) const
private

Populate a DoF vector with values from the interface using ArborX acceleration.

This internal function populates a DoF vector solution_out by sampling values from solution_in at the interface using the fast nearest-point projection approach based on ArborX. Compared to extend_interface_values(), this method leverages spatial acceleration structures for improved performance.

Template Parameters
n_componentsNumber of vector components to extract (default is 1).
Parameters
solution_outOutput vector to be filled with interpolated values at the interface.
solution_inInput vector from which to sample the values.
zero_outIf true, the solution_out vector is zeroed before values are written.
operationOptional unary operation to apply to each sampled value (e.g., scaling).

◆ get_projected_points()

template<int dim, typename number >
const std::vector< dealii::Point< dim > > & MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::get_projected_points ( ) const

Get the computed nearest points corresponding to the nodal locations.

This function returns the result of the last call to reinit(). Each point corresponds to a nodal location from the source DoFHandler within a narrow band around the requested level set isocontour.

Note
Make sure that you have called reinit() before.
Returns
A vector of projected points on the interface.

◆ get_projected_points_dof_indices()

template<int dim, typename number >
const std::vector< std::vector< dealii::types::global_dof_index > > & MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::get_projected_points_dof_indices ( ) const

Get the global DoF indices associated with each nearest point.

For each point in the stencil, this function provides the set of DoF indices (per component) in the source FE space that the projected values correspond to.

Note
You must call reinit() before using this method.
Returns
A vector of vectors of global DoF indices.

◆ local_compute_nearest_point()

template<int dim, typename number >
void MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::local_compute_nearest_point ( )
private

Create a surface mesh and identify the closest point as the nearest vertex of the surface mesh.

◆ local_compute_nearest_point_fast()

template<int dim, typename number >
void MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::local_compute_nearest_point_fast ( )
private

Fast path – create a surface mesh and identify the closest point as the nearest vertex of the surface mesh.

◆ local_compute_normal_and_tangential_correction()

template<int dim, typename number >
bool MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::local_compute_normal_and_tangential_correction ( std::vector< dealii::Point< dim > > &  y)
private

Perform a closest point projection of a point x to the surface by an iterative correction procedure in the normal direction and the tangential direction. First, we iteratively correct in normal direction

(k+1) (k) / (k) \ y = y - d nΓ | y | for k=0...max_iter \ /

with y being the closest point of a support point, d the signed distance function and nΓ the interface normal vector. The iteration is finished once the required tolerance for d is achieved. Then, the algorithm continues with the tangential correction step

(k+1) (k+1) / (k+1) \ / (k+1) \ y = y - ω | y | tΓ | y | i\ / i \ /

with the tangential vector to the interface tΓ and the tangential distance ω

 /  (k)    \                            2D: {0}

ω = | y - x | · tΓ for i in i \ / i 3D: {0,1}

◆ local_compute_normal_and_tangential_correction_coquerelle()

template<int dim, typename number >
bool MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::local_compute_normal_and_tangential_correction_coquerelle ( std::vector< dealii::Point< dim > > &  y)
private

Perform a closest point projection of a point x to the surface by an iterative correction procedure in the normal direction and the tangential direction according to

M. Coquerelle, S. Glockner (2014). A fourth-order accurate curvature computation in a level set framework for two-phase flows subjected to surface tension forces. First, the point is corrected in tangential direction via

(0) (0) / (0) \ / (0) \ y = y - ω | y | tΓ | y | i\ / i \ /

with the tangential vector to the interface tΓ and the tangential distance ω

 /  (0)    \                            2D: {0}

ω = | y - x | · tΓ for i in i \ / i 3D: {0,1}

and subsequently is iteratively corrected in normal direction

(k+1) (k) / (k) \ y = y - d nΓ | y | for k=0...max_iter \ /

with y being the closest point of a support point, d the signed distance function and nΓ the interface normal vector. The iteration is finished once the required tolerance for d is achieved for all points within the input/output list of points y.

◆ local_compute_normal_correction()

template<int dim, typename number >
bool MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::local_compute_normal_correction ( std::vector< dealii::Point< dim > > &  y)
private

Perform a closest point projection to the surface by an iterative correction procedure in the normal direction according to:

(k+1) (k) / (k) \ / (k) \ y = y - d | y | nΓ | y | for k=0...max_iter \ / \ /

with y being the closest point of a support point, d the signed distance function and nΓ the interface normal vector. The iteration is skipped once the required tolerance for d is achieved for all points within the input/output list of points y.

◆ register_dof_handlers()

template<int dim, typename number >
void MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::register_dof_handlers ( const dealii::DoFHandler< dim > *  dof_handler_src_in,
const dealii::DoFHandler< dim > *  dof_handler_dst_in 
)
private

Register DoFHandler objects for source and destination spaces.

Registers the degrees of freedom handlers used for sampling (dof_handler_src_in) and for interpolation or projection (dof_handler_dst_in). These define the finite element spaces used during interface value transfer.

Parameters
dof_handler_src_inPointer to the DoFHandler used to extract interface values.
dof_handler_dst_inPointer to the DoFHandler used to store the resulting values.

◆ reinit()

template<int dim, typename number >
void MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::reinit ( const dealii::DoFHandler< dim > *  dof_handler_src_in,
const dealii::DoFHandler< dim > *  dof_handler_dst_in = nullptr 
)

Initialize projection by computing nearest points for each DoF in the given DoFHandler.

This function performs the projection of nodal locations from dof_handler_src_in to the interface defined by the level set function. Depending on the algorithm type, this may involve nearest neighbor queries or iterative corrections.

If the source DoFHandler corresponds to a CutFEM method, you must also provide a destination DoFHandler dof_handler_dst_in which must have the same unit support points and number of components.

Parameters
dof_handler_src_inThe source DoFHandler (used to define the nodal stencil points).
dof_handler_dst_inThe optional destination DoFHandler (used for CutFEM or non-matching cases).

◆ run_projection_algorithm()

template<int dim, typename number >
void MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::run_projection_algorithm ( )
private

Run the projection algorithm to determine nearest points on the interface.

Executes the projection procedure using precomputed support points and the ArborX spatial search structures. The resulting coordinates of the closest points to the discrete interface are stored in projected_points_at_interface.

◆ write_to_file()

template<int dim, typename number >
void MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::write_to_file ( const std::string  filename_without_ending) const

Write the computed nearest points to a file.

Dumps the list of nearest points (computed via reinit()) to a plain text table file with the given filename. Each line contains the coordinates of a point.

Parameters
filename_without_endingThe base name of the output file.

Member Data Documentation

◆ dof_handler_dst

template<int dim, typename number >
const dealii::DoFHandler<dim>* MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::dof_handler_dst = nullptr
private

Optional destination DoFHandler: used when projecting between different FE spaces (e.g. cutFEM). Required when src_is_cut = true.

◆ dof_handler_ls

template<int dim, typename number >
const dealii::DoFHandler<dim>& MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::dof_handler_ls
private

DoFHandler associated with the level set function (signed distance field)

◆ dof_handler_src

template<int dim, typename number >
const dealii::DoFHandler<dim>* MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::dof_handler_src = nullptr
private

Source DoFHandler: values are projected from this FE space.

◆ dof_indices

template<int dim, typename number >
std::vector<std::vector<dealii::types::global_dof_index> > MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::dof_indices
private

Global DoF indices (per stencil point) — maps each stencil entry to its target DoFs.

◆ ghost_surface_indices

template<int dim, typename number >
std::vector<dealii::types::global_dof_index> MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::ghost_surface_indices
private

Global indices of surface/interface points owned remotely (ghost points) corresponding to the stencil point owned by this rank

◆ input_vector_is_cut

template<int dim, typename number >
bool MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::input_vector_is_cut = false
private

Indicates whether the input vector corresponds to a cut DoFHandler (e.g. in embedded methods)

◆ is_reinit_called

template<int dim, typename number >
bool MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::is_reinit_called = false
private

Tracks whether the reinit() function has been called, to prevent misuse.

◆ locally_owned_surface_indices

template<int dim, typename number >
std::vector<dealii::types::global_dof_index> MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::locally_owned_surface_indices
private

Global indices of surface/interface points owned by this MPI rank.

◆ mapping

template<int dim, typename number >
const dealii::Mapping<dim>& MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::mapping
private

Mapping.

◆ mpi_comm

template<int dim, typename number >
const MPI_Comm MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::mpi_comm
private

Communicator associated with this projection process.

◆ narrow_band_threshold

template<int dim, typename number >
const number MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::narrow_band_threshold
private

Threshold defining the narrow band for projection — usually a fraction of max(|distance|). Prevents projection far from the interface in regions where distance field may saturate. In the default case, we limit the interval for closest point projection to max(distance)*0.9999 to avoid projection in regions, where the distance is constant at max(distance).

◆ nearest_point_data

template<int dim, typename number >
const NearestPointData<number>& MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::nearest_point_data
private

Parameters controlling the nearest point projection (e.g., tolerance, contour value, subdivisions, etc.)

◆ normal_vector

template<int dim, typename number >
const BlockVectorType& MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::normal_vector
private

Optional vector containing the interface normals at DoFs (used for projection direction or correction)

◆ partitioner

template<int dim, typename number >
dealii::Utilities::MPI::NoncontiguousPartitioner MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::partitioner
private

Noncontiguous partitioner used to communicate surface point values across MPI ranks.

◆ pcout

template<int dim, typename number >
dealii::ConditionalOStream MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::pcout
private

◆ points_not_found

template<int dim, typename number >
std::vector<dealii::Point<dim> > MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::points_not_found
mutable

List of points where the projection failed or did not converge (for debug purposes).

◆ projected_points_at_interface

template<int dim, typename number >
std::vector<dealii::Point<dim> > MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::projected_points_at_interface
private

Projected physical coordinates on the interface, corresponding to each DoF in the stencil.

◆ remote_point_evaluation

template<int dim, typename number >
dealii::Utilities::MPI::RemotePointEvaluation<dim, dim>& MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::remote_point_evaluation
private

Object for evaluating remote points across MPI ranks (used to gather values at projected positions)

◆ signed_distance

template<int dim, typename number >
const VectorType& MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::signed_distance
private

Level set / signed distance function used to define the interface.

◆ stencil

template<int dim, typename number >
std::vector<dealii::Point<dim> > MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::stencil
private

Coordinates (physical space) of the stencil points used as nearest point queries.

◆ surface_cells_and_unit_points

template<int dim, typename number >
std::vector<std::pair<std::pair<unsigned int, unsigned int>, std::vector<dealii::Point<dim> > > > MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::surface_cells_and_unit_points
private

Stores pairs of (cell level, cell index) with corresponding unit reference points on the interface. Used to evaluate FE values at interface locations.

◆ timer_output

template<int dim, typename number >
std::optional<std::reference_wrapper<dealii::TimerOutput> > MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::timer_output
private

Optional scoped timer for profiling different stages of projection.

◆ tol_distance

template<int dim, typename number >
const number MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::tol_distance
private

◆ tolerance_normal_vector

template<int dim, typename number >
const number MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::tolerance_normal_vector
private

Tolerance for accuracy of the normal vector, if used in projection.

◆ total_points_rpe

template<int dim, typename number >
int MeltPoolDG::LevelSet::Tools::NearestPoint< dim, number >::total_points_rpe = 0
private

Temporary variable used to count total projected points in RPE or partitioning.


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