A field that specifies an inhomogeneous total monomer concentration. More...

#include <Mask.h>

Public Member Functions
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
	Mask ()
	Constructor.
	~Mask ()
	Destructor.
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).

Detailed Description

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

A field that specifies an inhomogeneous total monomer concentration.

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> 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 each of these two representations when the other is modified, as appropriate. A pointer to an associated FieldIo object (an instance of temnplate parameter FIT) is used for these conversions. The FieldIo class that is used as an argument for parameter FIT should be a subclass of Rp::FieldIo.

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.

Signal : A Mask owns an instance of class Util::Signal<void> that notifies all observers whenever the field owned by the Mask is modified. This Signal<void> object is returned by non-const reference by the Rp::Mask::signal() accessor function. The Util::Signal<void>::addObserver member function may used to add an observer object, and to specify a zero-parameter member function of each observer that will be called whenever the field is modified.

Template parameters :

D : dimension of space
RFT : real field type (Rpc::RField<D> or Rpg::RField<D>)
FIT : FieldIo type (Rpc::FieldIo<D> or Rpg::FieldIo<D>)

Subclasses : Specializations of the class template Mask <D, RFT, FIT> are used as base classes for the class templates Rpc::Mask <D > and Rpg::Mask <D> that are used by the pscf_rpc and pscf_rpg programs, respectively.

Definition at line 91 of file field/Mask.h.

Constructor & Destructor Documentation

◆ Mask()

template<int D, class RFT, class FIT>

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

protected

Constructor.

Definition at line 29 of file Mask.tpp.

◆ ~Mask()

template<int D, class RFT, class FIT>

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

protected

Destructor.

Definition at line 51 of file Mask.tpp.

Member Function Documentation

◆ setFieldIo()

template<int D, class RFT, class FIT>

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

Create association with FieldIo (store pointer).

Parameters

fieldIo associated FieldIo object

Definition at line 60 of file Mask.tpp.

References fieldIo().

◆ setReadUnitCell()

template<int D, class RFT, class FIT>

void Pscf::Rp::Mask< 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 67 of file Mask.tpp.

References UTIL_CHECK.

◆ setWriteUnitCell()

template<int D, class RFT, class FIT>

void Pscf::Rp::Mask< 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 78 of file Mask.tpp.

References UTIL_CHECK.

◆ allocateBasis()

template<int D, class RFT, class FIT>

void Pscf::Rp::Mask< 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 88 of file Mask.tpp.

References nBasis(), and UTIL_CHECK.

◆ allocateRGrid()

template<int D, class RFT, class FIT>

void Pscf::Rp::Mask< 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 105 of file Mask.tpp.

References meshDimensions(), and UTIL_CHECK.

◆ setBasis()

template<int D, class RFT, class FIT>

void Pscf::Rp::Mask< 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 126 of file Mask.tpp.

◆ setRGrid()

template<int D, class RFT, class FIT>

void Pscf::Rp::Mask< 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 162 of file Mask.tpp.

◆ readBasis() [1/2]

template<int D, class RFT, class FIT>

void Pscf::Rp::Mask< 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 200 of file Mask.tpp.

Referenced by readBasis().

◆ readBasis() [2/2]

template<int D, class RFT, class FIT>

void Pscf::Rp::Mask< 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 250 of file Mask.tpp.

References fieldIo(), and readBasis().

◆ readRGrid() [1/2]

template<int D, class RFT, class FIT>

void Pscf::Rp::Mask< 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 267 of file Mask.tpp.

References isSymmetric().

Referenced by readRGrid().

◆ readRGrid() [2/2]

template<int D, class RFT, class FIT>

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

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

◆ writeBasis() [1/2]

template<int D, class RFT, class FIT>

void Pscf::Rp::Mask< 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 340 of file Mask.tpp.

References fieldIo(), and UTIL_CHECK.

Referenced by writeBasis().

◆ writeBasis() [2/2]

template<int D, class RFT, class FIT>

void Pscf::Rp::Mask< 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 356 of file Mask.tpp.

References fieldIo(), and writeBasis().

◆ writeRGrid() [1/2]

template<int D, class RFT, class FIT>

void Pscf::Rp::Mask< 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 368 of file Mask.tpp.

Referenced by writeRGrid().

◆ writeRGrid() [2/2]

template<int D, class RFT, class FIT>

void Pscf::Rp::Mask< 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 385 of file Mask.tpp.

References fieldIo(), and writeRGrid().

◆ basis()

template<int D, class RFT, class FIT>

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

inline

Get the field in basis format.

Definition at line 480 of file field/Mask.h.

References UTIL_ASSERT.

Referenced by phiTot().

◆ rgrid()

template<int D, class RFT, class FIT>

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

inline

Get the field in r-grid format.

Definition at line 489 of file field/Mask.h.

References UTIL_ASSERT.

◆ phiTot()

template<int D, class RFT, class FIT>

double Pscf::Rp::Mask< 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 319 of file Mask.tpp.

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

◆ signal()

template<int D, class RFT, class FIT>

Signal< void > & Pscf::Rp::Mask< 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 399 of file Mask.tpp.

References UTIL_CHECK.

◆ isAllocatedBasis()

template<int D, class RFT, class FIT>

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

inline

Has memory been allocated in basis format?

Definition at line 497 of file field/Mask.h.

◆ isAllocatedRGrid()

template<int D, class RFT, class FIT>

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

inline

Has memory been allocated in rgrid format?

Definition at line 502 of file field/Mask.h.

◆ hasData()

template<int D, class RFT, class FIT>

bool Pscf::Rp::Mask< 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 field/Mask.h.

Referenced by phiTot().

◆ isSymmetric()

template<int D, class RFT, class FIT>

bool Pscf::Rp::Mask< 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 field/Mask.h.

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

◆ meshDimensions()

template<int D, class RFT, class FIT>

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

inlineprotected

Mesh dimensions in each direction, set by allocation.

Definition at line 378 of file field/Mask.h.

Referenced by allocateRGrid().

◆ meshSize()

template<int D, class RFT, class FIT>

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

inlineprotected

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

Definition at line 384 of file field/Mask.h.

◆ nBasis()

template<int D, class RFT, class FIT>

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

inlineprotected

Number of basis functions, set by allocation.

Definition at line 390 of file field/Mask.h.

Referenced by allocateBasis().

◆ fieldIo()

template<int D, class RFT, class FIT>

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

inlineprotected

Associated FieldIo object (const reference).

Definition at line 396 of file field/Mask.h.

References UTIL_CHECK.

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

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

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Mask()

◆ ~Mask()

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