Advanced Sampling Methods

Overview

Methods available in PySAGES

pysages.methods.abf.ABF(cvs, grid, **kwargs)	Adaptive Biasing Force Method.
pysages.methods.ann.ANN(cvs, grid, topology, ...)	Implementation of the sampling method described in "Learning free energy landscapes using artificial neural networks" [J.
pysages.methods.ffs.FFS(cvs, **kwargs)	Constructor of the Forward Flux Sampling method.
pysages.methods.funn.FUNN(cvs, grid, ...)	Implementation of the sampling method described in "Adaptive enhanced sampling by force-biasing using neural networks" [J.
pysages.methods.metad.Metadynamics(cvs, ...)	Implementation of Standard and Well-tempered Metadynamics as described in [PNAS 99.20, 12562-6 (2002)](https://doi.org/10.1073/pnas.202427399) and [Phys.
pysages.methods.umbrella_integration.UmbrellaIntegration(...)	This class combines harmonic biasing with multiple replicas.
pysages.methods.harmonic_bias.HarmonicBias(...)	Harmonic bias method class.
pysages.methods.spline_string.SplineString(...)	This class combines UmbrellaIntegration of multiple replicas with the path evolution of the spline (improved) string method.

Utility classes for Methods

pysages.methods.utils.HistogramLogger(period)	Implements a Callback functor for methods.
pysages.methods.utils.MetaDLogger(...)	Logs the state of the collective variable and other parameters in Metadynamics.

Abstract base classes

pysages.methods.core.SamplingMethod(cvs, ...)	Abstract base class for all sampling methods.
pysages.methods.core.GriddedSamplingMethod(...)	Base class for sampling methods that use grids.
pysages.methods.core.NNSamplingMethod(cvs, ...)	Base class for sampling methods that use neural networks.

Contents:

• pysages.methods.abf
  • ABFState
  • ABF
  • build_force_estimator()
• pysages.methods.ann
  • ANNState
  • ANN
  • build_free_energy_learner()
• pysages.methods.ffs
  • FFSState
  • FFS
  • check_input()
  • basin_sampling()
  • initial_flow()
• pysages.methods.funn
  • FUNNState
  • PartialFUNNState
  • FUNN
  • build_free_energy_grad_learner()
  • build_force_estimator()
• pysages.methods.harmonic_bias
  • HarmonicBiasState
  • HarmonicBias
• pysages.methods.metad
  • MetadynamicsState
  • PartialMetadynamicsState
  • Metadynamics
  • build_gaussian_accumulator()
  • build_bias_grad_evaluator()
  • sum_of_gaussians()
• pysages.methods.umbrella_integration
  • UmbrellaIntegration
• Spline String Method
  • SplineString
• pysages.methods.utils
  • SerialExecutor
  • ReplicasConfiguration
  • HistogramLogger
  • MetaDLogger
  • listify()
  • numpyfy_vals()
• pysages.methods.core
  • Result
  • SamplingMethod
  • GriddedSamplingMethod
  • NNSamplingMethod
  • run()

Advanced Sampling Methods

Advanced sampling methods are summarized in this sub-module. Methods have two objectives in PySAGES.

• Building python functions that bias simulations.

• Conducting the simulations run. This can include a single replica run, but also the orchestration of multiple replicas with complex interactions between one another.

The biasing part is implemented, such that each class provides a core.SamplingMethod.build() member function. This function is called internally by PySAGES once at initialization and returns two functions.

• an initialize function to generate the first internal state for biasing.

• and an update function, that invokes the calculation of the biasing forces.

This functional design is mandated by the jax implementation of PySAGES. The functions are just in time compiled for maximum performance. For new methods, the user has to implement this interface for custom biasing.

The conducting of simulation runs is designed closer to python’s object-oriented design. The core.SamplingMethod.run() function uses a user-provided function to generate the simulation context for the chosen backend. This member function sets up the necessary replica (simple ones only need one) of the simulation, conducts the bias simulation. Depending on the methods it may also collect information for analysis.

Each method inherits an abstract base implementation from SamplingMethod, see for details the class documentation. Any non-abstract method class has an accompanying state. This state is a data class for JAX and can contain only JAXArray of fixed dimensions. Methods use this state to carry information to conduct their biasing. There are two special members each state should provide:

• bias is an array of shape (Nparticles, 3) which must contain the biasing forces for each particle after the invocation of the biasing function.

• xi contains the last state of the collective variables used for biasing.

More members are allowed to provide the necessary information.

Biasing and simulation orchestration can be separated into a different classes. The harmonic_bias.HarmonicBias class for example provides a harmonic_bias.HarmonicBias.build() function for generate functions for harmonic biasing forces. The methods, however, just inherit the basic implementation of a single replica run. umbrella_integration.UmbrellaIntegration on the other hand, does not implement a new biasing method (and thus has no internal state as well). Instead it inherits the biasing from harmonic_bias.HarmonicBias but re-implements umbrella_integration.UmbrellaIntegration.run() to sample multiple replicas along a path to estimate free energy differences.