Class to compute and store properties associated with wavevectors. More...

#include <WaveList.h>

Public Member Functions
Construction, Destruction and Initialization
	WaveList (bool isRealField=true)
	Constructor.
	~WaveList ()
	Destructor.
void	allocate (Mesh< D > const &m, UnitCell< D > const &c)
	Allocate memory and set association with a Mesh and UnitCell object.
Computation
void	clearUnitCellData ()
	Clear all internal data that depends on lattice parameters.
void	computeMinimumImages ()
	Compute minimum images of wavevectors, and also calculates kSq.
void	computeKSq ()
	Compute square norm \|k\|^2 for all wavevectors.
void	computedKSq ()
	Compute derivatives of \|k\|^2 w/ respect to unit cell parameters.
void	sortWaves ()
	Sort waves in order of ascending wavevector norm.
Data Access
DArray< IntVec< D > > const &	minImages () const
	Get the array of minimum image vectors by const reference.
RField< D > const &	kSq () const
	Get the kSq array on the device by const reference.
RField< D > const &	dKSq (int i) const
	Get derivatives of kSq with respect to unit cell parameter i.
DArray< RField< D > > const &	dKSq () const
	Get all derivatives of kSq with respect to unit cell parameters.
DArray< bool > const &	implicitInverse () const
	Get the implicitInverse array by reference.
DArray< int > const &	sortedIds () const
	Get the sortedIds array by reference.
GArray< Pair< int > > const &	sortedBunches () const
	Get the sortedBunches array by reference.
DArray< int > const &	bunchIds () const
	Get the bunchIds array by reference.
IntVec< D > const &	kMeshDimensions () const
	Return the dimensions of the k-grid mesh.
int	kSize () const
	Return the number of points in the k-grid mesh.
int	nBunch () const
	Return the number of bunches of sorted waves.
Boolean Queries
bool	isAllocated () const
	Has memory been allocated for arrays?
bool	hasMinImages () const
	Are minimum images up to date ?
bool	hasKSq () const
	Are values of kSq up-to-date ?
bool	hasdKSq () const
	Are values of dKSq up-to-date?
bool	isSorted () const
	Have the waves been sorted by magnitude ?
bool	isRealField () const
	Is this WaveList set up for use with real-valued fields?

Detailed Description

template<int D>
class Pscf::Prdc::Cpu::WaveList< D >

Class to compute and store properties associated with wavevectors.

A WaveList computes and stores minimum images of wavevectors, square norms of wavevectors (kSq), and derivatives of the square norms with respect to the unit cell parameters (dKSq). A WaveList can also be used to sort wavevectors in order of increasing wavevector norm.

A WaveList computes these properties for a mesh of grid points in k-space. Different dimensions are used for this mesh depending on the value of the parameter isRealField that is passed to constructor. This parameter specifies whether this class will use a k-space mesh designed for real or complex fields throughout the lifetime of this WaveList object. If isRealField == true, this class uses the k-space mesh used by FFTW for the result of a real-to-complex discrete Fourier transform, which is contains slightly more than half the number of grid points as the corresponding real-space mesh. If isRealField == true, this class uses a k-space mesh with dimensions that are the same as those of the associated real-space mesh. The dimensions of this k-space mesh are returned as an IntVec<D> by member function kMeshDimensions().

In most of the arrays constructed by this class, each element corresponds to a wavevector in the associated k-space mesh, and the index of each element correspond to the rank of the associated wavevector within that mesh. This applies to the arrays returned by the functions minImages(), kSq(), dkSq(int i), and bunchIds().

Any time the lattice parameters change, the clearUnitCellData() method should be called. This function sets internal flags that mark some properties as being outdated, indicating that they are outdated and thus must be recalculated before the next use.

Definition at line 66 of file cpu/WaveList.h.

Constructor & Destructor Documentation

◆ WaveList()

template<int D>

Pscf::Prdc::Cpu::WaveList< D >::WaveList ( bool isRealField = true )

Constructor.

Parameters

isRealField Will this object be used for real-valued fields?

Definition at line 30 of file cpu/WaveList.tpp.

References isRealField().

◆ ~WaveList()

template<int D>

Pscf::Prdc::Cpu::WaveList< D >::~WaveList ( )

Destructor.

Definition at line 47 of file cpu/WaveList.tpp.

Member Function Documentation

◆ allocate()

template<int D>

void Pscf::Prdc::Cpu::WaveList< D >::allocate	(	Mesh< D > const &	m,
		UnitCell< D > const &	c )

Allocate memory and set association with a Mesh and UnitCell object.

Parameters

m	spatial discretization mesh (input)
c	crystallographic unit cell (input)

Definition at line 54 of file cpu/WaveList.tpp.

References Pscf::MeshIterator< D >::atEnd(), Pscf::MeshIterator< D >::begin(), clearUnitCellData(), Pscf::Prdc::Cpu::FFT< D >::computeKMesh(), Pscf::Prdc::Cpu::FFT< D >::hasImplicitInverse(), Pscf::Prdc::UnitCellBase< D >::nParameter(), Pscf::MeshIterator< D >::position(), Pscf::MeshIterator< D >::rank(), Pscf::Mesh< D >::size(), and UTIL_CHECK.

◆ clearUnitCellData()

template<int D>

void Pscf::Prdc::Cpu::WaveList< D >::clearUnitCellData ( )

Clear all internal data that depends on lattice parameters.

Sets hasKSq_ and hasdKSq_ to false. Sets hasMinImages_ to false if the unit cell type has variable angles. Sets isSorted_ to false if the unit cell has more than one unit cell parameter.

Definition at line 107 of file cpu/WaveList.tpp.

References Pscf::Prdc::hasVariableAngle().

Referenced by allocate().

◆ computeMinimumImages()

template<int D>

void Pscf::Prdc::Cpu::WaveList< D >::computeMinimumImages ( )

Compute minimum images of wavevectors, and also calculates kSq.

This function recomputes the minimum images of all wavevectors if necessary (i.e., if hasMinImages() == false), but does nothing if if minimum images are up to date (if hasMinImages() == true).

The minimum images may change if a lattice angle in the unit cell is changed, so this method should be called whenever such changes occur.

In the process of computing the minimum images, the square norm |k|^2 for all wavevectors is also calculated and stored, so it is not necessary to call computeKSq after calling this method. computeKSq is provided to allow calculation of kSq without recalculating minimum images.

Definition at line 125 of file cpu/WaveList.tpp.

References Pscf::MeshIterator< D >::atEnd(), Pscf::MeshIterator< D >::begin(), Pscf::MeshIterator< D >::position(), Pscf::MeshIterator< D >::rank(), and UTIL_CHECK.

Referenced by computedKSq(), and computeKSq().

◆ computeKSq()

template<int D>

void Pscf::Prdc::Cpu::WaveList< D >::computeKSq ( )

Compute square norm |k|^2 for all wavevectors.

This function recomputes values of the square norm for all wavevectors if necessary (i.e., if hasKSq() == false), and does nothing if these values are up to date (if hasKSq() == true). Minimum image values are updated if necessary.

Definition at line 152 of file cpu/WaveList.tpp.

References Pscf::MeshIterator< D >::atEnd(), Pscf::MeshIterator< D >::begin(), computeMinimumImages(), Pscf::MeshIterator< D >::rank(), and UTIL_CHECK.

Referenced by sortWaves().

◆ computedKSq()

template<int D>

void Pscf::Prdc::Cpu::WaveList< D >::computedKSq ( )

Compute derivatives of |k|^2 w/ respect to unit cell parameters.

This function computes values of the derivatives of wavevector square norms with respect to unit cell parameters if necessary (i.e., if hasdKSq() == false), and does nothing if these values are up to date. Minimum images are updated if necessary.

Definition at line 184 of file cpu/WaveList.tpp.

References Pscf::MeshIterator< D >::atEnd(), Pscf::MeshIterator< D >::begin(), computeMinimumImages(), Pscf::MeshIterator< D >::rank(), and UTIL_CHECK.

◆ sortWaves()

template<int D>

void Pscf::Prdc::Cpu::WaveList< D >::sortWaves ( )

Sort waves in order of ascending wavevector norm.

This function computes the sortedIds, sortedBunches, and bunchIds arrays. Values of kSq are updated before sorting waves if hasKSq() is false on entry.

Definition at line 221 of file cpu/WaveList.tpp.

References computeKSq(), Pscf::Sort::findBunches(), Pscf::Sort::sort(), and UTIL_CHECK.

◆ minImages()

template<int D>

DArray< IntVec< D > > const & Pscf::Prdc::Cpu::WaveList< D >::minImages ( ) const

inline

Get the array of minimum image vectors by const reference.

This function returns an array of kSize elements in which each element is an IntVec<D> containing the integer coordinates of the minimum image of one wavevector in the k-space mesh used for a discrete Fourier transforms. Array indices correspond to ranks in this k-space mesh.

Definition at line 449 of file cpu/WaveList.h.

References UTIL_CHECK.

◆ kSq()

template<int D>

RField< D > const & Pscf::Prdc::Cpu::WaveList< D >::kSq ( ) const

inline

Get the kSq array on the device by const reference.

This function returns an array in which each element is the square magnitude |k|^2 of a wavevector in the k-space mesh used for a discrete Fourier transform. Array indices correspond to ranks within this k-space mesh.

Definition at line 457 of file cpu/WaveList.h.

References UTIL_CHECK.

Referenced by Pscf::Rpc::BinaryStructureFactor< D >::setup().

◆ dKSq() [1/2]

template<int D>

RField< D > const & Pscf::Prdc::Cpu::WaveList< D >::dKSq ( int i ) const

inline

Get derivatives of kSq with respect to unit cell parameter i.

This function returns an array in which element j contains the derivative of the square-wavevector kSq[j] wtih respect to unit cell parameter number i, multiplied by a weight factor. If the flag isRealField is true, then the weight factor is 2.0 for waves that have an implicit inverse and and 1.0 otherwise. If isReaField is false, then the weight factor is 1.0 for all wavevectors. The inclusion of a weight factor is designed to simplify use of this array to compute stress.

Values of the grid array index j correspond to the the rank of the k-space mesh used for discrete Fourier transforms.

Parameters

i	index of lattice parameter

Definition at line 465 of file cpu/WaveList.h.

References UTIL_CHECK.

◆ dKSq() [2/2]

template<int D>

DArray< RField< D > > const & Pscf::Prdc::Cpu::WaveList< D >::dKSq ( ) const

inline

Get all derivatives of kSq with respect to unit cell parameters.

Element i of the DArray is the RField<D> that can also be obtained from member function dKSq(int i). See documentation of that function.

Definition at line 473 of file cpu/WaveList.h.

References UTIL_CHECK.

◆ implicitInverse()

template<int D>

DArray< bool > const & Pscf::Prdc::Cpu::WaveList< D >::implicitInverse ( ) const

inline

Get the implicitInverse array by reference.

This array is defined on a k-grid mesh, with a boolean value for each gridpoint. The boolean represents whether the inverse of the wave at the given gridpoint is an implicit wave in the k-space mesh used for a discrete Fourier transform of a real function. The inverse is implicit if it is outside the bounds of this truncated k-space mesh. Array indices correspond to ranks within this k-space mesh.

This function throws an Exception if isRealField == false, because there are no implicit inverses in such a case.

Definition at line 481 of file cpu/WaveList.h.

References UTIL_CHECK.

Referenced by Pscf::Rpc::BinaryStructureFactor< D >::setup().

◆ sortedIds()

template<int D>

DArray< int > const & Pscf::Prdc::Cpu::WaveList< D >::sortedIds ( ) const

inline

Get the sortedIds array by reference.

The array returned by this function contains k-grid rank indices of wavevectors sorted in order of increasing wavevector magnitude.

This method throws an Exception if isSorted == false.

Definition at line 490 of file cpu/WaveList.h.

References UTIL_CHECK.

◆ sortedBunches()

template<int D>

GArray< Pair< int > > const & Pscf::Prdc::Cpu::WaveList< D >::sortedBunches ( ) const

inline

Get the sortedBunches array by reference.

Each element in this array contains a Pair<int> of two integers that give upper and lower bounds for array indices in the sortedIds array of a contiguous slice (a "bunch") of sorted waves for which the wavevector have equal vector magitudes. The first integer in such a pair is the array index of the first wavevector in such a bunch, and the second is one greater than the index of the last wavevector in the bunch.

This method throws an Exception if isSorted == false.

Definition at line 498 of file cpu/WaveList.h.

References UTIL_CHECK.

◆ bunchIds()

template<int D>

DArray< int > const & Pscf::Prdc::Cpu::WaveList< D >::bunchIds ( ) const

inline

Get the bunchIds array by reference.

This function returns an array, indexed by wave rank, in which the value is the integer identifier of a bunch to which the wave belongs. Each such value corresponds to an array index of the corresponding bunch in the sortedBunches array.

This method throws an Exception if isSorted == false.

Definition at line 506 of file cpu/WaveList.h.

References UTIL_CHECK.

◆ kMeshDimensions()

template<int D>

IntVec< D > const & Pscf::Prdc::Cpu::WaveList< D >::kMeshDimensions ( ) const

inline

Return the dimensions of the k-grid mesh.

If isRealField() == true, the reciprocal-space grid is smaller than the real-space grid. Otherwise, the two grids are identical.

Definition at line 266 of file cpu/WaveList.h.

◆ kSize()

template<int D>

int Pscf::Prdc::Cpu::WaveList< D >::kSize ( ) const

inline

Return the number of points in the k-grid mesh.

If isRealField() == true, kSize is approximately half the size of the real-space grid. Otherwise, the two grids are identical.

Definition at line 275 of file cpu/WaveList.h.

◆ nBunch()

template<int D>

int Pscf::Prdc::Cpu::WaveList< D >::nBunch ( ) const

inline

Return the number of bunches of sorted waves.

Definition at line 281 of file cpu/WaveList.h.

References UTIL_CHECK.

◆ isAllocated()

template<int D>

bool Pscf::Prdc::Cpu::WaveList< D >::isAllocated ( ) const

inline

Has memory been allocated for arrays?

Definition at line 294 of file cpu/WaveList.h.

◆ hasMinImages()

template<int D>

bool Pscf::Prdc::Cpu::WaveList< D >::hasMinImages ( ) const

inline

Are minimum images up to date ?

Definition at line 300 of file cpu/WaveList.h.

◆ hasKSq()

template<int D>

bool Pscf::Prdc::Cpu::WaveList< D >::hasKSq ( ) const

inline

Are values of kSq up-to-date ?

Definition at line 306 of file cpu/WaveList.h.

◆ hasdKSq()

template<int D>

bool Pscf::Prdc::Cpu::WaveList< D >::hasdKSq ( ) const

inline

Are values of dKSq up-to-date?

Definition at line 312 of file cpu/WaveList.h.

◆ isSorted()

template<int D>

bool Pscf::Prdc::Cpu::WaveList< D >::isSorted ( ) const

inline

Have the waves been sorted by magnitude ?

Definition at line 318 of file cpu/WaveList.h.

◆ isRealField()

template<int D>

bool Pscf::Prdc::Cpu::WaveList< D >::isRealField ( ) const

inline

Is this WaveList set up for use with real-valued fields?

Definition at line 324 of file cpu/WaveList.h.

Referenced by WaveList().

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ WaveList()

◆ ~WaveList()

Member Function Documentation

◆ allocate()

◆ clearUnitCellData()

◆ computeMinimumImages()

◆ computeKSq()

◆ computedKSq()

◆ sortWaves()

◆ minImages()

◆ kSq()

◆ dKSq() [1/2]

◆ dKSq() [2/2]

◆ implicitInverse()

◆ sortedIds()

◆ sortedBunches()

◆ bunchIds()

◆ kMeshDimensions()

◆ kSize()

◆ nBunch()

◆ isAllocated()

◆ hasMinImages()

◆ hasKSq()

◆ hasdKSq()

◆ isSorted()

◆ isRealField()