Updated the MEASURE documentation to reflect recent changes.

Most important are the changes to the input and output file syntax. Since
we probably won't have a web form or GUI for generating an input file for
some time, it is extremely important that this documentation be complete,
comprehensible, and accurate. Also important is the installation procedure,
which has changed somewhat since MEASURE was merged into the RMG-Py source
tree. However, I expect most users to start with the web interface, so
installation may be less important in the near term.

Also fixed the API documentation to reflect the new functions for reading
and writing MEASURE files.

Author: jwallen

documentation/source/developers/measure/input.rst

@@ -6,7 +6,7 @@
 
 .. autoclass:: rmgpy.measure.input.InputError
 
-.. autofunction:: rmgpy.measure.input.readInput
+.. autofunction:: rmgpy.measure.input.readFile
 
 .. autofunction:: rmgpy.measure.input.generateThermoFromStates
 

documentation/source/developers/measure/output.rst

@@ -7,9 +7,7 @@
 Input and Output File Writing
 =============================
 
-.. autofunction:: rmgpy.measure.output.writeInput
-
-.. autofunction:: rmgpy.measure.output.writeOutput
+.. autofunction:: rmgpy.measure.output.writeFile
 
 Helper Functions
 ================

documentation/source/users/measure/input.rst

@@ -2,10 +2,11 @@
 Creating Input Files
 ********************
 
-There are three parts to a MEASURE input file, giving the species, path 
-reaction, and algorithm parameters. The species section must come before the
-reaction section. Before discussing each of these sections, a brief word on the 
-input file syntax will be provided.
+There are four parts to a MEASURE input file, giving the species, important
+unimolecular and bimolecular configurations, path reactions, and algorithm 
+parameters. The species section must come before the reaction section. Before 
+discussing each of these sections, a brief word on the general input file 
+syntax will be given.
 
 Syntax
 ======
@@ -19,20 +20,20 @@ specified as text strings, numbers, or objects. Text strings must be wrapped in
 either single or double quotes. There are two ways to specify numeric 
 quantities:
 
-* Dimensionless quantities or values already in SI units can be specified as
-  a simple literal, such as ``0.99``.
+* Dimensionless quantities can be specified as a simple literal, such as 
+  ``0.99``.
 
-* Quantities not in SI units are specified using a tuple of the form 
+* Dimensional quantities are specified using a tuple of the form 
   ``(value, units)``, where ``value`` is either a single number or a list of
-  numbers, and ``units`` is a string, e.g. ``(-10.0,'kcal/mol')`` and
+  numbers, and ``units`` is a string, e.g. ``(-10.0,'kcal/mol')`` or
   ``([1.0, 2.0, 3.0],"m")``.
 
 .. note::
 
     MEASURE uses the ``quantities`` package to convert your numeric parameters
     into SI units, and therefore inherits all of the idiosyncracies from that 
     package. In particular, the ``quantities`` package does *not*
-    follow the SI convention that all units after the circumflex are in the
+    follow the SI convention that all units after the forward slash are in the
     denominator. For example, ``J/mol*K`` would be interpreted as ``(J/mol)*K``
     rather than ``J/(mol*K)``. Thus we recommend using parentheses where
     necessary to make your intentions explicit.
@@ -71,49 +72,104 @@ bimolecular reactant channels. When specifying the ``states`` parameter, use a
 =========================== ====================================================
 Parameter                   Description
 =========================== ====================================================
-``rotationalConstants``     A list of the external rotational constants
-``symmetry``                The external symmetry number
-``frequencies``             A list of the vibrational frequencies
+``rotations``               Parameters describing the external rotational motion, as a ``RigidRotor()`` object
+``vibrations``              Parameters describing the internal vibrational motion, as a ``HarmonicOscillator()`` object
+``torsions``                Parameters describing the internal torsional motion, as a list of ``HinderedRotor()`` objects
 ``frequencyScaleFactor``    The frequency scale factor to use (1.0 if not specified)
-``hinderedRotors``          A list of simple Pitzer hindered rotors, specified as 3-tuples (``frequency``, ``barrier``, ``symmetry``)
 ``spinMultiplicity``        The ground-state spin multiplicity (degeneracy)
 =========================== ====================================================
 
+The ``RigidRotor()``, ``HarmonicOscillator()``, and ``HinderedRotor()``
+constructors match the corresponding classes in the :mod:`rmgpy.statmech`
+module. The parameters for each are also summarized below:
+
+=========================== ====================================================
+Parameter                   Description
+=========================== ====================================================
+``RigidRotor()``
+--------------------------- ----------------------------------------------------
+`linear`                    ``True`` if the associated molecule is linear, ``False`` if nonlinear
+`inertia`                   A list of the moment(s) of inertia of the molecule (1 if linear, 3 if nonlinear)
+`symmetry`                  The total external rotational symmetry number
+--------------------------- ----------------------------------------------------
+``HarmonicOscillator()``
+--------------------------- ----------------------------------------------------
+`frequencies`               The set of vibrational frequencies
+--------------------------- ----------------------------------------------------
+``HinderedRotor()``
+--------------------------- ----------------------------------------------------
+`inertia`                   The reduced moment of inertia of the hindered rotor
+`symmetry`                  The symmetry number for the hindered rotation
+`barrier`                   The barrier height of the cosine potential
+`fourier`                   The :math:`2 \times C` array of Fourier coefficients for the Fourier series potential
+=========================== ====================================================
+
+For each ``HinderedRotor()``, you need only specify one of the barrier height
+or Fourier series coefficients.
+
 If ``states`` is specified and ``thermo`` is not, then the thermodynamic
 parameters will be automatically computed. This is recommended unless you have
 thermodynamic data that you believe to be more accurate than the molecular
 degrees of freedom data. You can use any of the thermodynamics models in the
-``chempy.thermo`` module (from the ChemPy package); see that package for more
-information on the available models and their syntax.
+``rmgpy.thermo`` module; see that package for more information on the available
+models and their syntax.
 
 The following is an example of a typical species item, based on the acetylperoxy
 radical :math:`\ce{CH3C(=O)OO.}`::
 
     species(
-        label="acetylperoxy",
-        SMILES="CC(=O)O[O]",
-        E0=(-144.766,"kJ/mol"),
+        label='acetylperoxy',
+        SMILES='CC(=O)O[O]',
+        E0=(-34.6,'kcal/mol'),
         states=States(
-            rotationalConstants=([54.2978, 104.836, 156.049], "amu/angstrom^2"),
-            symmetry=1,
-            frequencies=([321.607, 503.468, 539.885, 547.148, 731.506, 979.187, 1043.98, 1126.42, 1188.62, 1399.43, 1458.2, 1463.42, 1881.7, 3055.28, 3115.45, 3155.14], "cm^-1"),
-            frequencyScaleFactor=1.0,
-            hinderedRotors=[
-                ((7.38359,"amu*angstrom^2"), (25.5921,"kJ/mol"), 1),
-                ((2.94725,"amu*angstrom^2"), (5.11105,"kJ/mol"), 3),
+            rotations=RigidRotor(
+                linear=False,
+                inertia=([54.2978, 104.8364, 156.0495],"amu*angstrom^2"),
+                symmetry=1,
+            ),
+            vibrations=HarmonicOscillator(
+                frequencies=([321.607, 503.468, 539.885, 547.148, 731.506, 979.187, 1043.981, 1126.416, 1188.619, 1399.432, 1458.200, 1463.423, 1881.701, 3055.285, 3115.447, 3155.144], 'cm^-1'),
+            ),
+            torsions=[
+                HinderedRotor(inertia=(7.38359,"amu*angstrom^2"), barrier=(6.11665,"kcal/mol"), symmetry=1),
+                HinderedRotor(inertia=(2.94725,"amu*angstrom^2"), barrier=(1.22157,"kcal/mol"), symmetry=3),
             ],
+            frequencyScaleFactor=0.99,
             spinMultiplicity=2,
         ),
-        thermo=ThermoGAModel(
-            Tdata=([303.231, 385.553, 467.875, 550.197, 632.519, 714.841, 797.163, 879.485, 961.807, 1044.13, 1126.45, 1208.77, 1291.09, 1373.42, 1455.74, 1538.06, 1620.38, 1702.7, 1785.03, 1867.35], "K"),
-            Cpdata=([80.917, 92.4545, 102.856, 111.821, 119.406, 125.81, 131.243, 135.887, 139.882, 143.341, 146.352, 148.984, 151.294, 153.33, 155.129, 156.725, 158.145, 159.413, 160.548, 161.567], "J/(mol*K)"),
-            H298=(-127.614, "kJ/mol"),
-            S298=(314.403, "J/(mol*K)"),
-        ),
-        lennardJones=LennardJones(sigma=(5.09e-10,"m"), epsilon=(6.53048e-21,"J")),
-        molecularWeight=(75.0434,"g/mol"),
+        lennardJones=LennardJones(sigma=(5.09,'angstrom'), epsilon=(473,'K')),
     )
 
+Molecular Configurations
+========================
+
+MEASURE is largely able to determine the molecular configurations that define
+the potential energy surface for your reaction network simply by inspecting the
+path reactions. However, you must indicate which unimolecular and bimolecular
+configurations you wish to include in the master equation formulation; all 
+others will be treated as irreversible sinks. 
+
+* For a unimolecular configuration, use the ``isomer()`` method, passing as the
+  only parameter a string containing the label of the species to treat as a 
+  unimolecular isomer.
+
+* For a bimolecular configuration, use the ``reactants()`` method, passing as
+  the two parameters a pair of strings containing the labels of the species to 
+  treat as a bimolecular reactant channel. (A reactant channel is allowed to be
+  both a source and a sink, i.e. both association and dissociation pathways are
+  kept.)
+
+For example, the following input specifies acetylperoxy as a unimolecular
+isomer and acetyl + oxygen as a bimolecular reactant channel.
+  
+    isomer('acetylperoxy')
+
+    reactants('acetyl', 'oxygen')
+
+You do not need to specify the product channels (infinite sinks) in this 
+manner, as any configuration not marked as an isomer or reactant channel will
+be treated as a product channel.
+
 Path Reaction Parameters
 ========================
 
@@ -127,17 +183,9 @@ Parameter              Required?            Description
 ``reactants``          All reactions        A list of strings indicating the labels of the reactant species
 ``products``           All reactions        A list of strings indicating the labels of the product species
 ``transitionState``    All reactions        Information about the transition state, using a ``TransitionState()`` block; see below
-``reversible``                              ``True`` (default) if the reaction is reversible, ``False`` if not
 ``kinetics``                                The high pressure-limit kinetics for the reaction
 ====================== ==================== ====================================
 
-The direction and reversibility of the reactions determine how bimolecular
-configurations are divided into reactants. If the bimolecular configuration is
-listed as the reactants or ``reversible`` is ``True``, the configuration is
-set as a reactant channel. If the bimolecular configuration is listed as the
-products and ``reversible`` is ``False``, the configuration is set as a product
-channel.
-
 The type of information specified with each path reaction determines how the
 microcanonical rate coefficient is computed:
 
@@ -164,7 +212,6 @@ The following is an example of a typical reaction item, based on the reaction
     reaction(
         reactants=['acetylperoxy'],
         products=['ketene', 'hydroperoxyl'],
-        reversible=False,
         kinetics=Arrhenius(
             A=(2.62e9,'s^-1'),
             n=1.24,
@@ -173,11 +220,15 @@ The following is an example of a typical reaction item, based on the reaction
         transitionState=TransitionState(
             E0=(0.6,'kcal/mol'),
             states=States(
-                rotationalConstants=([55.4256, 136.1886, 188.2442], 'amu*angstrom^2'),
-                symmetry=1,
-                frequencies=([59.306,  205.421,  354.483,  468.861,  482.875,  545.574,  657.825,  891.898, 1023.947, 1085.617, 1257.494, 1316.937, 1378.552, 1688.566, 2175.346, 3079.822, 3154.325], 'cm^-1'),
+                rotations=RigidRotor(
+                    linear=False,
+                    inertia=([55.4256, 136.1886, 188.2442],"amu*angstrom^2"),
+                    symmetry=1,
+                ),
+                vibrations=HarmonicOscillator(
+                    frequencies=([59.306,  205.421,  354.483,  468.861,  482.875,  545.574,  657.825,  891.898, 1023.947, 1085.617, 1257.494, 1316.937, 1378.552, 1688.566, 2175.346, 3079.822, 3154.325], 'cm^-1'),
+                ),
                 frequencyScaleFactor=0.99,
-                hinderedRotors=[],
                 spinMultiplicity=2,
             ),
             frequency=(-1048.9950,'cm^-1'),
@@ -193,7 +244,7 @@ Collision Model
 The collision model to use when constructing the master equation is specified
 using a ``collisionModel()`` block, where you must specify both the ``type``
 of model, the value of any required ``parameters`` as a list of quantities,
-and a list of tuples specifying the labels of the species in the bath gas and
+and a dictionary specifying the labels of the species in the bath gas and
 their relative mole fractions. The collision models available are:
 
 * ``single exponential down`` - Specify ``alpha0``, ``T0`` and ``n`` for the 
@@ -267,11 +318,11 @@ Use a ``method()`` block to specify the approximate method to use when computing
 :math:`k(T,P)` values from the full master equation. There are currently three
 methods available: ``modified strong collision`` (MSC), ``reservoir state`` 
 (RS), and ``chemically-significant eigenvalues`` (CSE). The details of each of 
-these methods is provided in the :doc:`../theory/index`. In short: MSC is the
-fastest but least accurate, RS usually provides a good balance of speed and
-accuracy, while CSE is the most accurate but is slow and not robust. Currently
-we recommend using MSC during initial explorations, then RS when more accurate
-numbers are needed.
+these methods is provided in the :doc:`../../theory/measure/index`. In short: 
+MSC is the fastest but least accurate, RS usually provides a good balance of 
+speed and accuracy (except at very high temperatures), while CSE is the most 
+accurate but is slow and not robust. Currently we recommend using MSC during 
+initial explorations, then RS when more accurate numbers are needed.
 
 An example ``method()`` block is given below::
 

documentation/source/users/measure/installation.rst

@@ -28,25 +28,35 @@ Python standard library:
 * `Cairo <http://cairographics.org/>`_. Provides 2D drawing support, used for
   automatic drawing of potential energy surfaces.
 
-Finally, MEASURE also depends on the Green group's base library for Python
-projects, named `ChemPy <http://github.com/jwallen/ChemPy>`_.
-
 Installing MEASURE
 ==================
 
-Once you have obtained the required dependencies, MEASURE can be installed by
-executing the following command from within the root package directory::
+.. note::
+
+    MEASURE can also be used directly from the web! Visit 
+    http://rmg.mit.edu/measure/ for more information.
+
+MEASURE is installed automatically as part of the installation process for 
+RMG-Py. You can obtain a copy of RMG-Py from 
+http://github.com/GreenGroup/RMG-Py, either by downloading the current snapshot
+or by cloning the repository using `git <http://git-scm.com/>`_. The latter is
+recommended so that you can easily keep up to date with new features and 
+bugfixes.
+
+Once you have obtained the required dependencies, RMG-Py and MEASURE can be 
+installed by executing the following command from within the root package 
+directory::
 
     $ python setup.py install
 
 This will move all of the necessary files to the appropriate Python installation
 location on disk. If Cython is installed, this will also compile the appropriate
 modules prior to installation.
 
-You can also use MEASURE without installing if you prefer. This is done by
-appending the full path to the package's root directory to your ``PYTHONPATH``
-environment variable. To compile the Cython modules in this case, use the
-command ::
+You can also use RMG-Py and MEASURE without installing if you prefer. This is 
+done by appending the full path to the package's root directory to your 
+``PYTHONPATH`` environment variable. To compile the Cython modules in this 
+case, use the command ::
 
     $ python setup.py build_ext --inplace
 

documentation/source/users/measure/introduction.rst

@@ -19,11 +19,11 @@ About MEASURE
 MEASURE was originally developed by Joshua W. Allen under the tutelage of
 `Prof. William H. Green <http://web.mit.edu/greengp/>`_ in the 
 `Department of Chemical Engineering <http://web.mit.edu/cheme/>`_ at the 
-`Massachusetts Institute of Technology <http://web.mit.edu/>`_. Its original 
-purpose was to be a component of the automatic reaction mechanism generation
-software `RMG <http://rmg.sourceforge.net/>`_. Since then it has also been 
-adapted as a standalone package useful for investigating individual reaction 
-networks in greater detail.
+`Massachusetts Institute of Technology <http://web.mit.edu/>`_. It is a
+component of the automatic reaction mechanism generation software 
+`RMG <http://rmg.sourceforge.net/>`_, and provides functionality for estimating
+pressure-dependent rate coefficients to that software. It is also useful as
+a tool for exploring individual reaction networks in detail.
 
 MEASURE is written in the `Python <http://www.python.org/>`_ programming
 language to facilitate ease of development, installation, and use. Certain

documentation/source/users/measure/output.rst

@@ -2,19 +2,33 @@
 Parsing Output Files
 ********************
 
+Output File
+===========
+
 The syntax of MEASURE output files closely mirrors that of the input files.
-The output files contain two sections: 
+In fact, the output file contains the entire contents of the input file. In
+addition, the output file contains a block of ``pdepreaction()`` calls. The 
+parameters of each ``pdepreaction()`` block match those of the ``reaction()`` 
+block from the input file, except that no transition state data is given and 
+the ``kinetics`` are by definition pressure-dependent. 
+
+A ``pdepreaction()`` item is printed for the forward and reverse direction of 
+every reaction involving isomers and reactant channels only. For reactions 
+involving a product channel, there is only a ``pdepreaction()`` item for the 
+direction in which the product channel is the product of the reaction. To use
+this output, you must either keep all of the reactions and treat them as
+irreversible, or discard the duplicate reverse directions and treat the
+remaining reactions as reversible. This decision is left to the end user.
 
-* The first section contains all of the species involved in the reaction 
-  network, including the bath gas(es), as ``species()`` blocks. This is largely
-  a reproduction of the same section of the input file. 
+Log File
+========
 
-* The second section contains all of the path reactions - reactions between any 
-  pair of molecular configurations on the potential energy surface, not just 
-  those directly adjacent - as ``pdepreaction()`` blocks. The parameters of each 
-  ``pdepreaction()`` block match those of the ``reaction()`` block from the  
-  input file, except that no transition state data is given and the ``kinetics``  
-  are by definition pressure-dependent.
+A log file containing similar information to that displayed on the console
+during MEASURE execution is also automatically saved. This file has the name
+``MEASURE.log`` and is found in the same directory as the output file. The
+log file accepts logging messages at an equal or greater level of detail than
+the console; thus, it is often useful (and recommended) to examine both if
+something unexpected has occurred.
 
 The ``examples`` directory contains both MEASURE input files and the resulting
 output files.