adaptive-sampling


Nameadaptive-sampling JSON
Version 3.0.1 PyPI version JSON
download
home_pagehttps://github.com/ochsenfeld-lab/adaptive_sampling
SummarySampling algorithms for molecular transitions
upload_time2024-02-01 11:51:37
maintainer
docs_urlNone
authorAndreas Hulm
requires_python
licenseMIT
keywords computational chemistry molecular dynamics free energy chemical reactions
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            Adaptive Sampling
=================

This 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 thereof

*   Coordination numbers 

*   Minimized Cartesian RMSD (Kabsch algorithm)

*   Adaptive path collective variables (PCVs) [12, 13]

## Install:
To install adaptive_sampling type:
```shell
$ pip install adaptive-sampling
```


## Requirements:
* python >= 3.8
* numpy >= 1.19
* torch >= 1.10
* scipy >= 1.7

## Basic Usage:
To use adaptive sampling with your MD code of choice add a function called `get_sampling_data()` to the corresponding python interface that returns an object containing all required data. Hard-coded dependencies can be avoided by wrapping the `adaptive_sampling` import in a `try/except` clause:

```python
class MD:
    # Your MD code
    ...

    def get_sampling_data(self):
        try:
            from adaptive_sampling.interface.sampling_data import SamplingData

            mass   = ...
            coords = ...
            forces = ...
            epot   = ...
            temp   = ...
            natoms = ...
            step   = ...
            dt     = ...

            return SamplingData(mass, coords, forces, epot, temp, natoms, step, dt)
        except ImportError as e:
            raise NotImplementedError("`get_sampling_data()` is missing `adaptive_sampling` package") from e
```
The bias force on atoms in the N-th step can be obtained by calling `step_bias()` on any sampling algorithm:
```python
from adaptive_sampling.sampling_tools import *

# initialize MD code
the_md = MD(...)

# collective variable
atom_indices = [0, 1] 
minimum   = 1.0  # Angstrom
maximum   = 3.5  # Angstrom
bin_width = 0.1  # Angstrom 
collective_var = [["distance", atom_indices, minimum, maximum, bin_width]]

# extended-system eABF 
ext_sigma = 0.1  # thermal width of coupling between CV and extended variable in Angstrom
ext_mass = 20.0  # mass of extended variable 
the_bias = eABF(
    ext_sigma, 
    ext_mass, 
    the_md, 
    collective_var, 
    output_freq=10, 
    f_conf=100, 
    equil_temp=300.0
)

for md_step in range(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_step
```
This 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:
```python
import numpy as np
from adaptive_sampling.processing_tools import mbar

traj_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 sampling
minimum   = 1.0     
maximum   = 3.5    
bin_width = 0.1    
grid = np.arange(minimum, maximum, bin_width)

cv = traj_dat[:,1]  # trajectory of collective variable
la = traj_dat[:,2]  # trajectory of extended system

# run MBAR and compute free energy profile and probability density from statistical weights
traj_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:
```shell
$ pip install pdoc3
$ pdoc --html adaptive_sampling -o doc/
```
## References:
1.  Comer et al., J. Phys. Chem. B (2015); <https://doi.org/10.1021/jp506633n> 
2.  Lesage et al., J. Phys. Chem. B (2017); <https://doi.org/10.1021/acs.jpcb.6b10055>
3.  Shirts et al., J. Chem. Phys. (2008); <https://doi.org/10.1063/1.2978177>
4.  Hulm et al., J. Chem. Phys. (2022); <https://doi.org/10.1063/5.0095554>
5.  Barducci et al., Phys. rev. lett. (2008); <https://doi.org/10.1103/PhysRevLett.100.020603>
6.  Fu et al., J. Phys. Chem. Lett. (2018); <https://doi.org/10.1021/acs.jpclett.8b01994>
7.  Hamelberg et al., J. Chem. Phys. (2004); <https://doi.org/10.1063/1.1755656>
8.  Miao et al., J. Chem. Theory Comput. (2015); <https://doi.org/10.1021/acs.jctc.5b00436>
9.  Zhao et al., J. Phys. Chem. Lett. (2023); <https://doi.org/10.1021/acs.jpclett.2c03688>
10.  Chen et al., J. Chem. Theory Comput. (2021); <https://doi.org/10.1021/acs.jctc.1c00103>
11.  Semelak et al., J. Chem. Theory Comput. (2023); <https://doi.org/10.1021/acs.jctc.3c00366>
12.  Branduardi, et al., J. Chem. Phys. (2007); <https://doi.org/10.1063/1.2432340>
13.  Leines et al., Phys. Ref. Lett. (2012); <https://doi.org/10.1103/PhysRevLett.109.020601>

## This 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.0095554>

Other related references:
*	Dietschreit et al., J. Chem. Phys., (2022); <https://aip.scitation.org/doi/10.1063/5.0102075>
*   Hulm et al., J. Chem. Theory. Comput., (2023); <https://doi.org/10.1021/acs.jctc.3c00938>
*   Stan et. al., ACS Cent. Sci., (2024); <https://doi.org/10.1021/acscentsci.3c01403>

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/ochsenfeld-lab/adaptive_sampling",
    "name": "adaptive-sampling",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "computational chemistry,molecular dynamics,free energy,chemical reactions",
    "author": "Andreas Hulm",
    "author_email": "andreas.hulm@cup.uni-muenchen.de",
    "download_url": "https://files.pythonhosted.org/packages/5b/0a/2c7135468c615f0cb508e11dbf7a870519cf5b49191d5fe1488a4183ecf4/adaptive_sampling-3.0.1.tar.gz",
    "platform": null,
    "description": "Adaptive Sampling\n=================\n\nThis package implements various sampling algorithms for the calculation of free energy profiles of molecular transitions. \n\n## Available Sampling Methods Include:\n*\tAdaptive Biasing Force (ABF) method [1] \n\t\n* \tExtended-system ABF (eABF) [2]\n\n\t* On-the-fly free energy estimate from the Corrected Z-Averaged Restraint (CZAR) [2]\n\t\n\t* Application of Multistate Bannett's Acceptance Ratio (MBAR) [3] to recover full statistical information in post-processing [4]\n\t\n* \t(Well-Tempered) Metadynamics (WTM) [5] and WTM-eABF [6]\n\n* \tAccelerated MD (aMD), Gaussian accelerated MD (GaMD), Sigmoid Accelerated MD (SaMD) [7, 8, 9]\n\n*\tGaussian-accelerated WTM-eABF [10]\n\n*   Free-energy Nudged Elastic Band Method [11]\n\n## Implemented Collective Variables:\n\n*   Distances, angles and torsion angles as well as linear combinations thereof\n\n*   Coordination numbers \n\n*   Minimized Cartesian RMSD (Kabsch algorithm)\n\n*   Adaptive path collective variables (PCVs) [12, 13]\n\n## Install:\nTo install adaptive_sampling type:\n```shell\n$ pip install adaptive-sampling\n```\n\n\n## Requirements:\n* python >= 3.8\n* numpy >= 1.19\n* torch >= 1.10\n* scipy >= 1.7\n\n## Basic Usage:\nTo use adaptive sampling with your MD code of choice add a function called `get_sampling_data()` to the corresponding python interface that returns an object containing all required data. Hard-coded dependencies can be avoided by wrapping the `adaptive_sampling` import in a `try/except` clause:\n\n```python\nclass MD:\n    # Your MD code\n    ...\n\n    def get_sampling_data(self):\n        try:\n            from adaptive_sampling.interface.sampling_data import SamplingData\n\n            mass   = ...\n            coords = ...\n            forces = ...\n            epot   = ...\n            temp   = ...\n            natoms = ...\n            step   = ...\n            dt     = ...\n\n            return SamplingData(mass, coords, forces, epot, temp, natoms, step, dt)\n        except ImportError as e:\n            raise NotImplementedError(\"`get_sampling_data()` is missing `adaptive_sampling` package\") from e\n```\nThe bias force on atoms in the N-th step can be obtained by calling `step_bias()` on any sampling algorithm:\n```python\nfrom adaptive_sampling.sampling_tools import *\n\n# initialize MD code\nthe_md = MD(...)\n\n# collective variable\natom_indices = [0, 1] \nminimum   = 1.0  # Angstrom\nmaximum   = 3.5  # Angstrom\nbin_width = 0.1  # Angstrom \ncollective_var = [[\"distance\", atom_indices, minimum, maximum, bin_width]]\n\n# extended-system eABF \next_sigma = 0.1  # thermal width of coupling between CV and extended variable in Angstrom\next_mass = 20.0  # mass of extended variable \nthe_bias = eABF(\n    ext_sigma, \n    ext_mass, \n    the_md, \n    collective_var, \n    output_freq=10, \n    f_conf=100, \n    equil_temp=300.0\n)\n\nfor md_step in range(steps):\n    # propagate langevin dynamics and calc forces \n    ... \n    bias_force = the_bias.step_bias(write_output=True, write_traj=True)\n    the_md.forces += bias_force\n    ...\n    # finish md_step\n```\nThis automatically writes an on-the-fly free energy estimate in the output file and all necessary data for post-processing in a trajectory file.\nFor extended-system dynamics unbiased statistical weights of individual frames can be obtained using the MBAR estimator:\n```python\nimport numpy as np\nfrom adaptive_sampling.processing_tools import mbar\n\ntraj_dat = np.loadtxt('CV_traj.dat', skiprows=1)\next_sigma = 0.1    # thermal width of coupling between CV and extended variable \n\n# grid for free energy profile can be different than during sampling\nminimum   = 1.0     \nmaximum   = 3.5    \nbin_width = 0.1    \ngrid = np.arange(minimum, maximum, bin_width)\n\ncv = traj_dat[:,1]  # trajectory of collective variable\nla = traj_dat[:,2]  # trajectory of extended system\n\n# run MBAR and compute free energy profile and probability density from statistical weights\ntraj_list, indices, meta_f = mbar.get_windows(grid, cv, la, ext_sigma, equil_temp=300.0)\n\nexp_U, frames_per_traj = mbar.build_boltzmann(\n    traj_list, \n    meta_f, \n    equil_temp=300.0,\n)\n\nweights = mbar.run_mbar(\n    exp_U,\n    frames_per_traj,\n    max_iter=10000,\n    conv=1.0e-7,\n    conv_errvec=1.0,\n    outfreq=100,\n    device='cpu',\n)\n\npmf, rho = mbar.pmf_from_weights(grid, cv[indices], weights, equil_temp=300.0)\n```\n\n## Documentation:\nCode documentation can be created with pdoc3:\n```shell\n$ pip install pdoc3\n$ pdoc --html adaptive_sampling -o doc/\n```\n## References:\n1.  Comer et al., J. Phys. Chem. B (2015); <https://doi.org/10.1021/jp506633n> \n2.  Lesage et al., J. Phys. Chem. B (2017); <https://doi.org/10.1021/acs.jpcb.6b10055>\n3.  Shirts et al., J. Chem. Phys. (2008); <https://doi.org/10.1063/1.2978177>\n4.  Hulm et al., J. Chem. Phys. (2022); <https://doi.org/10.1063/5.0095554>\n5.  Barducci et al., Phys. rev. lett. (2008); <https://doi.org/10.1103/PhysRevLett.100.020603>\n6.  Fu et al., J. Phys. Chem. Lett. (2018); <https://doi.org/10.1021/acs.jpclett.8b01994>\n7.  Hamelberg et al., J. Chem. Phys. (2004); <https://doi.org/10.1063/1.1755656>\n8.  Miao et al., J. Chem. Theory Comput. (2015); <https://doi.org/10.1021/acs.jctc.5b00436>\n9.  Zhao et al., J. Phys. Chem. Lett. (2023); <https://doi.org/10.1021/acs.jpclett.2c03688>\n10.  Chen et al., J. Chem. Theory Comput. (2021); <https://doi.org/10.1021/acs.jctc.1c00103>\n11.  Semelak et al., J. Chem. Theory Comput. (2023); <https://doi.org/10.1021/acs.jctc.3c00366>\n12.  Branduardi, et al., J. Chem. Phys. (2007); <https://doi.org/10.1063/1.2432340>\n13.  Leines et al., Phys. Ref. Lett. (2012); <https://doi.org/10.1103/PhysRevLett.109.020601>\n\n## This and Related Work:\nIf you use this package in your work please cite:\n* \tHulm et al., J. Chem. Phys., 157, 024110 (2022); <https://doi.org/10.1063/5.0095554>\n\nOther related references:\n*\tDietschreit et al., J. Chem. Phys., (2022); <https://aip.scitation.org/doi/10.1063/5.0102075>\n*   Hulm et al., J. Chem. Theory. Comput., (2023); <https://doi.org/10.1021/acs.jctc.3c00938>\n*   Stan et. al., ACS Cent. Sci., (2024); <https://doi.org/10.1021/acscentsci.3c01403>\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Sampling algorithms for molecular transitions",
    "version": "3.0.1",
    "project_urls": {
        "Download": "https://github.com/ochsenfeld-lab/adaptive_sampling/archive/refs/tags/v3.0.0.zip",
        "Homepage": "https://github.com/ochsenfeld-lab/adaptive_sampling"
    },
    "split_keywords": [
        "computational chemistry",
        "molecular dynamics",
        "free energy",
        "chemical reactions"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "5b0a2c7135468c615f0cb508e11dbf7a870519cf5b49191d5fe1488a4183ecf4",
                "md5": "8bdda6878e3f66a2adcdad67dd3ff3e7",
                "sha256": "e6192bd9e6e28d4533d6890bfea8f877a1e895ea78e25f610b6f9a73757325ca"
            },
            "downloads": -1,
            "filename": "adaptive_sampling-3.0.1.tar.gz",
            "has_sig": false,
            "md5_digest": "8bdda6878e3f66a2adcdad67dd3ff3e7",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 61458,
            "upload_time": "2024-02-01T11:51:37",
            "upload_time_iso_8601": "2024-02-01T11:51:37.938197Z",
            "url": "https://files.pythonhosted.org/packages/5b/0a/2c7135468c615f0cb508e11dbf7a870519cf5b49191d5fe1488a4183ecf4/adaptive_sampling-3.0.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-02-01 11:51:37",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "ochsenfeld-lab",
    "github_project": "adaptive_sampling",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "adaptive-sampling"
}
        
Elapsed time: 4.50403s