A container of w fields stored in both basis and r-grid format. More...

#include <WFields.h>

Public Member Functions
Initialization and Memory Management
void	setFieldIo (FIT const &fieldIo)
	Create association with FIT (store pointer).
void	setReadUnitCell (UnitCell< D > &cell)
	Set unit cell used when reading field files.
void	setWriteUnitCell (UnitCell< D > const &cell)
	Set unit cell used when writing field files.
void	setNMonomer (int nMonomer)
	Set stored value of nMonomer.
void	allocateRGrid (IntVec< D > const &dimensions)
	Allocate or re-allocate memory for fields in rgrid format.
void	allocateBasis (int nBasis)
	Allocate or re-allocate memory for fields in basis format.
void	allocate (int nMonomer, int nBasis, IntVec< D > const &dimensions)
	Allocate memory for all fields.
Field Modifiers
void	setBasis (DArray< DArray< double > > const &fields)
	Set field component values, in symmetrized Fourier format.
void	setRGrid (DArray< RFT > const &fields, bool isSymmetric=false)
	Set fields values in real-space (r-grid) format.
void	readBasis (std::istream &in)
	Read fields from an input stream in symmetrized basis format.
void	readBasis (std::string filename)
	Read fields from a named file, in symmetrized basis format.
void	readRGrid (std::istream &in, bool isSymmetric=false)
	Reads fields from an input stream in real-space (r-grid) format.
void	readRGrid (std::string filename, bool isSymmetric=false)
	Reads fields from a named file in real-space (r-grid) format.
void	symmetrize ()
	Symmetrize r-grid fields, compute corresponding basis components.
void	clear ()
	Clear data stored in this object without deallocating.
Signal< void > &	signal ()
	Get a signal that notifies observers of field modification.
Field Output
void	writeBasis (std::ostream &out) const
	Write fields to an input stream in symmetrized basis format.
void	writeBasis (std::string filename) const
	Write fields to a named file, in symmetrized basis format.
void	writeRGrid (std::ostream &out) const
	Writes fields to an input stream in real-space (r-grid) format.
void	writeRGrid (std::string filename) const
	Writes fields to a named file in real-space (r-grid) format.
Field Accessors (by const reference)
DArray< DArray< double > > const &	basis () const
	Get array of all fields in basis format.
DArray< double > const &	basis (int monomerId) const
	Get the field for one monomer type in basis format.
DArray< RFT > const &	rgrid () const
	Get array of all fields in r-space grid format.
RFT const &	rgrid (int monomerId) const
	Get the field for one monomer type in r-space grid format.
Boolean Queries
bool	isAllocatedRGrid () const
	Has memory been allocated for fields in r-grid format?
bool	isAllocatedBasis () const
	Has memory been allocated for fields in basis format?
bool	hasData () const
	Has field data been set in either format?
bool	isSymmetric () const
	Are fields symmetric under all elements of the space group?

Protected Member Functions
	WFields ()
	Constructor.
	~WFields ()
	Destructor.
IntVec< D > const &	meshDimensions () const
	Get mesh dimensions in each direction, set on r-grid allocation.
int	meshSize () const
	Get mesh size (number of grid points), set on r-grid allocation.
int	nBasis () const
	Get number of basis functions, set on basis allocation.
int	nMonomer () const
	Get number of monomer types.
FIT const &	fieldIo () const
	Get associated FIT object (const reference).

Detailed Description

template<int D, class RFT, class FIT>
class Pscf::Rp::WFields< D, RFT, FIT >

A container of w fields stored in both basis and r-grid format.

Template parameters : The template parameters represent:

- D   : integer dimensionality of space, D=1,2, or 3
- RFT : r-grid field type (e.g., Prdc::Cpu::RField<D>)
- FIT : class for field IO operations (e.g., Rpc:: FieldIo<D>)

Field Representations : A WFields object contains a list of nMonomer chemical potential (w) fields that are each associated with a monomer type. The fields may be stored in two different formats:

A DArray of RFT containers holds valus of each field on the nodes of a regular grid. This is accessed by the rgrid() and rgrid(int) member functions.
A DArray of DArray<double> containers holds components of each field in a symmetry-adapted Fourier expansion (i.e., in basis format). This is accessed by the basis() and basis(int) member functions.

A WFields is designed to automatically update one of these representations when the other is modified, as appropriate. A pointer to an associated FIT object is used for these conversions.

The setBasis and readBasis functions allow the user to input new components in basis format, and both internally recompute the values in r-grid format. The setRGrid and readRGrid functions allow the user to input the fields in r-grid format, and compute corresponding components in basis format if and only if the user declares that the fields are known to be invariant under all symmetries of the space group. A boolean flag named isSymmetric is used to keep track of whether the current field is symmetric, and thus whether the basis format exists.

Signal : A WFields object owns an instance of class Util::Signal<void> that notifies all observers whenever the fields owned by the WFields are modified. This signal object may be accessed by reference using the signal() member function. The Util::Signal<void>::addObserver function may used to add "observer" objects and indicate a zero-parameter member function of each observer that will be called whenever the fields are modified.

Subclasses : Specializations of Rp::WFields are used as base for specializations of Rpc::WFields and Rpg::WFields :

Each specialization Rpc::WFields <D> with D=1, 2, or 3 is derived from a specialization of Rp::WFields with template arguments D, RFT = Cpu::RFT <D> and FIT = Rpc::FIT <D> , and is used in the pscf_rpc CPU program.
Each specialization Rpg::WFields <D> with D=1, 2 or 3 is derived from specializations of Rp::WFields with template arguments D, RFT = Cuda::RFT <D> and FIT = Rpg::FIT <D> , and is used in the pscf_rpg GPU program.

Definition at line 92 of file rp/field/WFields.h.

Constructor & Destructor Documentation

◆ WFields()

template<int D, class RFT, class FIT>

Pscf::Rp::WFields< D, RFT, FIT >::WFields ( )

protected

Constructor.

Definition at line 31 of file rp/field/WFields.tpp.

◆ ~WFields()

template<int D, class RFT, class FIT>

Pscf::Rp::WFields< D, RFT, FIT >::~WFields ( )

protected

Destructor.

Definition at line 54 of file rp/field/WFields.tpp.

Member Function Documentation

◆ setFieldIo()

template<int D, class RFT, class FIT>

void Pscf::Rp::WFields< D, RFT, FIT >::setFieldIo ( FIT const & fieldIo )

Create association with FIT (store pointer).

Parameters

fieldIo associated FIT object

Definition at line 63 of file rp/field/WFields.tpp.

References fieldIo().

◆ setReadUnitCell()

template<int D, class RFT, class FIT>

void Pscf::Rp::WFields< D, RFT, FIT >::setReadUnitCell ( UnitCell< D > & cell )

Set unit cell used when reading field files.

This function creates a stored pointer to a UnitCell<D> that is is used by the readBasis and readRGrid functions, which reset the unit cell parameters in this object to those read from the field file header. This function may only be called once.

Parameters

cell	unit cell that is modified by readBasis and readRGrid.

Definition at line 70 of file rp/field/WFields.tpp.

References UTIL_CHECK.

◆ setWriteUnitCell()

template<int D, class RFT, class FIT>

void Pscf::Rp::WFields< D, RFT, FIT >::setWriteUnitCell ( UnitCell< D > const & cell )

Set unit cell used when writing field files.

This function creates a stored pointer to a UnitCell<D> that is is used by the writeBasis and writeRGrid functions, which each write the unit cell parameters from in this object to a field file header. This function may only be called once.

Parameters

cell	unit cell that is used by writeBasis and writeRGrid.

Definition at line 80 of file rp/field/WFields.tpp.

References UTIL_CHECK.

◆ setNMonomer()

template<int D, class RFT, class FIT>

void Pscf::Rp::WFields< D, RFT, FIT >::setNMonomer ( int nMonomer )

Set stored value of nMonomer.

May only be called once.

Parameters

nMonomer number of monomer types.

Definition at line 90 of file rp/field/WFields.tpp.

References nMonomer(), and UTIL_CHECK.

Referenced by allocate().

◆ allocateRGrid()

template<int D, class RFT, class FIT>

void Pscf::Rp::WFields< D, RFT, FIT >::allocateRGrid ( IntVec< D > const & dimensions )

Allocate or re-allocate memory for fields in rgrid format.

Parameters

dimensions dimensions of spatial mesh

Definition at line 102 of file rp/field/WFields.tpp.

References meshDimensions(), and UTIL_CHECK.

Referenced by allocate(), readBasis(), readRGrid(), setBasis(), and setRGrid().

◆ allocateBasis()

template<int D, class RFT, class FIT>

void Pscf::Rp::WFields< D, RFT, FIT >::allocateBasis ( int nBasis )

Allocate or re-allocate memory for fields in basis format.

Parameters

nBasis number of basis functions

Definition at line 129 of file rp/field/WFields.tpp.

References nBasis(), and UTIL_CHECK.

Referenced by allocate(), readBasis(), readRGrid(), setBasis(), and setRGrid().

◆ allocate()

template<int D, class RFT, class FIT>

void Pscf::Rp::WFields< D, RFT, FIT >::allocate	(	int	nMonomer,
		int	nBasis,
		IntVec< D > const &	dimensions )

Allocate memory for all fields.

This function may only be called once.

Parameters

nMonomer	number of monomer types
nBasis	number of basis functions
dimensions	dimensions of spatial mesh

Definition at line 148 of file rp/field/WFields.tpp.

References allocateBasis(), allocateRGrid(), meshDimensions(), nBasis(), nMonomer(), and setNMonomer().

◆ setBasis()

template<int D, class RFT, class FIT>

void Pscf::Rp::WFields< D, RFT, FIT >::setBasis ( DArray< DArray< double > > const & fields )

Set field component values, in symmetrized Fourier format.

This function also computes and stores the corresponding r-grid representation. On return, hasData and isSymmetric are both true.

The associated basis must be initialized on entry. As needed, r-grid and/or basis fields may be allocated within this function.

Parameters

fields array of new fields in basis format

Definition at line 164 of file rp/field/WFields.tpp.

References allocateBasis(), allocateRGrid(), basis(), Util::Array< Data >::capacity(), Pscf::Mesh< D >::dimensions(), fieldIo(), signal(), Pscf::Mesh< D >::size(), and UTIL_CHECK.

◆ setRGrid()

template<int D, class RFT, class FIT>

void Pscf::Rp::WFields< D, RFT, FIT >::setRGrid	(	DArray< RFT > const &	fields,
		bool	isSymmetric = false )

Set fields values in real-space (r-grid) format.

If the isSymmetric parameter is true, this function assumes that the fields are known to be symmetric and so computes and stores the corresponding basis components. If isSymmetric is false, it only sets the values in the r-grid format.

On return, hasData is true and the persistent isSymmetric flag defined by the class is set to the value of the isSymmetric input parameter.

As needed, r-grid and/or basis fields may be allocated within this function. If the isSymmetric parameter is true, the a basis must be initialized prior to entry.

Parameters

fields	array of new fields in r-grid format
isSymmetric	is this field symmetric under the space group?

Definition at line 208 of file rp/field/WFields.tpp.

References allocateBasis(), allocateRGrid(), basis(), Util::Array< Data >::capacity(), Pscf::Mesh< D >::dimensions(), Pscf::VecOp::eqV(), fieldIo(), isSymmetric(), signal(), Pscf::Mesh< D >::size(), and UTIL_CHECK.

◆ readBasis() [1/2]

template<int D, class RFT, class FIT>

void Pscf::Rp::WFields< D, RFT, FIT >::readBasis ( std::istream & in )

Read fields from an input stream in symmetrized basis format.

This function also computes and stores the corresponding r-grid representation. On return, hasData and isSymmetric are both true.

As needed, r-grid and/or basis fields can be allocated within this function, if not allocated on entry. An associated basis will be initialized if not initialized on entry.

Parameters

in	input stream from which to read fields

Definition at line 251 of file rp/field/WFields.tpp.

References allocateBasis(), allocateRGrid(), basis(), Pscf::Mesh< D >::dimensions(), fieldIo(), Pscf::Prdc::readBasisData(), Pscf::Prdc::readNBasis(), signal(), Pscf::Mesh< D >::size(), and UTIL_CHECK.

Referenced by readBasis().

◆ readBasis() [2/2]

template<int D, class RFT, class FIT>

void Pscf::Rp::WFields< D, RFT, FIT >::readBasis ( std::string filename )

Read fields from a named file, in symmetrized basis format.

This function also computes and stores the corresponding r-grid representation. On return, hasData and isSymmetric are both true.

As needed, r-grid and/or basis fields may be allocated within this function, if not allocated on entry. An associated basis will be initialized if not initialized on entry.

Parameters

filename file from which to read fields

Definition at line 304 of file rp/field/WFields.tpp.

References fieldIo(), and readBasis().

◆ readRGrid() [1/2]

template<int D, class RFT, class FIT>

void Pscf::Rp::WFields< D, RFT, FIT >::readRGrid	(	std::istream &	in,
		bool	isSymmetric = false )

Reads fields from an input stream in real-space (r-grid) format.

If the isSymmetric parameter is true, this function assumes that the fields are known to be symmetric and so computes and stores the corresponding basis components. If isSymmetric is false, it only sets the values in the r-grid format.

On return, hasData is true and the persistent isSymmetric flag defined by the class is set to the value of the isSymmetric input parameter.

As needed, r-grid and/or basis fields may be allocated within this function, if not allocated on entry. An associated basis will be initialized if not initialized on entry.

Parameters

in	input stream from which to read fields
isSymmetric	is this field symmetric under the space group?

Definition at line 325 of file rp/field/WFields.tpp.

References allocateBasis(), allocateRGrid(), basis(), Pscf::Mesh< D >::dimensions(), fieldIo(), isSymmetric(), signal(), and UTIL_CHECK.

Referenced by readRGrid().

◆ readRGrid() [2/2]

template<int D, class RFT, class FIT>

void Pscf::Rp::WFields< D, RFT, FIT >::readRGrid	(	std::string	filename,
		bool	isSymmetric = false )

Reads fields from a named file in real-space (r-grid) format.

If the isSymmetric parameter is true, this function assumes that the fields are known to be symmetric and so computes and stores the corresponding basis components. If isSymmetric is false, it only sets the values in the r-grid format.

On return, hasData is true and the persistent isSymmetric flag defined by the class is set to the value of the isSymmetric input parameter.

As needed, r-grid and/or basis fields may be allocated within this function, if not allocated on entry. An associated basis will be initialized if not initialized on entry.

Parameters

filename	file from which to read fields
isSymmetric	Is this field symmetric under the space group?

Definition at line 363 of file rp/field/WFields.tpp.

References fieldIo(), isSymmetric(), and readRGrid().

◆ symmetrize()

template<int D, class RFT, class FIT>

void Pscf::Rp::WFields< D, RFT, FIT >::symmetrize ( )

Symmetrize r-grid fields, compute corresponding basis components.

This function may be used after setting or reading w fields in r-grid format that are known to be symmetric under the space group to remove small deviations from symmetry and generate basis components.

The function symmetrizes the fields by converting from r-grid to basis format and then back again, while also storing the resulting basis components and setting isSymmetric() true.

This function assumes that the current wFieldsRGrid fields are known by the user to be symmetric, and does NOT check this. Applying this function to fields that are not symmetric will silently corrupt the fields.

On entry, hasData() must be true and isSymmetric() must be false. On exit, isSymmetric() is true.

Definition at line 376 of file rp/field/WFields.tpp.

References fieldIo(), signal(), and UTIL_CHECK.

◆ clear()

template<int D, class RField, class FieldIo>

void Pscf::Rp::WFields< D, RField, FieldIo >::clear ( )

inline

Clear data stored in this object without deallocating.

Definition at line 536 of file rp/field/WFields.h.

◆ signal()

template<int D, class RFT, class FIT>

Signal< void > & Pscf::Rp::WFields< D, RFT, FIT >::signal ( )

Get a signal that notifies observers of field modification.

Definition at line 455 of file rp/field/WFields.tpp.

References UTIL_CHECK.

Referenced by readBasis(), readRGrid(), setBasis(), setRGrid(), and symmetrize().

◆ writeBasis() [1/2]

template<int D, class RFT, class FIT>

void Pscf::Rp::WFields< D, RFT, FIT >::writeBasis ( std::ostream & out ) const

Write fields to an input stream in symmetrized basis format.

Parameters

out	output stream to which to write fields

Definition at line 393 of file rp/field/WFields.tpp.

References fieldIo(), and UTIL_CHECK.

Referenced by writeBasis().

◆ writeBasis() [2/2]

template<int D, class RFT, class FIT>

void Pscf::Rp::WFields< D, RFT, FIT >::writeBasis ( std::string filename ) const

Write fields to a named file, in symmetrized basis format.

Parameters

filename file to which to write fields

Definition at line 410 of file rp/field/WFields.tpp.

References fieldIo(), and writeBasis().

◆ writeRGrid() [1/2]

template<int D, class RFT, class FIT>

void Pscf::Rp::WFields< D, RFT, FIT >::writeRGrid ( std::ostream & out ) const

Writes fields to an input stream in real-space (r-grid) format.

Parameters

out	output stream to which to write fields

Definition at line 422 of file rp/field/WFields.tpp.

References fieldIo(), and UTIL_CHECK.

Referenced by writeRGrid().

◆ writeRGrid() [2/2]

template<int D, class RFT, class FIT>

void Pscf::Rp::WFields< D, RFT, FIT >::writeRGrid ( std::string filename ) const

Writes fields to a named file in real-space (r-grid) format.

Parameters

filename file to which to write fields

Definition at line 441 of file rp/field/WFields.tpp.

References fieldIo(), and writeRGrid().

◆ basis() [1/2]

template<int D, class RFT, class FIT>

DArray< DArray< double > > const & Pscf::Rp::WFields< D, RFT, FIT >::basis ( ) const

inline

Get array of all fields in basis format.

The array capacity is equal to the number of monomer types.

Definition at line 542 of file rp/field/WFields.h.

References UTIL_ASSERT.

Referenced by readBasis(), readRGrid(), setBasis(), and setRGrid().

◆ basis() [2/2]

template<int D, class RFT, class FIT>

DArray< double > const & Pscf::Rp::WFields< D, RFT, FIT >::basis ( int monomerId ) const

inline

Get the field for one monomer type in basis format.

An Exception is thrown if isSymmetric is false.

Parameters

monomerId integer monomer type index (0,...,nMonomer-1)

Definition at line 550 of file rp/field/WFields.h.

References UTIL_ASSERT.

◆ rgrid() [1/2]

template<int D, class RFT, class FIT>

DArray< RFT > const & Pscf::Rp::WFields< D, RFT, FIT >::rgrid ( ) const

inline

Get array of all fields in r-space grid format.

The array capacity is equal to the number of monomer types.

Definition at line 560 of file rp/field/WFields.h.

References UTIL_ASSERT.

◆ rgrid() [2/2]

template<int D, class RFT, class FIT>

RFT const & Pscf::Rp::WFields< D, RFT, FIT >::rgrid ( int monomerId ) const

inline

Get the field for one monomer type in r-space grid format.

Parameters

monomerId integer monomer type index (0,..,nMonomer-1)

Definition at line 568 of file rp/field/WFields.h.

References UTIL_ASSERT.

◆ isAllocatedRGrid()

template<int D, class RFT, class FIT>

bool Pscf::Rp::WFields< D, RFT, FIT >::isAllocatedRGrid ( ) const

inline

Has memory been allocated for fields in r-grid format?

Definition at line 576 of file rp/field/WFields.h.

◆ isAllocatedBasis()

template<int D, class RFT, class FIT>

bool Pscf::Rp::WFields< D, RFT, FIT >::isAllocatedBasis ( ) const

inline

Has memory been allocated for fields in basis format?

Definition at line 581 of file rp/field/WFields.h.

◆ hasData()

template<int D, class RFT, class FIT>

bool Pscf::Rp::WFields< D, RFT, FIT >::hasData ( ) const

inline

Has field data been set in either format?

This flag is set true in setBasis and setRGrid.

Definition at line 586 of file rp/field/WFields.h.

◆ isSymmetric()

template<int D, class RFT, class FIT>

bool Pscf::Rp::WFields< D, RFT, FIT >::isSymmetric ( ) const

inline

Are fields symmetric under all elements of the space group?

A valid basis format exists if and only if isSymmetric is true. This flag is set true when the fields are input in basis format by the function setBasis or readBasis, or when they are set in grid format by calling the function setRGrid or readRGrid with function parameter isSymmetric == true.

Definition at line 591 of file rp/field/WFields.h.

Referenced by readRGrid(), readRGrid(), and setRGrid().

◆ meshDimensions()

template<int D, class RFT, class FIT>

IntVec< D > const & Pscf::Rp::WFields< D, RFT, FIT >::meshDimensions ( ) const

inlineprotected

Get mesh dimensions in each direction, set on r-grid allocation.

Definition at line 600 of file rp/field/WFields.h.

Referenced by allocate(), and allocateRGrid().

◆ meshSize()

template<int D, class RFT, class FIT>

int Pscf::Rp::WFields< D, RFT, FIT >::meshSize ( ) const

inlineprotected

Get mesh size (number of grid points), set on r-grid allocation.

Definition at line 605 of file rp/field/WFields.h.

◆ nBasis()

template<int D, class RFT, class FIT>

int Pscf::Rp::WFields< D, RFT, FIT >::nBasis ( ) const

inlineprotected

Get number of basis functions, set on basis allocation.

Definition at line 610 of file rp/field/WFields.h.

Referenced by allocate(), and allocateBasis().

◆ nMonomer()

template<int D, class RFT, class FIT>

int Pscf::Rp::WFields< D, RFT, FIT >::nMonomer ( ) const

inlineprotected

Get number of monomer types.

Definition at line 615 of file rp/field/WFields.h.

Referenced by allocate(), and setNMonomer().

◆ fieldIo()

template<int D, class RFT, class FIT>

FIT const & Pscf::Rp::WFields< D, RFT, FIT >::fieldIo ( ) const

inlineprotected

Get associated FIT object (const reference).

Definition at line 620 of file rp/field/WFields.h.

References UTIL_CHECK.

Referenced by readBasis(), readBasis(), readRGrid(), readRGrid(), setBasis(), setFieldIo(), setRGrid(), symmetrize(), writeBasis(), writeBasis(), writeRGrid(), and writeRGrid().

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

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ WFields()

◆ ~WFields()

Member Function Documentation

◆ setFieldIo()

◆ setReadUnitCell()

◆ setWriteUnitCell()

◆ setNMonomer()

◆ allocateRGrid()

◆ allocateBasis()

◆ allocate()

◆ setBasis()

◆ setRGrid()

◆ readBasis() [1/2]

◆ readBasis() [2/2]

◆ readRGrid() [1/2]

◆ readRGrid() [2/2]

◆ symmetrize()

◆ clear()

◆ signal()

◆ writeBasis() [1/2]

◆ writeBasis() [2/2]

◆ writeRGrid() [1/2]

◆ writeRGrid() [2/2]

◆ basis() [1/2]

◆ basis() [2/2]

◆ rgrid() [1/2]

◆ rgrid() [2/2]

◆ isAllocatedRGrid()

◆ isAllocatedBasis()

◆ hasData()

◆ isSymmetric()

◆ meshDimensions()

◆ meshSize()

◆ nBasis()

◆ nMonomer()

◆ fieldIo()