Merge remote-tracking branch 'origin/main' into log_time

.github/workflows/CI.yml

@@ -44,3 +44,7 @@ jobs:
 
       - name: Run tests
         run: pytest -v -s
+
+      - name: Test torchmd-train utility
+        run: torchmd-train --help
+

.github/workflows/docs_build.yaml

@@ -0,0 +1,36 @@
+name: Build Documentation
+
+on:
+  push:
+    branches:
+      - "main"
+  pull_request:
+    branches:
+      - "main"
+
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Set up Env
+      uses: mamba-org/setup-micromamba@v1
+      with:
+        environment-file: environment.yml
+        init-shell: bash
+        generate-run-shell: true
+
+    - name: Install docs dependencies
+      run: |
+        pip install -vv .
+        pip install -r docs/requirements.txt
+      shell: bash -el {0}
+
+    - name: Build Sphinx Documentation
+      run: |
+        cd docs
+        make html
+      shell: bash -el {0}

.gitignore

@@ -133,3 +133,11 @@ dmypy.json
 
 # temp directories
 logs/
+
+# Docs
+docs/build/
+docs/source/generated
+
+# Extra
+
+*~

.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: "2"
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+     python: "mambaforge-22.9"
+  jobs:
+     post_create_environment:
+       - pip install -r docs/requirements.txt
+       - pip install .
+
+conda:
+  environment: environment.yml
+
+
+sphinx:
+  configuration: docs/source/conf.py

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 www.compscience.org
+Copyright (c) 2021-2023 Universitat Pompeu Fabra,  https://www.compscience.org
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,10 +1,16 @@
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![CI](https://github.com/torchmd/torchmd-net/actions/workflows/CI.yml/badge.svg)](https://github.com/torchmd/torchmd-net/actions/workflows/CI.yml)
+[![Documentation Status](https://readthedocs.org/projects/torchmd-net/badge/?version=latest)](https://torchmd-net.readthedocs.io/en/latest/?badge=latest)  
 
 # TorchMD-NET
 
 TorchMD-NET provides state-of-the-art neural networks potentials (NNPs) and a mechanism to train them. It offers efficient and fast implementations if several NNPs and it is integrated in GPU-accelerated molecular dynamics code like [ACEMD](https://www.acellera.com/products/molecular-dynamics-software-gpu-acemd/), [OpenMM](https://www.openmm.org) and [TorchMD](https://github.com/torchmd/torchmd). TorchMD-NET exposes its NNPs as [PyTorch](https://pytorch.org) modules.
 
+
+## Documentation
+
+Documentation is available at https://torchmd-net.readthedocs.io  
+
 ## Available architectures
 
 - [Equivariant Transformer (ET)](https://arxiv.org/abs/2202.02541)
@@ -13,28 +19,17 @@ TorchMD-NET provides state-of-the-art neural networks potentials (NNPs) and a me
 - [TensorNet](https://arxiv.org/abs/2306.06482)
 
 
-## Installation
 
-1. Clone the repository:
-    ```shell
-    git clone https://github.com/torchmd/torchmd-net.git
-    cd torchmd-net
-    ```
-
-2. Install [Mambaforge](https://github.com/conda-forge/miniforge/#mambaforge). We recommend to use `mamba` rather than `conda`.
+## Installation  
+TorchMD-Net is available in [conda-forge](https://conda-forge.org/) and can be installed with:  
+```shell
+mamba install torchmd-net
+```
+We recommend using [Mamba](https://github.com/conda-forge/miniforge/#mambaforge) instead of conda.  
 
-3. Create an environment and activate it:
-    ```shell
-    mamba env create -f environment.yml
-    mamba activate torchmd-net
-    ```
+### Install from source  
 
-4. Install TorchMD-NET into the environment:
-    ```shell
-    pip install -e .
-    ```
-This will install TorchMD-NET in editable mode, so that changes to the source code are immediately available.
-Besides making all python utilities available environment-wide, this will also install the `torchmd-train` command line utility.
+TorchMD-Net is installed using pip, but you will need to install some dependencies before. Check [this documentation page](https://torchmd-net.readthedocs.io/en/latest/installation.html#install-from-source).  
 
 ## Usage
 Specifying training arguments can either be done via a configuration yaml file or through command line arguments directly. Several examples of architectural and training specifications for some models and datasets can be found in [examples/](https://github.com/torchmd/torchmd-net/tree/main/examples). Note that if a parameter is present both in the yaml file and the command line, the command line version takes precedence.
@@ -104,26 +99,30 @@ url={https://openreview.net/forum?id=zNHzqZ9wrRB}
 #### Graph Network 
 
 ```
-@misc{majewski2022machine,
-      title={Machine Learning Coarse-Grained Potentials of Protein Thermodynamics}, 
-      author={Maciej Majewski and Adrià Pérez and Philipp Thölke and Stefan Doerr and Nicholas E. Charron and Toni Giorgino and Brooke E. Husic and Cecilia Clementi and Frank Noé and Gianni De Fabritiis},
-      year={2022},
-      eprint={2212.07492},
-      archivePrefix={arXiv},
-      primaryClass={q-bio.BM}
+@article{Majewski2023,
+  title = {Machine learning coarse-grained potentials of protein thermodynamics},
+  volume = {14},
+  ISSN = {2041-1723},
+  url = {http://dx.doi.org/10.1038/s41467-023-41343-1},
+  DOI = {10.1038/s41467-023-41343-1},
+  number = {1},
+  journal = {Nature Communications},
+  publisher = {Springer Science and Business Media LLC},
+  author = {Majewski,  Maciej and Pérez,  Adrià and Th\"{o}lke,  Philipp and Doerr,  Stefan and Charron,  Nicholas E. and Giorgino,  Toni and Husic,  Brooke E. and Clementi,  Cecilia and Noé,  Frank and De Fabritiis,  Gianni},
+  year = {2023},
+  month = sep 
 }
 ```
 
 #### TensorNet
 
 ```
-@misc{simeon2023tensornet,
-      title={TensorNet: Cartesian Tensor Representations for Efficient Learning of Molecular Potentials}, 
-      author={Guillem Simeon and Gianni de Fabritiis},
-      year={2023},
-      eprint={2306.06482},
-      archivePrefix={arXiv},
-      primaryClass={cs.LG}
+@inproceedings{simeon2023tensornet,
+title={TensorNet: Cartesian Tensor Representations for Efficient Learning of Molecular Potentials},
+author={Guillem Simeon and Gianni De Fabritiis},
+booktitle={Thirty-seventh Conference on Neural Information Processing Systems},
+year={2023},
+url={https://openreview.net/forum?id=BEHlPdBZ2e}
 }
 ```
 

benchmarks/inference.py

@@ -1,3 +1,7 @@
+# Copyright Universitat Pompeu Fabra 2020-2023  https://www.compscience.org
+# Distributed under the MIT License.
+# (See accompanying file README.md file or copy at http://opensource.org/licenses/MIT)
+
 """
 Benchmark script for inference.
 This script compiles a model using torch.compile and measures the time it takes to run a forward and backward pass for a certain molecule.

benchmarks/neighbors.py

@@ -1,3 +1,7 @@
+# Copyright Universitat Pompeu Fabra 2020-2023  https://www.compscience.org
+# Distributed under the MIT License.
+# (See accompanying file README.md file or copy at http://opensource.org/licenses/MIT)
+
 import os
 import torch
 import numpy as np

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/style.css

@@ -0,0 +1,59 @@
+@import 'theme.css';
+
+.rst-content dl:not(.docutils) dt:first-child {
+  margin-top: 0;
+}
+
+.rst-content dl:not(.docutils) dl dt {
+    margin-bottom: 4px;
+    border: none;
+    border-left: solid 3px #ccc;
+    background: #f0f0f0;
+    color: #555;
+}
+
+.rst-content dl table,
+.rst-content dl ul,
+.rst-content dl ol,
+.rst-content dl p {
+    margin-bottom: 8px !important;
+}
+
+.rst-content dl:not(.docutils) dt {
+    display: table;
+    margin: 6px 0;
+    font-size: 90%;
+    line-height: normal;
+    background: #e7f2fa;
+    color: #2980B9;
+    border-top: solid 3px #6ab0de;
+    padding: 6px;
+    position: relative;
+}
+
+html.writer-html5 .rst-content dl.field-list {
+    display: initial;
+}
+
+html.writer-html5 .rst-content dl.field-list>dd,
+html.writer-html5 .rst-content dl.field-list>dt {
+    margin-bottom: 4px;
+    padding-left: 6px;
+}
+
+p {
+    line-height: 20px;
+    font-size: 14px;
+}
+
+html.writer-html5 .rst-content dl.field-list>dt:after {
+    content: initial;
+}
+
+dt.field-even {
+    text-transform: uppercase;
+}
+
+dt.field-odd {
+    text-transform: uppercase;
+}

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,5 @@
+sphinx==7.2.6
+sphinx-rtd-theme==1.3.0
+sphinxcontrib-autoprogram==0.1.8
+sphinxcontrib-napoleon==0.7
+gitpython

docs/source/api.rst

@@ -0,0 +1,10 @@
+API Reference
+=============
+
+.. autosummary::
+   :toctree: generated
+   :recursive:
+
+   torchmdnet
+
+