From bea2bb939c2d9ba51a1c4ce9e6e7e786b145aa09 Mon Sep 17 00:00:00 2001
From: Gabriel Studer <gabriel.studer@unibas.ch>
Date: Thu, 30 Apr 2015 08:01:05 +0200
Subject: [PATCH] add a link to mol.mm into the overall documentation and
generate an entry page for the mm module
---
modules/index.rst | 2 +-
modules/mol/mm/doc/molmm.rst | 74 ++++++++++++++++++++++++++++++++++++
2 files changed, 75 insertions(+), 1 deletion(-)
create mode 100644 modules/mol/mm/doc/molmm.rst
diff --git a/modules/index.rst b/modules/index.rst
index 5f043a238..e88395ef9 100644
--- a/modules/index.rst
+++ b/modules/index.rst
@@ -43,7 +43,7 @@ For Starters
Molecules
--------------------------------------------------------------------------------
-**Overview**: :doc:`molecules intro <intro-01>` | :doc:`mol overview <mol/base/mol>` | :doc:`graphical entity<gfx/entity>` | :doc:`entity <mol/base/entity>` | :doc:`queries <mol/base/query>` | :doc:`algorithms <mol/alg/molalg>`
+**Overview**: :doc:`molecules intro <intro-01>` | :doc:`mol overview <mol/base/mol>` | :doc:`graphical entity<gfx/entity>` | :doc:`entity <mol/base/entity>` | :doc:`queries <mol/base/query>` | :doc:`algorithms <mol/alg/molalg>` | :doc:`mm <mol/mm/molmm>`
**Trajectories**: :doc:`basics <mol/base/traj>` | :ref:`analysis <traj-analysis>`
diff --git a/modules/mol/mm/doc/molmm.rst b/modules/mol/mm/doc/molmm.rst
new file mode 100644
index 000000000..91e08c6e4
--- /dev/null
+++ b/modules/mol/mm/doc/molmm.rst
@@ -0,0 +1,74 @@
+The mm Module
+================================================================================
+
+.. currentmodule:: ost.mol
+
+Introduction
+--------------------------------------------------------------------------------
+
+The mol.mm module provides a wrapper around the
+`OpenMM <http://openmm.org>`_ molecular mechanics library to provide
+basic md capabilities fully embedded into the OpenStructure universe.
+The heart of every simulation is the :class:`Topology` describing how the
+particles of an :class:`EntityHandle` interact. The :class:`Simulation` finally
+connects the two and allows to perform energy minimizations or move the simulation
+through time using an :class:`Integrator`.
+A :class:`Topology` can either be built from scratch by adding
+one interaction after the other or fully automatically using the
+:class:`TopologyCreator`. The whole process of :class:`Topology` building
+and setting up a :class:`Simulation` gets controlled with the :class:`Settings`.
+
+
+Installation
+--------------------------------------------------------------------------------
+
+Openstructure does not come by default with
+`OpenMM <http://openmm.org>`_ support.
+You have to install it by yourself as an additional dependency and
+recompile OpenStructure to dive into the amazing world of GPU accelerated
+molecular mechanics. Once installed, you have to pass cmake additional
+flags to allow compilation with OpenMM support. e.g.:
+
+ .. code-block:: bash
+
+ cmake . -DENABLE_MM=1 -DOPEN_MM_INCLUDE_DIR=/path/to/openmm/include
+ -DOPEN_MM_LIBRARY=/path/to/openmm/lib/libOpenMM.so
+
+
+Setting up a simple simulation
+--------------------------------------------------------------------------------
+
+
+ .. code-block:: python
+
+ from ost.mol import mm
+
+ prot=io.LoadPDB('awesome_structure.pdb')
+
+ #set up the simulation
+ settings = mm.Settings()
+ settings.integrator = mm.LangevinIntegrator(310,1,0.002)
+ settings.forcefield = mm.LoadCHARMMForcefield()
+ sim = mm.Simulation(prot,settings)
+
+ #minimize it
+ sim.ApplySD(tolerance = 1.0, max_iterations = 200)
+
+ #create a trajectory observer and register it to the simulation
+ observer = mm.TrajWriter(10,"example_traj.pdb","example_traj.dcd")
+ sim.Register(observer)
+
+ #run the simulation
+ sim.Steps(10000)
+
+ #Trajectory Observer needs to finalize, otherwise you might get a corrupt dcd file
+ observer.Finalize()
+
+
+Doing more sophisticated stuff
+--------------------------------------------------------------------------------
+
+You want to create your own :class:`BuildingBlock` to parametrize custom
+residues? Or even generate your custom :class:`Forcefield`?
+Check out the mm section in the example script directory.
+
--
GitLab