Inverse Trafo mapping class template. More...

#include <inverse_mapping.hpp>

Public Types
typedef DataType_	DataType
	the datatype to be used More...

typedef InvMapDataType::DomainPointType	DomainPointType
	the domain point type More...

typedef InvMapDataType::ImagePointType	ImagePointType
	the image point type More...

typedef InverseMappingData< DataType, shape_dim, world_dim >	InvMapDataType
	the inverse mapping data type More...

typedef TrafoType::ShapeType	ShapeType
	the shape type More...

typedef Trafo_	TrafoType
	the underlying trafo type More...

Public Member Functions
	InverseMapping (const TrafoType &trafo, DataType bbox_tol=DataType(1E-2), DataType domain_tol=DataType(1E-4))
	Constructor. More...

virtual	~InverseMapping ()
	virtual destructor More...

bool	find_candidate_cells (std::vector< Index > &cells, const ImagePointType &img_point) const
	Determines a set of candidate cells by a bounding-box test. More...

void	init_bounding_boxes (DataType bbox_tol)
	Initializes the cell bounding boxes array. More...

bool	test_domain_point (const DomainPointType &dom_point) const
	Tests whether a given domain point is on the reference element. More...

InvMapDataType	unmap_point (const ImagePointType &img_point, bool ignore_failures=false) const
	Unmaps a given image point. More...

InvMapDataType	unmap_point (const ImagePointType &img_point, const std::vector< Index > &cells, bool ignore_failures=false) const
	Unmaps a given image point. More...

bool	unmap_point_by_newton (DomainPointType &dom_point, const ImagePointType &img_point, const Index cell) const
	Unmaps a given point on a particular cell by Newton iteration. More...

Static Public Attributes
static constexpr int	shape_dim = ShapeType::dimension
	the shape dimension More...

static constexpr int	world_dim = TrafoType::world_dim
	the world dimension More...

Protected Types
typedef Tiny::Matrix< DataType_, 2, world_dim >	BBox
	our bounding box type More...

Protected Attributes
std::vector< BBox >	_bboxes
	the array of cell bounding boxes More...

DataType	_domain_tol
	tolerance for unmapped domain coordinates More...

Index	_newton_max_iter
	maximum number of newton iterations for unmapping More...

DataType	_newton_tol
	absolute tolerance for newton iteration More...

const TrafoType &	_trafo
	the trafo mapping More...

Detailed Description

template<typename Trafo_, typename DataType_>
class FEAT::Trafo::InverseMapping< Trafo_, DataType_ >

Inverse Trafo mapping class template.

This class template implements an "inverse trafo mapping", which is capable of unmapping points, i.e. it can determine the cells and reference coordinates that can be mapped onto a given input point using the "normal" transformation.

Template Parameters

Trafo_	The type of the trafo mapping that is to be inverted.
DataType_	The datatype that is used for internal calculations.

Attention: Note to implementors: The implementation of this class works only for the standard first-order transformations (both simplexes and hypercube). If you want to add support for higher-order (iso-parametric) transformations, you will need to find a way to compute the cell bounding boxes for the candidate cell selection, as the algorithm implemented in the init_bounding_boxes() function works only for first-order trafos!

Author: Peter Zajac

Definition at line 156 of file inverse_mapping.hpp.

Member Typedef Documentation

◆ BBox

template<typename Trafo_ , typename DataType_ >

typedef Tiny::Matrix<DataType_, 2, world_dim> FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::BBox

protected

our bounding box type

Definition at line 180 of file inverse_mapping.hpp.

◆ DataType

template<typename Trafo_ , typename DataType_ >

typedef DataType_ FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::DataType

the datatype to be used

Definition at line 162 of file inverse_mapping.hpp.

◆ DomainPointType

template<typename Trafo_ , typename DataType_ >

typedef InvMapDataType::DomainPointType FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::DomainPointType

the domain point type

Definition at line 176 of file inverse_mapping.hpp.

◆ ImagePointType

template<typename Trafo_ , typename DataType_ >

typedef InvMapDataType::ImagePointType FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::ImagePointType

the image point type

Definition at line 174 of file inverse_mapping.hpp.

◆ InvMapDataType

template<typename Trafo_ , typename DataType_ >

typedef InverseMappingData<DataType, shape_dim, world_dim> FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::InvMapDataType

the inverse mapping data type

Definition at line 171 of file inverse_mapping.hpp.

◆ ShapeType

template<typename Trafo_ , typename DataType_ >

typedef TrafoType::ShapeType FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::ShapeType

the shape type

Definition at line 164 of file inverse_mapping.hpp.

◆ TrafoType

template<typename Trafo_ , typename DataType_ >

typedef Trafo_ FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::TrafoType

the underlying trafo type

Definition at line 160 of file inverse_mapping.hpp.

Constructor & Destructor Documentation

◆ InverseMapping()

template<typename Trafo_ , typename DataType_ >

FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::InverseMapping	(	const TrafoType &	trafo,
		DataType	bbox_tol = `DataType(1E-2)`,
		DataType	domain_tol = `DataType(1E-4)`
	)

inlineexplicit

Constructor.

Parameters

[in]	trafo	The resident trafo mapping that is to be inverted.
[in]	bbox_tol	The bounding box tolerance used for building the cell bounding boxes.
[in]	domain_tol	The coordinate tolerance for the unmapped domain points.

This constructor automatically initializes the bounding boxes and sets the default parameters for the Newton iteration to:

tolerance: eps^(0.9)
max. iterations: 10

Definition at line 210 of file inverse_mapping.hpp.

References FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::init_bounding_boxes().

◆ ~InverseMapping()

template<typename Trafo_ , typename DataType_ >

virtual FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::~InverseMapping ( )

inlinevirtual

virtual destructor

Definition at line 223 of file inverse_mapping.hpp.

Member Function Documentation

◆ find_candidate_cells()

template<typename Trafo_ , typename DataType_ >

bool FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::find_candidate_cells	(	std::vector< Index > &	cells,
		const ImagePointType &	img_point
	)		const

inline

Determines a set of candidate cells by a bounding-box test.

This function determines a set of "candidate" cells which may intersect with a given image point by applying a simple bounding-box test.

Note: This function may (and often will) give you "false positives", i.e. the candidate cells that are selected by this function may not intersect with the given input point.
However, this function never produces "false negatives", i.e. if a cell actually intersects with the given input point, then this particular cell will definitely be selected as a candidate.

Parameters

[out]	cells	A transient vector that receives the indices of all found candidate cells.
[in]	img_point	The image point for which the candidates are to be found.

Returns: true, if at least one candidate cell was found, otherwise false.

Definition at line 463 of file inverse_mapping.hpp.

References FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::_bboxes, FEAT::img_point, and FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::shape_dim.

Referenced by FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::unmap_point().

◆ init_bounding_boxes()

template<typename Trafo_ , typename DataType_ >

void FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::init_bounding_boxes ( DataType bbox_tol )

inline

Initializes the cell bounding boxes array.

Parameters

[in] bbox_tol The bounding box tolerance used for building the cell bounding boxes.

Note: This function is automatically called by the constructor. You only need to call this function explicitly if the underlying mesh or trafo has changed.

Definition at line 237 of file inverse_mapping.hpp.

References FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::_bboxes, FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::_trafo, FEAT::Math::minimax(), and FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::world_dim.

Referenced by FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::InverseMapping().

◆ test_domain_point()

template<typename Trafo_ , typename DataType_ >

bool FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::test_domain_point ( const DomainPointType & dom_point ) const

inline

Tests whether a given domain point is on the reference element.

Parameters

[in] dom_point The domain point that is to be tested.

Returns: true, if dom_point is on the reference element, otherwise false.

Definition at line 566 of file inverse_mapping.hpp.

References FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::_domain_tol, and FEAT::dom_point.

Referenced by FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::unmap_point().

◆ unmap_point() [1/2]

template<typename Trafo_ , typename DataType_ >

InvMapDataType FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::unmap_point	(	const ImagePointType &	img_point,
		bool	ignore_failures = `false`
	)		const

inline

Unmaps a given image point.

This function "unmaps" a point given in real world coordinates, i.e. this function determines the set of cells that intersect with the given point and also computes the corresponding domain points for each of these cells.

This function performs several steps:

First, this function determines a set of candidate cells by using a simple bounding box test provided by the find_candidate_cells() function.
Then, for each of the candidate cells, this function tries to unmap the given point onto the cell to obtain the domain point coordinates by using a Newton iteration provided by the unmap_point_by_newton() function.
Finally, this function checks whether the unmapped point is on the reference cell by using the test_domain_point() function.

Attention: This function may throw an InverseMappingError if the given input point img_point could not be unmapped for a candidate cell, unless ignore_failures was set to true. This usually indicates that the mesh has quite ill-formed cell shapes, which cause the Newton iteration to diverge – especially, if the point to be tested is not on the candidate cell, but outside of it.

Parameters

[in]	img_point	The image point that is to be unmapped.
[in]	ignore_failures	Specifies whether to ignore cells on which the Newton iteration broke down. If set to `false`, an InverseMappingError will be thrown if Newton fails to converge, otherwise the corresponding cell will be skipped.

Returns: An InverseMappingData object that contains the set of cells and domain points, which are mapped onto the given img_point.

Definition at line 317 of file inverse_mapping.hpp.

References FEAT::Trafo::InverseMappingData< DataType_, shape_dim_, world_dim_ >::cells, FEAT::dom_point, FEAT::Trafo::InverseMappingData< DataType_, shape_dim_, world_dim_ >::dom_points, FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::find_candidate_cells(), FEAT::img_point, FEAT::Trafo::InverseMappingData< DataType_, shape_dim_, world_dim_ >::img_point, FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::test_domain_point(), and FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::unmap_point_by_newton().

Referenced by FEAT::Assembly::DiscreteEvaluator::eval_fe_function(), and FEAT::Assembly::DiscreteEvaluator::eval_fe_gradient().

◆ unmap_point() [2/2]

template<typename Trafo_ , typename DataType_ >

InvMapDataType FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::unmap_point	(	const ImagePointType &	img_point,
		const std::vector< Index > &	cells,
		bool	ignore_failures = `false`
	)		const

inline

Unmaps a given image point.

This function "unmaps" a point given in real world coordinates, i.e. this function determines the set of cells that intersect with the given point and also computes the corresponding domain points for each of these cells.

This function performs several steps:

First, for each of the candidate cells, this function tries to unmap the given point onto the cell to obtain the domain point coordinates by using a Newton iteration provided by the unmap_point_by_newton() function.
Finally, this function checks whether the unmapped point is on the reference cell by using the test_domain_point() function.

Attention: This function may throw an InverseMappingError if the given input point img_point could not be unmapped for a candidate cell, unless ignore_failures was set to true. This usually indicates that the mesh has quite ill-formed cell shapes, which cause the Newton iteration to diverge – especially, if the point to be tested is not on the candidate cell, but outside of it.

\Note You should be sure that at least on cell in the given Cell array does indeed contain the inquired point. Else you the more costly overload function above

Parameters

[in]	img_point	The image point that is to be unmapped.
[in]	cell	A transient reference to a vector of indices containing the possible candidates which may contain the image point.
[in]	ignore_failures	Specifies whether to ignore cells on which the Newton iteration broke down. If set to `false`, an InverseMappingError will be thrown if Newton fails to converge, otherwise the corresponding cell will be skipped.

Returns: An InverseMappingData object that contains the set of cells and domain points, which are mapped onto the given img_point.

Definition at line 400 of file inverse_mapping.hpp.

References FEAT::Trafo::InverseMappingData< DataType_, shape_dim_, world_dim_ >::cells, FEAT::dom_point, FEAT::Trafo::InverseMappingData< DataType_, shape_dim_, world_dim_ >::dom_points, FEAT::img_point, FEAT::Trafo::InverseMappingData< DataType_, shape_dim_, world_dim_ >::img_point, FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::test_domain_point(), and FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::unmap_point_by_newton().

◆ unmap_point_by_newton()

template<typename Trafo_ , typename DataType_ >

bool FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::unmap_point_by_newton	(	DomainPointType &	dom_point,
		const ImagePointType &	img_point,
		const Index	cell
	)		const

inline

Unmaps a given point on a particular cell by Newton iteration.

Parameters

[out]	dom_point	The domain point that is to be computed.
[in]	img_point	The image point that is to be unmapped.
[in]	cell	The index of the cell on which `img_point` is to be unmapped.

Returns: true, if the Newton iteration successfully unmapped the input point, or false, if the Newton iteration did not converge.

Definition at line 505 of file inverse_mapping.hpp.

References FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::_newton_max_iter, FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::_newton_tol, FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::_trafo, FEAT::dom_point, FEAT::img_point, FEAT::jac_inv, FEAT::Tiny::Vector< T_, n_, s_ >::norm_euclid_sqr(), FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::shape_dim, and FEAT::Math::sqr().

Referenced by FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::unmap_point().

Member Data Documentation

◆ _bboxes

template<typename Trafo_ , typename DataType_ >

std::vector<BBox> FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::_bboxes

protected

the array of cell bounding boxes

Definition at line 184 of file inverse_mapping.hpp.

Referenced by FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::find_candidate_cells(), and FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::init_bounding_boxes().

◆ _domain_tol

template<typename Trafo_ , typename DataType_ >

DataType FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::_domain_tol

protected

tolerance for unmapped domain coordinates

Definition at line 186 of file inverse_mapping.hpp.

Referenced by FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::test_domain_point().

◆ _newton_max_iter

template<typename Trafo_ , typename DataType_ >

Index FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::_newton_max_iter

protected

maximum number of newton iterations for unmapping

Definition at line 190 of file inverse_mapping.hpp.

Referenced by FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::unmap_point_by_newton().

◆ _newton_tol

template<typename Trafo_ , typename DataType_ >

DataType FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::_newton_tol

protected

absolute tolerance for newton iteration

Definition at line 188 of file inverse_mapping.hpp.

Referenced by FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::unmap_point_by_newton().

◆ _trafo

template<typename Trafo_ , typename DataType_ >

const TrafoType& FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::_trafo

protected

the trafo mapping

Definition at line 182 of file inverse_mapping.hpp.

Referenced by FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::init_bounding_boxes(), and FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::unmap_point_by_newton().

◆ shape_dim

template<typename Trafo_ , typename DataType_ >

constexpr int FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::shape_dim = ShapeType::dimension

staticconstexpr

the shape dimension

Definition at line 166 of file inverse_mapping.hpp.

Referenced by FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::find_candidate_cells(), and FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::unmap_point_by_newton().

◆ world_dim

template<typename Trafo_ , typename DataType_ >

constexpr int FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::world_dim = TrafoType::world_dim

staticconstexpr

the world dimension

Definition at line 168 of file inverse_mapping.hpp.

Referenced by FEAT::Trafo::InverseMapping< Trafo_, DataType_ >::init_bounding_boxes().

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

kernel/trafo/inverse_mapping.hpp

Public Types

Public Member Functions

Static Public Attributes

Protected Types

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ BBox

◆ DataType

◆ DomainPointType

◆ ImagePointType

◆ InvMapDataType

◆ ShapeType

◆ TrafoType

Constructor & Destructor Documentation

◆ InverseMapping()

◆ ~InverseMapping()

Member Function Documentation

◆ find_candidate_cells()

◆ init_bounding_boxes()

◆ test_domain_point()

◆ unmap_point() [1/2]

◆ unmap_point() [2/2]

◆ unmap_point_by_newton()

Member Data Documentation

◆ _bboxes

◆ _domain_tol

◆ _newton_max_iter

◆ _newton_tol

◆ _trafo

◆ shape_dim

◆ world_dim