From 4fef9e1900c76c5bed17ebd71b27978aa0c4378c Mon Sep 17 00:00:00 2001 From: Aaron Virshup Date: Wed, 28 Sep 2016 14:44:25 -0700 Subject: [PATCH] Reorganize docs --- RELEASE.md | 68 +++++++++-- docs/api/atoms.rst | 6 + docs/biomolecule.rst | 55 +++++++++ docs/conf.py | 8 +- docs/contents.rst | 13 -- docs/creating_and_converting.rst | 73 ++++++++++- docs/dynamics.rst | 17 +++ docs/features.rst | 39 +++--- docs/geometry.rst | 41 +++++++ docs/howdoi.rst | 203 ------------------------------- docs/index.rst | 75 +++++------- docs/install.rst | 57 ++++++--- docs/properties.rst | 29 +++++ docs/quickstart.rst | 57 +++++++++ docs/structure.rst | 29 +---- docs/visualization.rst | 87 +++++++++++++ 16 files changed, 514 insertions(+), 343 deletions(-) create mode 100644 docs/api/atoms.rst create mode 100644 docs/biomolecule.rst delete mode 100644 docs/contents.rst create mode 100644 docs/dynamics.rst create mode 100644 docs/geometry.rst delete mode 100644 docs/howdoi.rst create mode 100644 docs/properties.rst create mode 100644 docs/quickstart.rst create mode 100644 docs/visualization.rst diff --git a/RELEASE.md b/RELEASE.md index deda84d..f9cd093 100644 --- a/RELEASE.md +++ b/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. \ No newline at end of file +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. diff --git a/docs/api/atoms.rst b/docs/api/atoms.rst new file mode 100644 index 0000000..ae69e59 --- /dev/null +++ b/docs/api/atoms.rst @@ -0,0 +1,6 @@ +============ +Atom objects +============ + +.. autoclass:: moldesign.Atom + :members: diff --git a/docs/biomolecule.rst b/docs/biomolecule.rst new file mode 100644 index 0000000..270f833 --- /dev/null +++ b/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 ` +and :class:`Residues `. 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 `. 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 `_. + +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. + + + + + diff --git a/docs/conf.py b/docs/conf.py index b37dc36..1d99014 100644 --- a/docs/conf.py +++ b/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. diff --git a/docs/contents.rst b/docs/contents.rst deleted file mode 100644 index e2ebbbf..0000000 --- a/docs/contents.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. toctree:: - :maxdepth: 3 - :caption: Contents - :name: mastertoc - - Introduction - Installation - How do I ...? - Atoms, molecules, and biomolecules - Complete API reference <_moldesign_api/moldesign> - -* :ref:`Alphabetical index ` -* :ref:`Search ` diff --git a/docs/creating_and_converting.rst b/docs/creating_and_converting.rst index 263354a..7378f37 100644 --- a/docs/creating_and_converting.rst +++ b/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 `_ + + >>> 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 `_, 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 `_ / `Pybel `_ : ``mdt.interfaces.pybel_to_mdt(pybel_molecule)`` +- `OpenMM `_: ``mdt.interfaces.openmm_topology_to_mdt(openmm_topology)`` +- `BioPython `_: ``mdt.interfaces.biopython_to_mdt(biopython_pdb_structure)`` +- `PdbFixer `_: ``mdt.interfaces.pdbfixer_to_mdt(pdbfixer_object)`` \ No newline at end of file diff --git a/docs/dynamics.rst b/docs/dynamics.rst new file mode 100644 index 0000000..ecd1cf8 --- /dev/null +++ b/docs/dynamics.rst @@ -0,0 +1,17 @@ +Molecular dynamics +================== + +Protein MD +---------- + +WIP + +Small molecule MD +----------------- + +WIP + +Quantum chemical potentials +--------------------------- + +WIP \ No newline at end of file diff --git a/docs/features.rst b/docs/features.rst index eae1880..27d5dfd 100644 --- a/docs/features.rst +++ b/docs/features.rst @@ -6,22 +6,13 @@ Molecular Design Toolkit Features -Simulation methods ------------------- - -Energy models -^^^^^^^^^^^^^ - -**Methods** - - - :meth:`Molecule.calculate` Calculate molecular properties using the assigned energy model - - - :meth:`Molecule.minimize` Perform an energy minimization using the assigned energy model - -**Classical** +Molecular Mechanics +------------------- - :class:`models.Forcefield` Generic Forcefield energy model (automatically chosen implementation) + - :class:`models.GAFF` Amber force field for small organic molecules + - :class:`models.OpenMMEnergyModel` OpenMM energy kernel for Amber/CHARMM-like forcefields - :class:`models.SanderEnergyModel` Sander energy kernel (from AmberTools) for Amber/CHARMM-like forcefields @@ -30,11 +21,15 @@ Energy models - :class:`models.HarmonicOscillator` A 1-D Harmonic oscillator centered at x=0 (for testing and toy models) -**Quantum** - - :class:`models.RHF` Generic restricted Hartree-Fock (automatically chosen implementation) +Quantum Chemistry +----------------- + + - :class:`models.RHF` Restricted Hartree-Fock (automatically chosen implementation) - - :class:`models.DFT` Generic density functional theories (automatically chosen implementation) + - :class:`models.DFT` Density functional theories (automatically chosen implementation) + + - :class:`models.CASSCF` Complete-active space MCSCF (automatically chosen implementation) - :class:`models.Semiempirical` Generic semiempirical theories (automatically chosen implementation) @@ -43,8 +38,8 @@ Energy models - :class:`models.SQM` SQM semi-empirical energy kernel (from AmberTools), includes implementations for a large number of semiempirical models, including MNDO, AM1, PM3, PM6, DFTB -Integrators -^^^^^^^^^^^ +Molecular Dynamics +^^^^^^^^^^^^^^^^^^ - :class:`integrators.VelocityVerlet` Generic Velocity Verlet dynamics (automatically chosen implementation) @@ -57,8 +52,8 @@ Integrators - :class:`integrators.SurfaceHopping` Multi-state surface hopping dynamics using fewest switched. Implementation: internal. -Interactive Widgets -------------------- +Interactive visualization +------------------------- - :class:`viewer.Configurator` Automatically generates user interfaces for configuring simulations @@ -107,8 +102,8 @@ Simulation results are stored in numpy arrays with an explicit unit system based - :meth:`Trajectory.time` :meth:`Trajectory.potential_energy` :meth:`Trajectory.kinetic_temperature` ``...`` - Return timeseries of times, energies, temperatures, etc. over the course of a trajectory -Conversions ------------ +Interfaces +---------- **Files and databases** diff --git a/docs/geometry.rst b/docs/geometry.rst new file mode 100644 index 0000000..3acae61 --- /dev/null +++ b/docs/geometry.rst @@ -0,0 +1,41 @@ +Geometry tools +============== + + +Measure geometry +---------------- + +The :mod:`moldesign.geom` module contains a variety of methods for measuring (and +manipulate geometry). + +You can get the distance between any two atoms with the +:meth:`atom.distance ` method. + + >>> atom1.distance(atom2) + [...] angstrom + +Bond angles and dihedral (twist) angles can be measured using the :meth:`moldesign.geom.angle` +and :meth:`moldesign.geom.dihedral` methods: + + >>> moldesign.geom.angle(atom1, atom2, atom3) + [...] radians + >>> moldesign.geom.dihedral(atom1, atom2, atom3, atom4) + [...] radians + + +Manipulate geometry +------------------- + +WIP + + +Analyze dynamics +---------------- + +WIP + + +Constrain geometry +------------------ + +WIP \ No newline at end of file diff --git a/docs/howdoi.rst b/docs/howdoi.rst deleted file mode 100644 index 85716e3..0000000 --- a/docs/howdoi.rst +++ /dev/null @@ -1,203 +0,0 @@ -============= -How do I ...? -============= - -.. contents:: Quick guides to common tasks - :depth: 2 - - -How do I create a small molecule? ---------------------------------- -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 `_ - - >>> benzene = mdt.from_smiles('c1ccccc1') - >>> caffeine = mdt.from_smiles('CN1C=NC2=C1C(=O)N(C(=O)N2C)C') - -or read it from a number of file formats: - - >>> benzene = mdt.read('/home/myuser/benzene.sdf') - >>> caffeine = mdt.read('/home/myuser/caffeine.xyz') - - - -How do I import a biomolecule? ------------------------------- - -Basic PDB structures -^^^^^^^^^^^^^^^^^^^^ -If you're looking for a specific biomolecule, you'll find its structure on -`the RCSB Protein Databank (PDB) `_ (if a structure exists). Structures in PDB are -indexed with 4-character codes (such as `1MBN `_, `3AID `_, `3FPP `_, ...). - -To download a structure with -a specific PDB code, you can use - - >>> mol = mdt.from_pdb('3AID') - >>> mol.draw() - - .. image:: img/howdoi_pdb1.png - -You can, of course, also read in files from a variety of formats: - - >>> mol = mdt.read('/path/to/3AID.pdb') - -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 `_. - -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. - - -How do I measure bonds? ------------------------ - -The :mod:`moldesign.geom` module contains a variety of methods for measuring (and -manipulate geometry). - -You can get the distance between any two atoms with the -:meth:`atom.distance ` method. - - >>> atom1.distance(atom2) - [...] angstrom - -Bond angles and dihedral (twist) angles can be measured using the :meth:`moldesign.geom.angle` -and :meth:`moldesign.geom.dihedral` methods: - - >>> moldesign.geom.angle(atom1, atom2, atom3) - [...] radians - >>> moldesign.geom.dihedral(atom1, atom2, atom3, atom4) - [...] radians - - - -How do I visualize molecular orbitals? --------------------------------------- -First, you'll need to calculate the molecule's electronic structure using a quantum chemistry -model. Quantum chemistry models are a type of -:class:`Energy Model ` in MDT. - -You can use iPython's autocomplete to get a list of the available methods by typing -``mdt.models.`` and then hitting the ``Tab`` key: - -.. image:: img/howdoi_method_autocomplete.png - -In this example, let's set up a small molecule with a simple quantum chemistry model - -`restricted Hartree-Fock. `_ - - >>> mol = mdt.from_name('benzene') - >>> mol.set_energy_model(mdt.models.RHF(basis='6-31g')) - - -Next, we'll run a calculation with this model - this will calculate several relevant properties for -the molecule. - - >>> mol.calculate() - >>> mol.potential_energy - -6275.56597497 eV - >>> mol.wfn - - -These properties are stored in a :class:`dict` at ``mol.properties``: - - >>> mol.properties.keys() - ['wfn', 'positions', 'mulliken', 'potential_energy'] - -Most relevant for our purposes, we've calculated the electronic state of the molecule and are -ready to visualize it. - - >>> mol.draw_orbitals() - - .. image:: img/howdoi_orbs.png - -In an actual notebook, you can use the controls on the right to control the visualization. - - - - -How do I perform an energy minimization? ----------------------------------------- -First, you'll need to create an :class:`EnergyModel ` for your molecule. Energy models can include quantum chemical, molecular mechanics, or wide assortment of other methods. - -We'll follow the same setup as the previous step: - - >>> mol = mdt.from_name('benzene') - >>> mol.set_energy_model(mdt.models.RHF(basis='sto-3g')) - -Now that our molecule has an :class:`EnergyModel `, we can calculate energies and forces: - - >>> mol.calculate_forces() # returns vector of forces - >>> mol.calculate_potential_energy() # returns the molecule's energy - -You're now ready to use the molecule's :meth:`minimize ` method: - - >>> trajectory = mol.minimize(nsteps=10, frame_interval=1) - -And you can visualize the minimization process using the trajectory object: - - >>> trajectory.draw_orbitals() - -.. image:: img/benz_min_traj.png - - -How do I customize a 3D view? ------------------------------ -First, create a viewer. It will be rendered in your notebook when it's the last object evaluated in a code cell. - - >>> import moldesign as mdt - >>> from moldesign import units as u - >>> mol = mdt.from_pdb('3AID') - >>> viewer = mol.draw3d() - >>> viewer - -.. image:: img/howdoi_view1.png - -At this point, the viewer will be drawn into your notebook. You can continue to manipulate it after it's been drawn. - -For starters, let's turn all the waters purple. - - >>> wateratoms = [atom for atom in mol.atoms if atom.residue.type == 'water'] - >>> viewer.vdw(atoms=wateratoms, color='purple') - -.. image:: img/howdoi_purplewater.png - -Next, let's make that drug molecule really stand out with with a transparent sphere, an arrow, -and a label: - - >>> drug = mol.chains['A'].residues['ARQ401'] - >>> r = drug.center_of_mass - >>> sphere = viewer.draw_sphere(position=r, radius=6*u.angstrom, opacity=0.5, color='green') - >>> arrow = viewer.draw_arrow(start=r+[0,0,26]*u.angstrom, end=r+[0,0,6]*u.angstrom, radius=3) - >>> label = viewer.draw_label(text="Here's the drug", position=r) - -.. image:: img/howdoi_annotated.png - -Maybe that's too much - let's remove the label and the sphere. - - >>> viewer.remove(label) - >>> viewer.remove(sphere) - -.. image:: img/howdoi_subtle.png - - diff --git a/docs/index.rst b/docs/index.rst index be94c8f..26dc7b9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,56 +1,47 @@ -=========================================== -Molecular Design Toolkit: API documentation -=========================================== +Molecular Design Toolkit |version| +################################## -These pages provide reference API documentation for the Molecular Design Toolkit. +Molecular science is hard - the software shouldn't make it harder. The `Molecular Design Toolkit `_ offers access to a large and still-growing set of computational modeling methods from a science-focused, Python API. When you +call MDT functions from a Jupyter notebook, you'll also be get inline 2D and 3D visualization, +plotting support, and interactivity. -Just getting started? We recommend trying out `the tutorials and -walkthroughs `_ before diving into the API. +`Try a live demo now. `_ +MDT is free, open source, and is built for scientific collaboration. -Quick install -------------- -Get the latest stable version: -.. code-block:: bash - $ pip install moldesign +.. toctree:: + :maxdepth: 2 + :numbered: + :caption: Getting started -**Note:** some users may need to run the installation as root, i.e. ``sudo pip install moldesign`` + quickstart + features + install -Or get the source code on github: -.. code-block:: bash +.. toctree:: + :maxdepth: 2 + :numbered: + :caption: Recipes - $ git clone github.com/autodesk/molecular-design-toolkit + creating_and_converting + structure + biomolecule + geometry + properties + dynamics + visualization -Get started ------------ -At the command line, run +.. toctree:: + :maxdepth: 2 + :numbered: + :caption: API Reference -.. code-block:: bash + api/general + api/atoms - $ python -m moldesign intro - - -Explore the API ---------------- -The Jupyter online documentation system is a powerful tool for discovering functionality. - -To get a list of all members of a module or class, type ``modulename.``, then hit `tab`. - -.. image:: img/tab_autocomplete.png - -To get online documentation about a function or method, type the method's name, then hit `shift+tab` - -.. image:: img/shifttab_online.png - -To get the complete docstring for any object, type its name then a question mark. - -.. image:: img/questiondoc.png - - -Get help --------- -Click a link in the navigation menu (to your left) for in-depth documentation. +* :ref:`Alphabetical index ` +* :ref:`Search ` \ No newline at end of file diff --git a/docs/install.rst b/docs/install.rst index dbd3f69..6e4de94 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -107,7 +107,8 @@ If you run into problems, see the `documentation `_ and Changing where your jobs run ============================ -The toolkit is built to run jobs using the `Docker containerization technology `_ (which *has nothing to do with molecular docking*). Docker eliminates the need to configure or compile +The toolkit is built to run jobs using the `Docker containerization technology `_ +(which *has nothing to do with molecular docking*). Docker eliminates the need to configure or compile software on different computers. By default, MDT is configured to use a free cloud-based docker cluster provided by Autodesk @@ -115,30 +116,52 @@ Research. If you'd like to run jobs on your local machine, you'll need to instal things. -Running jobs locally --------------------- -Using a docker-machine -^^^^^^^^^^^^^^^^^^^^^^ -A recent version of Docker (>1.11) is required. +Running locally with Docker +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +First, create or edit a file at ``$HOME/.moldesign/moldesign.yml`` with the line -*Mac or Windows*: Download and install the `Docker Toolbox `_. +.. code-block:: yaml -*Linux*: `Follow the instructions for your distribution `_. + engine_type: docker -Next, create a docker-machine (ideally, it should have at least 4 GB of RAM and 40 GB of disk -space): +Next, install Docker if necessary (version 1.11 or higher is required): + +- *Mac*: Download and install `Docker for Mac `_. +- *Windows*: Download and install `Docker for Windows `_. +- *Linux*: `Follow the instructions for your distribution `_. + +Once Docker is up and running, make sure to allocate enough RAM - 4 GB will work well for the +included example jobs. + +Running locally with CloudComputeCannon +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Our group has also developed +`CloudComputeCannon `_, a lightweight, +Docker-based job scheduling system which is more suitable for production than a bare Docker engine. + +You'll need Docker installed locally (see steps above). To install CCC: + +1. `Install the Node.js `_ javascript interpreter if necessary. +2. Update NPM if necessary: ``npm install npm -g`` +3. Do a global install of cloud compute cannon: ``npm install -g cloud-compute-cannon`` + +To run it: + +- To **start** the CCC scheduler, make sure Docker is running locally, then run ``ccc server-install`` +- To **stop** the CCC scheduler, run ``ccc server-stop`` + +Finally, update your MDT configuration to point to the CCC server by default by putting these lines in +``$HOME/.moldesign/moldesign.yml``: + +.. code-block:: yaml + + engine_type: cloudcomputecannon + default_ccc_server: localhost:9000 -.. code-block:: bash - $ docker-machine create --driver virtualbox --virtualbox-memory "4096" --virtualbox-disk-size "40000" -Running jobs on AWS --------------------- -coming soon System-specific installation ============================ diff --git a/docs/properties.rst b/docs/properties.rst new file mode 100644 index 0000000..ea10d92 --- /dev/null +++ b/docs/properties.rst @@ -0,0 +1,29 @@ +Property calculations +===================== + + +Optimize a geometry +------------------- +First, you'll need to create an :class:`EnergyModel ` for your molecule. Energy models can include quantum chemical, molecular mechanics, or wide assortment of other methods. + +We'll follow the same setup as the previous step: + + >>> mol = mdt.from_name('benzene') + >>> mol.set_energy_model(mdt.models.RHF(basis='sto-3g')) + +Now that our molecule has an :class:`EnergyModel `, we can calculate energies and forces: + + >>> mol.calculate_forces() # returns vector of forces + >>> mol.calculate_potential_energy() # returns the molecule's energy + +You're now ready to use the molecule's :meth:`minimize ` method: + + >>> trajectory = mol.minimize(nsteps=10, frame_interval=1) + +And you can visualize the minimization process using the trajectory object: + + >>> trajectory.draw_orbitals() + +.. image:: img/benz_min_traj.png + + diff --git a/docs/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 0000000..85653d7 --- /dev/null +++ b/docs/quickstart.rst @@ -0,0 +1,57 @@ +========== +Quickstart +========== + +These pages provide reference API documentation for the Molecular Design Toolkit. + +Just getting started? We recommend trying out `the tutorials and +walkthroughs `_ before diving into the API. + + +Install with pip +---------------- +Get the latest stable version: + +.. code-block:: bash + + $ pip install moldesign + +**Note:** some users may need to run the installation as root, i.e. ``sudo pip install moldesign``, +see `Installing MDT`_ for details. + +Or get the source code on github: + +.. code-block:: bash + + $ git clone github.com/autodesk/molecular-design-toolkit + + +Get started +----------- +At the command line, run + +.. code-block:: bash + + $ python -m moldesign intro + + +Explore the API +--------------- +The Jupyter online documentation system is a powerful tool for discovering functionality. + +To get a list of all members of a module or class, type ``modulename.``, then hit `tab`. + +.. image:: img/tab_autocomplete.png + +To get online documentation about a function or method, type the method's name, then hit `shift+tab` + +.. image:: img/shifttab_online.png + +To get the complete docstring for any object, type its name then a question mark. + +.. image:: img/questiondoc.png + + +Get help +-------- +Click a link in the navigation menu (to your left) for in-depth documentation. diff --git a/docs/structure.rst b/docs/structure.rst index aa13bed..cd16e01 100644 --- a/docs/structure.rst +++ b/docs/structure.rst @@ -1,6 +1,6 @@ -Atoms, molecules, and biomolecules ----------------------------------- -The Molecular design toolkit is built around familiar physical objects. Below is a quick rundown of +Molecular structure +------------------- +MDT is built around familiar physical objects. Below is a quick rundown of those objects and how they relate to one another. For most of the examples here, we'll look at a benzene molecule, which you can create as follows: @@ -167,29 +167,6 @@ Note: NotCalculatedError: The 'potential_energy' property hasn't been calculated yet. ... -Primary structure -""""""""""""""""" -**Class documentation:** :class:`moldesign.Chain`, :class:`moldesign.Residue` - -Biomolecules also contain primary structure information such as :class:`Chains ` -and :class:`Residues `. 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 `. 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`. - - Electronic structure """""""""""""""""""" **Class documentation:** :class:`moldesign.orbitals.wfn.ElectronicWfn` diff --git a/docs/visualization.rst b/docs/visualization.rst new file mode 100644 index 0000000..2a39330 --- /dev/null +++ b/docs/visualization.rst @@ -0,0 +1,87 @@ +Visualization +============= + + + +Visualize molecular orbitals +---------------------------- +First, you'll need to calculate the molecule's electronic structure using a quantum chemistry +model. Quantum chemistry models are a type of +:class:`Energy Model ` in MDT. + +You can use iPython's autocomplete to get a list of the available methods by typing +``mdt.models.`` and then hitting the ``Tab`` key: + +.. image:: img/howdoi_method_autocomplete.png + +In this example, let's set up a small molecule with a simple quantum chemistry model - +`restricted Hartree-Fock. `_ + + >>> mol = mdt.from_name('benzene') + >>> mol.set_energy_model(mdt.models.RHF(basis='6-31g')) + + +Next, we'll run a calculation with this model - this will calculate several relevant properties for +the molecule. + + >>> mol.calculate() + >>> mol.potential_energy + -6275.56597497 eV + >>> mol.wfn + + +These properties are stored in a :class:`dict` at ``mol.properties``: + + >>> mol.properties.keys() + ['wfn', 'positions', 'mulliken', 'potential_energy'] + +Most relevant for our purposes, we've calculated the electronic state of the molecule and are +ready to visualize it. + + >>> mol.draw_orbitals() + + .. image:: img/howdoi_orbs.png + +In an actual notebook, you can use the controls on the right to control the visualization. + + + +Maniuplate a 3D visualization +----------------------------- +First, create a viewer. It will be rendered in your notebook when it's the last object evaluated in a code cell. + + >>> import moldesign as mdt + >>> from moldesign import units as u + >>> mol = mdt.from_pdb('3AID') + >>> viewer = mol.draw3d() + >>> viewer + +.. image:: img/howdoi_view1.png + +At this point, the viewer will be drawn into your notebook. You can continue to manipulate it after it's been drawn. + +For starters, let's turn all the waters purple. + + >>> wateratoms = [atom for atom in mol.atoms if atom.residue.type == 'water'] + >>> viewer.vdw(atoms=wateratoms, color='purple') + +.. image:: img/howdoi_purplewater.png + +Next, let's make that drug molecule really stand out with with a transparent sphere, an arrow, +and a label: + + >>> drug = mol.chains['A'].residues['ARQ401'] + >>> r = drug.center_of_mass + >>> sphere = viewer.draw_sphere(position=r, radius=6*u.angstrom, opacity=0.5, color='green') + >>> arrow = viewer.draw_arrow(start=r+[0,0,26]*u.angstrom, end=r+[0,0,6]*u.angstrom, radius=3) + >>> label = viewer.draw_label(text="Here's the drug", position=r) + +.. image:: img/howdoi_annotated.png + +Maybe that's too much - let's remove the label and the sphere. + + >>> viewer.remove(label) + >>> viewer.remove(sphere) + +.. image:: img/howdoi_subtle.png +