Spectral::Swsh Namespace Reference

Namespace for spin-weighted spherical harmonic utilities. More...

Classes
class	CoefficientsMetadata
	A container for libsharp metadata for the spin-weighted spherical harmonics modal representation. More...
class	CollocationMetadata
	A wrapper class for the spherical harmonic library collocation data. More...
struct	InverseSwshTransform
	A DataBox mutate-compatible computational struct for performing several spin-weighted inverse spherical harmonic transforms. Internally dispatches to libsharp. More...
struct	LibsharpCoefficientInfo
	Points to a single pair of modes in a libsharp-compatible spin-weighted spherical harmonic modal representation. More...
struct	LibsharpCollocationPoint
	A container for reporting a single collocation point for libsharp compatible data structures. More...
class	SpinWeightedSphericalHarmonic
	A utility for evaluating a particular spin-weighted spherical harmonic function at arbitrary points. More...
class	SwshInterpolator
	Performs interpolation for spin-weighted spherical harmonics by taking advantage of the Clenshaw method of expanding recurrence relations. More...
struct	SwshTransform
	A DataBox mutate-compatible computational struct for performing several spin-weighted spherical harmonic transforms. Internally dispatches to libsharp. More...

Typedefs
template<typename DerivativeTagList, ComplexRepresentation Representation = ComplexRepresentation::Interleaved>
using	AngularDerivatives
	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.
template<typename DerivativeTag>
using	coefficient_buffer_tags_for_derivative_tag
	A metafunction for determining the coefficient buffers needed by angular_derivatives() to avoid repeatedly allocating space for modal data each time a derivative is taken.
template<int Spin, typename TagList>
using	get_tags_with_spin
	Extract from TagList the subset of those tags that have a static int member spin equal to the template parameter Spin.
template<int Spin, typename TagList>
using	get_prefix_tags_that_wrap_tags_with_spin
	Extract from TagList the subset of those tags that wrap a tag that has a static int member spin equal to the template parameter Spin.
template<ComplexRepresentation Representation, typename DerivativeTagList>
using	make_transform_list_from_derivative_tags
	Assemble a tmpl::list of SwshTransforms given a list of Spectral::Swsh::Tags::Derivative<Tag, Derivative> that need to be computed. The SwshTransforms constructed by this type alias correspond to the Tags in the list.
template<ComplexRepresentation Representation, typename TagList>
using	make_transform_list
	Assemble a tmpl::list of SwshTransforms or InverseSwshTransforms given a list of tags TagList that need to be transformed. The Representation is the Spectral::Swsh::ComplexRepresentation to use for the transformations.
template<ComplexRepresentation Representation, typename TagList>
using	make_inverse_transform_list
	Assemble a tmpl::list of SwshTransforms or InverseSwshTransforms given a list of tags TagList that need to be transformed. The Representation is the Spectral::Swsh::ComplexRepresentation to use for the transformations.

Enumerations
enum class	ComplexRepresentation { Interleaved , RealsThenImags }
	A set of labels for the possible representations of complex numbers for the ComplexDataView and the computations performed in the spin-weighted spherical harmonic transform library. More...

Functions
constexpr size_t	size_of_libsharp_coefficient_vector (const size_t l_max)
	Convenience function for determining the number of spin-weighted spherical harmonics coefficients that are stored for a given l_max
constexpr double	sharp_swsh_sign_change (const int from_spin_weight, const int to_spin_weight, const bool real)
	Compute the relative sign change necessary to convert between the libsharp basis for spin weight from_spin_weight to the basis for spin weight to_spin_weight, for the real component coefficients if real is true, otherwise for the imaginary component coefficients. The sign change for a given coefficient is equivalent to the product of sharp_swsh_sign(from_spin, m, real) * sharp_swsh_sign(to_spin, m, real). Due to the form of the signs, it does not end up depending on m (the m's in the power of \(-1\)'s cancel). For full details of the libsharp sign conventions, see the documentation for TransformJob.
constexpr double	sharp_swsh_sign (const int spin_weight, const int m, const bool real)
	Compute the sign change between the libsharp convention and the set of spin-weighted spherical harmonics given by the relation to the Wigner rotation matrices.
const CoefficientsMetadata &	cached_coefficients_metadata (size_t l_max)
	Generation function for obtaining a CoefficientsMetadata object which is computed by the libsharp calls only once, then lazily cached as a singleton via a static member of a function template. This is the preferred method for obtaining a CoefficientsMetadata when the l_max is not very large.
template<int Spin>
std::complex< double >	libsharp_mode_to_goldberg (size_t l, int m, size_t l_max, const SpinWeighted< ComplexModalVector, Spin > &libsharp_modes, size_t radial_offset)
	Compute the mode coefficient for the convention of [89]. See the documentation for TransformJob for complete details on the libsharp and Goldberg coefficient representations.
template<int Spin>
void	goldberg_modes_to_libsharp_modes_single_pair (const LibsharpCoefficientInfo &coefficient_info, gsl::not_null< SpinWeighted< ComplexModalVector, Spin > * > libsharp_modes, size_t radial_offset, std::complex< double > goldberg_plus_m_mode_value, std::complex< double > goldberg_minus_m_mode_value)
	Set modes of a libsharp-compatible data structure by specifying the modes in the [89] representation.
template<int Spin>
void	goldberg_modes_to_libsharp_modes_single_pair (size_t l, int m, size_t l_max, gsl::not_null< SpinWeighted< ComplexModalVector, Spin > * > libsharp_modes, size_t radial_offset, std::complex< double > goldberg_plus_m_mode_value, std::complex< double > goldberg_minus_m_mode_value)
	Set modes of a libsharp-compatible data structure by specifying the modes in the [89] representation.
constexpr size_t	goldberg_mode_index (const size_t l_max, const size_t l, const int m, const size_t radial_offset=0)
	Returns the index into a vector of modes consistent with [89].
constexpr size_t	number_of_swsh_collocation_points (const size_t l_max)
	Convenience function for determining the number of spin-weighted spherical harmonic collocation values that are stored for a given l_max for a libsharp-compatible set of collocation points.
constexpr size_t	number_of_swsh_theta_collocation_points (const size_t l_max)
	Returns the number of spin-weighted spherical harmonic collocation values in \(\theta\) for a libsharp-compatible set of collocation points.
constexpr size_t	number_of_swsh_phi_collocation_points (const size_t l_max)
	Returns the number of spin-weighted spherical harmonic collocation values in \(\phi\) for a libsharp-compatible set of collocation points.
Mesh< 3 >	swsh_volume_mesh_for_radial_operations (const size_t l_max, const size_t number_of_radial_points)
	Obtain the three-dimensional mesh associated with a libsharp-compatible sequence of spherical nodal shells.
template<ComplexRepresentation Representation>
const CollocationMetadata< Representation > &	cached_collocation_metadata (size_t l_max)
	precomputation function for those collocation grids that are requested
void	create_angular_and_cartesian_coordinates (const gsl::not_null< tnsr::i< DataVector, 3 > * > cartesian_coordinates, const gsl::not_null< tnsr::i< DataVector, 2, ::Frame::Spherical<::Frame::Inertial > > * > angular_coordinates, size_t l_max)
	Store the libsharp-compatible collocation grid and corresponding unit-sphere cartesian grid in the supplied buffers.
template<int Spin>
auto	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.
template<typename DerivativeKindList, ComplexRepresentation Representation = ComplexRepresentation::Interleaved, typename... ArgumentTypes>
void	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.
template<typename DerivKind, ComplexRepresentation Representation = ComplexRepresentation::Interleaved, int Spin>
SpinWeighted< ComplexDataVector, Tags::derivative_spin_weight< DerivKind >+Spin >	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<ComplexRepresentation Representation = ComplexRepresentation::Interleaved, int Spin, typename... ModalThenNodalTypes>
void	swsh_transform (const size_t l_max, const size_t number_of_radial_points, const gsl::not_null< SpinWeighted< ComplexModalVector, Spin > * > first_coefficient, const ModalThenNodalTypes &... coefficients_then_collocations)
	Perform a forward libsharp spin-weighted spherical harmonic transform on any number of supplied SpinWeighted<ComplexDataVector, Spin>.
template<ComplexRepresentation Representation = ComplexRepresentation::Interleaved, int Spin>
SpinWeighted< ComplexModalVector, Spin >	swsh_transform (size_t l_max, size_t number_of_radial_points, const SpinWeighted< ComplexDataVector, Spin > &collocation)
	Perform a forward libsharp spin-weighted spherical harmonic transform on a single supplied SpinWeighted<ComplexDataVector, Spin>.
template<ComplexRepresentation Representation = ComplexRepresentation::Interleaved, int Spin, typename... NodalThenModalTypes>
void	inverse_swsh_transform (const size_t l_max, const size_t number_of_radial_points, const gsl::not_null< SpinWeighted< ComplexDataVector, Spin > * > first_collocation, const NodalThenModalTypes &... collocations_then_coefficients)
	Perform an inverse libsharp spin-weighted spherical harmonic transform on any number of supplied SpinWeighted<ComplexModalVector, Spin>.
template<ComplexRepresentation Representation = ComplexRepresentation::Interleaved, int Spin>
SpinWeighted< ComplexDataVector, Spin >	inverse_swsh_transform (size_t l_max, size_t number_of_radial_points, const SpinWeighted< ComplexModalVector, Spin > &libsharp_coefficients)
	Perform an inverse libsharp spin-weighted spherical harmonic transform on a single supplied SpinWeighted<ComplexModalVector, Spin>.
template<int Spin>
void	interpolate_to_collocation (gsl::not_null< SpinWeighted< ComplexDataVector, Spin > * > target, const SpinWeighted< ComplexDataVector, Spin > &source, size_t target_l_max, size_t source_l_max, size_t number_of_radial_points)
	Convert spin-weighted spherical harmonic data to a new set of collocation points (either downsampling or upsampling)
template<int Spin>
std::complex< double >	libsharp_mode_to_goldberg_plus_m (const LibsharpCoefficientInfo &coefficient_info, const SpinWeighted< ComplexModalVector, Spin > &libsharp_modes, size_t radial_offset)
	Compute the mode coefficient for the convention of [89].
template<int Spin>
std::complex< double >	libsharp_mode_to_goldberg_minus_m (const LibsharpCoefficientInfo &coefficient_info, const SpinWeighted< ComplexModalVector, Spin > &libsharp_modes, size_t radial_offset)
	Compute the mode coefficient for the convention of [89].
template<int Spin>
void	libsharp_to_goldberg_modes (gsl::not_null< SpinWeighted< ComplexModalVector, Spin > * > goldberg_modes, const SpinWeighted< ComplexModalVector, Spin > &libsharp_modes, size_t l_max)
	Compute the set of Goldberg Spin-weighted spherical harmonic modes (in the convention of [89]) from a libsharp-compatible series of modes.
template<int Spin>
SpinWeighted< ComplexModalVector, Spin >	libsharp_to_goldberg_modes (const SpinWeighted< ComplexModalVector, Spin > &libsharp_modes, size_t l_max)
	Compute the set of Goldberg Spin-weighted spherical harmonic modes (in the convention of [89]) from a libsharp-compatible series of modes.
template<int Spin>
void	goldberg_to_libsharp_modes (gsl::not_null< SpinWeighted< ComplexModalVector, Spin > * > libsharp_modes, const SpinWeighted< ComplexModalVector, Spin > &goldberg_modes, size_t l_max)
	Compute the set of libsharp-compatible spin-weighted spherical harmonic modes from a set of Goldberg modes (following the convention of [89])
template<int Spin>
SpinWeighted< ComplexModalVector, Spin >	goldberg_to_libsharp_modes (const SpinWeighted< ComplexModalVector, Spin > &goldberg_modes, size_t l_max)
	Compute the set of libsharp-compatible spin-weighted spherical harmonic modes from a set of Goldberg modes (following the convention of [89])
template<int Spin>
void	filter_swsh_volume_quantity (gsl::not_null< SpinWeighted< ComplexDataVector, Spin > * > to_filter, size_t l_max, size_t filter_max_l, double exponential_alpha, size_t exponential_half_power, gsl::not_null< ComplexDataVector * > buffer, gsl::not_null< SpinWeighted< ComplexModalVector, Spin > * > transform_buffer)
	Filter a volume collocation set in the form of consecutive libsharp-compatible spherical shells.
template<int Spin>
void	filter_swsh_volume_quantity (gsl::not_null< SpinWeighted< ComplexDataVector, Spin > * > to_filter, size_t l_max, size_t filter_max_l, double exponential_alpha, size_t exponential_half_power)
	Filter a volume collocation set in the form of consecutive libsharp-compatible spherical shells.
template<int Spin>
void	filter_swsh_volume_quantity (gsl::not_null< SpinWeighted< ComplexDataVector, Spin > * > to_filter, size_t l_max, size_t filter_min_l, size_t filter_max_l, double exponential_alpha, size_t exponential_half_power, gsl::not_null< ComplexDataVector * > buffer, gsl::not_null< SpinWeighted< ComplexModalVector, Spin > * > transform_buffer)
	Filter a volume collocation set in the form of consecutive libsharp-compatible spherical shells.
template<int Spin>
void	filter_swsh_volume_quantity (gsl::not_null< SpinWeighted< ComplexDataVector, Spin > * > to_filter, size_t l_max, size_t filter_min_l, size_t filter_max_l, double exponential_alpha, size_t exponential_half_power)
	Filter a volume collocation set in the form of consecutive libsharp-compatible spherical shells.
template<int Spin>
void	filter_swsh_boundary_quantity (gsl::not_null< SpinWeighted< ComplexDataVector, Spin > * > to_filter, size_t l_max, size_t filter_max_l, gsl::not_null< SpinWeighted< ComplexModalVector, Spin > * > transform_buffer)
	Filter a libsharp-compatible set of collocation points on a spherical surface.
template<int Spin>
void	filter_swsh_boundary_quantity (gsl::not_null< SpinWeighted< ComplexDataVector, Spin > * > to_filter, size_t l_max, size_t filter_max_l)
	Filter a libsharp-compatible set of collocation points on a spherical surface.
template<int Spin>
void	filter_swsh_boundary_quantity (gsl::not_null< SpinWeighted< ComplexDataVector, Spin > * > to_filter, size_t l_max, size_t filter_min_l, size_t filter_max_l, gsl::not_null< SpinWeighted< ComplexModalVector, Spin > * > transform_buffer)
	Filter a libsharp-compatible set of collocation points on a spherical surface.
template<int Spin>
void	filter_swsh_boundary_quantity (gsl::not_null< SpinWeighted< ComplexDataVector, Spin > * > to_filter, size_t l_max, size_t filter_min_l, size_t filter_max_l)
	Filter a libsharp-compatible set of collocation points on a spherical surface.

Variables
constexpr size_t	collocation_maximum_l_max = 200

Detailed Description

Namespace for spin-weighted spherical harmonic utilities.

Enumeration Type Documentation

ComplexRepresentation

enum class Spectral::Swsh::ComplexRepresentation

strong

A set of labels for the possible representations of complex numbers for the ComplexDataView and the computations performed in the spin-weighted spherical harmonic transform library.

Details

The representation describes one of two behaviors:

• Interleaved: The vectors of complex numbers will be represented by alternating doubles in memory. This causes both the real and imaginary part at a given gridpoint to be near one another, but successive real values farther. This is the native representation of complex data in the C++ standard, and is the representation needed for Blaze math operations. Therefore, using this representation type in libsharp computations will cause operations which access only the real or imaginary parts individually to trace over larger memory regions. However, this representation will give rise to fewer copying operations to perform the libsharp operations.
• RealsThenImags: The vectors of complex numbers will primarily be represented by a pair of vectors of doubles, one for the real values and one for the imaginary values (the full computation cannot be performed exclusively in this representation, as it must return to a vector of std::complex<double> for Blaze math operations). This causes the successive real values for different gridpoints to be closer in memory, but the real and imaginary parts for a given gridpoint to be farther in memory. This is not the native representation for complex data in C++, so the data must be transformed between operations which use Blaze and the transform operations which use RealsThenImags. Therefore, using this representation in libsharp computations will cause operations which act on real or imaginary parts individually to have better memory locality (so likely improved cache performance, but such statements are highly hardware-dependent). However, this representation will give rise to more copying operations to perform the libsharp operations.

Note

The pair of representations is provided as a means to 'turn a dial' in optimizations. It is unclear which of these representations will be preferable, and it may well be the case that different representations are better for different calculation types or different hardware. Therefore, when optimizing code which uses libsharp, it is encouraged to profile the cost of each representation for a computation and choose the one which performs best.

Function Documentation

cached_collocation_metadata()

template<ComplexRepresentation Representation>

const CollocationMetadata< Representation > & Spectral::Swsh::cached_collocation_metadata

(

size_t

l_max

)

precomputation function for those collocation grids that are requested

Details

keeps a compile-time structure which acts as a thread-safe lookup table for all l_max values that have been requested so far during execution, so that the libsharp generation need not be re-run. If it has been generated, it's returned by reference. Otherwise, the new grid is generated and put in the lookup table before it is returned by reference.