Iterates over spectral coefficients stored in SPHEREPACK format. More...

#include <SpherepackIterator.hpp>

Public Types
enum class	CoefficientArray { a , b }
	SPHEREPACK has two coefficient variables, 'a' and 'b', that hold the cos(mphi) and sin(mphi) parts of the spectral coefficients.

Public Member Functions
	SpherepackIterator (size_t l_max_input, size_t m_max_input, size_t stride=1, bool zero_m_is_real=true)
	Construct a SpherepackIterator. More...

size_t	l_max () const

size_t	m_max () const

size_t	n_th () const

size_t	n_ph () const

size_t	stride () const

bool	zero_m_is_real () const

size_t	spherepack_array_size () const
	Size of a SPHEREPACK coefficient array (a and b combined), not counting stride. For non-unit stride, the size of the array should be spherepack_array_size()*stride.

SpherepackIterator &	operator++ ()

	operator bool () const

size_t	operator() () const
	Current index into a SPHEREPACK coefficient array.

std::optional< size_t >	compact_index (const size_t offset) const
	Given an offset into a SPHEREPACK coefficient array, return the compact index corresponding to that offset. More...

size_t	current_compact_index () const
	Returns the current compact index that SpherepackIterator uses internally. This does not index a SPHEREPACK coefficient array. More...

size_t	l () const
	Current values of l and m.

size_t	m () const

CoefficientArray	coefficient_array () const
	Whether the iterator points to an element of 'a' or 'b', i.e. points to the cos(mphi) or sin(mphi) part of a spectral coefficient.

SpherepackIterator &	reset ()
	Reset iterator back to beginning value. Returns *this.

SpherepackIterator &	set (size_t l_input, size_t m_input, CoefficientArray coefficient_array_input)
	Set iterator to specific value of l, m, array. Returns *this.

SpherepackIterator &	set (size_t l_input, int m_input)
	Same as 'set' above, but assumes CoefficientArray is 'a' for m>=0 and 'b' for m<0. This is useful when converting between true spherical harmonics (which allow negative values of m) and SPHEREPACK coefficients (which have only positive values of m, but two arrays for sin(mphi) and cos(mphi) parts).

SpherepackIterator &	set (size_t compact_index)
	Set iterator to a specific compact index. Returns *this.

Detailed Description

Iterates over spectral coefficients stored in SPHEREPACK format.

Details

The internal SPHEREPACK ordering is not intuitive, so SpherepackIterator exists for the purpose of iterating over an array containing SPHEREPACK coefficients and determining the (l,m) of each entry in the array.

SPHEREPACK expands \(f(\theta,\phi)\) as

\[ f(\theta,\phi) = \frac{1}{2} \sum_{l=0}^{l_{max}} \bar{P}_l^0 a(0,l) + \sum_{m=1}^{m_{max}} \sum_{l=m}^{l_{max}} \bar{P}_l^m \left( a(m,l) \cos(m \phi) - b(m,l) \sin(m \phi)\right) \]

where \(a(m,l)\) and \(b(m,l)\) are the SPHEREPACK spectral coefficients, and \(\bar{P}_l^m\) are unit-orthonormal associated Legendre polynomials:

\[ \bar{P}_l^m = (-1)^m \sqrt{\frac{(2l+1)(l-m)!}{2(l+m)!}} P_l^m, \]

where \(P_l^m\) are the associated Legendre polynomials as defined for example in Jackson "Classical Electrodynamics".

Example

  const size_t l_max = 4;
  const size_t m_max = 2;
  const size_t stride = 5;
  ylm::SpherepackIterator iter(l_max, m_max, stride, zero_m_is_real);
  // Allocate space for a SPHEREPACK array
  std::vector<double> array(iter.spherepack_array_size() * stride);
  // Set each array element equal to l+m for real part
  // and l-m for imaginary part.
  size_t i = 0;
  for (iter.reset(); iter; ++iter, ++i) {
    if (iter.coefficient_array() ==
        ylm::SpherepackIterator::CoefficientArray::a) {
      array[iter()] = iter.l() + iter.m();
    } else {
      array[iter()] = iter.l() - iter.m();
    }
    CHECK(iter.l() == test_l[i]);
    CHECK(iter.m() == test_m[i]);
    CHECK(iter() == test_index[i]);
  }

Constructor & Destructor Documentation

◆ SpherepackIterator()

ylm::SpherepackIterator::SpherepackIterator	(	size_t	l_max_input,
		size_t	m_max_input,
		size_t	stride = `1`,
		bool	zero_m_is_real = `true`
	)

Construct a SpherepackIterator.

For all uses of SpherepackIterator by the SPHEREPACK routines, zero_m_is_real should be true, indicating that the m=0 values of the coefficients are real (or in other words, the 'b' array has no m=0 values).

However, we sometimes use the same storage scheme (and hence SpherepackIterator) to hold spin-weighted-spherical-harmonic coefficients of complex quantities, in which case the m=0 values of the coefficients can be complex; in that case, zero_m_is_real should be false.

Member Function Documentation

◆ compact_index()

std::optional< size_t > ylm::SpherepackIterator::compact_index ( const size_t offset ) const

inline

Given an offset into a SPHEREPACK coefficient array, return the compact index corresponding to that offset.

Essentially the inverse of operator(). If the offset points to an element that SPHEREPACK doesn't actually use (i.e. no compact index can reach the given offset), then a std::nullopt is returned.

◆ current_compact_index()

size_t ylm::SpherepackIterator::current_compact_index ( ) const

inline

Returns the current compact index that SpherepackIterator uses internally. This does not index a SPHEREPACK coefficient array.

See also: operator() for an index into a SPHEREPACK coefficient array

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

src/NumericalAlgorithms/SphericalHarmonics/SpherepackIterator.hpp

Public Types

Public Member Functions