Merge pull request #52 from jag1g13/dev

Pre PyCGTOOL v2.0.0 merge

.coveragerc

@@ -0,0 +1,21 @@
+# .coveragerc to control coverage.py
+[run]
+branch = True
+source = pycgtool
+
+[report]
+# Regexes for lines to exclude from consideration
+exclude_lines =
+    # Have to re-enable the standard pragma
+    pragma: no cover
+
+    # Don't complain about missing debug-only code:
+    def __repr__
+
+    # Don't complain if tests don't hit defensive assertion code:
+    raise AssertionError
+    raise NotImplementedError
+
+ignore_errors = True
+show_missing = True
+sort = miss

.github/workflows/publish.yml

@@ -0,0 +1,61 @@
+name: Publish
+
+on:
+  release:
+    types:
+      - created
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Python
+        uses: actions/setup-python@v1
+        with:
+          python-version: "3.8"
+
+      - name: Install Poetry
+        uses: snok/[email protected]
+
+      - name: Publish
+        env:
+          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          poetry config pypi-token.pypi $PYPI_TOKEN
+          poetry publish --build
+
+  build-release-artifacts:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Python
+        uses: actions/setup-python@v1
+        with:
+          python-version: "3.8"
+
+      - name: Install prerequisites
+        run: |
+          python -m pip install --upgrade pip
+          pip install pyinstaller
+          pip install .
+
+      - name: Build distributable
+        run: |
+          pyinstaller pycgtool/__main__.py --name pycgtool-${{ matrix.os }} --onefile --collect-data mdtraj --hidden-import xdrlib
+
+      - uses: ncipollo/release-action@v1
+        with:
+          allowUpdates: true
+          artifacts: dist/pycgtool-${{ matrix.os }}
+          omitBodyDuringUpdate: true
+          token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/python-package.yml

@@ -5,16 +5,16 @@ name: Python package
 
 on:
   push:
-    branches: [ master ]
+    branches: [ master, dev ]
   pull_request:
-    branches: [ master ]
+    branches: [ master, dev ]
 
 jobs:
   build:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [3.7, 3.8, 3.9]
+        python-version: ["3.6", "3.7", "3.8", "3.9"]
         os: [ubuntu-latest, macos-latest]
 
     runs-on: ${{ matrix.os }}
@@ -27,13 +27,30 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
 
-    - name: Install project and dependencies
+    - name: Update pip
       run: |
-        pip install --upgrade pip
-        pip install -r requirements.txt mdtraj
-        pip install pytest coverage
+        python -m pip install --upgrade pip
 
-    - name: Test with pytest
+    - name: Get pip cache dir
+      id: pip-cache
       run: |
-        coverage run --source=pycgtool -m pytest
-        coverage report --skip-covered
+        echo "::set-output name=dir::$(pip cache dir)"
+
+    - name: Cache pip
+      uses: actions/cache@v2
+      with:
+        # This path is specific to Ubuntu
+        path: ${{ steps.pip-cache.outputs.dir }}
+        # Look to see if there is a cache hit for the corresponding requirements file
+        key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-pip-
+          ${{ runner.os }}-    
+
+    - name: Install dependencies
+      run: |
+        pip install tox
+
+    - name: Run tests / linter
+      run: |
+        tox

.gitignore

@@ -36,4 +36,4 @@ settings.json
 .cache/
 /notes/
 *.offsets
-*.pkl
+*.pkl

.readthedocs.yml

@@ -0,0 +1,12 @@
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  version: 3.7
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
+
+## [2.0.0-beta.5](https://github.com/jag1g13/pycgtool/compare/v1.0.2...v2.0.0-beta.5) (2021-11-14)
+
+
+### Features
+
+* add flag to get version number ([f3660f7](https://github.com/jag1g13/pycgtool/commit/f3660f7081b7265a39569338e693d32a1d4030ec))
+
+
+### Bug Fixes
+
+* catch updated exception from MDTraj 1.9.7 ([b1d1e6d](https://github.com/jag1g13/pycgtool/commit/b1d1e6db76a1ce5c9273f6cf0833440c337aa302))
+* skip NaNs in bond sample output ([ef5a977](https://github.com/jag1g13/pycgtool/commit/ef5a97750dde27d48f83dc0f8472b4cc88f645aa))
+
+## [2.0.0-beta.4](https://github.com/jag1g13/pycgtool/compare/v2.0.0-beta.3...v2.0.0-beta.4) (2021-10-09)
+
+
+### Bug Fixes
+
+* add data files to installable package ([a9fdae8](https://github.com/jag1g13/pycgtool/commit/a9fdae85d5f9d2bff9dcfd4fe0fbc8a683dbe773))
+* backup forcefield directories instead of overwrite ([19b4054](https://github.com/jag1g13/pycgtool/commit/19b40540b0254c47d7a70eef12c2200bb96a4b9d))
+* backup frame and forcefield output files ([626cc3a](https://github.com/jag1g13/pycgtool/commit/626cc3a839a21699ac4c28eab55f385c6a199327))
+* create output directory if it doesn't exist ([c4694e8](https://github.com/jag1g13/pycgtool/commit/c4694e811201c7538819757bc52ea21ecd9f196f))
+* **tests:** add missing mapping test file ([db0be76](https://github.com/jag1g13/pycgtool/commit/db0be763bab6f629706597da1cb43d4ce3ff0914))
+* use correct reference coordinate for virtual bead calc ([a0a61f2](https://github.com/jag1g13/pycgtool/commit/a0a61f2dd2ae38d63b6de5a516f324865e93fe04))
+
+## [2.0.0-beta.3](https://github.com/jag1g13/pycgtool/compare/v2.0.0-beta.2...v2.0.0-beta.3) (2021-08-14)
+
+
+### Bug Fixes
+
+* avoid bond calc and traj output when no atoms ([ba0e5ab](https://github.com/jag1g13/pycgtool/commit/ba0e5ab1339f1f2821a0edb08a5b7f661c9ac29f)), closes [#51](https://github.com/jag1g13/pycgtool/issues/51)
+* catch zero volume PDB box and warn ([61a5b80](https://github.com/jag1g13/pycgtool/commit/61a5b809e0cd4dffaf3e2e2bbe2ab74fcc0488aa))
+* handle empty output frames correctly ([3d4b9ad](https://github.com/jag1g13/pycgtool/commit/3d4b9adccce32c95d4114c994133d3db6efd1556)), closes [#51](https://github.com/jag1g13/pycgtool/issues/51)
+
+## [2.0.0-beta.2](https://github.com/jag1g13/pycgtool/compare/v2.0.0-beta.1...v2.0.0-beta.2) (2021-05-28)
+
+
+### Bug Fixes
+
+* use absolute imports in entrypoint script ([1509247](https://github.com/jag1g13/pycgtool/commit/15092476496724e61a7c2f1367cdaa8ebe5fe0f2))
+
+## [2.0.0-beta.1](https://github.com/jag1g13/pycgtool/compare/v2.0.0-alpha.5...v2.0.0-beta.1) (2021-05-10)
+
+
+### Features
+
+* add initial trial for backmapping ([ab97010](https://github.com/jag1g13/pycgtool/commit/ab97010846815df7309b646d0bfe9f9e246890ba))
+
+
+### Bug Fixes
+
+* add missing changes to poetry lockfile ([3edf562](https://github.com/jag1g13/pycgtool/commit/3edf562f1dfb71599dc40d78e5b824c0c2417eca))
+* attempt fix to ci config ([4551eb5](https://github.com/jag1g13/pycgtool/commit/4551eb5c46d70c9dadbc1397150705a1bd726b82))
+* avoid warnings with unnecessary topology file ([717c227](https://github.com/jag1g13/pycgtool/commit/717c22723c4b5857f5e4a2bd7f956ecafb3258d3))
+* cast unitcell to float32 to avoid numpy warn ([a89d2ce](https://github.com/jag1g13/pycgtool/commit/a89d2cee5e789ad7c85f593f1a8b9d73ba1e50e6))
+* **ci:** remove unused numpy import ([bb27619](https://github.com/jag1g13/pycgtool/commit/bb276195d9f1f76668d3133607a49f07ce4a8de4))
+* fix count of frames in trajectory ([d02cd34](https://github.com/jag1g13/pycgtool/commit/d02cd3485cd474cf539a7e628dddfc4eaa953e51))
+* Move bond dump files to output directory ([1439235](https://github.com/jag1g13/pycgtool/commit/1439235f3a48da84af4b3fe064e1da9b39aa71e9))
+* python 3.10 this time - not 3.1 ([5143191](https://github.com/jag1g13/pycgtool/commit/51431910aeb8b70bef90aba82183d040282d6912))
+* remove 3.10 - it's not in the cache yet ([80a90e1](https://github.com/jag1g13/pycgtool/commit/80a90e1c62f245dab2f85e2533612c8b19a7c9d0))
+* replace reference to requirements.txt in CI ([3d1bd7f](https://github.com/jag1g13/pycgtool/commit/3d1bd7f5fde17b5c0300f70300cfa3b0f42cb3f1))
+* update tests to match refactoring in __main__ ([0dbce7d](https://github.com/jag1g13/pycgtool/commit/0dbce7d50e35fa1ffed959a40f7c9a2aa6dda873))
+
+## [2.0.0-alpha.5](https://github.com/jag1g13/pycgtool/compare/v1.0.1...v2.0.0-alpha.5) (2020-09-23)
+
+
+### Features
+
+* Add option for performance profiling ([cbd56ed](https://github.com/jag1g13/pycgtool/commit/cbd56ed8177e17bfc43284d4b09320fc24b8b939))
+
+
+### Bug Fixes
+
+* Account for MDTraj renaming in mol mappings ([6c7c07f](https://github.com/jag1g13/pycgtool/commit/6c7c07f748c5aabd21b3ba8997dfd9ae7d97f1b9))
+* Call CI tools from inside Poetry env ([60e3e9d](https://github.com/jag1g13/pycgtool/commit/60e3e9db94f61dfb33840bd17716d5e48499f5c9))
+* Distinguish between failure cases in traj cmp ([0ede47c](https://github.com/jag1g13/pycgtool/commit/0ede47c99d8667cae1ff38023c1a877b22ca0db7))
+* Drop support for Python 3.5 ([d50adb2](https://github.com/jag1g13/pycgtool/commit/d50adb2820b8519eaa3d77af95f4f45deb399e35))
+* Fix CI failing to find Flake8 ([4b8e375](https://github.com/jag1g13/pycgtool/commit/4b8e37563cd5f7ce8e4d3b0c55f0bf869f39c3b9))
+* Fix err in file comparison when diff lengths ([6994993](https://github.com/jag1g13/pycgtool/commit/69949934801986578e52a73e3da0e18dd546be2f))
+* Fix error when reading zero size box ([c44f621](https://github.com/jag1g13/pycgtool/commit/c44f62171a5d9b37b591736f3869e892e3d49a32))
+* Fix failing bond dump test ([8d7d06f](https://github.com/jag1g13/pycgtool/commit/8d7d06f9e90ca5cbceadc29630e8d8208829eff3))
+* Fix linting errors raised by pyflakes ([d275329](https://github.com/jag1g13/pycgtool/commit/d2753290f96181b1b4ed00d92a70cad244abd2a3))
+* Fix remaining test failures ([50ec715](https://github.com/jag1g13/pycgtool/commit/50ec7156e790a8ed475414c95196e5861027e006))
+* Replace time.clock with time.process_time ([d1f6981](https://github.com/jag1g13/pycgtool/commit/d1f69810475e2e3af4beb2652688c05d11b73a86))
+* Update Poetry lock file ([f08dd83](https://github.com/jag1g13/pycgtool/commit/f08dd839fde66c739e52920a1ca92d5b7ec2b135))

README.md

@@ -1,27 +1,24 @@
-[![Build Status](https://travis-ci.org/jag1g13/pycgtool.svg?branch=master)](https://travis-ci.org/jag1g13/pycgtool) [![Documentation Status](https://readthedocs.org/projects/pycgtool/badge/?version=master)](http://pycgtool.readthedocs.io/en/master/?badge=master) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.259330.svg)](https://doi.org/10.5281/zenodo.259330)
-
 # PyCGTOOL
 
-Please see http://pycgtool.readthedocs.io/en/master/ for full documentation.
-
-A Python program for automated generation of coarse-grained molecular dynamics models from atomistic simulation trajectories.
-
-The aim of this project is to provide a tool to aid in parametrising coarse-grained (CG) molecular mechanics models.  PyCGTOOL generates coarse-grained models from atomistic simulation trajectories using a user-provided mapping.  Equilibrium values and force constants of bonded terms are calculated by Boltzmann Inversion of bond distributions collected from the input trajectory.
+[![License](https://img.shields.io/github/license/jag1g13/pycgtool.svg)](LICENSE)
+[![Python package](https://github.com/jag1g13/pycgtool/actions/workflows/python-package.yml/badge.svg?branch=dev)](https://github.com/jag1g13/pycgtool/actions)
+[![Documentation](https://readthedocs.org/projects/pycgtool/badge/?version=dev)](http://pycgtool.readthedocs.io/en/dev)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.598143.svg)](https://doi.org/10.5281/zenodo.598143)
+[![PyPi Version](https://img.shields.io/pypi/v/pycgtool.svg)](https://pypi.python.org/pypi/pycgtool/)
+[![conda-forge Version](https://anaconda.org/conda-forge/pycgtool/badges/version.svg)](https://anaconda.org/conda-forge/pycgtool/badges/version.svg)
 
-Alternatively map-only mode (behaving similarly to MARTINIZE) may be used to generate initial coordinates to use with existing CG topologies such as the MARTINI lipid models.  For instance, a pre-equilibrated atomistic membrane may be used to create starting coordinates for a MARTINI membrane simulation.
+Generate coarse-grained molecular dynamics models from atomistic trajectories.
 
-PyCGTOOL makes it easy to test multiple variations in mapping and bond topology by making simple changes to the config files.
+PyCGTOOL is a tool to aid in parametrising coarse-grained (CG) molecular mechanics models of small molecules, for example for simulations using the popular MARTINI model.
+It generates coarse-grained model parameters from atomistic simulation trajectories using a user-provided mapping.
+Equilibrium values and force constants of bonded terms are calculated by Boltzmann Inversion of bond distributions collected from the input trajectory.
 
-This version has several advantages over the original C++ implementation CGTOOL:
-* PyCGTOOL is able to run anywhere the necessary library dependencies are available (all available from pip)
-* Does not require that residues are present in contiguous sorted blocks
-* May map multiple residues with a single pass
-* Support for polymers such as DNA or proteins making use of GROMACS' pdb2gmx
-* Much more automated testing ensures that regressions will be identified quickly
+Alternatively map-only mode (behaving similarly to MARTINIZE) may be used to generate initial coordinates to use with existing CG topologies such as the MARTINI lipid models.
+For instance, a pre-equilibrated atomistic membrane may be used to create starting coordinates for a CG membrane simulation.
 
-If you experience problems or wish to see a new feature added please [file an issue](https://github.com/jag1g13/pycgtool/issues).
+PyCGTOOL makes it quick and easy to test multiple variations in mapping and bond topology by making simple changes to the config files.
 
-If you find PyCGTOOL useful, please cite our JCIM paper https://doi.org/10.1021/acs.jcim.7b00096.
+If you find PyCGTOOL useful, please cite our JCIM paper (https://doi.org/10.1021/acs.jcim.7b00096) and the code itself (https://doi.org/10.5281/zenodo.598143).
 
 ```bibtex
 @article{Graham2017,
@@ -39,28 +36,82 @@ If you find PyCGTOOL useful, please cite our JCIM paper https://doi.org/10.1021/
 }
 ```
 
-## Usage
-Input to PyCGTOOL is GROMACS GRO and XTC files, along with two custom files: MAP and BND.  These files provide the atomistic-to-CG mapping and bonded topology respectively.  Example files are present in the [test/data](https://github.com/jag1g13/pycgtool/tree/master/test/data) directory.  The format of these files is described in the [full documentation](http://pycgtool.readthedocs.io/en/master/).
+## Install
+
+PyCGTOOL requires Python 3.6 or higher and may be installed using either `pip` or `conda`:
+```
+pip install pycgtool
+```
+
+```
+conda install -c conda-forge pycgtool
+```
 
-To run PyCGTOOL:
-`pycgtool.py -g <GRO file> -x <XTC file> -m <MAP file> -b <BND file>`
+Alternatively, you may download a pre-packaged version for your operating system from the [releases page](https://github.com/jag1g13/pycgtool/releases) on GitHub.
+These pre-packaged versions include all dependencies and should be suitable in cases where you cannot install packages using one of the above methods.
+**Warning**: This installation method is not extensively tested - installing via `pip` or `conda` should be prefered in most cases.
 
-To run PyCGTOOL in map-only mode:
-`pycgtool.py -g <GRO file> -m <MAP file>`
+### MDTraj on macOS
 
-To see the help text:
-`pycgtool.py -h`
+On some versions macOS, with some versions of the Clang compiler, MDTraj may fail to load GROMACS XTC simulation trajectories.
+If you encounter this issue, please make sure you have the latest version of MDTraj installed.
+
+For more information see [MDTraj/#1572](https://github.com/mdtraj/mdtraj/issues/1572).
+
+## Usage
+
+Input to PyCGTOOL is an atomistic simulation trajectory in the form of a topology (e.g. PDB, GRO, etc.) and a trajectory file (e.g. XTC, DCD, etc.), along with two custom files which describe the CG model to be generated: mapping (`.map`) and bonding (`.bnd`).
+These files provide the atomistic-to-CG mapping and bonded topology respectively and use a format similar to GROMACS `.itp` files.
+Topology and trajectory files are processed using [MDTraj](https://www.mdtraj.org) so most common formats are accepted.
+
+Example mapping and bond files are present in the [test/data](https://github.com/jag1g13/pycgtool/tree/master/test/data) directory.
+The format of these files is described fully in the [documentation page on file formats](https://pycgtool.readthedocs.io/en/dev/file-formats.html).
 
 For more information, see [the tutorial](https://pycgtool.readthedocs.io/en/master/tutorial.html).
-It is important to perform validation of any new parameter set; a brief example is present at the end of the tutorial.
+It is important to perform validation of any new parameter set - a brief example is present at the end of the tutorial.
+
+For a full list of options, see the [documentation](https://pycgtool.readthedocs.io/en/master/index.html) or use:
+```
+pycgtool -h
+```
+
+### Generate a Model
+
+To generate a CG model from an atomistic simulation:
+```
+pycgtool <topology file> <trajectory file> -m <MAP file> -b <BND file>
+```
+
+### Map Only
+
+To use PyCGTOOL to convert a set of atomistic simulation coordinates to CG coordinates:
+```
+pycgtool <topology file> -m <MAP file>
+```
+
+Or to convert a complete simulation trajectory:
+```
+pycgtool <topology file> <trajectory file> -m <MAP file>
+```
+
+## Maintainers
+
+James Graham ([@jag1g13](https://github.com/jag1g13))
+
+## Contributing
+
+If you experience problems using PyCGTOOL or wish to see a new feature added please [open an issue](https://github.com/jag1g13/pycgtool/issues/new).
+
+To help develop PyCGTOOL, you can create a fork of this repository, clone your fork and install PyCGTOOL in development mode using [Poetry](https://python-poetry.org/):
+```
+poetry install
+```
+
+This will result in an editable mode install (similar to `pip install -e .`) along with all the necessary runtime and development dependencies.
+Testing and linting is handled by [Tox](https://tox.readthedocs.io/en/latest/) - use `tox` to run the full test suite and linter as they are configured in the Continuous Integration pipeline.
 
-## Requirements
-PyCGTOOL requires:
-* Python3
-* [NumPy](http://www.numpy.org/)
-* [simpletraj](https://github.com/arose/simpletraj)
+When you're ready for your work to be merged, please submit a Pull Request.
 
-The bundled test code may be run using your preferred Python testing frontend although py.test or nose2 is recommended.
-All library dependencies may be installed from pip using the command `pip install -r requirements.txt`
+## License
 
-This program is a reimplementation of the earlier [CGTOOL](https://bitbucket.org/jag1g13/cgtool).
+[GPL-3.0](LICENSE) © James Graham, University of Southampton