#include <gromacs/awh/awh.h>

Description

Coupling of the accelerated weight histogram method (AWH) with the system.

AWH calculates the free energy along order parameters of the system. Free energy barriers are overcome by adaptively tuning a bias potential along the order parameter such that the biased distribution along the parameter converges toward a chosen target distribution.

The Awh class takes care of the coupling between the system and the AWH bias(es). The Awh class contains one or more BiasCoupledToSystem objects. The BiasCoupledToSystem class takes care of the reaction coordinate input and force output for the single Bias object it containts.

Todo:: Update parameter reading and checkpointing, when general C++ framework is ready.

Public Member Functions
	Awh (FILE fplog, const t_inputrec &inputRecord, const t_commrec commRecord, const gmx_multisim_t multiSimRecord, const AwhParams &awhParams, const std::string &biasInitFilename, pull_t pull_work)
	Construct an AWH at the start of a simulation. More...

real	applyBiasForcesAndUpdateBias (int ePBC, const t_mdatoms &mdatoms, const matrix box, gmx::ForceWithVirial forceWithVirial, double t, int64_t step, gmx_wallcycle wallcycle, FILE *fplog)
	Peform an AWH update, to be called every MD step. More...

void	updateHistory (AwhHistory *awhHistory) const
	Update the AWH history in preparation for writing to checkpoint file. More...

std::shared_ptr< AwhHistory >	initHistoryFromState () const
	Allocate and initialize an AWH history with the given AWH state. More...

void	restoreStateFromHistory (const AwhHistory *awhHistory)
	Restore the AWH state from the given history. More...

void	writeToEnergyFrame (int64_t step, t_enxframe *fr) const
	Fills the AWH data block of an energy frame with data at certain steps. More...

Static Public Member Functions
static const char *	externalPotentialString ()
	Returns string "AWH" for registering AWH as an external potential provider with the pull module.

static void	registerAwhWithPull (const AwhParams &awhParams, pull_t *pull_work)
	Register the AWH biased coordinates with pull. More...

Constructor & Destructor Documentation

gmx::Awh::Awh	(	FILE *	fplog,
		const t_inputrec &	inputRecord,
		const t_commrec *	commRecord,
		const gmx_multisim_t *	multiSimRecord,
		const AwhParams &	awhParams,
		const std::string &	biasInitFilename,
		pull_t *	pull_work
	)

Construct an AWH at the start of a simulation.

AWH will here also register itself with the pull struct as the potential provider for the pull coordinates given as AWH coordinates in the user input. This allows AWH to later apply the bias force to these coordinate in Awh::applyBiasForcesAndUpdateBias.

Parameters

[in,out]	fplog	General output file, normally md.log, can be nullptr.
[in]	inputRecord	General input parameters (as set up by grompp).
[in]	commRecord	Struct for communication, can be nullptr.
[in]	multiSimRecord	Multi-sim handler
[in]	awhParams	AWH input parameters, consistent with the relevant parts of `inputRecord` (as set up by grompp).
[in]	biasInitFilename	Name of file to read PMF and target from.
[in,out]	pull_work	Pointer to a pull struct which AWH will couple to, has to be initialized, is assumed not to change during the lifetime of the Awh object.

Member Function Documentation

real gmx::Awh::applyBiasForcesAndUpdateBias	(	int	ePBC,
		const t_mdatoms &	mdatoms,
		const matrix	box,
		gmx::ForceWithVirial *	forceWithVirial,
		double	t,
		int64_t	step,
		gmx_wallcycle *	wallcycle,
		FILE *	fplog
	)

Peform an AWH update, to be called every MD step.

An update has two tasks: apply the bias force and improve the bias and the free energy estimate that AWH keeps internally.

For the first task, AWH retrieves the pull coordinate values from the pull struct. With these, the bias potential and forces are calculated. The bias force together with the atom forces and virial are passed on to pull which applies the bias force to the atoms. This is done at every step.

Secondly, coordinate values are regularly sampled and kept by AWH. Convergence of the bias and free energy estimate is achieved by updating the AWH bias state after a certain number of samples has been collected.

Note: Requires that pull_potential from pull.h has been called first since AWH needs the current coordinate values (the pull code checks for this).

Parameters

[in]	mdatoms	Atom properties.
[in]	ePBC	Type of periodic boundary conditions.
[in]	box	Box vectors.
[in,out]	forceWithVirial	Force and virial buffers, should cover at least the local atoms.
[in]	t	Time.
[in]	step	The current MD step.
[in,out]	wallcycle	Wallcycle counter, can be nullptr.
[in,out]	fplog	General output file, normally md.log, can be nullptr.

Returns: the potential energy for the bias.

std::shared_ptr< AwhHistory > gmx::Awh::initHistoryFromState ( ) const

Allocate and initialize an AWH history with the given AWH state.

This function should be called at the start of a new simulation at least on the master rank. Note that only constant data will be initialized here. History data is set by Awh::updateHistory.

Returns: a shared pointer to the AWH history on the rank that does I/O, nullptr otherwise.

void gmx::Awh::registerAwhWithPull	(	const AwhParams &	awhParams,
		pull_t *	pull_work
	)

static

Register the AWH biased coordinates with pull.

This function is public because it needs to be called by grompp (and is otherwise only called by Awh()). Pull requires all external potentials to register themselves before the end of pre-processing and before the first MD step. If this has not happened, pull with throw an error.

Parameters

[in]	awhParams	The AWH parameters.
[in,out]	pull_work	Pull struct which AWH will register the bias into.

void gmx::Awh::restoreStateFromHistory ( const AwhHistory * awhHistory )

Restore the AWH state from the given history.

Should be called on all ranks (for internal MPI broadcast). Should pass a point to an AwhHistory on the master rank that is compatible with the AWH setup in this simulation. Will throw an exception if it is not compatible.

Parameters

[in] awhHistory AWH history to restore from.

void gmx::Awh::updateHistory ( AwhHistory * awhHistory ) const

Update the AWH history in preparation for writing to checkpoint file.

Should be called at least on the master rank at checkpoint steps.

Should be called with a valid awhHistory (is checked).

Parameters

[in,out] awhHistory AWH history to set.

void gmx::Awh::writeToEnergyFrame	(	int64_t	step,
		t_enxframe *	fr
	)		const

Fills the AWH data block of an energy frame with data at certain steps.

Parameters

[in]	step	The current MD step.
[in,out]	fr	Energy data frame.

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

src/gromacs/awh/awh.h
src/gromacs/awh/awh.cpp

Description

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation