README.md 4.95 KB
Newer Older
Xiang Gao's avatar
Xiang Gao committed
1
# <img src=https://raw.githubusercontent.com/aiqm/torchani/master/logo1.png width=180/>  Accurate Neural Network Potential on PyTorch
Gao, Xiang's avatar
Gao, Xiang committed
2

3
4
5
6
7
8
Metrics:

![PyPI](https://img.shields.io/pypi/v/torchani.svg)
![PyPI - Downloads](https://img.shields.io/pypi/dm/torchani.svg)

Checks:
9
10
11

[![Actions Status](https://github.com/aiqm/torchani/workflows/docs/badge.svg)](https://github.com/aiqm/torchani/actions)
[![Actions Status](https://github.com/aiqm/torchani/workflows/flake8/badge.svg)](https://github.com/aiqm/torchani/actions)
12
[![Actions Status](https://github.com/aiqm/torchani/workflows/mypy/badge.svg)](https://github.com/aiqm/torchani/actions)
13
14
15
[![Actions Status](https://github.com/aiqm/torchani/workflows/runnable%20submodules/badge.svg)](https://github.com/aiqm/torchani/actions)
[![Actions Status](https://github.com/aiqm/torchani/workflows/tools/badge.svg)](https://github.com/aiqm/torchani/actions)
[![Actions Status](https://github.com/aiqm/torchani/workflows/unit%20tests/badge.svg)](https://github.com/aiqm/torchani/actions)
16
[![CodeFactor](https://www.codefactor.io/repository/github/aiqm/torchani/badge/master)](https://www.codefactor.io/repository/github/aiqm/torchani/overview/master)
Gao, Xiang's avatar
Gao, Xiang committed
17
[![Total alerts](https://img.shields.io/lgtm/alerts/g/aiqm/torchani.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/aiqm/torchani/alerts/)
Gao, Xiang's avatar
Gao, Xiang committed
18

19
Deploy:
20

21
22
[![Actions Status](https://github.com/aiqm/torchani/workflows/deploy-docs/badge.svg)](https://github.com/aiqm/torchani/actions)
[![Actions Status](https://github.com/aiqm/torchani/workflows/deploy-pypi/badge.svg)](https://github.com/aiqm/torchani/actions)
23

24
25
26
27
28
We only provide compatibility with nightly PyTorch, but you can check if stable PyTorch happens to be supported by looking at the following badge:

[![Actions Status](https://github.com/aiqm/torchani/workflows/stable-torch/badge.svg)](https://github.com/aiqm/torchani/actions)


Gao, Xiang's avatar
Gao, Xiang committed
29
TorchANI is a pytorch implementation of ANI. It is currently under alpha release, which means, the API is not stable yet. If you find a bug of TorchANI, or have some feature request, feel free to open an issue on GitHub, or send us a pull request.
Gao, Xiang's avatar
Gao, Xiang committed
30

Xiang Gao's avatar
Xiang Gao committed
31
32
<img src=https://raw.githubusercontent.com/aiqm/torchani/master/logo2.png width=500/>

33

Gao, Xiang's avatar
Gao, Xiang committed
34
35
# Install

36
TorchANI requires the latest preview version of PyTorch. Please install PyTorch before installing TorchANI.
Gao, Xiang's avatar
Gao, Xiang committed
37

38
39
40
Please see [PyTorch's official site](https://pytorch.org/get-started/locally/) for instructions of installing latest preview version of PyTorch.

Note that if you updated TorchANI, you may also need to update PyTorch.
41

42
After installing the correct PyTorch, you can install TorchANI by `pip` or `conda`:
43

Richard Xue's avatar
Richard Xue committed
44
```bash
45
pip install torchani
46
```
Gao, Xiang's avatar
Gao, Xiang committed
47

48
or
Gao, Xiang's avatar
Gao, Xiang committed
49
50

```bash
51
conda install -c conda-forge torchani
Gao, Xiang's avatar
Gao, Xiang committed
52
53
```

54
See https://github.com/conda-forge/torchani-feedstock for more information about the conda package.
Gao, Xiang's avatar
Gao, Xiang committed
55

56
57
58
59
60
61
To run the tests and examples, you must manually download a data package

```bash
./download.sh
```

62

63
# Citation
Gao, Xiang's avatar
Gao, Xiang committed
64

65
Please cite the following paper if you use TorchANI 
Gao, Xiang's avatar
Gao, Xiang committed
66

67
68
69
* Xiang Gao, Farhad Ramezanghorbani, Olexandr Isayev, Justin S. Smith, and Adrian E. Roitberg. *TorchANI: A Free and Open Source PyTorch Based Deep Learning Implementation of the ANI Neural Network Potentials*. Journal of Chemical Information and Modeling 2020 60 (7), 3408-3415, [![DOI for Citing](https://img.shields.io/badge/DOI-10.1021%2Facs.jcim.0c00451-green.svg)](https://doi.org/10.1021/acs.jcim.0c00451)

[![JCIM Cover](https://pubs.acs.org/na101/home/literatum/publisher/achs/journals/content/jcisd8/2020/jcisd8.2020.60.issue-7/jcisd8.2020.60.issue-7/20200727/jcisd8.2020.60.issue-7.largecover.jpg)](https://pubs.acs.org/toc/jcisd8/60/7)
70
71

* Please refer to [isayev/ASE_ANI](https://github.com/isayev/ASE_ANI) for ANI model references.
72
73
74
75
76
77

# ANI model parameters
All the ANI model parameters including (ANI2x, ANI1x, and ANI1ccx) are accessible from the following repositories:
- [isayev/ASE_ANI](https://github.com/isayev/ASE_ANI)
- [aiqm/ani-model-zoo](https://github.com/aiqm/ani-model-zoo)

78
79
80
81
82
83
84
85
86
87
88
89
90
91

# Develop

To install TorchANI from GitHub:

```bash
git clone https://github.com/aiqm/torchani.git
cd torchani
pip install -e .
```

After TorchANI has been installed, you can build the documents by running `sphinx-build docs build`. But make sure you
install dependencies:
```bash
92
pip install -r docs_requirements.txt
93
94
```

95
96
97
98
99
To manually run unit tests, do

```bash
pytest -v
```
100

101
102
103
104
If you opened a pull request, you could see your generated documents at https://aiqm.github.io/torchani-test-docs/ after you `docs` check succeed.
Keep in mind that this repository is only for the purpose of convenience of development, and only keeps the latest push.
The CI runing for other pull requests might overwrite this repository. You could rerun the `docs` check to overwrite this repo to your build.

105

Gao, Xiang's avatar
Gao, Xiang committed
106
# Note to TorchANI developers
Gao, Xiang's avatar
Gao, Xiang committed
107
108
109
110
111

Never commit to the master branch directly. If you need to change something, create a new branch, submit a PR on GitHub.

You must pass all the tests on GitHub before your PR can be merged.

Gao, Xiang's avatar
Gao, Xiang committed
112
Code review is required before merging pull request.