Action: OPES_EXPANDED

Module	opes
Description	Usage
On-the-fly probability enhanced sampling with expanded ensembles for the target distribution.

Output components

This action can calculate the values in the following table when the associated keyword is included in the input for the action. These values can be referenced elsewhere in the input by using this Action's label followed by a dot and the name of the value required from the list below.

Name	Type	Keyword	Description
bias	scalar	default	the instantaneous value of the bias potential
work	scalar	CALC_WORK	total accumulated work done by the bias

Input

The arguments that serve as the input for this action are specified using one or more of the keywords in the following table.

Keyword	Type	Description
ARG	scalar	the label of the ECVs that define the expansion

Further details and examples

On-the-fly probability enhanced sampling with expanded ensembles for the target distribution.

This method is similar to the OPES method with expanded ensembles target distribution (replica-exchange-like) that is discussed in the paper cited below.

An expanded ensemble is obtained by summing a set of ensembles at slightly different termodynamic conditions, or with slightly different Hamiltonians. Such ensembles can be sampled via methods like replica exchange, or this OPES_EXPANDED bias action. A typical example is a multicanonical simulation, in which a whole range of temperatures is sampled instead of a single one.

In oreder to define an expanded target ensemble we use the EXPANSION_CV (ECVs) that are discussed on the module page, $\Delta u_\lambda(\mathbf{x})$ . The bias at step $n$ is

$V_n(\mathbf{x})=-\frac{1}{\beta}\log \left(\frac{1}{N_{\{\lambda\}}}\sum_\lambda e^{-\Delta u_\lambda(\mathbf{x})+\beta\Delta F_n(\lambda)}\right)\, .$

See the paper cited below for more details on the method.

Notice that the estimates in the DELTAFS file are expressed in energy units, and should be multiplied by $\beta$ to be dimensionless as in the paper cited below. The DELTAFS file also contains an estimate of $c(t)=\frac{1}{\beta} \log \langle e^{\beta V}\rangle$ . Similarly to OPES_METAD, it is printed only for reference, since $c(t)$ reaches a fixed value as the bias converges, and should NOT be used for reweighting. Its value is also needed for restarting a simulation.

You can store the instantaneous $\Delta F_n(\lambda)$ estimates also in a more readable format using STATE_WFILE and STATE_WSTRIDE. Restart can be done either from a DELTAFS file or from a STATE_RFILE, it is equivalent.

Contrary to OPES_METAD, OPES_EXPANDED does not use kernel density estimation.

Examples

Click on the labels of the actions for more information on what each action computes

# simulate multiple temperatures, as in parallel tempering
eneThe ENERGY action with label ene calculates the following quantities: Quantity    Type    Description  
ene scalar the internal energy: ENERGYCalculate the total potential energy of the simulation box. More details
ecvThe ECV_MULTITHERMAL action with label ecv calculates the following quantities: Quantity    Type    Description  
ecv.ene scalar the value of the argument named ene: ECV_MULTITHERMALExpand a simulation to sample multiple temperatures simultaneously. This action has hidden defaults. More details ARGthe label of the internal energy of the system=ene TEMP_MAXthe maximum of the temperature range=1000
ecv: ECV_MULTITHERMALExpand a simulation to sample multiple temperatures simultaneously. This action uses the defaults shown here. More details ARGthe label of the internal energy of the system=ene TEMP_MAXthe maximum of the temperature range=1000  TEMP temperature=-1
opesThe OPES_EXPANDED action with label opes calculates the following quantities: Quantity    Type    Description  
opes.bias scalar the instantaneous value of the bias potential: OPES_EXPANDEDOn-the-fly probability enhanced sampling with expanded ensembles for the target distribution. This action has hidden defaults. More details ARGthe label of the ECVs that define the expansion=ecv.* PACEhow often the bias is updated=500
opes: OPES_EXPANDEDOn-the-fly probability enhanced sampling with expanded ensembles for the target distribution. This action uses the defaults shown here. More details ARGthe label of the ECVs that define the expansion=ecv.* PACEhow often the bias is updated=500  OBSERVATION_STEPS number of unbiased initial PACE steps to collect statistics for initialization=100 FILE a file with the estimate of the relative Delta F for each component of the target and of the global c(t)=DELTAFS PRINT_STRIDE stride for printing to DELTAFS file, in units of PACE=100
PRINTPrint quantities to a file. More details FILEthe name of the file on which to output these quantities=COLVAR STRIDE the frequency with which the quantities of interest should be output=500 ARGthe labels of the values that you would like to print to the file=ene,opes.bias

You can easily combine multiple ECVs. The OPES_EXPANDED bias will create a multidimensional target grid to sample all the combinations.

Click on the labels of the actions for more information on what each action computes

# simulate multiple temperatures while biasing a CV
eneThe ENERGY action with label ene calculates the following quantities: Quantity    Type    Description  
ene scalar the internal energy: ENERGYCalculate the total potential energy of the simulation box. More details
dstThe DISTANCE action with label dst calculates the following quantities: Quantity    Type    Description  
dst scalar the DISTANCE between this pair of atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2

ecv1The ECV_MULTITHERMAL action with label ecv1 calculates the following quantities: Quantity    Type    Description  
ecv1.ene scalar the value of the argument named ene: ECV_MULTITHERMALExpand a simulation to sample multiple temperatures simultaneously. This action has hidden defaults. More details ARGthe label of the internal energy of the system=ene TEMP_SET_ALLmanually set all the temperatures=200,300,500,1000
ecv1: ECV_MULTITHERMALExpand a simulation to sample multiple temperatures simultaneously. This action uses the defaults shown here. More details ARGthe label of the internal energy of the system=ene TEMP_SET_ALLmanually set all the temperatures=200,300,500,1000  TEMP temperature=-1
ecv2The ECV_UMBRELLAS_LINE action with label ecv2 calculates the following quantities: Quantity    Type    Description  
ecv2.dst scalar the value of the argument named dst: ECV_UMBRELLAS_LINETarget a multiumbrella ensemble, by combining systems each with a parabolic bias potential at a different location. This action has hidden defaults. More details ARGthe labels of the scalar values that are input to this action=dst CV_MINthe minimum of the CV range to be explored=1.2 CV_MAXthe maximum of the CV range to be explored=4.3 SIGMAsigma of the umbrella Gaussians=0.5
ecv2: ECV_UMBRELLAS_LINETarget a multiumbrella ensemble, by combining systems each with a parabolic bias potential at a different location. This action uses the defaults shown here. More details ARGthe labels of the scalar values that are input to this action=dst CV_MINthe minimum of the CV range to be explored=1.2 CV_MAXthe maximum of the CV range to be explored=4.3 SIGMAsigma of the umbrella Gaussians=0.5  TEMP temperature=-1 SPACING the distance between umbrellas, in units of SIGMA=1
opesThe OPES_EXPANDED action with label opes calculates the following quantities: Quantity    Type    Description  
opes.bias scalar the instantaneous value of the bias potential: OPES_EXPANDEDOn-the-fly probability enhanced sampling with expanded ensembles for the target distribution. This action has hidden defaults. More details ARGthe label of the ECVs that define the expansion=ecv1.*,ecv2.* PACEhow often the bias is updated=500 OBSERVATION_STEPS number of unbiased initial PACE steps to collect statistics for initialization=1
opes: OPES_EXPANDEDOn-the-fly probability enhanced sampling with expanded ensembles for the target distribution. This action uses the defaults shown here. More details ARGthe label of the ECVs that define the expansion=ecv1.*,ecv2.* PACEhow often the bias is updated=500 OBSERVATION_STEPS number of unbiased initial PACE steps to collect statistics for initialization=1  FILE a file with the estimate of the relative Delta F for each component of the target and of the global c(t)=DELTAFS PRINT_STRIDE stride for printing to DELTAFS file, in units of PACE=100

PRINTPrint quantities to a file. More details FILEthe name of the file on which to output these quantities=COLVAR STRIDE the frequency with which the quantities of interest should be output=500 ARGthe labels of the values that you would like to print to the file=ene,dst,opes.bias

If an ECV is based on more than one CV you must provide all the output component, in the proper order. You can use the regular expressions discussed here for that, like in the following example.

Click on the labels of the actions for more information on what each action computes

# simulate multiple temperatures and pressures while biasing a two-CVs linear path
eneThe ENERGY action with label ene calculates the following quantities: Quantity    Type    Description  
ene scalar the internal energy: ENERGYCalculate the total potential energy of the simulation box. More details
volThe VOLUME action with label vol calculates the following quantities: Quantity    Type    Description  
vol scalar the volume of simulation box: VOLUMECalculate the volume the simulation box. More details
ecv_mtpThe ECV_MULTITHERMAL_MULTIBARIC action with label ecv_mtp calculates the following quantities: Quantity    Type    Description  
ecv_mtp.ene scalar the value of the argument named ene
ecv_mtp.vol scalar the value of the argument named vol: ECV_MULTITHERMAL_MULTIBARICExpand a simulation to sample multiple temperatures and pressures. More details ...
  ARGthe labels of the potential energy and of the volume of the system=ene,vol
  TEMP temperature=300
  TEMP_MINthe minimum of the temperature range=200
  TEMP_MAXthe maximum of the temperature range=800
  PRESSUREpressure=0.06022140857*1000 #1 kbar
  PRESSURE_MINthe minimum of the pressure range=0
  PRESSURE_MAXthe maximum of the pressure range=0.06022140857*2000 #2 kbar
...

cv1The DISTANCE action with label cv1 calculates the following quantities: Quantity    Type    Description  
cv1 scalar the DISTANCE between this pair of atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2
cv2The DISTANCE action with label cv2 calculates the following quantities: Quantity    Type    Description  
cv2 scalar the DISTANCE between this pair of atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=3,4
ecv_umbThe ECV_UMBRELLAS_LINE action with label ecv_umb calculates the following quantities: Quantity    Type    Description  
ecv_umb.cv1 scalar the value of the argument named cv1
ecv_umb.cv2 scalar the value of the argument named cv2: ECV_UMBRELLAS_LINETarget a multiumbrella ensemble, by combining systems each with a parabolic bias potential at a different location. This action has hidden defaults. More details ARGthe labels of the scalar values that are input to this action=cv1,cv2 TEMP temperature=300 CV_MINthe minimum of the CV range to be explored=0.1,0.1 CV_MAXthe maximum of the CV range to be explored=1.5,1.5 SIGMAsigma of the umbrella Gaussians=0.2 BARRIERa guess of the free energy barrier to be overcome (better to stay higher than lower)=70
ecv_umb: ECV_UMBRELLAS_LINETarget a multiumbrella ensemble, by combining systems each with a parabolic bias potential at a different location. This action uses the defaults shown here. More details ARGthe labels of the scalar values that are input to this action=cv1,cv2 TEMP temperature=300 CV_MINthe minimum of the CV range to be explored=0.1,0.1 CV_MAXthe maximum of the CV range to be explored=1.5,1.5 SIGMAsigma of the umbrella Gaussians=0.2 BARRIERa guess of the free energy barrier to be overcome (better to stay higher than lower)=70  SPACING the distance between umbrellas, in units of SIGMA=1

opesThe OPES_EXPANDED action with label opes calculates the following quantities: Quantity    Type    Description  
opes.bias scalar the instantaneous value of the bias potential: OPES_EXPANDEDOn-the-fly probability enhanced sampling with expanded ensembles for the target distribution. This action has hidden defaults. More details ARGthe label of the ECVs that define the expansion=(ecv_.*) PACEhow often the bias is updated=500 WALKERS_MPI switch on MPI version of multiple walkers PRINT_STRIDE stride for printing to DELTAFS file, in units of PACE=1000
opes: OPES_EXPANDEDOn-the-fly probability enhanced sampling with expanded ensembles for the target distribution. This action uses the defaults shown here. More details ARGthe label of the ECVs that define the expansion=(ecv_.*) PACEhow often the bias is updated=500 WALKERS_MPI switch on MPI version of multiple walkers PRINT_STRIDE stride for printing to DELTAFS file, in units of PACE=1000  OBSERVATION_STEPS number of unbiased initial PACE steps to collect statistics for initialization=100 FILE a file with the estimate of the relative Delta F for each component of the target and of the global c(t)=DELTAFS

PRINTPrint quantities to a file. More details FILEthe name of the file on which to output these quantities=COLVAR STRIDE the frequency with which the quantities of interest should be output=500 ARGthe labels of the values that you would like to print to the file=ene,vol,cv1,cv2,opes.bias

References

More information about how this action can be used is available in the following articles:

M. Invernizzi, P. M. Piaggi, M. Parrinello, Unified Approach to Enhanced Sampling. Physical Review X. 10 (2020)

Syntax

The following table describes the keywords and options that can be used with this action

Keyword	Type	Default	Description
ARG	input	none	the label of the ECVs that define the expansion
PACE	compulsory	none	how often the bias is updated
OBSERVATION_STEPS	compulsory	100	number of unbiased initial PACE steps to collect statistics for initialization
FILE	compulsory	DELTAFS	a file with the estimate of the relative Delta F for each component of the target and of the global c(t)
PRINT_STRIDE	compulsory	100	stride for printing to DELTAFS file, in units of PACE
NUMERICAL_DERIVATIVES	optional	false	calculate the derivatives for these quantities numerically
FMT	optional	not used	specify format for DELTAFS file
STATE_RFILE	optional	not used	read from this file the Delta F estimates and all the info needed to RESTART the simulation
STATE_WFILE	optional	not used	write to this file the Delta F estimates and all the info needed to RESTART the simulation
STATE_WSTRIDE	optional	not used	number of MD steps between writing the STATE_WFILE
STORE_STATES	optional	false	append to STATE_WFILE instead of ovewriting it each time
CALC_WORK	optional	false	calculate the total accumulated work done by the bias since last restart
WALKERS_MPI	optional	false	switch on MPI version of multiple walkers
SERIAL	optional	false	perform calculations in serial
RESTART	optional	not used	allows per-action setting of restart (YES/NO/AUTO)
UPDATE_FROM	optional	not used	Only update this action from this time
UPDATE_UNTIL	optional	not used	Only update this action until this time

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

Quantity	Type	Description
ene	scalar	the internal energy