domain::CoordinateMaps::FocallyLiftedMapHelpers Namespace Reference

Holds helper functions for use with domain::CoordinateMaps::FocallyLiftedMap. More...

Functions
template<typename T >
void	scale_factor (const gsl::not_null< tt::remove_cvref_wrap_t< T > * > &result, const std::array< T, 3 > &src_point, const std::array< double, 3 > &proj_center, const std::array< double, 3 > &sphere_center, double radius, bool src_is_between_proj_and_target)
	Finds how long to extend a line segment to have it intersect a point on a 2-sphere. More...
std::optional< double >	try_scale_factor (const std::array< double, 3 > &src_point, const std::array< double, 3 > &proj_center, const std::array< double, 3 > &sphere_center, double radius, bool pick_larger_root, bool pick_root_greater_than_one, bool solve_for_root_minus_one=true)
template<typename T >
void	d_scale_factor_d_src_point (const gsl::not_null< std::array< tt::remove_cvref_wrap_t< T >, 3 > * > &result, const std::array< T, 3 > &intersection_point, const std::array< double, 3 > &proj_center, const std::array< double, 3 > &sphere_center, const T &lambda)

Detailed Description

Holds helper functions for use with domain::CoordinateMaps::FocallyLiftedMap.

Function Documentation

d_scale_factor_d_src_point()

template<typename T >

void domain::CoordinateMaps::FocallyLiftedMapHelpers::d_scale_factor_d_src_point	(	const gsl::not_null< std::array< tt::remove_cvref_wrap_t< T >, 3 > * > &	result,
		const std::array< T, 3 > &	intersection_point,
		const std::array< double, 3 > &	proj_center,
		const std::array< double, 3 > &	sphere_center,
		const T &	lambda
	)

Computes $\partial \lambda /\partial x_0^i$, where $\lambda$ is the quantity returned by scale_factor and x_0 is src_point in the scale_factor function.

The formula (see FocallyLiftedMap) is

$$\begin{array}{rl}\frac{\partial \lambda }{\partial x_0^j}& ={\lambda }^2\frac{C_j-x_1^j}{|x_1^i-P^i{|}^2+(x_1^i-P^i)(P_i-C_i)}.\end{array}$$

Note that it takes intersection_point and not src_point as a parameter.

In the arguments to the function below, intersection_point is $x_1$, proj_center is $P^i$, sphere_center is $C^i$, and radius is $R$.

scale_factor()

template<typename T >

void domain::CoordinateMaps::FocallyLiftedMapHelpers::scale_factor	(	const gsl::not_null< tt::remove_cvref_wrap_t< T > * > &	result,
		const std::array< T, 3 > &	src_point,
		const std::array< double, 3 > &	proj_center,
		const std::array< double, 3 > &	sphere_center,
		double	radius,
		bool	src_is_between_proj_and_target
	)

Finds how long to extend a line segment to have it intersect a point on a 2-sphere.

Details

Consider a 2-sphere with center $C^i$ and radius $R$, and and let $P^i$ and $x_0^i$ be two arbitrary 3D points.

Consider the line passing through $P^i$ and $x_0^i$. If this line intersects the sphere at a point $x_1^i$, then we can write

$$x_1^i=P^i+(x_0^i-P^i)\lambda ,$$

where $\lambda$ is a scale factor.

scale_factor computes and returns $\lambda$.

Even more detail:

To solve for $\lambda$, we note that $x_1^i$ is on the surface of the sphere, so

$$|x_1^i-C^i{|}^2=R^2,$$

(where $|A^i{|}^2$ means ${\delta }_{ij}{A}^i{A}^j$),

or equivalently

$$|P^i-C^i+(x_0^i-P^i)\lambda {|}^2=R^2.$$

This is a quadratic equation for $\lambda$ and it generally has more than one real root. It takes the usual form $a{\lambda }^2+b\lambda +c=0$, with

$$\begin{array}{rl}a& =|x_0^i-P^i{|}^2,\\ b& =2(x_0^i-P^i)(P^j-C^j){\delta }_{ij},\\ c& =|P^i-C^i{|}^2-R^2,\end{array}$$

So how do we choose between multiple roots? Some of the maps that use scale_factor assume that for all points, $x_0^i$ is between $P^i$ and $x_1^i$. Those maps should set the parameter src_is_between_proj_and_target to true. Other maps assume that for all points, $x^i$ is always between $x_0^i$ and $P^i$. Those maps should set the parameter src_is_between_proj_and_target to false.

Warning

If we ever add maps where src_is_between_proj_and_target can change from point to point, the logic of scale_factor needs to be changed.

In the arguments to the function below, src_point is $x_0^i$, proj_center is $P^i$, sphere_center is $C^i$, and radius is $R$.

try_scale_factor()

std::optional< double > domain::CoordinateMaps::FocallyLiftedMapHelpers::try_scale_factor	(	const std::array< double, 3 > &	src_point,
		const std::array< double, 3 > &	proj_center,
		const std::array< double, 3 > &	sphere_center,
		double	radius,
		bool	pick_larger_root,
		bool	pick_root_greater_than_one,
		bool	solve_for_root_minus_one = true
	)

Solves a problem of the same form as scale_factor, but is used only by the inverse function to compute $\tilde{\lambda }$ and $\overline{\lambda }$. try_scale_factor is used in two contexts:

try_scale_factor is used to determine $\overline{\lambda }$ given $x^i$. $\overline{\lambda }$ is defined by

$$\begin{array}{r}{x}_1^i=P^i+(x^i-P^i)\overline{\lambda }.\end{array}$$

try_scale_factor is used by the lambda_tilde functions of some of the InnerMap classes (namely those InnerMap classes where $x_0^i$ is a spherical surface) to solve for $\tilde{\lambda }$ given $x^i$. $\tilde{\lambda }$ is defined by

$$\begin{array}{r}{x}_0^i=P^i+(x^i-P^i)\tilde{\lambda }.\end{array}$$

In both of these contexts, the input parameter src_point is $x^i$, a point that is supposed to be in the range of the FocallyLiftedMap. Because the inverse function can be and is called for an arbitrary $x^i$ that might not be in the range of the FocallyLiftedMap, try_scale_factor returns a std::optional, with a default-constructed std::optional if the roots it finds are not as expected (i.e. if the inverse map was called for a point not in the range of the map).

Because try_scale_factor can be called in different situations, it has additional boolean arguments pick_larger_root and pick_root_greater_than_one that allow the caller to choose which root to return.

Furthermore, to reduce roundoff errors near $\tilde{\lambda }=1$, the default behavior is to solve the quadratic equation for $\tilde{\lambda }-1$ (and then add $1$ to the solution). If instead one wants to solve the quadratic equation directly for $\tilde{\lambda }$ so as to obtain slightly different roundoff behavior, then one should specify the argument solve_for_root_minus_one to be false.

try_scale_factor is not templated on type because it is used only by the inverse function, which works only on doubles.