File IO and other utilities for complex fields. More...

#include <FieldIo.h>

Public Member Functions
Construction, Initialization and Destruction
	FieldIo ()
	Constructor.
virtual	~FieldIo ()
	Destructor.
void	associate (Mesh< D > const &mesh, FFT const &fft, typename UnitCell< D >::LatticeSystem const &lattice)
	Create associations with other members of the parent Domain.
void	setFileMaster (FileMaster const &fileMaster)
	Create an association with a FileMaster.
void	setNMonomer (int nMonomer)
	Set the number of monomer types.
Field File IO - Real Space Grid Format
virtual void	readFields (std::istream &in, DArray< CFT > &fields, UnitCell< D > &unitCell) const =0
	Read array of complex fields from an input stream.
void	readFields (std::string filename, DArray< CFT > &fields, UnitCell< D > &unitCell) const
	Read an array of complex fields from a named file.
virtual void	readFieldsData (std::istream &in, DArray< CFT > &fields, int nMonomer) const =0
	Read data for array of r-grid fields, with no header section.
virtual void	readField (std::istream &in, CFT &field, UnitCell< D > &unitCell) const =0
	Read a single r-grid field from an input stream.
void	readField (std::string filename, CFT &field, UnitCell< D > &unitCell) const
	Read a single field from a named file.
virtual void	writeFields (std::ostream &out, DArray< CFT > const &fields, UnitCell< D > const &unitCell, bool writeHeader=true, bool writeMeshSize=true) const =0
	Write an array of complex fields to an output stream.
void	writeFields (std::string filename, DArray< CFT > const &fields, UnitCell< D > const &unitCell) const
	Write an array of complex fields to a named file.
virtual void	writeField (std::ostream &out, CFT const &field, UnitCell< D > const &unitCell, bool writeHeader=true) const =0
	Write a single complex field to an an output stream.
void	writeField (std::string filename, CFT const &field, UnitCell< D > const &unitCell) const
	Write a single complex field to a named file.
Fourier Transformations
void	convertRGridToKGrid (DArray< CFT > const &in, DArray< CFT > &out) const
	Fourier transform array of fields from r-grid to k-grid format.
void	convertRGridToKGrid (std::string const &inFileName, std::string const &outFileName) const
	Fourier transform a field file from r-grid to k-grid format.
void	convertKGridToRGrid (DArray< CFT > const &in, DArray< CFT > &out) const
	Fourier transform an array of fields from k-grid to r-grid format.
void	convertKGridToRGrid (std::string const &inFileName, std::string const &outFileName) const
	Transform a field file from Fourier (k-grid) to r-grid format.
Field File IO Utilities
void	readFieldHeader (std::istream &in, int &nMonomer, UnitCell< D > &unitCell) const
	Reader header of field file (fortran PSCF format)
void	writeFieldHeader (std::ostream &out, int nMonomer, UnitCell< D > const &unitCell) const
	Write header for field file (fortran pscf format).
Accessor functions (const references)
Mesh< D > const &	mesh () const
	Get spatial discretization mesh by const reference.
FileMaster const &	fileMaster () const
	Get associated FileMaster by const reference.

Protected Member Functions
UnitCell< D >::LatticeSystem const &	lattice () const
	Get the lattice type enum value by const reference.
FFT const &	fft () const
	Get FFT object by const reference.
void	checkAllocate () const
	Check if r-grid workspace is allocated, allocate if necessary.

Detailed Description

template<int D, class CFT, class FFT>
class Pscf::Cp::FieldIo< D, CFT, FFT >

File IO and other utilities for complex fields.

This class template provides functions to read and write complex fields, and other utilities for manipulating such fields and field files.

Template parameters:

D : integer dimension of space, i.e., 1, 2, or 3
CFT : complex field type, e.g., CField<D>
FFT : fast Fourier transform type, e.g., FFT<D>

Subclasses: The Cl:FieldIo template is a base class for two class templates named FieldIo that are defined in namespaces Pscf::Cpc and Pscf::Cpg. The Pscf::Cpc::FieldIo<int D> template is derived from a partial specialization of Cp::FieldIo with parameters CFT = Cpu::CField<D> and FFT = Cpu::FFT<D>, which both use standard CPU hardware. The analogous class template Cpg::FieldIo<int D> in the Pscf::Cpg namespace is derived from a partial specialization of Cp::FieldIo with CFT = Cuda::CField<D> and FFT = Cuda::FFT<D>, which use GPU hardware.

Pure virtual member functions : This class template declares several pure virtual functions. These are all functions for which slightly different implementations are required for Cpu and Cuda code, generally because the Cuda versions must explicitly transfer data between Cpu and Gpu memory.

Definition at line 62 of file cp/field/FieldIo.h.

Constructor & Destructor Documentation

◆ FieldIo()

template<int D, class CFT, class FFT>

Pscf::Cp::FieldIo< D, CFT, FFT >::FieldIo ( )

Constructor.

Definition at line 38 of file cp/field/FieldIo.tpp.

◆ ~FieldIo()

template<int D, class CFT, class FFT>

Pscf::Cp::FieldIo< D, CFT, FFT >::~FieldIo ( )

virtual

Destructor.

Definition at line 50 of file cp/field/FieldIo.tpp.

Member Function Documentation

◆ associate()

template<int D, class CFT, class FFT>

void Pscf::Cp::FieldIo< D, CFT, FFT >::associate	(	Mesh< D > const &	mesh,
		FFT const &	fft,
		typename UnitCell< D >::LatticeSystem const &	lattice )

Create associations with other members of the parent Domain.

This function may be called within the constructor of the Domain object, since addresses of other members of the Domain are known at this point.

Parameters

mesh	associated spatial discretization Mesh<D>
fft	associated FFT object for fast transforms
lattice	lattice system type (enumeration value)

Definition at line 60 of file cp/field/FieldIo.tpp.

References fft(), lattice(), and mesh().

◆ setFileMaster()

template<int D, class CFT, class FFT>

void Pscf::Cp::FieldIo< D, CFT, FFT >::setFileMaster ( FileMaster const & fileMaster )

Create an association with a FileMaster.

The FileMaster is used to open and close files in all member functions that take file name arguments and that open and close files. This allows prefixes for input and output files (if any) to be automatically prepended to file names.

Parameters

fileMaster associated FileMaster (for file paths)

Definition at line 74 of file cp/field/FieldIo.tpp.

References fileMaster().

◆ setNMonomer()

template<int D, class CFT, class FFT>

void Pscf::Cp::FieldIo< D, CFT, FFT >::setNMonomer ( int nMonomer )

Set the number of monomer types.

This is used to allocate private arrays of fields used by some functions that read field data into this workspace memory. This function may only be called once, shortly after the value of nMonomer is read from the parameter file.

Parameters

nMonomer number of monomer types

Definition at line 82 of file cp/field/FieldIo.tpp.

References UTIL_CHECK.

◆ readFields() [1/2]

template<int D, class CFT, class FFT>

virtual void Pscf::Cp::FieldIo< D, CFT, FFT >::readFields	(	std::istream &	in,
		DArray< CFT > &	fields,
		UnitCell< D > &	unitCell ) const

pure virtual

Read array of complex fields from an input stream.

Upon successful return, element fields[i] of the fields array is the instance of CFT containing the r-grid field associated with monomer type i.

On entry, array fields must either be unallocated or be allocated with capacity equal to the number of monomers in the field file, with mesh dimensions for each field equal to mesh().dimensions(). If it is unallocated, it will be allocated within this function.

Parameters

in	input stream (i.e., input file)
fields	array of r-grid fields
unitCell	associated crystallographic unit cell

Implemented in Pscf::Cpc::FieldIo< D >.

Referenced by convertKGridToRGrid(), convertRGridToKGrid(), and readFields().

◆ readFields() [2/2]

template<int D, class CFT, class FFT>

void Pscf::Cp::FieldIo< D, CFT, FFT >::readFields	(	std::string	filename,
		DArray< CFT > &	fields,
		UnitCell< D > &	unitCell ) const

Read an array of complex fields from a named file.

This function opens an input file with the specified filename, reads fields in real-space grid format from that file, and then closes the file. The overloaded readFieldsRGrid member function that takes a std::istream& argument is called to read the file.

Parameters

filename	name of input file
fields	array of r-grid fields (instances of CFT)
unitCell	associated crystallographic unit cell

Definition at line 95 of file cp/field/FieldIo.tpp.

References fileMaster(), and readFields().

◆ readFieldsData()

template<int D, class CFT, class FFT>

virtual void Pscf::Cp::FieldIo< D, CFT, FFT >::readFieldsData	(	std::istream &	in,
		DArray< CFT > &	fields,
		int	nMonomer ) const

pure virtual

Read data for array of r-grid fields, with no header section.

This function reads the data section of the rgrid-field format, without first reading a header.

On entry, array fields must either be unallocated or be allocated with capacity equal to the number of monomers in the field file, with mesh dimensions for each field equal to mesh().dimensions(). If it is unallocated, it will be allocated within this function.

Parameters

in	input file stream
fields	array of r-grid fields (instances of CFT)
nMonomer	expected number of monomer types (input

Implemented in Pscf::Cpc::FieldIo< D >.

◆ readField() [1/2]

template<int D, class CFT, class FFT>

virtual void Pscf::Cp::FieldIo< D, CFT, FFT >::readField	(	std::istream &	in,
		CFT &	field,
		UnitCell< D > &	unitCell ) const

pure virtual

Read a single r-grid field from an input stream.

On entry, the field must either be unallocated or be allocated with a mesh dimension equal to mesh().dimensions(). If it is unallocated, it will be allocated within this function.

Parameters

in	input stream (i.e., input file)
field	single r-grid field (instance of CFT)
unitCell	associated crystallographic unit cell

Implemented in Pscf::Cpc::FieldIo< D >.

Referenced by readField().

◆ readField() [2/2]

template<int D, class CFT, class FFT>

void Pscf::Cp::FieldIo< D, CFT, FFT >::readField	(	std::string	filename,
		CFT &	field,
		UnitCell< D > &	unitCell ) const

Read a single field from a named file.

This function opens an input file with the specified filename, reads a complex field from that file, and then closes the file. The overloaded readField member function that takes a std::istream& argument is called internally to read the file.

Parameters

filename	name of input file
field	single field defined on r-space grid
unitCell	associated crystallographic unit cell

Definition at line 110 of file cp/field/FieldIo.tpp.

References fileMaster(), and readField().

◆ writeFields() [1/2]

template<int D, class CFT, class FFT>

virtual void Pscf::Cp::FieldIo< D, CFT, FFT >::writeFields	(	std::ostream &	out,
		DArray< CFT > const &	fields,
		UnitCell< D > const &	unitCell,
		bool	writeHeader = true,
		bool	writeMeshSize = true ) const

pure virtual

Write an array of complex fields to an output stream.

On entry, the container fields must be allocated, and the mesh dimensions of each field must equal mesh().dimensions(). The writeHeader argument may be set false to completely suppress writing of the file header.

Parameters

out	output stream (i.e., output file)
fields	array of RField objects (fields on r-space grid)
unitCell	associated crystallographic unit cell
writeHeader	iff true, write file header
writeMeshSize	iff true, write mesh dimensions after header

Implemented in Pscf::Cpc::FieldIo< D >.

Referenced by convertKGridToRGrid(), convertRGridToKGrid(), and writeFields().

◆ writeFields() [2/2]

template<int D, class CFT, class FFT>

void Pscf::Cp::FieldIo< D, CFT, FFT >::writeFields	(	std::string	filename,
		DArray< CFT > const &	fields,
		UnitCell< D > const &	unitCell ) const

Write an array of complex fields to a named file.

This function opens a file, writes field file header and data to the file, and closes the file. The overloaded writeFieldsGrid member function that takes a std::ostream& argument is called internally with writeHeader == true to write the data.

Parameters

filename	name of output file
fields	array of CFT objects (fields on a grid)
unitCell	associated crystallographic unit cell

Definition at line 125 of file cp/field/FieldIo.tpp.

References fileMaster(), and writeFields().

◆ writeField() [1/2]

template<int D, class CFT, class FFT>

virtual void Pscf::Cp::FieldIo< D, CFT, FFT >::writeField	(	std::ostream &	out,
		CFT const &	field,
		UnitCell< D > const &	unitCell,
		bool	writeHeader = true ) const

pure virtual

Write a single complex field to an an output stream.

On entry, the field container must be allocated with mesh dimensions equal to mesh().dimensions(). The writeHeader argument may be set false to suppress writing of the file header.

Parameters

out	output stream
field	field defined on r-space grid
unitCell	associated crystallographic unit cell
writeHeader	should a file header be written?

Implemented in Pscf::Cpc::FieldIo< D >.

Referenced by writeField().

◆ writeField() [2/2]

template<int D, class CFT, class FFT>

void Pscf::Cp::FieldIo< D, CFT, FFT >::writeField	(	std::string	filename,
		CFT const &	field,
		UnitCell< D > const &	unitCell ) const

Write a single complex field to a named file.

This function opens a file, writes the header and data for a single field to the file, and closes that file. The overloaded writeFieldGrid member function that takes a std::ostream& argument is called internally with writeHeader == true to write the file.

Parameters

filename	name of output file
field	field defined on r-space grid
unitCell	associated crystallographic unit cell

Definition at line 143 of file cp/field/FieldIo.tpp.

References fileMaster(), and writeField().

◆ convertRGridToKGrid() [1/2]

template<int D, class CFT, class FFT>

void Pscf::Cp::FieldIo< D, CFT, FFT >::convertRGridToKGrid	(	DArray< CFT > const &	in,
		DArray< CFT > &	out ) const

Fourier transform array of fields from r-grid to k-grid format.

This function simply calls the forward FFT repeatedly for an array of fields. The in and out arrays must contain equal numbers of fields defined with equal mesh dimensions.

Parameters

in	fields defined on real-space grid (r-grid)
out	fields in discrete Fourier format (k-grid)

Definition at line 160 of file cp/field/FieldIo.tpp.

References Util::Array< Data >::capacity(), fft(), and UTIL_CHECK.

Referenced by convertRGridToKGrid().

◆ convertRGridToKGrid() [2/2]

template<int D, class CFT, class FFT>

void Pscf::Cp::FieldIo< D, CFT, FFT >::convertRGridToKGrid	(	std::string const &	inFileName,
		std::string const &	outFileName ) const

Fourier transform a field file from r-grid to k-grid format.

The number of monomers in the input file must equal the number set by the setNMonomer(int) member function.

Parameters

inFileName	name of input file (r-grid format)
outFileName	name of output file (k-grid format)

Definition at line 176 of file cp/field/FieldIo.tpp.

References Pscf::Prdc::allocateFields(), checkAllocate(), convertRGridToKGrid(), mesh(), readFields(), and writeFields().

◆ convertKGridToRGrid() [1/2]

template<int D, class CFT, class FFT>

void Pscf::Cp::FieldIo< D, CFT, FFT >::convertKGridToRGrid	(	DArray< CFT > const &	in,
		DArray< CFT > &	out ) const

Fourier transform an array of fields from k-grid to r-grid format.

This function simply calls the inverse FFT repeatedly for an array of fields. The in and out arrays must contain equal numbers of fields defined with equal mesh dimensions.

Parameters

in	fields in discrete Fourier format (k-grid)
out	fields defined on real-space grid (r-grid)

Definition at line 193 of file cp/field/FieldIo.tpp.

References Util::Array< Data >::capacity(), fft(), and UTIL_CHECK.

Referenced by convertKGridToRGrid().

◆ convertKGridToRGrid() [2/2]

template<int D, class CFT, class FFT>

void Pscf::Cp::FieldIo< D, CFT, FFT >::convertKGridToRGrid	(	std::string const &	inFileName,
		std::string const &	outFileName ) const

Transform a field file from Fourier (k-grid) to r-grid format.

The number of monomers in the input file must equal the number set by the setNMonomer(int) member function.

Parameters

inFileName	name of input file (k-grid format)
outFileName	name of output file (r-grid format)

Definition at line 209 of file cp/field/FieldIo.tpp.

References Pscf::Prdc::allocateFields(), checkAllocate(), convertKGridToRGrid(), mesh(), readFields(), and writeFields().

◆ readFieldHeader()

template<int D, class CFT, class FFT>

void Pscf::Cp::FieldIo< D, CFT, FFT >::readFieldHeader	(	std::istream &	in,
		int &	nMonomer,
		UnitCell< D > &	unitCell ) const

Reader header of field file (fortran PSCF format)

This reads the common part of the header for all PSCF field file formats. This contains the dimension of space, the lattice system, a list of unit cell parameters, the space group name as an optional parameter, and the number of monomer types. The unit cell data is used to update a UnitCell<D> that is passed as a parameter by non-const reference.

On return, parameter nMonomer contains the number of monomer types declared in the field file header. This function does not require the number of monomers declared in the field file header to match the value of nMonomer set by the setNMonomer member function.

Consistency checks (Exceptions thrown on failure):

The value of "dim" in the header file must match the template parameter D. If the UnitCell<D> object passed to this function already contains a non-null lattice type, it must match the lattice system in the header file.

Parameters

in	input stream (i.e., file)
nMonomer	number of monomer types in the header (out)
unitCell	associated crystallographic unit cell (out)

Definition at line 250 of file cp/field/FieldIo.tpp.

References Util::Log::file(), Pscf::Prdc::UnitCellBase< D >::isInitialized(), lattice(), Pscf::Prdc::UnitCellBase< D >::nParameter(), Pscf::Prdc::readFieldHeader(), UTIL_CHECK, and UTIL_THROW.

◆ writeFieldHeader()

template<int D, class CFT, class FFT>

void Pscf::Cp::FieldIo< D, CFT, FFT >::writeFieldHeader	(	std::ostream &	out,
		int	nMonomer,
		UnitCell< D > const &	unitCell ) const

Write header for field file (fortran pscf format).

Parameters

out	output stream (i.e., file)
nMonomer	number of monomer types or fields
unitCell	associated crystallographic unit cell

Definition at line 296 of file cp/field/FieldIo.tpp.

References Pscf::Prdc::writeFieldHeader().

◆ mesh()

template<int D, class CFT, class FFT>

Mesh< D > const & Pscf::Cp::FieldIo< D, CFT, FFT >::mesh ( ) const

inline

Get spatial discretization mesh by const reference.

Definition at line 421 of file cp/field/FieldIo.h.

Referenced by associate(), checkAllocate(), convertKGridToRGrid(), and convertRGridToKGrid().

◆ fileMaster()

template<int D, class CFT, class FFT>

FileMaster const & Pscf::Cp::FieldIo< D, CFT, FFT >::fileMaster ( ) const

inline

Get associated FileMaster by const reference.

Definition at line 430 of file cp/field/FieldIo.h.

Referenced by readField(), readFields(), setFileMaster(), writeField(), and writeFields().

◆ lattice()

template<int D, class CFT, class FFT>

UnitCell< D >::LatticeSystem const & Pscf::Cp::FieldIo< D, CFT, FFT >::lattice ( ) const

inlineprotected

Get the lattice type enum value by const reference.

Definition at line 443 of file cp/field/FieldIo.h.

Referenced by associate(), and readFieldHeader().

◆ fft()

template<int D, class CFT, class FFT>

FFT const & Pscf::Cp::FieldIo< D, CFT, FFT >::fft ( ) const

inlineprotected

Get FFT object by const reference.

Definition at line 452 of file cp/field/FieldIo.h.

Referenced by associate(), convertKGridToRGrid(), and convertRGridToKGrid().

◆ checkAllocate()

template<int D, class CFT, class FFT>

void Pscf::Cp::FieldIo< D, CFT, FFT >::checkAllocate ( ) const

protected

Check if r-grid workspace is allocated, allocate if necessary.

Definition at line 315 of file cp/field/FieldIo.tpp.

References mesh(), and UTIL_CHECK.

Referenced by convertKGridToRGrid(), and convertRGridToKGrid().

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

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ FieldIo()

◆ ~FieldIo()

Member Function Documentation

◆ associate()

◆ setFileMaster()

◆ setNMonomer()

◆ readFields() [1/2]

◆ readFields() [2/2]

◆ readFieldsData()

◆ readField() [1/2]

◆ readField() [2/2]

◆ writeFields() [1/2]

◆ writeFields() [2/2]

◆ writeField() [1/2]

◆ writeField() [2/2]

◆ convertRGridToKGrid() [1/2]

◆ convertRGridToKGrid() [2/2]

◆ convertKGridToRGrid() [1/2]

◆ convertKGridToRGrid() [2/2]

◆ readFieldHeader()

◆ writeFieldHeader()

◆ mesh()

◆ fileMaster()

◆ lattice()

◆ fft()

◆ checkAllocate()