Merge pull request #99 from Autodesk/dev

Merge dev changes into master

This comprises most of the work for 0.7.3. There will be one final PR to do the final polishing for the release.

MANIFEST.in

@@ -5,6 +5,8 @@ include LICENSE
 include README.md
 include CONTRIBUTING.md
 include DEVELOPMENT.md
+include NOTICES
+include moldesign/HISTORY.rst
 recursive-include moldesign/_static_data *.*
 recursive-include moldesign/_notebooks *.*
 global-exclude *.py[cod] __pycache__ *~ *.bak

NOTICES

@@ -5,6 +5,7 @@ The Molecular Design Toolkit incorporates code from the following sources:
 Copyright (c) 2006-2015, Christoph Gohlke
 Copyright (c) 2006-2015, The Regents of the University of California
 SOURCE CODE: moldesign/external/transformations.py
+DESCRIPTION: Included in its entirety, with minor modifications to imports
 LICENSE: moldesign/external/transformations.py
 WEBSITE: http://www.lfd.uci.edu/~gohlke/
 
@@ -13,10 +14,23 @@ WEBSITE: http://www.lfd.uci.edu/~gohlke/
 -------------------------
 Copyright (c) 2007-2016 by the Sphinx team
 SOURCE CODE: moldesign/utils/docparsers/google.py
-Note that this source code has been heavily modified. Modifications are described in the file.
+DESCRIPTION: Includes code derived from the Napoleon Google-style docstring parsers.
+Note that these routines have been heavily modified as described in the file.
 LICENSE: moldesign/utils/docparsers/sphinxlicense
 WEBSITE: http://sphinx-doc.org
 
+
+       Python
+--------------------------------
+Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
+2011, 2012, 2013, 2014, 2015, 2016 Python Software Foundation; All Rights
+Reserved
+SOURCE CODE: moldesign/utils/utils.py (`methodcaller` class)
+DESCRIPTION: unmodified copy of the pure-python `methodcaller` class
+LICENSE: moldesign/external/licenses/python
+WEBSITE: https://www.python.org
+
+
    Versioneer
 -------------------------
 By Brian Warner

RELEASE.md

@@ -1,18 +1,62 @@
-# Creating new MDT project releases
+# Whenever commiting changes anywhere
+
+Make SURE that you've run `set_filters.sh` at the project base. This will make sure that you don't accidentally commit any `ipynb` output fields into the repository. You can check to make sure the filters are working by running `git diff` on any notebook file that has output in it: all `output` and `metadata` fields should remain blank.
+
+# Creating a Pull Request
 
 These instructions generally apply to [Autodesk/molecular-design-toolkit](https://github.com/Autodesk/molecular-design-toolkit),
 [Autodesk/py-cloud-compute-cannon](https://github.com/Autodesk/py-cloud-compute-cannon), and [Autodesk/notebook-molecular-visualization](https://github.com/Autodesk/notebook-molecular-visualization).
 
-This is only for project maintainers - everyone else should use PRs.
+1. Group all changes in a single branch.
+1. Run tests in `moldesign/_tests` with `py.test -n NCORES` where `NCORES` is the number of jobs to run simultanously.
+2. Create a pull-request for the appropriate branch in Autodesk/molecular-design-toolkit
+
+
+# Maintainers: Accepting a PR
+
+Work can be merged into `master` or a feature branch, as appropriate. Don't merge broken code
+into master, but it doesn't need to be totally production-ready either: only releases (below)
+are considered "stable".
+
+1. Review the code.
+1. Make sure that there's appropriate functional tests.
+1. Run all tests. They don't all *necessarily* need to pass, but you need to undertand why  what's passing and what's not.
+1. Run any example notebooks that might be affected by the PR.
+
+
+# Maintainers: Creating a new release
+
+Decide on the new version number (using [semantic versioning](http://semver.org/)).
+
+Everything here is HIGHLY PRELIMINARY!!! This will be a lot easier once Travis/Jenkins is up.
+
+1. Make sure all changes have been PR'd into master
+1. Check out a clean copy of master
+1. Run `check-manifest` at project root to make sure the distribution will include the necessary files.
+1. Increment the `default_version_tag` field in `moldesign.compute.config`, and commit the change
+1. Tag your local branch with the release number: `git tag [version]` (note: delete this tag with `git tag rm [version]` if you need to abort the release)
+4. Build new docker images: `cd docker_images; ./dockermake.py --all --repo docker.io/Autodesk/moldesign: --tag [version]`
+1. Confirm that all tests are passing *with and without* locally installed dependencies (pyscf, openbabel, etc)
+1. Confirm that all tutorial and example notebooks run without errors.
+
+If this is all succesfull - you're ready to make it public.
+
+1. Push docker images to cloud: `cd docker_images; ./dockermake.py --all --push --repo docker.io/Autodesk/moldesign: --tag [version]`
+4. `python setup.py register -r pypi`
+5. `python setup.py sdist upload -r pypi`
+1. `git push origin master --tags`
+
+The final step is the point of no return - you'll need to prep a new release if you discover a problem. Before that, you can undo
+what you've done by deleting your release off of PyPI and DockerHub.
+
+
+
+# Maintainers: updating docs
 
-Everything here is HIGHLY PRELIMINARY!!! This will change dramatically once Jenkins or Travis is up.
+Documentation is NOT coupled to the package releases; docs tend to get updated continuously.
 
-1. Push changes or merge PR into dev branch and check out a clean copy.
-1. Test it.
-1. Run `check-manifest` at project root. (Repeat steps 1-3 until this checks out OK)
-1. [MDT only] - update/push dockerfiles and image URLs in `moldesign.compute.configuration`
-2. Pull-request into master
-3. Tag master branch with new release number
-4. In repo root. `python setup.py register -r pypi`
-5. In repo root, `python setup.py sdist upload -r pypi`
-6. [MDT only] Run `cd docs; make html` and push contents of `_build/html` to the gh-pages branch.
+1. In the `master` branch, update the version numbers in `docs/conf.py`
+1. Run `cd docs; make clean; make html`. 
+1. In a separate directory, check out a fresh copy of the repo and run `git checkout gh-pages`
+1. Copy the contents of `[master branch]/docs/_build/html` into the root of the `gh-pages` branch.
+1. Commit your changes to the `gh-pages` branch and push them back to GitHub.

docs/api/atoms.rst

@@ -0,0 +1,6 @@
+============
+Atom objects
+============
+
+.. autoclass:: moldesign.Atom
+   :members:

docs/biomolecule.rst

@@ -0,0 +1,55 @@
+Biomolecular structure
+======================
+
+
+
+Primary structure
+-----------------
+**Class documentation:** :class:`moldesign.Chain`, :class:`moldesign.Residue`
+
+Biomolecules also contain primary structure information such as :class:`Chains <moldesign.Chain>`
+and :class:`Residues <moldesign.Residue>`. Chains can be accessed by name OR by index:
+
+   >>> chain1 = molecule.chains['A']
+   >>> chain2 = molecule.chains[0]
+   >>> chain1 is chain2
+   True
+
+Each chain contains :class:`residues <moldesign.Residue>`. In a chain, residues can similarly be
+accessed through a flat list or by name:
+
+   >>> res0 = molecule.residues[0]
+   >>> resA = molecule.chains['A'].residues['PRO1']
+   >>> res0 is resA
+   True
+
+A flat list of all residues in a molecule is also available at `molecule.residues`.
+
+
+
+Biomolecular assemblies
+-----------------------
+Many biomolecules in the PDB only contain a subset of the total biomolecular structure - the
+remaining parts of the structure can be generated via `symmetry transformations <http://pdb101.rcsb.org/learn/guide-to-understanding-pdb-data/biological-assemblies>`_.
+
+When you read in such a structure, MDT will issue a warning.
+
+   >>> mol = mdt.from_pdb('3FPP')
+   WARNING: This PDB file contains the following biomolecular assemblies:
+   WARNING: Assembly "1": 3 copies of chains A, B
+   WARNING: Use ``mdt.build_assembly([molecule],[assembly_name])`` to build one of the above assemblies
+
+To create the full assembly, run
+   >>> assembly = mdt.build_assembly(mol,"1")
+   >>> assembly.draw()
+
+   .. image:: img/howdoi_pdb_assm.png
+
+Note:
+   Only PDB-formatted files are currently supported for biomolecular assemblies - MMCif support
+   is in progress.
+
+
+
+
+

docs/conf.py

@@ -69,12 +69,12 @@
 #source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'contents'
+master_doc = 'index'
 
 # General information about the project.
 project = u'Molecular Design Toolkit'
 copyright = u'2016 Autodesk Research'
-author = u'Aaron Virshup, Dion Amago, Malte Tinnus (Bio/Nano Research Group, Autodesk)'
+author = u'Aaron Virshup, Dion Amago, Justin McCandless, Malte Tinnus (Bio/Nano Research Group, Autodesk)'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -83,9 +83,9 @@
 
 import moldesign
 # The short X.Y version.
-version = moldesign.__version__
+version = '0.7'
 # The full version, including alpha/beta/rc tags.
-release = moldesign.__version__
+release = '0.7.3'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/creating_and_converting.rst

@@ -1,9 +1,64 @@
-Creating and converting molecules
----------------------------------
+Creating molecules
+==================
 
 
-From other objects
-==================
+From names and ids
+------------------
+You can use an IUPAC name:
+
+   >>> import moldesign as mdt
+   >>> benzene = mdt.from_name('benzene')
+   >>> caffeine = mdt.from_name('1,3,7-Trimethylpurine-2,6-dione')
+
+or a `SMILES string <https://en.wikipedia.org/wiki/Simplified_molecular-input_line-entry_system>`_
+
+   >>> benzene = mdt.from_smiles('c1ccccc1')
+   >>> caffeine = mdt.from_smiles('CN1C=NC2=C1C(=O)N(C(=O)N2C)C')
+
+
+To download a biomolecular structure from the `Protein DataBank <http://www.rcsb.org/>`_, you can use
+
+   >>> hiv_protease = mdt.from_pdb('3AID')
+
+DNA helices can be generated from a genetic sequence:
+
+   >>> bdna = mdt.build_dna_helix('ACTG')
+
+
+From files
+----------
+MDT supports most common molecular formats via ``moldesign.read``. In most cases, the format can be inferred from the filename. Files compressed with `gz` or `bz2` can be read as well.
+
+   >>> benzene = mdt.read('benzene.sdf')
+   >>> caffeine = mdt.read('caffeine.xyz')
+   >>> lsd = mdt.read('lsd.mol2.gz')
+   >>> hiv_protease = mdt.read('3aid.pdb.bz2')
+   >>> zika_capsid = mdt.read('5ire.cif')
+
+In addition, any pickled python object can be read in with this function - files with ``pickle``, ``pkl``, and ``P`` are recognized as pickle files:
+   >>> saved_mol = mdt.read('molecule_1.pickle')
+   >>> saved_atom = mdt.read('atom_2.pkl.gz')
+   >>> saved_trajectory = mdt.read('traj.P.bz2')
+
+
+From strings
+------------
+File content in strings or file-like objects can be read as well, but the format needs to be explicitly specified.
+
+   >>> water_str = """ 3
+   >>>                 water xyz file
+   >>>                 O          0.98285        0.07497        0.04837
+   >>>                 H          0.70400        0.94631        0.36769
+   >>>                 H          1.95074        0.11856        0.06434 """
+   >>> water = mdt.read(water_str, format='xyz')
+   >>>
+   >>> import StringIO
+   >>> water_filelike = StringIO.StringIO(water_str)
+   >>> molecule = mdt.read(water_filelike, format='xyz')
+
+
+From other molecules
+--------------------
 You can create a new molecule from any collection of atoms.
 
 For instance, a list of atoms:
@@ -18,3 +73,13 @@ Or even a list of molecules, atoms, and residues:
    >>> dmso = mdt.from_name('dmso')
    >>> cobalt_atom = mdt.Atom(symbol='Co')
    >>> complex = mdt.Molecule([protein, dmso, cobalt_atom])
+
+
+From other python packages
+--------------------------
+MDT's interfaces allow it to import objects from a variety of other molecular modeling packages, including;
+
+- `OpenBabel <http://openbabel.org/>`_ / `Pybel <https://openbabel.org/docs/dev/UseTheLibrary/Python_Pybel.html>`_ : ``mdt.interfaces.pybel_to_mdt(pybel_molecule)``
+- `OpenMM <http://openmm.org/>`_: ``mdt.interfaces.openmm_topology_to_mdt(openmm_topology)``
+- `BioPython <http://biopython.org/wiki/Biopython>`_: ``mdt.interfaces.biopython_to_mdt(biopython_pdb_structure)``
+- `PdbFixer <https://github.com/pandegroup/pdbfixer>`_: ``mdt.interfaces.pdbfixer_to_mdt(pdbfixer_object)``

docs/dynamics.rst

@@ -0,0 +1,17 @@
+Molecular dynamics
+==================
+
+Protein MD
+----------
+
+WIP
+
+Small molecule MD
+-----------------
+
+WIP
+
+Quantum chemical potentials
+---------------------------
+
+WIP