Container for a field to which the total density is constrained. More...

#include <MaskReal.h>

Public Member Functions
	MaskReal ()
	Constructor.
	~MaskReal ()
	Destructor.
Initialization and Memory Management
void	setFieldIo (FIT const &fieldIo)
	Create association with FieldIo (store pointer).
void	setReadUnitCell (UnitCell< D > &cell)
	Set unit cell used when reading a mask field file.
void	setWriteUnitCell (UnitCell< D > const &cell)
	Set unit cell used when writing a mask field file.
void	allocateBasis (int nBasis)
	Allocate memory for the field in basis format.
void	allocateRGrid (IntVec< D > const &dimensions)
	Allocate memory for the field in rgrid format.
Field Mutators
void	setBasis (DArray< double > const &field)
	Set field component values, in symmetrized Fourier format.
void	setRGrid (RFT const &field, bool isSymmetric=false)
	Set field values in real-space (r-grid) format.
void	readBasis (std::istream &in)
	Read field from input stream in symmetrized basis format.
void	readBasis (std::string filename)
	Read field from a named file, in symmetrized basis format.
void	readRGrid (std::istream &in, bool isSymmetric=false)
	Reads field from an input stream in real-space (r-grid) format.
void	readRGrid (std::string filename, bool isSymmetric=false)
	Reads field from a named file, in real-space (r-grid) format.
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
DArray< double > const &	basis () const
	Get the field in basis format.
RFT const &	rgrid () const
	Get the field in r-grid format.
double	phiTot () const
	Return the volume fraction of unit cell occupied by material.
Signal< void > &	signal ()
	Get a signal that notifies observers of field modification.
Boolean Queries
bool	isAllocatedBasis () const
	Has memory been allocated in basis format?
bool	isAllocatedRGrid () const
	Has memory been allocated in rgrid format?
bool	hasData () const
	Has field data been set in either format?
bool	isSymmetric () const
	Are field symmetric under all elements of the space group?

Protected Member Functions
IntVec< D > const &	meshDimensions () const
	Mesh dimensions in each direction, set by allocation.
int	meshSize () const
	Mesh size (number of grid points), set by allocation.
int	nBasis () const
	Number of basis functions, set by allocation.
FIT const &	fieldIo () const
	Associated FieldIo object (const reference).
virtual double	rGridAverage () const =0
	Calculate the average value of the rgrid_ member.

Detailed Description

template<int D, class RFT, class FIT>
class Pscf::Prdc::MaskReal< D, RFT, FIT >

Container for a field to which the total density is constrained.

A system that contains a Mask must satisfy a modified version of the incompressibility constraint, in which the sum of the concentration (or volume fraction) fields of all monomer types must be equal to the Mask field. The Mask field takes values in the range [0, 1] everywhere. A system without a Mask is equivalent to one in which the mask field is equal to 1 at all points in the unit cell.

Field representations : A Mask <D> contains representations of the mask field in two formats:

An RFT object (where RFT is a template type parameter) contains values of the field on the nodes of a regular mesh. This is accessed by the rgrid() member function.
A DArray <double> that contains components of the field in a symmetry-adapted Fourier expansion (i.e., in basis format). This is accessed by the basis() member function.

A Mask is designed to automatically update one of these representations when the other is modified, when appropriate. A pointer to an associated FIT (another template parameter) is used for these conversions. The FieldIo class that is used to instantiate this template should be a subclass of Prdc::FieldIoReal.

The setBasis and readBasis functions allow the user to input field components in basis format, and both internally recompute the values in r-grid format. The setRGrid and readRGrid functions allows the user to input the field in r-grid format, and both recompute the components in basis format if and only if the user explicitly declares that the field is known to be invariant under all symmetries of the space group. A boolean member variable named isSymmetric is used to keep track of whether the current mask field is symmetric, and thus whether the symmetry-adapted basis representation exists.

Subclasses : Partial specializations of the template MaskReal <D, RFT, FIT> are used as base classes for the class templates Rpc::Mask <D > and Rpg::Mask <D> that are used by pscf_pc and pscf_pg, respectively.

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

Definition at line 83 of file MaskReal.h.

Constructor & Destructor Documentation

◆ MaskReal()

template<int D, class RFT, class FIT>

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

Constructor.

Definition at line 28 of file MaskReal.tpp.

◆ ~MaskReal()

template<int D, class RFT, class FIT>

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

Destructor.

Definition at line 50 of file MaskReal.tpp.

Member Function Documentation

◆ setFieldIo()

template<int D, class RFT, class FIT>

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

Create association with FieldIo (store pointer).

Parameters

fieldIo associated FieldIo object

Definition at line 59 of file MaskReal.tpp.

References fieldIo().

◆ setReadUnitCell()

template<int D, class RFT, class FIT>

void Pscf::Prdc::MaskReal< D, RFT, FIT >::setReadUnitCell ( UnitCell< D > & cell )

Set unit cell used when reading a mask field file.

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 66 of file MaskReal.tpp.

References UTIL_CHECK.

◆ setWriteUnitCell()

template<int D, class RFT, class FIT>

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

Set unit cell used when writing a mask field file.

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 77 of file MaskReal.tpp.

References UTIL_CHECK.

◆ allocateBasis()

template<int D, class RFT, class FIT>

void Pscf::Prdc::MaskReal< D, RFT, FIT >::allocateBasis ( int nBasis )

Allocate memory for the field in basis format.

An Exception will be thrown if this is called more than once.

Parameters

nBasis number of basis functions

Definition at line 87 of file MaskReal.tpp.

References nBasis(), and UTIL_CHECK.

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

◆ allocateRGrid()

template<int D, class RFT, class FIT>

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

Allocate memory for the field in rgrid format.

An Exception will be thrown if this is called more than once.

Parameters

dimensions dimensions of spatial mesh

Definition at line 104 of file MaskReal.tpp.

References meshDimensions(), and UTIL_CHECK.

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

◆ setBasis()

template<int D, class RFT, class FIT>

void Pscf::Prdc::MaskReal< D, RFT, FIT >::setBasis ( DArray< double > const & field )

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

field components of field in basis format

Definition at line 125 of file MaskReal.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::Prdc::MaskReal< D, RFT, FIT >::setRGrid	(	RFT const &	field,
		bool	isSymmetric = false )

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

If the isSymmetric parameter is true, this function assumes that the field 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, then a basis must be initialized prior to entry.

Parameters

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

Definition at line 161 of file MaskReal.tpp.

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

◆ readBasis() [1/2]

template<int D, class RFT, class FIT>

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

Read field from 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.

This object must already be allocated and associated with a a FieldIo object to run this function.

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

Parameters

in	input stream from which to read field

Definition at line 199 of file MaskReal.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::Prdc::MaskReal< D, RFT, FIT >::readBasis ( std::string filename )

Read field 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 functions, if not allocated on entry. An associated basis will be initialized if it is not initialized on entry.

Parameters

filename file from which to read field

Definition at line 249 of file MaskReal.tpp.

References fieldIo(), and readBasis().

◆ readRGrid() [1/2]

template<int D, class RFT, class FIT>

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

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

If the isSymmetric parameter is true, this function assumes that the field is known to be symmetric and so computes and stores the corresponding basis format. 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 functions, if not allocated on entry. An associated basis will be initialized if it is not initialized on entry.

Parameters

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

Definition at line 266 of file MaskReal.tpp.

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

Referenced by readRGrid().

◆ readRGrid() [2/2]

template<int D, class RFT, class FIT>

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

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

If the isSymmetric parameter is true, this function assumes that the field is known to be symmetric and so computes and stores the corresponding basis format. 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 functions, if not allocated on entry. An associated basis will be initialized if it is not initialized on entry.

Parameters

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

Definition at line 304 of file MaskReal.tpp.

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

◆ writeBasis() [1/2]

template<int D, class RFT, class FIT>

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

References fieldIo(), and UTIL_CHECK.

Referenced by writeBasis().

◆ writeBasis() [2/2]

template<int D, class RFT, class FIT>

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

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

Parameters

filename name of file to which to write fields

Definition at line 353 of file MaskReal.tpp.

References fieldIo(), and writeBasis().

◆ writeRGrid() [1/2]

template<int D, class RFT, class FIT>

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

References fieldIo(), and UTIL_CHECK.

Referenced by writeRGrid().

◆ writeRGrid() [2/2]

template<int D, class RFT, class FIT>

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

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

Parameters

filename name of file to which to write fields

Definition at line 382 of file MaskReal.tpp.

References fieldIo(), and writeRGrid().

◆ basis()

template<int D, class RFT, class FIT>

DArray< double > const & Pscf::Prdc::MaskReal< D, RFT, FIT >::basis ( ) const

inline

Get the field in basis format.

Definition at line 480 of file MaskReal.h.

References UTIL_ASSERT.

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

◆ rgrid()

template<int D, class RFT, class FIT>

RFT const & Pscf::Prdc::MaskReal< D, RFT, FIT >::rgrid ( ) const

inline

Get the field in r-grid format.

Definition at line 489 of file MaskReal.h.

References UTIL_ASSERT.

◆ phiTot()

template<int D, class RFT, class FIT>

double Pscf::Prdc::MaskReal< D, RFT, FIT >::phiTot ( ) const

Return the volume fraction of unit cell occupied by material.

This value is equivalent to the spatial average of the mask, which is the q=0 coefficient of the discrete Fourier transform.

If hasData == true and isSymmetric == false (i.e., data only exists in rgrid format), then this object must be associated with a FieldIo object in order to call phiTot(). In other cases, the FieldIo association is not necessary.

Definition at line 318 of file MaskReal.tpp.

References basis(), hasData(), isSymmetric(), and rGridAverage().

◆ signal()

template<int D, class RFT, class FIT>

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

Get a signal that notifies observers of field modification.

The Signal<void>::notify method is called by within all member functions that modify the field, to notify observers of this event. The Signal<void>::addObserver function may be applied to the Signal object returned by this function to add one or more observers.

Definition at line 396 of file MaskReal.tpp.

References UTIL_CHECK.

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

◆ isAllocatedBasis()

template<int D, class RFT, class FIT>

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

inline

Has memory been allocated in basis format?

Definition at line 497 of file MaskReal.h.

◆ isAllocatedRGrid()

template<int D, class RFT, class FIT>

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

inline

Has memory been allocated in rgrid format?

Definition at line 502 of file MaskReal.h.

◆ hasData()

template<int D, class RFT, class FIT>

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

Referenced by phiTot().

◆ isSymmetric()

template<int D, class RFT, class FIT>

bool Pscf::Prdc::MaskReal< D, RFT, FIT >::isSymmetric ( ) const

inline

Are field symmetric under all elements of the space group?

A valid basis format exists if and only if isSymmetric is true. This flat is set true if the field were input in basis format by the function setBasis, or if they were set in grid format by the function setRGrid but isSymmetric was set true.

Definition at line 512 of file MaskReal.h.

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

◆ meshDimensions()

template<int D, class RFT, class FIT>

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

inlineprotected

Mesh dimensions in each direction, set by allocation.

Definition at line 370 of file MaskReal.h.

Referenced by allocateRGrid().

◆ meshSize()

template<int D, class RFT, class FIT>

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

inlineprotected

Mesh size (number of grid points), set by allocation.

Definition at line 376 of file MaskReal.h.

◆ nBasis()

template<int D, class RFT, class FIT>

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

inlineprotected

Number of basis functions, set by allocation.

Definition at line 382 of file MaskReal.h.

Referenced by allocateBasis().

◆ fieldIo()

template<int D, class RFT, class FIT>

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

inlineprotected

Associated FieldIo object (const reference).

Definition at line 388 of file MaskReal.h.

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

◆ rGridAverage()

template<int D, class RFT, class FIT>

virtual double Pscf::Prdc::MaskReal< D, RFT, FIT >::rGridAverage ( ) const

protectedpure virtual

Calculate the average value of the rgrid_ member.

Must be implemented by subclasses, because this calculation depends on the specific implementation of the RFT type.

Implemented in Pscf::Rpc::Mask< D >, and Pscf::Rpg::Mask< D >.

Referenced by phiTot().

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

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ MaskReal()

◆ ~MaskReal()

Member Function Documentation

◆ setFieldIo()

◆ setReadUnitCell()

◆ setWriteUnitCell()

◆ allocateBasis()

◆ allocateRGrid()

◆ setBasis()

◆ setRGrid()

◆ readBasis() [1/2]

◆ readBasis() [2/2]

◆ readRGrid() [1/2]

◆ readRGrid() [2/2]

◆ writeBasis() [1/2]

◆ writeBasis() [2/2]

◆ writeRGrid() [1/2]

◆ writeRGrid() [2/2]

◆ basis()

◆ rgrid()

◆ phiTot()

◆ signal()

◆ isAllocatedBasis()

◆ isAllocatedRGrid()

◆ hasData()

◆ isSymmetric()

◆ meshDimensions()

◆ meshSize()

◆ nBasis()

◆ fieldIo()

◆ rGridAverage()