A single variable in a parameter file. More...

#include <Parameter.h>

Inheritance diagram for Util::Parameter:

Public Member Functions
	Parameter (const char *label, bool isRequired=true)
	Constructor. More...

virtual	~Parameter ()
	Destructor. More...

virtual void	readParam (std::istream &in)
	Read a label and (if the label matches) a parameter value. More...

virtual void	load (Serializable::IArchive &ar)
	Load from an archive. More...

virtual void	save (Serializable::OArchive &ar)
	Save to an archive. More...

std::string	label () const
	Return label string. More...

bool	isRequired () const
	Is this an optional parameter? More...

bool	isActive () const
	Is this parameter active? More...

Public Member Functions inherited from Util::ParamComponent
virtual	~ParamComponent ()
	Destructor. More...

virtual void	readParam (std::istream &in)=0
	Read parameter(s) from file. More...

virtual void	writeParam (std::ostream &out) const =0
	Read parameter(s) to file. More...

virtual void	load (Serializable::IArchive &ar)
	Load internal state from an archive. More...

virtual void	save (Serializable::OArchive &ar)
	Save internal state to an archive. More...

virtual void	resetParam ()
	Nontrivial implementation provided by ParamComposite subclass. More...

void	setIndent (const ParamComponent &parent, bool next=true)
	Set indent level. More...

std::string	indent () const
	Return indent string for this object (string of spaces). More...

template<class Archive >
void	serialize (Archive &ar, const unsigned int version)
	Serialize this ParamComponent as a string. More...

Public Member Functions inherited from Util::Serializable
virtual	~Serializable ()
	Destructor. More...

virtual void	save (OArchive &ar)=0
	Save to an archive. More...

virtual void	load (IArchive &ar)=0
	Load from an archive. More...

Public Member Functions inherited from Util::MpiFileIo
	MpiFileIo ()
	Constructor. More...

	MpiFileIo (const MpiFileIo &other)
	Copy constructor. More...

bool	isIoProcessor () const
	Can this processor do file I/O ? More...

void	setIoCommunicator (MPI::Intracomm &communicator)
	Set the communicator. More...

void	clearCommunicator ()
	Clear (nullify) the communicator. More...

bool	hasIoCommunicator () const
	Does this object have an associated MPI communicator? More...

MPI::Intracomm &	ioCommunicator () const
	Get the MPI communicator by reference. More...

Static Public Member Functions
template<class Type >
static void	saveOptional (Serializable::OArchive &ar, Type &value, bool isActive)
	Save an optional parameter value to an output archive. More...

template<class Type >
static void	saveOptionalCArray (Serializable::OArchive &ar, Type *ptr, int n, bool isActive)
	Save an optional C-array of n values to an output archive. More...

template<class Type >
static void	saveOptionalCArray2D (Serializable::OArchive &ar, Type *ptr, int m, int n, int np, bool isActive)
	Save an optional two-dimensional C array to an output archive. More...

Static Public Member Functions inherited from Util::ParamComponent
static void	initStatic ()
	Initialize static echo member to false. More...

static void	setEcho (bool echo=true)
	Enable or disable echoing for all subclasses of ParamComponent. More...

static bool	echo ()
	Get echo parameter. More...

Static Public Attributes
static const int	Width = 20
	Width of output field for a scalar variable. More...

static const int	Precision = 12
	Precision for io of floating point data field. More...

Protected Member Functions
virtual void	readLabel (std::istream &in)
	Read and attempt to match label string. More...

virtual void	readValue (std::istream &in)
	Read parameter value from an input stream. More...

virtual void	loadValue (Serializable::IArchive &ar)
	Load bare parameter value from an archive. More...

virtual void	saveValue (Serializable::OArchive &ar)
	Save parameter value to an archive. More...

virtual void	bcastValue ()
	Broadcast parameter value within the ioCommunicator. More...

Protected Member Functions inherited from Util::ParamComponent
	ParamComponent ()
	Constructor. More...

	ParamComponent (const ParamComponent &other)
	Copy constructor. More...

Protected Attributes
Label	label_
	Label object that contains parameter label string. More...

bool	isActive_
	Is this parameter active (always true if isRequired). More...

Additional Inherited Members
Public Types inherited from Util::Serializable
typedef BinaryFileOArchive	OArchive
	Type of output archive used by save method. More...

typedef BinaryFileIArchive	IArchive
	Type of input archive used by load method. More...

Detailed Description

A single variable in a parameter file.

Parameter is a base class for objects that read and write the value of a single C++ variable from or to a parameter file. The parameter file format for a parameter contains a string label followed by a value for the variable. Different subclasses of parameter are specialized for different variable types, which can include primitive C/C++ variables, user defined types that overload the << and >> operators, or any of several different types of container.

A Parameter may be required or optional element in a parameter file, depending on the value of the bool isRequired parameter of the constructor. An optional element becomes "active" when an entry with the correct label is read from a parameter file, or when an active value is loaded from an archive. By convention, a required Parameter is always active, even before its value is read or loaded. The bool functions isRequired() and isActive() can be used to query the state of a Parameter.

The overloaded saveOptional() static member functions can be used to save optional parameters to an archive in a form that records whether or not they are active.

Definition at line 45 of file Parameter.h.

Constructor & Destructor Documentation

◆ Parameter()

Util::Parameter::Parameter	(	const char *	label,
		bool	isRequired = `true`
	)

Constructor.

Parameters

label	label string preceding value in file format
isRequired	Is this a required parameter?

Definition at line 22 of file Parameter.cpp.

◆ ~Parameter()

Util::Parameter::~Parameter ( )

virtual

Destructor.

Definition at line 30 of file Parameter.cpp.

Member Function Documentation

◆ saveOptional()

template<class Type >

void Util::Parameter::saveOptional	(	Serializable::OArchive &	ar,
		Type &	value,
		bool	isActive
	)

static

Save an optional parameter value to an output archive.

Parameters

ar	output archive to which to save
value	reference to value of optional parameter
isActive	Is this parameter present in the parameter file?

Definition at line 231 of file Parameter.h.

References isActive().

◆ saveOptionalCArray()

template<class Type >

void Util::Parameter::saveOptionalCArray	(	Serializable::OArchive &	ar,
		Type *	ptr,
		int	n,
		bool	isActive
	)

static

Save an optional C-array of n values to an output archive.

Parameters

ar	output archive to which to save
ptr	pointer to first element of optional C-array parameter
n	number of elements in array
isActive	Is this parameter present in the parameter file?

Definition at line 244 of file Parameter.h.

References isActive(), and Util::BinaryFileOArchive::pack().

◆ saveOptionalCArray2D()

template<class Type >

void Util::Parameter::saveOptionalCArray2D	(	Serializable::OArchive &	ar,
		Type *	ptr,
		int	m,
		int	n,
		int	np,
		bool	isActive
	)

static

Save an optional two-dimensional C array to an output archive.

Parameters

ar	output archive to which to save
ptr	pointer to first element optional 2D C-array parameter
m	logical number of rows in array
n	logical number of columns in array
np	logical number of columns in array
isActive	Is this parameter present in the parameter file?

Definition at line 257 of file Parameter.h.

References isActive(), and Util::BinaryFileOArchive::pack().

◆ readParam()

void Util::Parameter::readParam ( std::istream & in )

virtual

Read a label and (if the label matches) a parameter value.

The parameter file format for a Parameter consists of a label string followed by value. The value is read if and only if the label matches the expected value for this Parameter. If this Parameter is required and the input label not match, an error message is printed to the log file and Exception is thrown. If the Parameter is not required and the input label does not match, the label string is retained in an buffer for later processing by the readParam method of other ParamComponent objects.

Upon entry to this function, a label string is read into a label buffer if and only if the buffer is empty. This buffer is a static member of the Label class, which can retain a label between invocations of the readParameter method of different ParamComponent objects. Once a label string is read from file, it remains in the label buffer until until it is matched, at which point the buffer is cleared to allow processing of the next label.

Parameters

in	input stream from which to read

Implements Util::ParamComponent.

Definition at line 42 of file Parameter.cpp.

References Util::bcast< bool >(), bcastValue(), Util::ParamComponent::echo(), Util::Log::file(), Util::MpiFileIo::hasIoCommunicator(), Util::ParamComponent::indent(), Util::MpiFileIo::ioCommunicator(), isActive_, Util::MpiFileIo::isIoProcessor(), Util::Label::isMatched(), isRequired(), label_, readLabel(), readValue(), UTIL_THROW, Width, and Util::ParamComponent::writeParam().

◆ load()

void Util::Parameter::load ( Serializable::IArchive & ar )

virtual

Load from an archive.

An optional Parameter loads the value of an isActive flag, and then loads the parameter value only if the isActive is true. A required Parameter simply loads the parameter value. The variable associated with an optional Parameter must be set to its default value before attempting to load the parameter. Optional parameters should be saved either using the save() method of an associated Parameter object or using the appropriate overloaded Parameter::saveOptional() static member function, which both use the required format.

Parameters

ar	input archive from which to load

Reimplemented from Util::ParamComponent.

Reimplemented in Util::ArrayParam< Type >, and Util::MatrixParam< Type >.

Definition at line 104 of file Parameter.cpp.

References Util::bcast< bool >(), bcastValue(), Util::ParamComponent::echo(), Util::Log::file(), Util::MpiFileIo::hasIoCommunicator(), Util::ParamComponent::indent(), Util::MpiFileIo::ioCommunicator(), isActive_, Util::MpiFileIo::isIoProcessor(), isRequired(), label_, loadValue(), UTIL_THROW, Width, and Util::ParamComponent::writeParam().

Referenced by Util::ParamComposite::loadParameter().

◆ save()

void Util::Parameter::save ( Serializable::OArchive & ar )

virtual

Save to an archive.

An optional Parameter saves the value of the isActive flag, and then saves a parameter value only if the isActive is true. A required Parameter simply saves its value. The label string is not saved to the archive.

The overloaded static saveOptional functions can also be used to save optional parameter values in this format.

Parameters

ar	output archive to which to save

Reimplemented from Util::ParamComponent.

Reimplemented in Util::ArrayParam< Type >, and Util::MatrixParam< Type >.

Definition at line 151 of file Parameter.cpp.

References isActive_, isRequired(), and saveValue().

◆ label()

std::string Util::Parameter::label ( ) const

Return label string.

Definition at line 164 of file Parameter.cpp.

Referenced by pscfpp.param.Composite::__init__(), pscfpp.param.Matrix::__init__(), pscfpp.param.Array::__init__(), pscfpp.param.Parameter::__init__(), pscfpp.command.Command::__init__(), pscfpp.param.Composite::getString(), pscfpp.param.Array::getString(), and pscfpp.param.Matrix::getString().

◆ isRequired()

bool Util::Parameter::isRequired ( ) const

Is this an optional parameter?

Definition at line 170 of file Parameter.cpp.

References Util::Label::isRequired(), and label_.

Referenced by load(), readParam(), and save().

◆ isActive()

bool Util::Parameter::isActive ( ) const

Is this parameter active?

Definition at line 176 of file Parameter.cpp.

References isActive_.

Referenced by saveOptional(), saveOptionalCArray(), saveOptionalCArray2D(), Util::DArrayParam< Type >::writeParam(), Util::FArrayParam< Type, Capacity >::writeParam(), and Util::FSArrayParam< Type, Capacity >::writeParam().

◆ readLabel()

void Util::Parameter::readLabel ( std::istream & in )

protectedvirtual

Read and attempt to match label string.

Parameters

in	input stream from which to read

Reimplemented in Util::ArrayParam< Type >, and Util::MatrixParam< Type >.

Definition at line 36 of file Parameter.cpp.

References label_.

Referenced by readParam().

◆ readValue()

virtual void Util::Parameter::readValue ( std::istream & in )

inlineprotectedvirtual

Read parameter value from an input stream.

Parameters

in	input stream from which to read

Reimplemented in Util::ArrayParam< Type >, Util::CArray2DParam< Type >, Util::DArrayParam< Type >, Util::DMatrixParam< Type >, Util::DSymmMatrixParam< Type >, Util::FArrayParam< Type, Capacity >, Util::FSArrayParam< Type, Capacity >, Util::MatrixParam< Type >, and Util::ScalarParam< Type >.

Definition at line 202 of file Parameter.h.

Referenced by readParam().

◆ loadValue()

virtual void Util::Parameter::loadValue ( Serializable::IArchive & ar )

inlineprotectedvirtual

Load bare parameter value from an archive.

Parameters

ar	input archive from which to load

Reimplemented in Util::CArray2DParam< Type >, Util::CArrayParam< Type >, Util::DArrayParam< Type >, Util::DMatrixParam< Type >, Util::DSymmMatrixParam< Type >, Util::FArrayParam< Type, Capacity >, Util::FSArrayParam< Type, Capacity >, and Util::ScalarParam< Type >.

Definition at line 209 of file Parameter.h.

Referenced by load().

◆ saveValue()

virtual void Util::Parameter::saveValue ( Serializable::OArchive & ar )

inlineprotectedvirtual

Save parameter value to an archive.

Parameters

ar	output archive to which to save

Reimplemented in Util::CArray2DParam< Type >, Util::CArrayParam< Type >, Util::DArrayParam< Type >, Util::DMatrixParam< Type >, Util::DSymmMatrixParam< Type >, Util::FArrayParam< Type, Capacity >, Util::FSArrayParam< Type, Capacity >, and Util::ScalarParam< Type >.

Definition at line 216 of file Parameter.h.

Referenced by save().

◆ bcastValue()

virtual void Util::Parameter::bcastValue ( )

inlineprotectedvirtual

Broadcast parameter value within the ioCommunicator.

Reimplemented in Util::CArray2DParam< Type >, Util::CArrayParam< Type >, Util::DArrayParam< Type >, Util::DMatrixParam< Type >, Util::DSymmMatrixParam< Type >, Util::FArrayParam< Type, Capacity >, Util::FSArrayParam< Type, Capacity >, and Util::ScalarParam< Type >.

Definition at line 222 of file Parameter.h.

Referenced by load(), and readParam().

Member Data Documentation

◆ Width

const int Util::Parameter::Width = 20

static

Width of output field for a scalar variable.

Definition at line 53 of file Parameter.h.

Referenced by load(), readParam(), Util::ArrayParam< Type >::writeParam(), Util::CArray2DParam< Type >::writeParam(), Util::DMatrixParam< Type >::writeParam(), Util::DSymmMatrixParam< Type >::writeParam(), and Util::ScalarParam< Type >::writeParam().

◆ Precision

const int Util::Parameter::Precision = 12

static

Precision for io of floating point data field.

Definition at line 56 of file Parameter.h.

Referenced by Util::ArrayParam< Type >::writeParam(), Util::CArray2DParam< Type >::writeParam(), Util::DMatrixParam< Type >::writeParam(), Util::DSymmMatrixParam< Type >::writeParam(), and Util::ScalarParam< Type >::writeParam().

◆ label_

Label Util::Parameter::label_

protected

Label object that contains parameter label string.

Definition at line 185 of file Parameter.h.

Referenced by isRequired(), load(), readLabel(), readParam(), Util::ArrayParam< Type >::save(), Util::ArrayParam< Type >::writeParam(), Util::CArray2DParam< Type >::writeParam(), and Util::DMatrixParam< Type >::writeParam().

◆ isActive_

bool Util::Parameter::isActive_

protected

Is this parameter active (always true if isRequired).

Definition at line 188 of file Parameter.h.

Referenced by isActive(), load(), readParam(), and save().

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

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Parameter()

◆ ~Parameter()

Member Function Documentation

◆ saveOptional()

◆ saveOptionalCArray()

◆ saveOptionalCArray2D()

◆ readParam()

◆ load()

◆ save()

◆ label()

◆ isRequired()

◆ isActive()

◆ readLabel()

◆ readValue()

◆ loadValue()

◆ saveValue()

◆ bcastValue()

Member Data Documentation

◆ Width

◆ Precision

◆ label_

◆ isActive_