DOC: Include updates for setting up ReadTheDocs page (#39)

* DOC: include documentation on BDSS objects

* DOC: include requirements files and dependencies for RTD

* FIX: ensure topology and coordinate GROMACS files are opened in UI, not saved

* DOC: update README and FragmentModel

* TST: unit test fixes for GROMACS input files

* DOC: update RTD links to subproject page

README.rst

@@ -9,6 +9,10 @@ FORCE BDSS GROMACS Plugin
    :target: http://codecov.io/github/force-h2020/force-bdss-plugin-gromacs?branch=master
    :alt: Coverage status
 
+.. image:: https://readthedocs.org/projects/force-gromacs/badge/?version=latest
+   :target: https://force-tutorial.readthedocs.io/projects/force-bdss-gromacs-plugin/en/latest/?badge=latest
+   :alt: Documentation Status
+
 This repository contains the implementation of a plugin for the Business Decision Support System (BDSS), contributing
 the `GROMACS <http://www.gromacs.org>`_ Molecular Dynamics package.
 It is implemented under the Formulations and Computational Engineering (FORCE) project within Horizon 2020
@@ -42,6 +46,9 @@ BDSS objects to be visible by both ``force-bdss`` and ``force-wfmanager`` applic
 Documentation
 -------------
 
-To build the Sphinx documentation in the ``doc/build`` directory run::
+Full documentation is being hosted at the `FORCE GROMACS ReadTheDocs page <https://force-tutorial.readthedocs.io/projects/force-bdss-gromacs-plugin>`_.
+
+Alternatively, to build the documentation locally in the ``doc/build`` directory, run::
 
     python -m ci docs
+

ci/__main__.py

@@ -15,6 +15,7 @@
 }
 
 ADDITIONAL_PIP_DEPS = [
+    'force_bdss>=0.4.0'
 ]
 
 

doc/rtd_requirements.txt

@@ -0,0 +1,4 @@
+sphinx==2.3.1
+docutils==0.16
+envisage>=4.9.2
+scipy>=1.2.1

doc/source/bdss-objects.rst

@@ -0,0 +1,108 @@
+BDSS Plugin Objects
+===================
+
+The FORCE Gromacs plugin also contributes serveral BDSS objects that can be used either
+out of the box or provide a base class for further customization.
+
+Data Sources
+------------
+
+FragmentDataSource
+~~~~~~~~~~~~~~~~~~
+
+The ``FragmentDataSource`` class provides an interface for a BDSS user to create a ``GromacsFragment`` that
+can be propagated through a Workflow as a ``DataValue``. The data source takes no input parameters, and produces
+a single output parameter, which is the ``GromacsFragment`` instance being constructed. Therefore it can be considered
+as a factory of ``GromacsFragment`` objects.
+
+The following information must be provided in the model interface:
+
+- **Name**: A human readable name of the fragment.
+- **Symbol**: The symbol that is used to idenfity the fragment in GROMACS input files
+- **Coordinate**: A path to the GROMACS coordinate ``.gro`` file that described the fragment's geometry
+- **Topology**: A path to the GROMACS topology ``.itp`` file that described the fragment's force field parameters
+
+MoleculeDataSource
+~~~~~~~~~~~~~~~~~~
+
+The ``MoleculeDataSource`` class provides an interface for a BDSS user to create a ``GromacsMolecule`` that
+can be propagated through a Workflow as a ``DataValue``. The data source takes one or more ``GromacsFragment``
+input parameters, and produces a single output parameter, which is the ``GromacsMolecule`` instance being constructed.
+Therefore it can be considered as a factory of ``GromacsMolecule`` objects.
+
+The following information must be provided in the model interface:
+
+- **No. Fragment Types**: The number of different fragment types in the molecule
+- **Fragment Numbers**: The stoichiometric number of each fragment type in the molecule
+
+SimulationDataSource
+~~~~~~~~~~~~~~~~~~~~
+
+The ``SimulationDataSource`` base class provides an interface for a BDSS user to create and run a
+``BaseGromacsSimulationBuilder`` instance that can construct and perform a ``GromacsPipeline`` object.
+The data source takes one or more ``GromacsMolecule`` input parameters, and produces a single output parameter,
+which is the file path to the GROMACS trajectory file that is expected to be post-processed by further data sources.
+
+The data source requires developers to implement the ``create_simulation_builder`` method, which produces
+a ``BaseGromacsSimulationBuilder`` instance.
+
+.. code-block:: python
+
+    def create_simulation_builder(self, model, parameters):
+        """Method that returns a `GromacsSimulationBuilder` object capable
+        of generating a `GromacsPipeline`
+
+        Parameters
+        ----------
+        model: SimulationDataSourceModel
+            The BaseDataSourceModel associated with this class
+        parameters: List(DataValue)
+            a list of DataValue objects containing the information needed
+            for the execution of the DataSource.
+
+        Returns
+        -------
+        simulation_builder: BaseGromacsSimulationBuilder
+            An object capable of generating a GromacsPipeline that calls
+            a Gromacs simulation
+        """
+
+It also emits a ``SimulationProgressEvent`` object containing
+the bash script for each GROMACS command that is called during the simulation.
+
+The following information must be provided in the model interface:
+
+- **Name**: A human readable name of the simulation.
+- **Output Directory**: The local directory path that will be used to contain simulation output and input files
+- **No. Molecule Types**: The number of different molecule types in the simulation cell
+- **Size**: The total number of fragments in the simulation
+- **No. Steps**: The length of the simulation in time steps
+- **MARTINI Parameter**: A path to the GROMACS topology ``.itp`` file that contains the MARTINI forcefield
+- **Minimization Parameter File**: File path to the GROMACS parameter ``.top`` file that contains the instructions for an
+  energy minimization run
+- **Production Parameter File**: File path to the GROMACS parameter ``.top`` file that contains the instructions for a
+  production run
+- **Overwrite Simulation Data?**: Whether or not to overwrite any existing simulation data files.
+- **Dry Run?**: Whether or not to perform a dry run of the simulation.
+- **MPI Run?**: Whether or not to perform an MPI run of the simulation using parallel processing
+- **No. Processes**: Number of processes to use in an MPI run
+- **Overwrite Data?**: Whether or not to overwrite any existing simulation data files.
+
+
+Notification Listeners
+----------------------
+
+HPCWriter
+~~~~~~~~~
+
+The ``HPCWriter`` class reacts to a ``SimulationProgressEvent`` in order to output bash file that can
+be used as a submission script to a HPC. The file contains the series of GROMACS commands that is communicated
+by the ``SimulationProgressEvent`` as well as a customizable header and prefix. The output file name is determined
+by the name of the simulation contained in the event's bash script.
+
+The following information must be provided in the model interface:
+
+- **Header**: The header of the output bash file containing HPC submission script details
+- **Prefix**: An extended multi-line section of the output bash file containing any additioanl submission script
+  details
+- **Dry Run?**: Whether or not to perform a dry run of writing the file.

doc/source/index.rst

@@ -14,6 +14,7 @@ User Manual
    :maxdepth: 1
 
    Introduction <introduction>
+   BDSS Objects <bdss-objects>
 
 API Reference
 =============

force_gromacs/data_sources/fragment/fragment_model.py

@@ -26,12 +26,14 @@ class FragmentDataSourceModel(BaseDataSourceModel):
     #: Location of Gromacs topology file containing molecular data
     topology = File(
         desc='File path for Gromacs topology file',
+        exists=True,
         verify=True
     )
 
     #: Location of Gromacs coordinate file containing molecular data
     coordinate = File(
         desc='File path for Gromacs coordinate file',
+        exists=True,
         verify=True
     )
 

force_gromacs/data_sources/fragment/tests/test_fragment_data_source.py

@@ -2,21 +2,23 @@
 #  All rights reserved.
 
 from unittest import TestCase
+from tempfile import NamedTemporaryFile
 
-from force_gromacs.gromacs_plugin import GromacsPlugin
+from force_gromacs.data_sources.fragment.fragment_factory import (
+    FragmentFactory)
 from force_gromacs.data_sources.fragment.fragment_data_source import (
     MissingFragmentException
 )
 from force_gromacs.tests.fixtures import (
-    gromacs_molecule_file
+    gromacs_molecule_file, gromacs_coordinate_file
 )
 
 
 class TestFragmentDataSource(TestCase):
 
     def setUp(self):
-        self.plugin = GromacsPlugin()
-        self.factory = self.plugin.data_source_factories[0]
+        self.factory = FragmentFactory(
+            plugin={'id': '0', 'name': 'test'})
         self.data_source = self.factory.create_data_source()
         self.model = self.factory.create_model()
 
@@ -25,7 +27,7 @@ def test_basic_function(self):
         self.model.name = "Solvent"
         self.model.symbol = "So"
         self.model.topology = gromacs_molecule_file
-        self.model.coordinate = "test_coord.gro"
+        self.model.coordinate = gromacs_coordinate_file
 
         res = self.data_source.run(self.model, [])
         self.assertEqual("FRAGMENT", res[0].type)
@@ -37,7 +39,7 @@ def test_basic_function(self):
         self.assertEqual(18.0, fragment.mass, )
         self.assertEqual(0, fragment.charge)
         self.assertEqual(gromacs_molecule_file, fragment.topology)
-        self.assertEqual("test_coord.gro", fragment.coordinate)
+        self.assertEqual(gromacs_coordinate_file, fragment.coordinate)
 
     def test_missing_fragment_error(self):
 
@@ -102,17 +104,18 @@ def test_model_verify(self):
             messages
         )
 
-        self.model.topology = "test_top.itp"
-        self.model.coordinate = "test_coord.go"
-        errors = self.model.verify()
-        messages = [error.local_error for error in errors]
-        self.assertEqual(2, len(messages))
-        self.assertNotIn(
-            'Gromacs file name is white space.',
-            messages
-        )
-
-        self.model.coordinate = "test_coord.gro"
+        with NamedTemporaryFile() as tmp_file:
+            self.model.topology = gromacs_molecule_file
+            self.model.coordinate = tmp_file.name
+            errors = self.model.verify()
+            messages = [error.local_error for error in errors]
+            self.assertEqual(2, len(messages))
+            self.assertNotIn(
+                'Gromacs file name is white space.',
+                messages
+            )
+
+        self.model.coordinate = gromacs_coordinate_file
         errors = self.model.verify()
         messages = [error.local_error for error in errors]
         self.assertEqual(1, len(messages))

setup.py

@@ -33,8 +33,5 @@ def write_version_py():
                 "force_gromacs.gromacs_plugin:GromacsPlugin"
             ]
         },
-    packages=find_packages(),
-    install_requires=[
-            "force_bdss >= 0.4.0",
-        ]
+    packages=find_packages()
 )