Spectral

Namespaces
namespace	Spectral
	Functionality associated with a particular choice of basis functions and quadrature for spectral operations.
namespace	Spectral::Swsh
	Namespace for spin-weighted spherical harmonic utilities.
namespace	Spectral::filtering
	Matrices for filtering spectral coefficients.

Classes
class	ylm::Spherepack
	Defines the C++ interface to SPHEREPACK. More...
class	ylm::SpherepackIterator
	Iterates over spectral coefficients stored in SPHEREPACK format. More...

Typedefs
template<typename DerivativeTagList , ComplexRepresentation Representation = ComplexRepresentation::Interleaved>
using	Spectral::Swsh::AngularDerivatives = detail::AngularDerivativesImpl< DerivativeTagList, typename detail::unique_derived_from_list< DerivativeTagList >::type, Representation >
	A DataBox mutate-compatible computational struct for computing a set of spin-weighted spherical harmonic derivatives by grouping and batch-computing spin-weighted spherical harmonic transforms. More...

Functions
template<int Spin>
auto	Spectral::Swsh::swsh_buffer (const size_t l_max, const size_t number_of_radial_points)
	Produces a SpinWeighted<ComplexModalVector, Spin> of the appropriate size to be used as a modal buffer for Spectral::Swsh::AngularDerivatives or Spectral::Swsh::angular_derivatives. More...
template<typename DerivativeKindList , ComplexRepresentation Representation = ComplexRepresentation::Interleaved, typename... ArgumentTypes>
void	Spectral::Swsh::angular_derivatives (const size_t l_max, const size_t number_of_radial_points, const ArgumentTypes &... arguments)
	Evaluate all of the spin-weighted derivatives in DerivKindList on input SpinWeighted<ComplexDataVector, Spin> collocation data, returning by pointer. More...
template<typename DerivKind , ComplexRepresentation Representation = ComplexRepresentation::Interleaved, int Spin>
SpinWeighted< ComplexDataVector, Tags::derivative_spin_weight< DerivKind >+Spin >	Spectral::Swsh::angular_derivative (size_t l_max, size_t number_of_radial_points, const SpinWeighted< ComplexDataVector, Spin > &to_differentiate)
	Evaluate the spin-weighted derivative DerivKind on the provided SpinWeighted<ComplexDataVector, Spin> collocation data, returning by value.
template<size_t Dim>
void	to_modal_coefficients (gsl::not_null< ComplexModalVector * > modal_coefficients, const ComplexDataVector &nodal_coefficients, const Mesh< Dim > &mesh)
	Compute the modal coefficients from the nodal coefficients. More...
template<size_t Dim>
void	to_modal_coefficients (gsl::not_null< ModalVector * > modal_coefficients, const DataVector &nodal_coefficients, const Mesh< Dim > &mesh)
	Compute the modal coefficients from the nodal coefficients. More...
template<size_t Dim>
ModalVector	to_modal_coefficients (const DataVector &nodal_coefficients, const Mesh< Dim > &mesh)
	Compute the modal coefficients from the nodal coefficients. More...
template<size_t Dim>
ComplexModalVector	to_modal_coefficients (const ComplexDataVector &nodal_coefficients, const Mesh< Dim > &mesh)
	Compute the modal coefficients from the nodal coefficients. More...
template<size_t Dim>
void	to_nodal_coefficients (gsl::not_null< ComplexDataVector * > nodal_coefficients, const ComplexModalVector &modal_coefficients, const Mesh< Dim > &mesh)
	Compute the nodal coefficients from the modal coefficients. More...
template<size_t Dim>
void	to_nodal_coefficients (gsl::not_null< DataVector * > nodal_coefficients, const ModalVector &modal_coefficients, const Mesh< Dim > &mesh)
	Compute the nodal coefficients from the modal coefficients. More...
template<size_t Dim>
DataVector	to_nodal_coefficients (const ModalVector &modal_coefficients, const Mesh< Dim > &mesh)
	Compute the nodal coefficients from the modal coefficients. More...
template<size_t Dim>
ComplexDataVector	to_nodal_coefficients (const ComplexModalVector &modal_coefficients, const Mesh< Dim > &mesh)
	Compute the nodal coefficients from the modal coefficients. More...
template<size_t Dim>
void	PowerMonitors::power_monitors (gsl::not_null< std::array< DataVector, Dim > * > result, const DataVector &u, const Mesh< Dim > &mesh)
	Returns array of power monitors in each spatial dimension. More...
template<size_t Dim>
std::array< DataVector, Dim >	PowerMonitors::power_monitors (const DataVector &u, const Mesh< Dim > &mesh)
	Returns array of power monitors in each spatial dimension. More...
double	PowerMonitors::relative_truncation_error (const DataVector &power_monitor, const size_t num_modes_to_use)
	Compute the negative log10 of the relative truncation error. More...
template<size_t Dim>
std::array< double, Dim >	PowerMonitors::absolute_truncation_error (const DataVector &tensor_component, const Mesh< Dim > &mesh)
	Returns an estimate of the absolute truncation error in each dimension. More...
void	ylm::real_spherical_harmonic (gsl::not_null< DataVector * > spherical_harmonic, const DataVector &theta, const DataVector &phi, size_t l, int m)
	Evaluates a real spherical harmonic of order l at the requested angles \(\theta\) and \(\phi\). More...
DataVector	ylm::real_spherical_harmonic (const DataVector &theta, const DataVector &phi, size_t l, int m)
	Evaluates a real spherical harmonic of order l at the requested angles \(\theta\) and \(\phi\). More...

Detailed Description

Things related to spectral transformations.

Typedef Documentation

AngularDerivatives

template<typename DerivativeTagList , ComplexRepresentation Representation = ComplexRepresentation::Interleaved>

using Spectral::Swsh::AngularDerivatives = typedef detail::AngularDerivativesImpl< DerivativeTagList, typename detail::unique_derived_from_list<DerivativeTagList>::type, Representation>

A DataBox mutate-compatible computational struct for computing a set of spin-weighted spherical harmonic derivatives by grouping and batch-computing spin-weighted spherical harmonic transforms.

Details

A derivative is evaluated for each tag in DerivativeTagList. All entries in DerivativeTagList must be the tag Spectral::Swsh::Tags::Derivative<Tag, DerivativeKind> prefixing the Tag to be differentiated, and indicating the spin-weighted derivative DerivativeKind to be taken. A DataBox on which this struct is invoked must contain:

• each of the tags in DerivativeTagList (the results of the computation)
• each of the tags Tag prefixed by Spectral::Swsh::Tags::Derivative in DerivativeTagList (the inputs of the computation).
• each of the tags Spectral::Swsh::Tags::SwshTransform<DerivativeTag> for DerivativeTagin DerivativeTagList (the buffers for the derivative applied to the modes)
• each of the tags Spectral::Swsh::Tags::SwshTransform<Tag> for Tag prefixed by any DerivativeTag in DerivativeTagList (the buffers for the transforms of the input data).

This function optimizes the derivative taking process by clustering like spins of tags, forward-transforming each spin cluster together, applying the factor for the derivative to each modal vector, re-clustering according to the new spin weights (the derivatives alter the spin weights), and finally inverse-transforming in clusters.

Function Documentation

absolute_truncation_error()

template<size_t Dim>

std::array< double, Dim > PowerMonitors::absolute_truncation_error	(	const DataVector &	tensor_component,
		const Mesh< Dim > &	mesh
	)

Returns an estimate of the absolute truncation error in each dimension.

The estimate of the numerical error is given by

\begin{align*} \mathcal{E}\left[P_k\right] = u_\mathrm{max} \times 10^{- \mathcal{T}[P_k]}, \end{align*}

where \( u_\mathrm{max} = \mathrm{max} |u|\) in the corresponding element and \( \mathcal{T}[P_k] \) is the relative error estimate computed from the power monitors \( P_k \).

Warning

This estimate is intended for visualization purposes only.

angular_derivatives()

template<typename DerivativeKindList , ComplexRepresentation Representation = ComplexRepresentation::Interleaved, typename... ArgumentTypes>

void Spectral::Swsh::angular_derivatives	(	const size_t	l_max,
		const size_t	number_of_radial_points,
		const ArgumentTypes &...	arguments
	)

Evaluate all of the spin-weighted derivatives in DerivKindList on input SpinWeighted<ComplexDataVector, Spin> collocation data, returning by pointer.

Details

This function provides two interfaces, one in which the caller provides the intermediate coefficient buffers needed during the computation of the derivatives, and one in which those buffers are temporarily allocated during the derivative function calls.

For the interface in which the caller does not provide buffers, the arguments must take the following structure (enforced by internal function calls):

• size_t l_max : angular resolution for the spherical representation
• size_t number_of_radial_points : radial resolution (number of consecutive blocks to evaluate derivatives, for each input vector )
• for each DerivKind in DerivKindList, a gsl::not_null<SpinWeighted<ComplexDataVector, Spin + Tags::derivative_spin_weight<DerivKind>>> : the output of the derivative evaluation
• for each DerivKind in DerivKindList, a const SpinWeighted<ComplexDataVector, Spin>& (where the Spin for these arguments matches the corresponding vector from the previous set) : the input to the derivative evaluation.

For the interface in which the caller does provide buffers, the arguments must take the following structure (enforced by internal function calls):

• size_t l_max : angular resolution for the spherical representation
• size_t number_of_radial_points : radial resolution (number of consecutive blocks to evaluate derivatives, for each input vector )
• for each DerivKind in DerivKindList, a gsl::not_null<SpinWeighted<ComplexModalVector, Spin + Tags::derivative_spin_weight<DerivKind>>> : the buffer for the spin-weighted spherical harmonic modes of the derivative quantities.
• for each DerivKind in DerivKindList, a const SpinWeighted<ComplexModalVector, Spin> (where the Spin for these arguments matches the corresponding vector from the previous set) : the buffer for the spin-weighted spherical harmonic modes of the input quantities.
• for each DerivKind in DerivKindList, a gsl::not_null<SpinWeighted<ComplexDataVector, Spin + Tags::derivative_spin_weight<DerivKind>>> : the output of the derivative evaluation
• for each DerivKind in DerivKindList, a const SpinWeighted<ComplexDataVector, Spin> (where the Spin for these arguments matches the corresponding vector from the previous set) : the input to the derivative evaluation.

The function swsh_buffer assists in generating the modal buffers of appropriate size.

power_monitors() [1/2]

template<size_t Dim>

std::array< DataVector, Dim > PowerMonitors::power_monitors	(	const DataVector &	u,
		const Mesh< Dim > &	mesh
	)

Returns array of power monitors in each spatial dimension.

Computed following Sec. 5.1 of Ref. [190]. For example, in the x dimension (indexed by \( k_0 \)), we compute

\begin{align*} P_{k_0}[\psi] = \sqrt{ \frac{1}{N_1 N_2} \sum_{k_1,k_2} \left| C_{k_0,k_1,k_2} \right|^2} , \end{align*}

where \( C_{k_0,k_1,k_2}\) are the modal coefficients of variable \( \psi \).

power_monitors() [2/2]

template<size_t Dim>

void PowerMonitors::power_monitors	(	gsl::not_null< std::array< DataVector, Dim > * >	result,
		const DataVector &	u,
		const Mesh< Dim > &	mesh
	)

Returns array of power monitors in each spatial dimension.

Computed following Sec. 5.1 of Ref. [190]. For example, in the x dimension (indexed by \( k_0 \)), we compute

\begin{align*} P_{k_0}[\psi] = \sqrt{ \frac{1}{N_1 N_2} \sum_{k_1,k_2} \left| C_{k_0,k_1,k_2} \right|^2} , \end{align*}

where \( C_{k_0,k_1,k_2}\) are the modal coefficients of variable \( \psi \).

real_spherical_harmonic() [1/2]

DataVector ylm::real_spherical_harmonic	(	const DataVector &	theta,
		const DataVector &	phi,
		size_t	l,
		int	m
	)

Evaluates a real spherical harmonic of order l at the requested angles \(\theta\) and \(\phi\).

The real spherical harmonics are defined as:

\begin{equation} Y_{lm}(\theta, \phi) = \begin{cases} \sqrt{2} (-1)^m \mathcal{I}[Y_l^{|m|}] & \text{if } m < 0 \\ Y_l^{0} & \text{if } m = 0 \\ \sqrt{2} (-1)^m \mathcal{R}[Y_l^{m}] & \text{if } m > 0 \end{cases} \end{equation}

where \(Y_l^m\) are the complex spherical harmonics and \(\mathcal{R}\) denotes the real part and \(\mathcal{I}\) denotes the imaginary part.

Note

This implementation uses the boost implementation of spherical harmonics. The calculation is not vectorized and may be slow. Stability has not been tested for large l.

real_spherical_harmonic() [2/2]

void ylm::real_spherical_harmonic	(	gsl::not_null< DataVector * >	spherical_harmonic,
		const DataVector &	theta,
		const DataVector &	phi,
		size_t	l,
		int	m
	)

Evaluates a real spherical harmonic of order l at the requested angles \(\theta\) and \(\phi\).

The real spherical harmonics are defined as:

\begin{equation} Y_{lm}(\theta, \phi) = \begin{cases} \sqrt{2} (-1)^m \mathcal{I}[Y_l^{|m|}] & \text{if } m < 0 \\ Y_l^{0} & \text{if } m = 0 \\ \sqrt{2} (-1)^m \mathcal{R}[Y_l^{m}] & \text{if } m > 0 \end{cases} \end{equation}

where \(Y_l^m\) are the complex spherical harmonics and \(\mathcal{R}\) denotes the real part and \(\mathcal{I}\) denotes the imaginary part.

Note

This implementation uses the boost implementation of spherical harmonics. The calculation is not vectorized and may be slow. Stability has not been tested for large l.

relative_truncation_error()

double PowerMonitors::relative_truncation_error	(	const DataVector &	power_monitor,
		const size_t	num_modes_to_use
	)

Compute the negative log10 of the relative truncation error.

Truncation error according to Eqs. (57) and (58) of Ref. [190], i.e.,

\begin{align*} \mathcal{T}\left[P_k\right] = \log_{10} \max \left(P_0, P_1\right) - \dfrac{\sum_{j=0}^{j_{\text{max}, k}} \log_{10} \left(P_j\right) w_j} {\sum_{j=0}^{j_{\text{max}, k}} w_j} , \end{align*}

with weights

\begin{align*} w_j = \exp\left[ - \left(j - j_{\text{max}, k} + \dfrac{1}{2}\right)^2 \right] . \end{align*}

where \( j_{\text{max}, k} = N_k - 1 \) and \( N_k \) is the number of modes or gridpoints in dimension k. Here the second term is a weighted average with larger weights toward the highest modes. This number should correspond to the number of digits resolved by the spectral expansion.

Note

Modes below a cutoff of \(100 \epsilon \mathrm{max}_k(P_k)\) are ignored in the weighted average, where \(\epsilon\) is the machine epsilon. This ensures that we don't underestimate the truncation error if some modes are zero (e.g. by symmetry). Furthermore, if the last two or more modes are zero, we assume that the function is represented exactly and return a relative truncation error of zero.

Details

The number of modes (num_modes_to_use) argument needs to be less or equal than the total number of power monitors (power_monitor.size()). In contrast with Ref. [190], here we index the modes starting from zero.

swsh_buffer()

template<int Spin>

auto Spectral::Swsh::swsh_buffer	(	const size_t	l_max,
		const size_t	number_of_radial_points
	)

Produces a SpinWeighted<ComplexModalVector, Spin> of the appropriate size to be used as a modal buffer for Spectral::Swsh::AngularDerivatives or Spectral::Swsh::angular_derivatives.

Details

The Spectral::Swsh::angular_derivatives and Spectral::Swsh::AngularDerivatives interfaces require that calling code provides a buffer for the intermediate transform results, to ensure that callers are aware of the allocations and can suitably reuse buffers if possible. This utility eases the creation of those buffers.

to_modal_coefficients() [1/4]

template<size_t Dim>

ComplexModalVector to_modal_coefficients	(	const ComplexDataVector &	nodal_coefficients,
		const Mesh< Dim > &	mesh
	)

Compute the modal coefficients from the nodal coefficients.

See also

Spectral::nodal_to_modal_matrix

to_modal_coefficients() [2/4]

template<size_t Dim>

ModalVector to_modal_coefficients	(	const DataVector &	nodal_coefficients,
		const Mesh< Dim > &	mesh
	)

Compute the modal coefficients from the nodal coefficients.

See also

Spectral::nodal_to_modal_matrix

to_modal_coefficients() [3/4]

template<size_t Dim>

void to_modal_coefficients	(	gsl::not_null< ComplexModalVector * >	modal_coefficients,
		const ComplexDataVector &	nodal_coefficients,
		const Mesh< Dim > &	mesh
	)

Compute the modal coefficients from the nodal coefficients.

See also

Spectral::nodal_to_modal_matrix

to_modal_coefficients() [4/4]

template<size_t Dim>

void to_modal_coefficients	(	gsl::not_null< ModalVector * >	modal_coefficients,
		const DataVector &	nodal_coefficients,
		const Mesh< Dim > &	mesh
	)

Compute the modal coefficients from the nodal coefficients.

See also

Spectral::nodal_to_modal_matrix

to_nodal_coefficients() [1/4]

template<size_t Dim>

ComplexDataVector to_nodal_coefficients	(	const ComplexModalVector &	modal_coefficients,
		const Mesh< Dim > &	mesh
	)

Compute the nodal coefficients from the modal coefficients.

See also

Spectral::modal_to_nodal_matrix

to_nodal_coefficients() [2/4]

template<size_t Dim>

DataVector to_nodal_coefficients	(	const ModalVector &	modal_coefficients,
		const Mesh< Dim > &	mesh
	)

Compute the nodal coefficients from the modal coefficients.

See also

Spectral::modal_to_nodal_matrix

to_nodal_coefficients() [3/4]

template<size_t Dim>

void to_nodal_coefficients	(	gsl::not_null< ComplexDataVector * >	nodal_coefficients,
		const ComplexModalVector &	modal_coefficients,
		const Mesh< Dim > &	mesh
	)

Compute the nodal coefficients from the modal coefficients.

See also

Spectral::modal_to_nodal_matrix

to_nodal_coefficients() [4/4]

template<size_t Dim>

void to_nodal_coefficients	(	gsl::not_null< DataVector * >	nodal_coefficients,
		const ModalVector &	modal_coefficients,
		const Mesh< Dim > &	mesh
	)

Compute the nodal coefficients from the modal coefficients.

See also

Spectral::modal_to_nodal_matrix