Package: adaptive-sampling
Adaptive SamplingThis package implements various sampling algorithms for the calculation of free energy profiles of molecular transitions.Available Sampling Methods Include:Adaptive Biasing Force (ABF) method [1]Extended-system ABF (eABF) [2]On-the-fly free energy estimate from the Corrected Z-Averaged Restraint (CZAR) [2]Application of Multistate Bannett's Acceptance Ratio (MBAR) [3] to recover full statistical information in post-processing [4](Well-Tempered) Metadynamics (WTM) [5] and WTM-eABF [6]Accelerated MD (aMD), Gaussian accelerated MD (GaMD), Sigmoid Accelerated MD (SaMD) [7, 8, 9]Gaussian-accelerated WTM-eABF [10]Free-energy Nudged Elastic Band Method [11]Implemented Collective Variables:Distances, angles and torsion angles as well as linear combinations thereofCoordination numbersMinimized Cartesian RMSD (Kabsch algorithm)Adaptive path collective variables (PCVs) [12, 13]Install:To install adaptive_sampling type:$pipinstalladaptive-samplingRequirements:python >= 3.8numpy >= 1.19torch >= 1.10scipy >= 1.7Basic Usage:To use adaptive sampling with your MD code of choice add a function calledget_sampling_data()to the corresponding python interface that returns an object containing all required data. Hard-coded dependencies can be avoided by wrapping theadaptive_samplingimport in atry/exceptclause:classMD:# Your MD code...defget_sampling_data(self):try:fromadaptive_sampling.interface.sampling_dataimportSamplingDatamass=...coords=...forces=...epot=...temp=...natoms=...step=...dt=...returnSamplingData(mass,coords,forces,epot,temp,natoms,step,dt)exceptImportErrorase:raiseNotImplementedError("`get_sampling_data()` is missing `adaptive_sampling` package")fromeThe bias force on atoms in the N-th step can be obtained by callingstep_bias()on any sampling algorithm:fromadaptive_sampling.sampling_toolsimport*# initialize MD codethe_md=MD(...)# collective variableatom_indices=[0,1]minimum=1.0# Angstrommaximum=3.5# Angstrombin_width=0.1# Angstromcollective_var=[["distance",atom_indices,minimum,maximum,bin_width]]# extended-system eABFext_sigma=0.1# thermal width of coupling between CV and extended variable in Angstromext_mass=20.0# mass of extended variablethe_bias=eABF(ext_sigma,ext_mass,the_md,collective_var,output_freq=10,f_conf=100,equil_temp=300.0)formd_stepinrange(steps):# propagate langevin dynamics and calc forces...bias_force=the_bias.step_bias(write_output=True,write_traj=True)the_md.forces+=bias_force...# finish md_stepThis automatically writes an on-the-fly free energy estimate in the output file and all necessary data for post-processing in a trajectory file.
For extended-system dynamics unbiased statistical weights of individual frames can be obtained using the MBAR estimator:importnumpyasnpfromadaptive_sampling.processing_toolsimportmbartraj_dat=np.loadtxt('CV_traj.dat',skiprows=1)ext_sigma=0.1# thermal width of coupling between CV and extended variable# grid for free energy profile can be different than during samplingminimum=1.0maximum=3.5bin_width=0.1grid=np.arange(minimum,maximum,bin_width)cv=traj_dat[:,1]# trajectory of collective variablela=traj_dat[:,2]# trajectory of extended system# run MBAR and compute free energy profile and probability density from statistical weightstraj_list,indices,meta_f=mbar.get_windows(grid,cv,la,ext_sigma,equil_temp=300.0)exp_U,frames_per_traj=mbar.build_boltzmann(traj_list,meta_f,equil_temp=300.0,)weights=mbar.run_mbar(exp_U,frames_per_traj,max_iter=10000,conv=1.0e-7,conv_errvec=1.0,outfreq=100,device='cpu',)pmf,rho=mbar.pmf_from_weights(grid,cv[indices],weights,equil_temp=300.0)Documentation:Code documentation can be created with pdoc3:$pipinstallpdoc3
$pdoc--htmladaptive_sampling-odoc/References:Comer et al., J. Phys. Chem. B (2015);https://doi.org/10.1021/jp506633nLesage et al., J. Phys. Chem. B (2017);https://doi.org/10.1021/acs.jpcb.6b10055Shirts et al., J. Chem. Phys. (2008);https://doi.org/10.1063/1.2978177Hulm et al., J. Chem. Phys. (2022);https://doi.org/10.1063/5.0095554Barducci et al., Phys. rev. lett. (2008);https://doi.org/10.1103/PhysRevLett.100.020603Fu et al., J. Phys. Chem. Lett. (2018);https://doi.org/10.1021/acs.jpclett.8b01994Hamelberg et al., J. Chem. Phys. (2004);https://doi.org/10.1063/1.1755656Miao et al., J. Chem. Theory Comput. (2015);https://doi.org/10.1021/acs.jctc.5b00436Zhao et al., J. Phys. Chem. Lett. (2023);https://doi.org/10.1021/acs.jpclett.2c03688Chen et al., J. Chem. Theory Comput. (2021);https://doi.org/10.1021/acs.jctc.1c00103Semelak et al., J. Chem. Theory Comput. (2023);https://doi.org/10.1021/acs.jctc.3c00366Branduardi, et al., J. Chem. Phys. (2007);https://doi.org/10.1063/1.2432340Leines et al., Phys. Ref. Lett. (2012);https://doi.org/10.1103/PhysRevLett.109.020601This and Related Work:If you use this package in your work please cite:Hulm et al., J. Chem. Phys., 157, 024110 (2022);https://doi.org/10.1063/5.0095554Other related references:Dietschreit et al., J. Chem. Phys., (2022);https://aip.scitation.org/doi/10.1063/5.0102075Hulm et al., J. Chem. Theory. Comput., (2023);https://doi.org/10.1021/acs.jctc.3c00938Stan et. al., ACS Cent. Sci., (2024);https://doi.org/10.1021/acscentsci.3c01403