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

#include <WFieldsReal.h>

Public Member Functions
	WFieldsReal ()
	Constructor.
	~WFieldsReal ()
	Destructor.
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
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::Prdc::WFieldsReal< 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 : field type for r-grid data (e.g., RField<D>)
- FIT : FieldIo type for field io operations (e.g., FieldIo<D>)

Field Representations : A WFieldsReal 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 WFieldsReal is designed to automatically update one of these representations when the other is modified, when 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.

Subclasses : Partial specializations of WFieldsReal are used as base classes for classes Rpc::WFieldContainer <D > and Rpg::WFieldContainer <D>:

Subclass Rpc::WFieldContainer <D> is derived from a partial specialization of WFieldsReal with template parameters RFT = Cpu::RFT <D> and FIT = Rpc::FIT <D> , and is used in the pscf_pc CPU program.
Subclass Rpg::WFieldContainer <D> is derived from a partial specialization of WFieldsReal with template parameters RFT = Cuda::RFT <D> and FIT = Rpg::FIT <D> , and is used in the pscf_pg GPU accelerated program.

Signal : A WFieldsReal owns an instance of class Util::Signal<void> that notifies all observers whenever the fields owned by the WFieldsReal 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.

Definition at line 92 of file WFieldsReal.h.

Constructor & Destructor Documentation

◆ WFieldsReal()

template<int D, class RFT, class FIT>

Pscf::Prdc::WFieldsReal< D, RFT, FIT >::WFieldsReal ( )

Constructor.

Definition at line 30 of file WFieldsReal.tpp.

◆ ~WFieldsReal()

template<int D, class RFT, class FIT>

Pscf::Prdc::WFieldsReal< D, RFT, FIT >::~WFieldsReal ( )

Destructor.

Definition at line 53 of file WFieldsReal.tpp.

Member Function Documentation

◆ setFieldIo()

template<int D, class RFT, class FIT>

void Pscf::Prdc::WFieldsReal< D, RFT, FIT >::setFieldIo ( FIT const & fieldIo )

Create association with FIT (store pointer).

Parameters

fieldIo associated FIT object

Definition at line 63 of file WFieldsReal.tpp.

References fieldIo().

◆ setReadUnitCell()

template<int D, class RFT, class FIT>

void Pscf::Prdc::WFieldsReal< 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 WFieldsReal.tpp.

References UTIL_CHECK.

◆ setWriteUnitCell()

template<int D, class RFT, class FIT>

void Pscf::Prdc::WFieldsReal< 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 WFieldsReal.tpp.

References UTIL_CHECK.

◆ setNMonomer()

template<int D, class RFT, class FIT>

void Pscf::Prdc::WFieldsReal< 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 WFieldsReal.tpp.

References nMonomer(), and UTIL_CHECK.

Referenced by allocate().

◆ allocateRGrid()

template<int D, class RFT, class FIT>

void Pscf::Prdc::WFieldsReal< 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 WFieldsReal.tpp.

References meshDimensions(), and UTIL_CHECK.

Referenced by allocate(), and readRGrid().

◆ allocateBasis()

template<int D, class RFT, class FIT>

void Pscf::Prdc::WFieldsReal< 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 WFieldsReal.tpp.

References nBasis(), and UTIL_CHECK.

◆ allocate()

template<int D, class RFT, class FIT>

void Pscf::Prdc::WFieldsReal< 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 149 of file WFieldsReal.tpp.

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

◆ setBasis()

template<int D, class RFT, class FIT>

void Pscf::Prdc::WFieldsReal< 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 165 of file WFieldsReal.tpp.

References fieldIo(), Pscf::Mesh< D >::size(), and UTIL_CHECK.

◆ setRGrid()

template<int D, class RFT, class FIT>

void Pscf::Prdc::WFieldsReal< 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 209 of file WFieldsReal.tpp.

References isSymmetric().

◆ readBasis() [1/2]

template<int D, class RFT, class FIT>

void Pscf::Prdc::WFieldsReal< 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 252 of file WFieldsReal.tpp.

References fieldIo(), and UTIL_CHECK.

Referenced by readBasis().

◆ readBasis() [2/2]

template<int D, class RFT, class FIT>

void Pscf::Prdc::WFieldsReal< 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 305 of file WFieldsReal.tpp.

References fieldIo(), and readBasis().

◆ readRGrid() [1/2]

template<int D, class RFT, class FIT>

void Pscf::Prdc::WFieldsReal< 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 326 of file WFieldsReal.tpp.

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

Referenced by readRGrid().

◆ readRGrid() [2/2]

template<int D, class RFT, class FIT>

void Pscf::Prdc::WFieldsReal< 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 364 of file WFieldsReal.tpp.

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

◆ symmetrize()

template<int D, class RFT, class FIT>

void Pscf::Prdc::WFieldsReal< 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 377 of file WFieldsReal.tpp.

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

◆ clear()

template<int D, class RField, class FieldIo>

void Pscf::Prdc::WFieldsReal< D, RField, FieldIo >::clear ( )

inline

Clear data stored in this object without deallocating.

Definition at line 544 of file WFieldsReal.h.

◆ signal()

template<int D, class RFT, class FIT>

Signal< void > & Pscf::Prdc::WFieldsReal< D, RFT, FIT >::signal ( )

Get a signal that notifies observers of field modification.

Definition at line 456 of file WFieldsReal.tpp.

References UTIL_CHECK.

Referenced by symmetrize().

◆ writeBasis() [1/2]

template<int D, class RFT, class FIT>

void Pscf::Prdc::WFieldsReal< 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 394 of file WFieldsReal.tpp.

References fieldIo(), and UTIL_CHECK.

Referenced by writeBasis().

◆ writeBasis() [2/2]

template<int D, class RFT, class FIT>

void Pscf::Prdc::WFieldsReal< 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 411 of file WFieldsReal.tpp.

References fieldIo(), and writeBasis().

◆ writeRGrid() [1/2]

template<int D, class RFT, class FIT>

void Pscf::Prdc::WFieldsReal< 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 423 of file WFieldsReal.tpp.

References fieldIo(), and UTIL_CHECK.

Referenced by writeRGrid().

◆ writeRGrid() [2/2]

template<int D, class RFT, class FIT>

void Pscf::Prdc::WFieldsReal< 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 442 of file WFieldsReal.tpp.

References fieldIo(), and writeRGrid().

◆ basis() [1/2]

template<int D, class RFT, class FIT>

DArray< DArray< double > > const & Pscf::Prdc::WFieldsReal< 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 551 of file WFieldsReal.h.

References UTIL_ASSERT.

◆ basis() [2/2]

template<int D, class RFT, class FIT>

DArray< double > const & Pscf::Prdc::WFieldsReal< 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 560 of file WFieldsReal.h.

References UTIL_ASSERT.

◆ rgrid() [1/2]

template<int D, class RFT, class FIT>

DArray< RFT > const & Pscf::Prdc::WFieldsReal< 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 571 of file WFieldsReal.h.

References UTIL_ASSERT.

◆ rgrid() [2/2]

template<int D, class RFT, class FIT>

RFT const & Pscf::Prdc::WFieldsReal< 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 580 of file WFieldsReal.h.

References UTIL_ASSERT.

◆ isAllocatedRGrid()

template<int D, class RFT, class FIT>

bool Pscf::Prdc::WFieldsReal< D, RFT, FIT >::isAllocatedRGrid ( ) const

inline

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

Definition at line 589 of file WFieldsReal.h.

◆ isAllocatedBasis()

template<int D, class RFT, class FIT>

bool Pscf::Prdc::WFieldsReal< D, RFT, FIT >::isAllocatedBasis ( ) const

inline

Has memory been allocated for fields in basis format?

Definition at line 595 of file WFieldsReal.h.

◆ hasData()

template<int D, class RFT, class FIT>

bool Pscf::Prdc::WFieldsReal< 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 601 of file WFieldsReal.h.

◆ isSymmetric()

template<int D, class RFT, class FIT>

bool Pscf::Prdc::WFieldsReal< 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 607 of file WFieldsReal.h.

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

◆ meshDimensions()

template<int D, class RFT, class FIT>

IntVec< D > const & Pscf::Prdc::WFieldsReal< D, RFT, FIT >::meshDimensions ( ) const

inlineprotected

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

Definition at line 616 of file WFieldsReal.h.

Referenced by allocate(), and allocateRGrid().

◆ meshSize()

template<int D, class RFT, class FIT>

int Pscf::Prdc::WFieldsReal< D, RFT, FIT >::meshSize ( ) const

inlineprotected

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

Definition at line 622 of file WFieldsReal.h.

◆ nBasis()

template<int D, class RFT, class FIT>

int Pscf::Prdc::WFieldsReal< D, RFT, FIT >::nBasis ( ) const

inlineprotected

Get number of basis functions, set on basis allocation.

Definition at line 628 of file WFieldsReal.h.

Referenced by allocate(), and allocateBasis().

◆ nMonomer()

template<int D, class RFT, class FIT>

int Pscf::Prdc::WFieldsReal< D, RFT, FIT >::nMonomer ( ) const

inlineprotected

Get number of monomer types.

Definition at line 634 of file WFieldsReal.h.

Referenced by allocate(), and setNMonomer().

◆ fieldIo()

template<int D, class RFT, class FIT>

FIT const & Pscf::Prdc::WFieldsReal< D, RFT, FIT >::fieldIo ( ) const

inlineprotected

Get associated FIT object (const reference).

Definition at line 640 of file WFieldsReal.h.

References UTIL_CHECK.

Referenced by readBasis(), readBasis(), readRGrid(), readRGrid(), setBasis(), setFieldIo(), 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

◆ WFieldsReal()

◆ ~WFieldsReal()

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()