Installation

taurenmd is written in, and depends on projects written in, Python; therefore, its installation process is based on the Python installation routines and related community-available tools. Find taurenmd:

  1. package at PyPI

  2. GitHub source repository

Supported Platforms

taurenmd is designed to run natively under any platform compatible with Python (paths are not hard coded ;-)). However, the libraries taurenmd depends on may or may not be compatible with all OS platforms, and we are not responsible for providing compatibility or support for such libraries. To be able to exploit all its features, you should choose a platform compatible with all the required Molecular Dynamics analysis libraries used by taurenmd. At the bottom of this page we have a section that describes taurenmd’s dependencies.

We can guarantee taurenmd works fully with all its dependencies using Anaconda on Ubuntu 18.04 LTS, and we are positive (not sure) it will be the same for any system supporting Anaconda.

Installation steps

From a previous defined environment

If you use Molecular Dynamics for your research, odds are you have already installed the required dependencies; if this is the case, you can just install taurenmd on top of them, run: pip install taurenmd in your MD analysis Python environment.

From scratch

To install taurenmd from scratch:

With Anaconda

If you use Anaconda as your Python package manager just do the following on your terminal:

  1. Download the taurenmd Anaconda environment file from our repository:

    curl https://raw.githubusercontent.com/joaomcteixeira/taurenmd/master/requirements.yml -o taurenmdenv.yml
    

If for some reason the above does not work, just open the link on your WebBrowser and save the text to a file (or save the file).

  1. Create a new Anaconda Python environment to host taurenmd. Choose the python version that best fits your needs; if you are not sure chose 3.7.:

    conda create -n taurenmd python=3.8
    conda env update -n taurenmd --file taurenmddev.yml
    

Where taurenmdenv.yml is the file downloaded in the previous step.

  1. Activate the newly created environment:

    conda activate taurenmd
    
  2. You are ready, type:

    taurenmd
    

to start using taurenmd.

With PyPI

If you do not use Anaconda and you actually rely on PyPI as your package manager, that is also (almost) perfectly fine.

  1. Create a new Python environment if you wish following the official instructions for your running Python version. We do not provide specific commands for these operations because these change with certain frequency, so it is best to refer to the official sources.

  2. Install taurenmd:

    python -m pip install --upgrade pip wheel
    pip3 install taurenmd[all]
    
  3. You should be good to go

Note. What is the problem with the pure PyPI installation?

taurenmd relies on OpenMM to read .cif topology files when using routines based on MDTraj, and OpenMM is not deployed on PyPI and requires installation through its conda channel. Therefore, unless you need to load .cif files you can use taurenmd from a pure PyPI installation. Otherwise, you should follow the With Anaconda instructions. May be you want to help us out solving this problem :-).

Other Platforms

We do not provide support for other distribution platforms such as HomeBrew or Chocolatey, but may be you can emulate the steps described above for these systems. Feel welcomed to improve this documentation with your insights!

User installation suggestions for particular systems:

  1. pyenv in Arch Linux

  2. on zsh

From GitHub

If you are a proficient Pythonista you might want to install taurenmd directly from the GitHub repository. If that is the case you might not need to read this section because you already know well what to do; nonetheless, let’s go through it:

Note

taurenmd follows Semantic Version 2.0, meaning that every single new addition to the master branch gets released on PyPI with a new version number. Therefore, installing from the master GitHub branch actually adds no benefit to installing with pip.

  1. Clone our repository: git clone https://github.com/joaomcteixeira/taurenmd

  2. Place yourself in the new taurenmd folder, in Linux-like systems: cd taurenmd.

  3. Install the dependencies using Anaconda. Choose your preferred python version.:

    conda create -n taurenmd python=3.8
    conda env update -n taurenmd --file requirements-dev.yml
    
  4. Install taurenmd with the following command: python setup.py develop --no-deps

  5. In the future, to keep your installation up to the latest:

  1. pull repository updates from the upstream repository: git pull (from within taurenmd git folder)

  2. because taurenmd developments are mostly reflected on new interfaces you need to update those as well: python setup.py develop --no-deps

  3. beaware, if the version increment denotes API breaks you might need to reinstall taurenmd from scratch.

Running taurenmd

After installation you can run taurenmd with the following command :-):

taurenmd

Please read our Usage page for, whatelse, usage instructions and examples.

Upgrade

To upgrade taurenmd and all its dependencies to the latest version:

  1. If you installed from PyPI:

    pip3 install -U --force-reinstall taurenmd
    
  2. If you installed from Anaconda:

    pip3 install -U --force-reinstall taurenmd --no-deps
    

Something failed

In case something is failing during installation, execution or upgrade, please write us an Issue explaining your situation.

How taurenmd manages its dependencies

By default, installing taurenmd does not install all its dependencies. Why? Because taurenmd relies on large and complex libraries required to manage the Molecular Dynamics (MD) data, such as MDAnalysis and MDTraj, and installing them automatically might not be the optimal solution for every case, for example:

  1. Many MD researchers may actually work on:

  • cutting edge development versions,

  • forked versions,

  • source-compiled versions

  1. There may be platform compatibility issues (read further),

  2. Lastly and minor, not all dependencies are required for every taurenmd command,

So installing those libraries by default together with taurenmd might be counter productive 1.

Nonetheless, taurenmd does provide an easy way to install this dependencies whenever possible and needed. These details are explained in the Installation steps section above.

The dependencies that are kept separate from the default installation process are listed bellow; here, links point to their respective official installation instructions.

  1. MDAnalysis Installation instructions

  2. MDTraj installation instructions

  3. OpenMM installation

  4. Numpy, is installed together with the above dependencies, so you should not need to reinstall it again, just stick to the version compatible with the 3 libraries, this should be managed automatically by your Python package manager. Nonetheless, and for your interest, taurenmd requires Numpy but it is not installed along with the main installation.

Other dependencies installed automatically

Other dependencies that are indeed automatically installed alongside with taurenmd are listed bellow:

  1. python-bioplottemplates

  2. pyquaterion

1

Dependency installation could be disabled using the --no-deps flag of pip, but we decided for the other strategy.