Detailed Description

Model of parameter dependence in a free energy perturbation theory.

A Perturbation object defines a parameter dependent statistical weight of the type used in free energy perturbation theory, replica exchange, and extended ensemble algorithms. In all of these applications, the probability of a microstate X is given by an exponential exp(-W(X,p)), where W(X,p) = beta*H depends upon a perturbation parameter p, H is the system Hamiltonian and beta = 1/kT is inverse temperature. Either the Hamiltonian or the inverse temperature may depend upon the perturbation parameter.

This class provides a method to modify the system parameters (beta and/or the potential energy parameters) so as to correspond to a given value of p, and methods to evaluate the derivative dW(X,p)/dp and difference W(X, p') - W(X, p) for a given system configuration.

Definition at line 39 of file Perturbation.h.

#include <Perturbation.h>

Inheritance diagram for McMd::Perturbation:

Public Member Functions
	Perturbation (int size, int rank)
	Constructor. More...

virtual	~Perturbation ()
	Destructor. More...

Mutators
void	readParameters (std::istream &in)
	Read perturbation parameter(s) from file. More...

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

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

void	setParameter (DArray< double > parameter)
	Sets the perturbation parameter value. More...

Accessors
double	parameter (int i, int id)
	Get parameter i of system id. More...

int	getNParameters () const
	Gets the number of parameters per system. More...

virtual double	parameter (int i) const =0
	Get perturbation parameter p[i] of index i for this system. More...

virtual double	derivative (int i) const =0
	Get derivative of the Boltzmann weight W(X,p) with respect to the perturbation parameter p[i] of index i. More...

virtual double	difference (DArray< double > iPartnerParameter) const =0
	Returns the difference W(X, p') - W(X, p). More...

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

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

	ParamComposite (int capacity)
	Constructor. More...

virtual	~ParamComposite ()
	Virtual destructor. More...

void	resetParam ()
	Resets ParamComposite to its empty state. More...

virtual void	readParam (std::istream &in)
	Read the parameter file block. More...

virtual void	readParamOptional (std::istream &in)
	Read optional parameter file block. More...

virtual void	writeParam (std::ostream &out)
	Write all parameters to an output stream. More...

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

virtual void	loadOptional (Serializable::IArchive &ar)
	Load an optional ParamComposite. More...

void	saveOptional (Serializable::OArchive &ar)
	Saves isActive flag, and then calls save() iff isActive is true. More...

void	readParamComposite (std::istream &in, ParamComposite &child, bool next=true)
	Add and read a required child ParamComposite. More...

void	readParamCompositeOptional (std::istream &in, ParamComposite &child, bool next=true)
	Add and attempt to read an optional child ParamComposite. More...

template<typename Type >
ScalarParam< Type > &	read (std::istream &in, const char *label, Type &value)
	Add and read a new required ScalarParam < Type > object. More...

template<typename Type >
ScalarParam< Type > &	readOptional (std::istream &in, const char *label, Type &value)
	Add and read a new optional ScalarParam < Type > object. More...

template<typename Type >
CArrayParam< Type > &	readCArray (std::istream &in, const char label, Type value, int n)
	Add and read a required C array parameter. More...

template<typename Type >
CArrayParam< Type > &	readOptionalCArray (std::istream &in, const char label, Type value, int n)
	Add and read an optional C array parameter. More...

template<typename Type >
DArrayParam< Type > &	readDArray (std::istream &in, const char *label, DArray< Type > &array, int n)
	Add and read a required DArray < Type > parameter. More...

template<typename Type >
DArrayParam< Type > &	readOptionalDArray (std::istream &in, const char *label, DArray< Type > &array, int n)
	Add and read an optional DArray < Type > parameter. More...

template<typename Type , int N>
FArrayParam< Type, N > &	readFArray (std::istream &in, const char *label, FArray< Type, N > &array)
	Add and read a required FArray < Type, N > array parameter. More...

template<typename Type , int N>
FArrayParam< Type, N > &	readOptionalFArray (std::istream &in, const char *label, FArray< Type, N > &array)
	Add and read an optional FArray < Type, N > array parameter. More...

template<typename Type >
CArray2DParam< Type > &	readCArray2D (std::istream &in, const char label, Type value, int m, int n, int np)
	Add and read a required CArray2DParam < Type > 2D C-array. More...

template<typename Type >
CArray2DParam< Type > &	readOptionalCArray2D (std::istream &in, const char label, Type value, int m, int n, int np)
	Add and read an optional CArray2DParam < Type > 2D C-array parameter. More...

template<typename Type >
DMatrixParam< Type > &	readDMatrix (std::istream &in, const char *label, DMatrix< Type > &matrix, int m, int n)
	Add and read a required DMatrix < Type > matrix parameter. More...

template<typename Type >
DMatrixParam< Type > &	readOptionalDMatrix (std::istream &in, const char *label, DMatrix< Type > &matrix, int m, int n)
	Add and read an optional DMatrix < Type > matrix parameter. More...

template<typename Type >
DSymmMatrixParam< Type > &	readDSymmMatrix (std::istream &in, const char *label, DMatrix< Type > &matrix, int n)
	Add and read a required symmetrix DMatrix. More...

template<typename Type >
DSymmMatrixParam< Type > &	readOptionalDSymmMatrix (std::istream &in, const char *label, DMatrix< Type > &matrix, int n)
	Add and read an optional DMatrix matrix parameter. More...

Begin &	readBegin (std::istream &in, const char *label, bool isRequired=true)
	Add and read a class label and opening bracket. More...

End &	readEnd (std::istream &in)
	Add and read the closing bracket. More...

Blank &	readBlank (std::istream &in)
	Add and read a new Blank object, representing a blank line. More...

void	loadParamComposite (Serializable::IArchive &ar, ParamComposite &child, bool next=true)
	Add and load a required child ParamComposite. More...

void	loadParamCompositeOptional (Serializable::IArchive &ar, ParamComposite &child, bool next=true)
	Add and load an optional child ParamComposite if isActive. More...

template<typename Type >
ScalarParam< Type > &	loadParameter (Serializable::IArchive &ar, const char *label, Type &value, bool isRequired)
	Add and load a new ScalarParam < Type > object. More...

template<typename Type >
ScalarParam< Type > &	loadParameter (Serializable::IArchive &ar, const char *label, Type &value)
	Add and load new required ScalarParam < Type > object. More...

template<typename Type >
CArrayParam< Type > &	loadCArray (Serializable::IArchive &ar, const char label, Type value, int n, bool isRequired)
	Add a C array parameter and load its elements. More...

template<typename Type >
CArrayParam< Type > &	loadCArray (Serializable::IArchive &ar, const char label, Type value, int n)
	Add and load a required CArrayParam< Type > array parameter. More...

template<typename Type >
DArrayParam< Type > &	loadDArray (Serializable::IArchive &ar, const char *label, DArray< Type > &array, int n, bool isRequired)
	Add an load a DArray < Type > array parameter. More...

template<typename Type >
DArrayParam< Type > &	loadDArray (Serializable::IArchive &ar, const char *label, DArray< Type > &array, int n)
	Add and load a required DArray< Type > array parameter. More...

template<typename Type , int N>
FArrayParam< Type, N > &	loadFArray (Serializable::IArchive &ar, const char *label, FArray< Type, N > &array, bool isRequired)
	Add and load an FArray < Type, N > fixed-size array parameter. More...

template<typename Type , int N>
FArrayParam< Type, N > &	loadFArray (Serializable::IArchive &ar, const char *label, FArray< Type, N > &array)
	Add and load a required FArray < Type > array parameter. More...

template<typename Type >
CArray2DParam< Type > &	loadCArray2D (Serializable::IArchive &ar, const char label, Type value, int m, int n, int np, bool isRequired)
	Add and load a CArray2DParam < Type > C 2D array parameter. More...

template<typename Type >
CArray2DParam< Type > &	loadCArray2D (Serializable::IArchive &ar, const char label, Type value, int m, int n, int np)
	Add and load a required < Type > matrix parameter. More...

template<typename Type >
DMatrixParam< Type > &	loadDMatrix (Serializable::IArchive &ar, const char *label, DMatrix< Type > &matrix, int m, int n, bool isRequired)
	Add and load a DMatrixParam < Type > matrix parameter. More...

template<typename Type >
DMatrixParam< Type > &	loadDMatrix (Serializable::IArchive &ar, const char *label, DMatrix< Type > &matrix, int m, int n)
	Add and load a required DMatrixParam < Type > matrix parameter. More...

template<typename Type >
DSymmMatrixParam< Type > &	loadDSymmMatrix (Serializable::IArchive &ar, const char *label, DMatrix< Type > &matrix, int n, bool isRequired)
	Add and load a symmetric DSymmMatrixParam < Type > matrix parameter. More...

template<typename Type >
DSymmMatrixParam< Type > &	loadDSymmMatrix (Serializable::IArchive &ar, const char *label, DMatrix< Type > &matrix, int n)
	Add and load a required DSymmMatrixParam < Type > matrix parameter. More...

void	addParamComposite (ParamComposite &child, bool next=true)
	Add a child ParamComposite object to the format array. More...

Begin &	addBegin (const char *label)
	Add a Begin object representing a class name and bracket. More...

End &	addEnd ()
	Add a closing bracket. More...

Blank &	addBlank ()
	Create and add a new Blank object, representing a blank line. More...

std::string	className () const
	Get class name string. More...

bool	isRequired () const
	Is this ParamComposite required in the input file? More...

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

Public Member Functions inherited from Util::ParamComponent
virtual	~ParamComponent ()
	Destructor. 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...

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...

Protected Member Functions
virtual void	setParameter ()=0
	Sets the perturbation parameter in the associated system. More...

Protected Member Functions inherited from Util::ParamComposite
void	setClassName (const char *className)
	Set class name string. More...

void	setIsRequired (bool isRequired)
	Set or unset the isActive flag. More...

void	setIsActive (bool isActive)
	Set or unset the isActive flag. More...

void	setParent (ParamComponent &param, bool next=true)
	Set this to the parent of a child component. More...

void	addComponent (ParamComponent &param, bool isLeaf=true)
	Add a new ParamComponent object to the format array. More...

template<typename Type >
ScalarParam< Type > &	add (std::istream &in, const char *label, Type &value, bool isRequired=true)
	Add a new required ScalarParam < Type > object. More...

template<typename Type >
CArrayParam< Type > &	addCArray (std::istream &in, const char label, Type value, int n, bool isRequired=true)
	Add (but do not read) a required C array parameter. More...

template<typename Type >
DArrayParam< Type > &	addDArray (std::istream &in, const char *label, DArray< Type > &array, int n, bool isRequired=true)
	Add (but do not read) a DArray < Type > parameter. More...

template<typename Type , int N>
FArrayParam< Type, N > &	addFArray (std::istream &in, const char *label, FArray< Type, N > &array, bool isRequired=true)
	Add (but do not read) a FArray < Type, N > array parameter. More...

template<typename Type >
CArray2DParam< Type > &	addCArray2D (std::istream &in, const char label, Type value, int m, int n, int np, bool isRequired=true)
	Add (but do not read) a CArray2DParam < Type > 2D C-array. More...

template<typename Type >
DMatrixParam< Type > &	addDMatrix (std::istream &in, const char *label, DMatrix< Type > &matrix, int m, int n, bool isRequired=true)
	Add and read a required DMatrix < Type > matrix parameter. More...

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

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

Protected Attributes
int	size_
	Number of systems (e.g., communicator size) More...

int	rank_
	Index for this system (e.g., communicator size) More...

int	nParameters_
	Number of perturbation parameters associated with a System. More...

int	mode_
	mode 0: parameters of all replica systems are specified. More...

DArray< double >	parameter_
	Value of the perturbation parameter for the associated System. More...

DArray< double >	initialParameter_
	Value of the perturbation parameter for the first replica System. More...

DArray< double >	finalParameter_
	Value of the perturbation parameter for the last replica System. More...

DMatrix< double >	parameters_
	Value of the perturbation parameter for all the replica Systems. 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...

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...

Constructor & Destructor Documentation

McMd::Perturbation::Perturbation	(	int	size,
		int	rank
	)

Constructor.

Parameters

size	number of parameter values (e.g., communicator size)
rank	index of this system (e.g., communicator rank)

Definition at line 16 of file Perturbation.cpp.

References Util::ParamComposite::setClassName().

McMd::Perturbation::~Perturbation ( )

virtual

Destructor.

Definition at line 27 of file Perturbation.cpp.

Member Function Documentation

void McMd::Perturbation::readParameters ( std::istream & in )

virtual

Read perturbation parameter(s) from file.

Parameters

in	input stream (file or std in).

Reimplemented from Util::ParamComposite.

Definition at line 33 of file Perturbation.cpp.

References Util::DMatrix< Data >::allocate(), Util::DArray< Data >::allocate(), finalParameter_, initialParameter_, mode_, nParameters_, parameter_, parameters_, rank_, setParameter(), and size_.

Referenced by McMd::McEnergyPerturbation::readParameters(), McMd::McExternalPerturbation< Interaction >::readParameters(), McMd::McPairPerturbation< Interaction >::readParameters(), and McMd::McPairExternalPerturbation< PairInteraction, ExternalInteraction >::readParameters().

void McMd::Perturbation::loadParameters ( Serializable::IArchive & ar )

virtual

Load internal state from an archive.

Parameters

ar	input/loading archive

Reimplemented from Util::ParamComposite.

Reimplemented in McMd::McPairPerturbation< Interaction >.

Definition at line 69 of file Perturbation.cpp.

References Util::DMatrix< Data >::allocate(), Util::DArray< Data >::allocate(), finalParameter_, initialParameter_, mode_, nParameters_, parameter_, parameters_, setParameter(), and size_.

Referenced by McMd::McPairPerturbation< Interaction >::loadParameters().

void McMd::Perturbation::save ( Serializable::OArchive & ar )

virtual

Save internal state to an archive.

Parameters

ar	output/saving archive

Reimplemented from Util::ParamComposite.

Definition at line 91 of file Perturbation.cpp.

References finalParameter_, initialParameter_, mode_, nParameters_, parameter_, and parameters_.

Referenced by McMd::System::savePerturbation().

void McMd::Perturbation::setParameter ( DArray< double > parameter )

Sets the perturbation parameter value.

This method sets the value of the member parameter, and calls the virtual void setParameter() method to modify the parameter of the associated System.

Parameters

parameter perturbation parameter value for associated System.

Definition at line 110 of file Perturbation.cpp.

References parameter(), parameter_, and setParameter().

double McMd::Perturbation::parameter	(	int	i,
		int	id
	)

Get parameter i of system id.

Parameters

i	index of perturbation parameter
id	id of system in a mpi simulation

Returns the value of the perturbation parameter p[i].

Definition at line 119 of file Perturbation.cpp.

References parameters_.

Referenced by McMd::LinearPerturbation< SystemType >::difference(), McMd::ReplicaMove::move(), McMd::BennettsMethod::sample(), and setParameter().

int McMd::Perturbation::getNParameters ( ) const

Gets the number of parameters per system.

Returns the number of perturbation parameters for this system.

Definition at line 125 of file Perturbation.cpp.

References nParameters_.

Referenced by McMd::BennettsMethod::BennettsMethod(), McMd::LinearPerturbation< SystemType >::difference(), McMd::McPairPerturbation< Interaction >::loadParameters(), McMd::McEnergyPerturbation::readParameters(), McMd::McExternalPerturbation< Interaction >::readParameters(), McMd::McPairPerturbation< Interaction >::readParameters(), McMd::McPairExternalPerturbation< PairInteraction, ExternalInteraction >::readParameters(), and McMd::ReplicaMove::ReplicaMove().

virtual double McMd::Perturbation::parameter ( int i ) const

pure virtual

Get perturbation parameter p[i] of index i for this system.

Returns the value of the perturbation parameter p[i].

Implemented in McMd::McPairExternalPerturbation< PairInteraction, ExternalInteraction >, McMd::McPairPerturbation< Interaction >, McMd::McExternalPerturbation< Interaction >, and McMd::McEnergyPerturbation.

virtual double McMd::Perturbation::derivative ( int i ) const

pure virtual

Get derivative of the Boltzmann weight W(X,p) with respect to the perturbation parameter p[i] of index i.

For a system in which W(X,p) = beta*H depends on a microstate X and a parameter p, this method returns the value of dW(X, p)/dp[i] for the current system microstate (i.e., for the current particle positions).

Implemented in McMd::McPairExternalPerturbation< PairInteraction, ExternalInteraction >, McMd::McPairPerturbation< Interaction >, McMd::McExternalPerturbation< Interaction >, and McMd::McEnergyPerturbation.

Referenced by McMd::LinearPerturbation< SystemType >::difference(), and McMd::ReplicaMove::move().

virtual double McMd::Perturbation::difference ( DArray< double > iPartnerParameter ) const

pure virtual

Returns the difference W(X, p') - W(X, p).

This method returns the difference W(X, p') - W(X, p) between value of the statistical weight W(X,p[i]) = H/kT for the current microstate, where p[i] is the value of the perturbation parameter in this system, and p'[i] = iPartnerParameter is the partner perturbation parameter value that is passed to this function.

Parameters

iPartnerParameter perturbation parameters for partner system.

Implemented in McMd::LinearPerturbation< SystemType >, and McMd::LinearPerturbation< McSystem >.

Referenced by McMd::BennettsMethod::sample().

virtual void McMd::Perturbation::setParameter ( )

protectedpure virtual

Sets the perturbation parameter in the associated system.

This method modifies the parameters of the associated System so as to correspond to the value of the parameter member variable.

Implemented in McMd::McPairExternalPerturbation< PairInteraction, ExternalInteraction >, McMd::McPairPerturbation< Interaction >, McMd::McExternalPerturbation< Interaction >, and McMd::McEnergyPerturbation.

Referenced by loadParameters(), readParameters(), and setParameter().