README and docs update #275

Author: pabloferz

README.md

@@ -27,46 +27,54 @@
 PySAGES (Python Suite for Advanced General Ensemble Simulations) is a Python
 implementation of [SSAGES](https://ssagesproject.github.io) with support for GPUs.
 
-**NOTICE**: This is in early stages of development. Expect breaking changes.
-
 ## Installation
 
-Currently, there is only support for
-[HOOMD-blue](https://glotzerlab.engin.umich.edu/hoomd-blue) and
-[OpenMM](http://openmm.org/), but gradual support for other molecular dynamics engines is
-planned (for instance, for all engines already supported by the original SSAGES).
+PySAGES currently supports [HOOMD-blue](https://glotzerlab.engin.umich.edu/hoomd-blue),
+[LAMMPS](https://www.lammps.org), [ASE](https://wiki.fysik.dtu.dk/ase/index.html), and
+[OpenMM](https://openmm.org). We plan to add support for other engines that have a python
+API, including those supported by the original SSAGES.
 
-You first need to install one of the following plugins depending on your molecular
-dynamics engine:
+Before installing PySAGES, you need to install one of the following plugins, depending on
+your molecular dynamics engine of choice:
 
-- For HOOMD-blue visit [HOOMD DLPack Plugin](https://github.com/SSAGESLabs/hoomd-dlext).
-- For OpenMM go to [OpenMM DLPack Plugin](https://github.com/SSAGESLabs/openmm-dlext).
+- [DLPack Plugin for HOOMD-blue](https://github.com/SSAGESLabs/hoomd-dlext)
+- [DLPack Plugin for OpenMM](https://github.com/SSAGESLabs/openmm-dlext)
+- [DLPack Plugin for LAMMPS](https://github.com/SSAGESLabs/lammps-dlext)
+- No plugin needed for ASE
 
-PySAGES also depends on [JAX](https://github.com/google/jax/), follow their installation
-guide to set it up. _NOTE:_ make sure you have jaxlib installed before using PySAGES.
-Depending on your local setup, you will have to install the jaxlib CPU version or the CUDA compatible flavor.
+You also need to install [JAX](https://github.com/google/jax), a library for
+high-performance numerical computing. Follow their installation guide and make sure you
+have it installed before using PySAGES. Depending on your local setup, you may need
+to install the CPU version or the CUDA compatible version.
 
-To test GPU support HOOMD-blue, HOOMD-dlext and JAX need to be built or installed with
-CUDA support.
+For GPU support, JAX and any backend (HOOMD-blue, LAMMPS, or OpenMM) need to be built or
+installed with CUDA support.
 
-Our installation tutorial on Google Colab enable you to see how PySAGES,
-HOOMD-blue and OpenMM can be built and installed into such environment.
-[![Install Env](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/SSAGESLabs/PySAGES/blob/main/examples/Install_PySAGES_Environment.ipynb)
+You can follow our installation tutorial on Google Colab to see how PySAGES, HOOMD-blue,
+and OpenMM can be built and installed in such an environment.
+[![Colab Badge]][Install Notebook]
 
 ## Usage
 
-PySAGES provide a straightforward interface to setup Collective Variables and Enhanced
-Sampling methods in your MD simulations. See the [documentation](https://pysages.readthedocs.io/en/latest/) to learn more.
+PySAGES provides a straightforward interface to set up collective variables and enhanced
+sampling methods in your MD simulations. See the
+[documentation](https://pysages.readthedocs.io/en/latest) to learn more.
 
-We provide ready-to-go examples for common methods.
-Checkout out the [examples](examples/) subfolder to look at different script and notebook examples.
-These include pre-set simulations and a tutorial on how to install PySAGES along with the supported MD engines.
+We provide ready-to-go examples for common methods. Check out the [examples](examples/)
+subfolder to look at different script and notebook examples. These include pre-set
+simulations and a tutorial on how to install PySAGES along with the supported MD engines.
 
 ## Development
 
-We believe in good software engineering and collaboration.
-As an open-source software we welcome all contributions.
-To ease collaboration we use [trunk](https://trunk.io) as a development tool free for open-source software.
-This includes version-checked linters that can be run automatically.
-We ship a launcher for trunk with this repo `./trunk`, no installation required.
-For details about how to use `./trunk fmt` to format existing code into this style and `./trunk check` to verify a consistent code style, check out the trunk documentation [page](https://docs.trunk.io/docs).
+We believe in good software engineering and collaboration. We welcome all contributions.
+To ease collaboration, we use [trunk](https://trunk.io) as a development tool free for
+open-source software. This includes version-checked linters that can be run automatically.
+We ship a launcher for trunk with this repo: `./trunk`, no installation required. For
+details about how to use `./trunk fmt` to format existing code into this style and
+`./trunk check` to verify a consistent code style, check out the [trunk documentation
+page](https://docs.trunk.io/docs).
+
+<!-- References -->
+
+[Colab Badge]: https://colab.research.google.com/assets/colab-badge.svg
+[Install Notebook]: https://colab.research.google.com/github/SSAGESLabs/PySAGES/blob/main/examples/Install_PySAGES_Environment.ipynb

docs/requirements.txt

@@ -1,6 +1,7 @@
 furo
 jaxlib
 myst-parser
+setuptools-scm
 sphinx
 sphinx-copybutton
 sphinx-design

docs/source/conf.py

@@ -4,6 +4,8 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+from setuptools_scm import get_version
+
 # -- Path setup --------------------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -24,8 +26,7 @@
 author = "PySAGES Team (Pablo Zubieta, Ludwig Schneider, Gustavo Pérez-Lemus, et al.)"
 
 # The full version, including alpha/beta/rc tags
-release = "0.2.0"
-version = "0.2.0"
+release = version = get_version(root="../..")
 
 # -- General configuration ---------------------------------------------------
 
@@ -62,6 +63,7 @@
 
 html_logo = "_static/pysages-bottom.svg"
 html_show_sphinx = False
+html_title = "PySAGES documentation"
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.

docs/source/index.md

@@ -1,6 +1,6 @@
 <!--
-You can adapt this file completely to your liking, but it
-should at least contain the root ```{toctree}``` block.
+You can adapt this file completely to your liking, but it should contain
+the root ```{toctree}``` block.
 -->
 
 # Python Suite for Advanced General Ensemble Simulations
@@ -12,9 +12,9 @@ should at least contain the root ```{toctree}``` block.
 :padding: 0
 
 ```{grid-item}
-[![CI]](https://github.com/SSAGESLabs/PySAGES/actions/workflows/ci.yml) &nbsp;
-[![Docker CI]](https://github.com/SSAGESLabs/PySAGES/actions/workflows/docker-ci.yml) &nbsp;
-[![Trunk]](https://github.com/SSAGESLabs/PySAGES/actions/workflows/trunk.yml)
+[![CI Badge]](https://github.com/SSAGESLabs/PySAGES/actions/workflows/ci.yml)  &nbsp;
+[![Docker CI Badge]](https://github.com/SSAGESLabs/PySAGES/actions/workflows/docker-ci.yml)  &nbsp;
+[![Trunk Badge]](https://github.com/SSAGESLabs/PySAGES/actions/workflows/trunk.yml)
 ```
 ````
 
@@ -42,12 +42,12 @@ this [interactive introduction][Intro] with PySAGES. Even better, PySAGES alread
 an extensible framework to compute collective variables and to perform enhanced-sampling
 MD simulations to discover reaction pathways and estimate free energies. Most research
 objectives are achievable by using these implemented collective variables and methods.
-PySAGES currently supports automatically connecting these methods to [HOOMD-blue] and
-[OpenMM]. Both engines offer a python interface to the user and implement the simulation
-on GPUs for best performance. PySAGES interacts with both backends directly on the GPU
-memory; copying between GPU and host memory is not required. This approach allows biased
-simulations without slowing the backend simulation engines down. PySAGES still implements
-all methods and collective variables as pure python for access and modification.
+PySAGES currently supports automatically connecting these methods to [ASE], [HOOMD-blue],
+[LAMMPS], and [OpenMM]. PySAGES communicates with these backends without copying data
+between GPU and host memory, except for ASE, which does not support GPU calculations
+directly. This approach allows biased simulations without slowing the backend simulation
+engines down. PySAGES still implements all methods and collective variables in pure python
+for access and modification.
 
 ## Indices and tables
 
@@ -66,9 +66,13 @@ mpi
 package-pysages
 ```
 
-[CI]: https://github.com/SSAGESLabs/PySAGES/actions/workflows/ci.yml/badge.svg?branch=main
-[Docker CI]: https://github.com/SSAGESLabs/PySAGES/actions/workflows/docker-ci.yml/badge.svg?branch=main
-[Trunk]: https://github.com/SSAGESLabs/PySAGES/actions/workflows/trunk.yml/badge.svg?branch=main
+<!-- References -->
+
+[CI Badge]: https://github.com/SSAGESLabs/PySAGES/actions/workflows/ci.yml/badge.svg?branch=main
+[Docker CI Badge]: https://github.com/SSAGESLabs/PySAGES/actions/workflows/docker-ci.yml/badge.svg?branch=main
+[Trunk Badge]: https://github.com/SSAGESLabs/PySAGES/actions/workflows/trunk.yml/badge.svg?branch=main
 [Intro]: https://colab.research.google.com/github/SSAGESLabs/PySAGES/blob/main/examples/Advanced_Sampling_Introduction.ipynb
+[ASE]: https://wiki.fysik.dtu.dk/ase/index.html
 [HOOMD-blue]: https://glotzerlab.engin.umich.edu/hoomd-blue
+[LAMMPS]: https://www.lammps.org
 [OpenMM]: https://openmm.org

docs/source/installation.md

@@ -0,0 +1,45 @@
+# Installation
+
+The dependencies for a PySAGES installation can change based on your desired simulation
+backend engine. Depending on your system setup, it may be necessary to reinstall the
+simulation backend, especially if you do not have write permission for your current
+installation. On top of the current installation, it is required that you install a
+plugin that connects PySAGES with the simulation engine:
+
+- [DLPack Plugin for HOOMD-blue](https://github.com/SSAGESLabs/hoomd-dlext)
+- [DLPack Plugin for OpenMM](https://github.com/SSAGESLabs/openmm-dlext)
+- [DLPack Plugin for LAMMPS](https://github.com/SSAGESLabs/lammps-dlext)
+- No plugin needed for ASE
+
+You also need to install [JAX](https://github.com/google/jax), a library for
+high-performance numerical computing. Follow their installation guide and make sure you
+have it installed before using PySAGES. Depending on your local setup, you may need
+to install the CPU version or the CUDA compatible version.
+
+For GPU support, JAX and any backend (HOOMD-blue, LAMMPS, or OpenMM) need to be built or
+installed with CUDA support.
+
+Once the installation requirements are satisfied, PySAGES can be installed with `pip`:
+
+```shell
+pip install git+https://github.com/SSAGESLabs/PySAGES.git
+```
+
+or
+
+```shell
+git clone https://github.com/SSAGESLabs/PySAGES.git
+cd PySAGES
+pip install .
+```
+
+For the latest version of PySAGES, it is possible to deploy simulations with a [docker
+container](https://hub.docker.com/r/ssages/pysages). However, at the moment we cannot
+guarantee a stable docker image for PySAGES.
+
+You can follow our installation tutorial on Google Colab to see how PySAGES, HOOMD-blue,
+and OpenMM can be built and installed in such an environment: [Install Notebook].
+
+<!-- References -->
+
+[Install Notebook]: https://colab.research.google.com/github/SSAGESLabs/PySAGES/blob/main/examples/Install_PySAGES_Environment.ipynb