CombinedOPES

CombinedOPES(system, variables, temperature, barrier, exploreBarrier, frequency, varianceFrequency, biasFactor=None, exploreBiasFactor=None, bounded=False, saveFrequency=None, biasDir=None, walkerId=None, warmupSteps=None, compressionThreshold=1.0, useExistingBandwidths=True, kernelShape='gaussian', statsWindowSize=10, minBandwidth=None, extraBias=None)

OPES and OPES-explore biasing the same collective variables together.

Implements the combined algorithm of Ray and Rizzi, https://doi.org/10.1021/acs.jctc.4c01231, often called OPES_COM. Both components deposit a kernel at the same steps, at the same CV values:

• the OPES component estimates its marginal distribution with weights exp(beta V_opes) from its own bias only (their Eq. 11), so that distribution is still biased by the explore component (Eq. 12);
• the explore component estimates its target distribution from the unweighted samples (Eq. 8), which feel both biases.

The total bias is V_opes + V_explore. Neither component estimates the unbiased distribution by itself, so a third estimate reweights every sample by exp(beta (V_opes + V_explore)), the paper's Eq. 14, and getFreeEnergy returns it. Its kernels are sized as those of the explore component's reweighted estimate.

Both components share one bias force, so the CVs are computed once per step. To weight OPES kernels by the OPES bias alone, the explore part of the force is switched off for a single energy evaluation at each deposition step.

Parameters:

Name	Type	Description	Default
system		The System to simulate. A CustomCVForce implementing the total bias is created and added to it.	required
variables		The collective variables both components bias.	required
temperature		The temperature at which the simulation is run.	required
barrier		The barrier of the OPES component, Delta E_OPES.	required
exploreBarrier		The barrier of the OPES-explore component, Delta E_EXPLORE. The paper finds systematic errors when it exceeds barrier, and a warning is issued in that case.	required
frequency		Interval in time steps at which both components deposit a kernel.	required
varianceFrequency		Interval in time steps at which to update the CV variance, or None for a fixed bandwidth taken from each variable's biasWidth. See OPES.	required
biasFactor		The OPES bias factor. Defaults to barrier / kT.	None
exploreBiasFactor		The OPES-explore bias factor. Defaults to exploreBarrier / kT.	None
saveFrequency		Interval in time steps at which to share the bias on disk.	None
biasDir		Directory shared with other walkers. Each component uses its own subdirectory.	None
walkerId		This walker's identifier within biasDir. See OPES.	None
extraBias		Other biases acting on the simulation, as in OPES. They join the weights of the OPES kernels and of the free energy estimate.	None
bounded	bool	Whether non-periodic CVs have reflective boundaries. See OPES.	False
warmupSteps		Unbiased steps for measuring the CV variance. See OPES.	None
compressionThreshold	float	Mahalanobis distance below which kernels are merged.	1.0
useExistingBandwidths	bool	Whether the merge search scales by existing kernels' bandwidths.	True
kernelShape	str	"gaussian" or "compact".	'gaussian'
statsWindowSize	int	Window, in deposition strides, of the running CV-mean estimate.	10
minBandwidth		Per-CV floor on the bandwidth of new kernels. None by default.	None

getBias

getBias()

The total bias potential on the grid, V_opes + V_explore.

getBiasEnergy

getBiasEnergy(context)

The total bias energy V_opes(s) + V_explore(s) applied in a Context.

getCollectiveVariables

getCollectiveVariables(simulation)

Current values of all collective variables in a Simulation.

getComponentBiasEnergies

getComponentBiasEnergies(context)

The OPES and OPES-explore bias energies applied in a Context.

The explore part of the force is switched off for one evaluation of the bias force group, then restored.

getComponentBiases

getComponentBiases()

The OPES and OPES-explore bias potentials on the grid.

getCt

getCt(estimate='current')

c(t) of the total bias, V_opes + V_explore.

"current" averages exp(-beta V) over the free energy estimate of getFreeEnergy; "running" is kT ln of the mean weight of its samples, with an initial sample under the flat bias -(barrier + exploreBarrier). See OPES.getCt.

getFreeEnergy

getFreeEnergy(correctSmoothing=False, pilotFactor=2.0)

Free energy as a function of the collective variables.

The estimate reweights every sample by the total bias, Eq. 14 of Ray and Rizzi. The grid and the smoothing correction follow OPES.getFreeEnergy.

getNumKernels

getNumKernels()

Numbers of kernels in the OPES and OPES-explore bias estimates.

getState

getState()

Flat, npz-writable snapshot of both components' accumulated state.

setState

setState(state)

Restore both components from a snapshot.

The snapshot comes from getState. The restored bias reaches the simulation at the start of the next step, or sooner through updateContext.

step

step(simulation, steps)

Advance the simulation by a number of time steps.

A CombinedOPES can also be passed to OPES.stepTogether along with other samplers.

updateContext

updateContext(context)

Push the current biases into a Context.

Each table stores its component's bias shifted up by that component's barrier, so the unexplored floor sits at 0, as in OPES.