mdstudio/charge_assign repository overview

⁠charge_assign

⁠Requirements

• networkx⁠ >= 2.0

• msgpack-python⁠ >= 0.4.8

• numpy⁠ >= 1.14.0

• nauty⁠ >= 26r7 (This modules relies on the dreadnaut executable which is part of the nauty package.)

• optional: rdkit⁠ >= v2017.03.3

⁠Installation

Charge assign can be used directly as a Python library, and it has a server mode in which it assigns charges based on a repository. For the server, see below under Docker.

Installing the dependencies is easiest by using Anaconda, as it can install all dependencies for you automatically. It is possible to use a combination of virtualenv, the system package manager, and manual installation as well, but this takes more work. Both approaches are detailed below.

⁠Conda

First, we create a new conda environment:

conda create -n charge_assign

Next, we can install charge_assign and its dependencies into it:

conda install -c rdkit,conda-forge -n charge_assign rdkit nauty
source activate charge_assign
cd charge_assign
pip install .

⁠Virtualenv

The rdkit and nauty packages are not available from PyPI, so they cannot be installed in the usual way inside a virtual environment. Instead, they must be installed manually first.

If you are running Ubuntu Linux, the following command will install rdkit from the repositories:

sudo apt-get install python-rdkit librdkit1 rdkit-data

On Fedora, CentOS and RHEL, you can use

sudo yum install rdkit

Installation instructions for nauty are available on the Nauty homepage⁠. You will have to either add its directory to your PATH variable, set the NAUTY_EXC environment variable to the directory, or add the location of the dreadnaut program to charge/settings.py.

Next, we can make a virtual environment and install charge_assign and its dependencies.

virtualenv -p python3 </path/to/env>
. </path/to/env>/bin/activate
cd charge_assign
pip install .

⁠Docker server

The charge assign server is a simple WSGI server on top of the charge assign library. It loads a repository ZIP file (see Repository.write()), and accepts molecule definitions in LGF format via a REST API, which then returns an LGF with charges included.

The easiest way to use the service is through Docker:

docker pull mdstudio/charge_assign
docker run -p 8080:8080 --mount-type=bind,source=/path/to/repo.zip,destination=/home/charge_assign/repo.zip --name charge_assign_server enitram/charge_assign

The server needs a repository in a ZIP file, which is bind-mounted in in the above example. You can create such a repository using the scripts/build_repo.py utility, see scripts/build_repo.py -h for instructions.

Once the server is running, you can connect to it through HTTP:

curl --data-binary @molecule.lgf -H 'Content-Type: text/plain' 'http://localhost:8080/charge_assign?total_charge=0'

Note that the data must be submitted as content type text/plain, while curl by default sends the input as a form, so the content type needs to be specified explicitly here. The --data-binary option is needed (rather than --data) because LGF is a whitespace-sensitive format, and --data does not preserve whitespace. The REST API is trivial: just send the LGF to /charge_assign?total_charge=<c> and you'll get a corresponding LGF with charges out, a 400 error if no charges could be assigned for some reason, and a 400 error if the input was invalid.

⁠Tests

To run the tests, use

pip install -e .[dev]

to install the required dependencies, and then run

pytest --cov

to run the test suite.

⁠Documentation

To build the documentation, you need to install sphinx first. Installing sphinx is easiest by using Anaconda.

conda install -n charge_assign sphinx sphinx_rtd_theme

Then run sphinx.

source activate charge_assign
cd charge_assign/doc/
make html

You can then find the documentation in charge_assign/doc/build/html/.