MFEM  v4.6.0
Finite element discretization library
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
mfem::InverseElementTransformation Class Reference

The inverse transformation of a given ElementTransformation. More...

#include <eltrans.hpp>

Collaboration diagram for mfem::InverseElementTransformation:
[legend]

Public Types

enum  InitGuessType { Center = 0, ClosestPhysNode = 1, ClosestRefNode = 2, GivenPoint = 3 }
 Algorithms for selecting an initial guess. More...
 
enum  SolverType { Newton = 0, NewtonSegmentProject = 1, NewtonElementProject = 2 }
 Solution strategy. More...
 
enum  TransformResult { Inside = 0, Outside = 1, Unknown = 2 }
 Values returned by Transform(). More...
 

Public Member Functions

 InverseElementTransformation (ElementTransformation *Trans=NULL)
 Construct the InverseElementTransformation with default parameters. More...
 
virtual ~InverseElementTransformation ()
 
void SetTransformation (ElementTransformation &Trans)
 Set a new forward ElementTransformation, Trans. More...
 
void SetInitialGuessType (InitGuessType itype)
 Choose how the initial guesses for subsequent calls to Transform() will be selected. More...
 
void SetInitialGuess (const IntegrationPoint &init_ip)
 Set the initial guess for subsequent calls to Transform(), switching to the GivenPoint InitGuessType at the same time. More...
 
void SetInitGuessPointsType (int q_type)
 Set the Quadrature1D type used for the Closest* initial guess types. More...
 
void SetInitGuessRelOrder (int order)
 Set the relative order used for the Closest* initial guess types. More...
 
void SetSolverType (SolverType stype)
 Specify which algorithm to use for solving the transformation equation, i.e. when calling the Transform() method. More...
 
void SetMaxIter (int max_it)
 Set the maximum number of iterations when solving for a reference point. More...
 
void SetReferenceTol (double ref_sp_tol)
 Set the reference-space convergence tolerance. More...
 
void SetPhysicalRelTol (double phys_rel_tol)
 Set the relative physical-space convergence tolerance. More...
 
void SetElementTol (double el_tol)
 Set the tolerance used to determine if a point lies inside or outside of the reference element. More...
 
void SetPrintLevel (int pr_level)
 Set the desired print level, useful for debugging. More...
 
int FindClosestPhysPoint (const Vector &pt, const IntegrationRule &ir)
 Find the IntegrationPoint mapped closest to pt. More...
 
int FindClosestRefPoint (const Vector &pt, const IntegrationRule &ir)
 Find the IntegrationPoint mapped closest to pt, using a norm that approximates the (unknown) distance in reference coordinates. More...
 
virtual int Transform (const Vector &pt, IntegrationPoint &ip)
 Given a point, pt, in physical space, find its reference coordinates, ip. More...
 

Protected Member Functions

void NewtonPrint (int mode, double val)
 
void NewtonPrintPoint (const char *prefix, const Vector &pt, const char *suffix)
 
int NewtonSolve (const Vector &pt, IntegrationPoint &ip)
 

Protected Attributes

ElementTransformationT
 
const IntegrationPointip0
 
int init_guess_type
 
int qpts_type
 
int rel_qpts_order
 
int solver_type
 
int max_iter
 
double ref_tol
 
double phys_rtol
 
double ip_tol
 
int print_level
 

Detailed Description

The inverse transformation of a given ElementTransformation.

Definition at line 185 of file eltrans.hpp.

Member Enumeration Documentation

◆ InitGuessType

Algorithms for selecting an initial guess.

Enumerator
Center 

Use the center of the reference element.

ClosestPhysNode 

Use the point returned by FindClosestPhysPoint() from a reference-space grid of type and size controlled by SetInitGuessPointsType() and SetInitGuessRelOrder(), respectively.

ClosestRefNode 

Use the point returned by FindClosestRefPoint() from a reference-space grid of type and size controlled by SetInitGuessPointsType() and SetInitGuessRelOrder(), respectively.

GivenPoint 

Use a specific point, set with SetInitialGuess().

Definition at line 189 of file eltrans.hpp.

◆ SolverType

Solution strategy.

Enumerator
Newton 

Use Newton's algorithm, without restricting the reference-space points (iterates) to the reference element.

NewtonSegmentProject 

Use Newton's algorithm, restricting the reference-space points to the reference element by scaling back the Newton increments, i.e. projecting new iterates, x_new, lying outside the element, to the intersection of the line segment [x_old, x_new] with the boundary.

NewtonElementProject 

Use Newton's algorithm, restricting the reference-space points to the reference element by projecting new iterates, x_new, lying outside the element, to the point on the boundary closest (in reference-space) to x_new.

Definition at line 204 of file eltrans.hpp.

◆ TransformResult

Values returned by Transform().

Enumerator
Inside 

The point is inside the element.

Outside 

The point is probably outside the element.

Unknown 

The algorithm failed to determine where the point is.

Definition at line 222 of file eltrans.hpp.

Constructor & Destructor Documentation

◆ InverseElementTransformation()

mfem::InverseElementTransformation::InverseElementTransformation ( ElementTransformation Trans = NULL)
inline

Construct the InverseElementTransformation with default parameters.

Some practical considerations regarding the choice of initial guess type and solver type:

  1. The combination of Center and NewtonSegmentProject provides the fastest way to estimate if a point lies inside an element, assuming that most queried elements are not very deformed, e.g. if most elements are convex.
  2. [Default] The combination of Center and NewtonElementProject provides a somewhat slower alternative to 1 with the benefit of being more reliable in the case when the query point is inside the element but potentially slower in the case when the query point is outside the element.
  3. The combination of ClosestPhysNode and NewtonElementProject is slower than 1 and 2 but much more reliable, especially in the case of highly distorted elements which do not have very high aspect ratios.
  4. The combination of ClosestRefNode and NewtonElementProject should generally be the most reliable, coming at a bit higher computational cost than 3 while performing better on distorted meshes with elements having high aspect ratios.
    Note
    None of these choices provide a guarantee that if a query point is inside the element then it will be found. The only guarantee is that if the Transform() method returns Inside then the point lies inside the element up to one of the specified physical- or reference-space tolerances.

Definition at line 275 of file eltrans.hpp.

◆ ~InverseElementTransformation()

virtual mfem::InverseElementTransformation::~InverseElementTransformation ( )
inlinevirtual

Definition at line 289 of file eltrans.hpp.

Member Function Documentation

◆ FindClosestPhysPoint()

int mfem::InverseElementTransformation::FindClosestPhysPoint ( const Vector pt,
const IntegrationRule ir 
)

Find the IntegrationPoint mapped closest to pt.

This function uses the given IntegrationRule, ir, maps its points to physical space and finds the one that is closest to the point pt.

Parameters
ptThe query point.
irThe IntegrationRule, i.e. the set of reference points to map to physical space and check.
Returns
The index of the IntegrationPoint in ir whose mapped point is closest to pt.
See also
FindClosestRefPoint().

Definition at line 70 of file eltrans.cpp.

◆ FindClosestRefPoint()

int mfem::InverseElementTransformation::FindClosestRefPoint ( const Vector pt,
const IntegrationRule ir 
)

Find the IntegrationPoint mapped closest to pt, using a norm that approximates the (unknown) distance in reference coordinates.

See also
FindClosestPhysPoint().

Definition at line 97 of file eltrans.cpp.

◆ NewtonPrint()

void mfem::InverseElementTransformation::NewtonPrint ( int  mode,
double  val 
)
protected

Definition at line 129 of file eltrans.cpp.

◆ NewtonPrintPoint()

void mfem::InverseElementTransformation::NewtonPrintPoint ( const char *  prefix,
const Vector pt,
const char *  suffix 
)
protected

Definition at line 158 of file eltrans.cpp.

◆ NewtonSolve()

int mfem::InverseElementTransformation::NewtonSolve ( const Vector pt,
IntegrationPoint ip 
)
protected

Definition at line 172 of file eltrans.cpp.

◆ SetElementTol()

void mfem::InverseElementTransformation::SetElementTol ( double  el_tol)
inline

Set the tolerance used to determine if a point lies inside or outside of the reference element.

This tolerance is used only with the pure Newton solver.

Definition at line 328 of file eltrans.hpp.

◆ SetInitGuessPointsType()

void mfem::InverseElementTransformation::SetInitGuessPointsType ( int  q_type)
inline

Set the Quadrature1D type used for the Closest* initial guess types.

Definition at line 304 of file eltrans.hpp.

◆ SetInitGuessRelOrder()

void mfem::InverseElementTransformation::SetInitGuessRelOrder ( int  order)
inline

Set the relative order used for the Closest* initial guess types.

The number of points in each spatial direction is given by the formula max(trans_order+order,0)+1, where trans_order is the order of the current ElementTransformation.

Definition at line 310 of file eltrans.hpp.

◆ SetInitialGuess()

void mfem::InverseElementTransformation::SetInitialGuess ( const IntegrationPoint init_ip)
inline

Set the initial guess for subsequent calls to Transform(), switching to the GivenPoint InitGuessType at the same time.

Definition at line 300 of file eltrans.hpp.

◆ SetInitialGuessType()

void mfem::InverseElementTransformation::SetInitialGuessType ( InitGuessType  itype)
inline

Choose how the initial guesses for subsequent calls to Transform() will be selected.

Definition at line 296 of file eltrans.hpp.

◆ SetMaxIter()

void mfem::InverseElementTransformation::SetMaxIter ( int  max_it)
inline

Set the maximum number of iterations when solving for a reference point.

Definition at line 317 of file eltrans.hpp.

◆ SetPhysicalRelTol()

void mfem::InverseElementTransformation::SetPhysicalRelTol ( double  phys_rel_tol)
inline

Set the relative physical-space convergence tolerance.

Definition at line 323 of file eltrans.hpp.

◆ SetPrintLevel()

void mfem::InverseElementTransformation::SetPrintLevel ( int  pr_level)
inline

Set the desired print level, useful for debugging.

The valid options are: -1 - never print (default); 0 - print only errors; 1 - print the first and last iterations; 2 - print every iteration; and 3 - print every iteration including point coordinates.

Definition at line 334 of file eltrans.hpp.

◆ SetReferenceTol()

void mfem::InverseElementTransformation::SetReferenceTol ( double  ref_sp_tol)
inline

Set the reference-space convergence tolerance.

Definition at line 320 of file eltrans.hpp.

◆ SetSolverType()

void mfem::InverseElementTransformation::SetSolverType ( SolverType  stype)
inline

Specify which algorithm to use for solving the transformation equation, i.e. when calling the Transform() method.

Definition at line 314 of file eltrans.hpp.

◆ SetTransformation()

void mfem::InverseElementTransformation::SetTransformation ( ElementTransformation Trans)
inline

Set a new forward ElementTransformation, Trans.

Definition at line 292 of file eltrans.hpp.

◆ Transform()

int mfem::InverseElementTransformation::Transform ( const Vector pt,
IntegrationPoint ip 
)
virtual

Given a point, pt, in physical space, find its reference coordinates, ip.

Returns
A value of type TransformResult.

Definition at line 336 of file eltrans.cpp.

Member Data Documentation

◆ init_guess_type

int mfem::InverseElementTransformation::init_guess_type
protected

Definition at line 235 of file eltrans.hpp.

◆ ip0

const IntegrationPoint* mfem::InverseElementTransformation::ip0
protected

Definition at line 234 of file eltrans.hpp.

◆ ip_tol

double mfem::InverseElementTransformation::ip_tol
protected

Definition at line 242 of file eltrans.hpp.

◆ max_iter

int mfem::InverseElementTransformation::max_iter
protected

Definition at line 239 of file eltrans.hpp.

◆ phys_rtol

double mfem::InverseElementTransformation::phys_rtol
protected

Definition at line 241 of file eltrans.hpp.

◆ print_level

int mfem::InverseElementTransformation::print_level
protected

Definition at line 243 of file eltrans.hpp.

◆ qpts_type

int mfem::InverseElementTransformation::qpts_type
protected

Definition at line 236 of file eltrans.hpp.

◆ ref_tol

double mfem::InverseElementTransformation::ref_tol
protected

Definition at line 240 of file eltrans.hpp.

◆ rel_qpts_order

int mfem::InverseElementTransformation::rel_qpts_order
protected

Definition at line 237 of file eltrans.hpp.

◆ solver_type

int mfem::InverseElementTransformation::solver_type
protected

Definition at line 238 of file eltrans.hpp.

◆ T

ElementTransformation* mfem::InverseElementTransformation::T
protected

Definition at line 231 of file eltrans.hpp.


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