Merge pull request #995 from OpenFreeEnergy/docs_user_guide_edits

Edits to User Guide documentation

docs/guide/introduction.rst

@@ -13,42 +13,42 @@ Workflow overview
 
 The overall workflow of OpenFE involves three stages:
 
-1. **Setup**: Defining the simulation campaign you are going to run.
-2. **Execution**: Running and performing initial analysis of your
+1. :ref:`Simulation setup <userguide_setup>`: Defining the simulation campaign you are going to run.
+2. :ref:`Execution <userguide_execution>`: Running and performing initial analysis of your
    simulation campaign.
-3. **Gather results**: Assembling the results from the simulation
+3. :ref:`Gather results <userguide_results>`: Assembling the results from the simulation
    campaign for further analysis.
 
-In many use cases, these stages may be done on different machines -- for
+In many use cases, these stages may be done on different machines. For
 example, you are likely to make use of HPC or cloud computing resources to
-run the simulation campaign. Because of this, each stage has a certain type
-of output, which is the input to the next stage.
+run the simulation campaign. Because of this, each stage has a defined output which 
+is then the input for the next stage:
 
 .. TODO make figure
 .. .. figure:: ???
     :alt: Setup -> (AlchemicalNetwork) -> Execution -> (ProtocolResults) -> Gather
 
     The main stages of a free energy calculation in OpenFE, and the intermediates between them.
 
-The output of **setup** is an :class:`.AlchemicalNetwork`. This contains all
-the information about what is being simulated (e.g., what ligands, host proteins, solvation details etc) and the
+The output of the :ref:`simulation setup <userguide_setup>` stage is an :class:`.AlchemicalNetwork`. This contains all
+the information about what is being simulated (e.g., what ligands, host proteins, solvation details, etc.) and the
 information about how to perform the simulation (the Protocol).
 
-The output of the **execution** stage is the basic results from each edge.
+The output of the :ref:`execution <userguide_execution>` stage is the basic results from each edge.
 This can depend of the specific analysis intended, but will either involve a
 :class:`.ProtocolResult` representing the calculated :math:`\Delta G` for
 each edge or the :class:`.ProtocolDAGResult` linked to the data needed to
 calculate that :math:`\Delta G`.
 
-The **gather results** stage takes these results and produces something
-useful to the user. For example, the CLI's ``gather`` command will create a
+The :ref:`gather results <userguide_results>` stage aggregates the individual results for further analysis. For example, the CLI's ``gather`` command will create a
 table of the :math:`\Delta G` for each leg.
 
+.. TODO: Should the CLI workflow be moved to under "CLI Interface"?
 
 CLI Workflow
 ------------
 
-We have separate CLI commands for each stage of setup, running, and
+We have separate CLI commands for each stage of setup, execution, and
 gathering results. With the CLI, the Python objects of
 :class:`.AlchemicalNetwork` and :class:`.ProtocolResult` are stored to disk
 in an intermediate representation between the commands.
@@ -61,7 +61,7 @@ in an intermediate representation between the commands.
    planner to generate the network, before saving each transformation as a
    JSON file.
 
-The commands used to generate an :class:`AlchemicalNetwork` using the CLI are:
+The commands used to generate an :class:`.AlchemicalNetwork` using the CLI are:
 
 * :ref:`cli_plan-rbfe-network`
 * :ref:`cli_plan-rhfe-network`
@@ -72,7 +72,7 @@ For example, you can create a relative binding free energy (RBFE) network using
 
     $ openfe plan-rbfe-network -p protein.pdb -M dir_with_sdfs/
 
-These will save the alchemical network represented as a JSON file for each
+This will save the alchemical network represented as a JSON file for each
 edge of the :class:`.AlchemicalNetwork` (i.e., each leg of the alchemical cycle).
 
 To run a given transformation, use the :ref:`cli_quickrun`; for example:
@@ -88,8 +88,8 @@ from the network planning command with something like this:
 .. TODO Link to example here. I think this is waiting on the CLI example
    being merged into example notebooks?
 
-Finally, to gather the results of that, assuming all results (and only
-results) are in the `results/` direcory, use the :ref:`cli_gather`:
+Finally, assuming all results (and only results) are in the `results/` directory,
+use the :ref:`cli_gather` to generate a summary table:
 
 .. code:: bash
 

docs/guide/results/index.rst

@@ -1,7 +1,7 @@
 .. _userguide_results:
 
-Working with Results
-=====================
+Results Gathering
+=================
 
 With simulations completed,
 the results of individual simulations can be inspected,

docs/guide/setup/alchemical_network_model.rst

@@ -3,20 +3,21 @@
 Alchemical Networks: Planning a Simulation Campaign
 ===================================================
 
-The goal of the setup stage is to create an :class:`.AlchemicalNetwork`,
-which contains all the information needed for a campaign of simulations.
-This section will describe the composition of the achemical network,
-including the OpenFE objects that define chemistry, as well as
-alchemical transformations.
+The ultimate goal of the setup stage is to create an :class:`.AlchemicalNetwork`,
+which contains all the information needed for a campaign of simulations, including the 
+``openfe`` objects that define the chemical systems and alchemical transformations.
 
 .. TODO provide a written or image based comparison between alchemical and thermodynamic cycles
 
-Like any network, the :class:`.AlchemicalNetwork` can be described in terms
-of nodes and edges between nodes. The nodes are :class:`.ChemicalSystem`\ s,
+Like any network, an :class:`.AlchemicalNetwork` can be described in terms
+of nodes and edges between nodes. The nodes are :class:`.ChemicalSystem`\s,
 which describe the specific molecules involved. The edges are
 :class:`.Transformation` objects, which carry all the information about how
 the simulation is to be performed.
 
+
+.. figure:: img/AlchemicalNetwork.png
+
 In practice, nodes must be associated with a transformation in order to be
 relevant in an alchemical network; that is, there are no disconnected nodes.
 This means that the alchemical network can be fully described by just the
@@ -32,14 +33,48 @@ containing the information for each :class:`.ChemicalSystem`, the
 relevant, atom mapping information for alchemical transformations. The latter
 is often done through a :class:`.LigandNetwork`.
 
+.. _alchemical_network_creation:
 
-.. figure:: img/AlchemicalNetwork.png
+3 Ways to Create an Alchemical Network
+--------------------------------------
+
+1. Python API 
+^^^^^^^^^^^^^
+
+You can manually create a :class:`.AlchemicalNetwork` by creating a list
+of :class:`.Transformation` objects. For examples using the Python API,
+see :ref:`cookbook on creating alchemical networks <cookbook/create_alchemical_network.nblink>`.
+
+2. Python ``NetworkPlanner`` Convenience Classes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+OpenFE also provides the convenience classes :class:`.RBFEAlchemicalNetworkPlanner` and :class:`.RHFEAlchemicalNetworkPlanner`,
+which use the :class:`.RelativeHybridTopologyProtocol` for creating :class:`.AlchemicalNetwork`\s.
+For example usage of these convenience classes, see :ref:`Relative Alchemical Network Planners cookbook <cookbook/rfe_alchemical_planners.nblink>`.
+
+.. note::
+   The Network Planners are provided for user convenience. While they cover
+   majority of use cases, they may not currently offer the complete range
+   of options available through the Python API.
+
+3. Command Line ``NetworkPlanner`` 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Alchemical Network Planners can also be called directly from the 
+:ref:`command line interface <userguide_cli_interface>`.
+
+For example, you can create a Relative Hydration Free Energy (RHFE) network
+using:
+
+.. code:: bash
+
+    $ openfe plan-rhfe-network -M dir_with_sdfs/
+
+or a Relative Binding Free Energy (RBFE) network using:
 
+.. code:: bash
 
-.. TODO where to find details on settings
+    $ openfe plan-rbfe-network -p protein.pdb -M dir_with_sdfs/
 
-See Also
---------
 
-* :ref:`Alchemical Network API reference <Alchemical Network Planning>`
-* :ref:`Chemical Systems UserGuide entry <userguide_chemicalsystems_and_components>`
+For more CLI details, see :ref:`RBFE CLI tutorial <rbfe_cli_tutorial>` and the :ref:`userguide_cli_interface`.

docs/guide/setup/chemical_systems_and_thermodynamic_cycles.rst

@@ -1,54 +1,61 @@
 .. _userguide_chemicalsystems_and_components:
 
-ChemicalSystems, Components and Thermodynamic Cycles
-====================================================
+Chemical Systems, Components and Thermodynamic Cycles
+=====================================================
+
+.. _userguide_chemical_systems:
 
 Chemical Systems
 ----------------
 
-In order to define the input systems to a Protocol,
-which correspond as the end states of an alchemical transformation,
-we need an object model to represent their chemical composition.
-In ``openfe`` a :class:`.ChemicalSystem` is used to capture this information,
-and represents the chemical models that are present in each end state.
+A :class:`.ChemicalSystem` represents the end state of an alchemical transformation,
+which can then be input to a :class:`.Protocol`. 
 
-A :class:`.ChemicalSystem` **does** include information, where present, on:
+A :class:`.ChemicalSystem` **does** contain the following information (when present):
 
 * exact atomic information (including protonation state) of protein, ligands, co-factors, and any crystallographic
   waters
 * atomic positions of all explicitly defined components such as ligands or proteins
 * the abstract definition of the solvation environment, if present
 
-It **does not** include any information on:
+A :class:`.ChemicalSystem` does **NOT** include the following:
 
 * forcefield applied to any component, including details on water model or virtual particles
-* thermodynamic conditions, i.e. temperature and pressure
+* thermodynamic conditions (e.g. temperature or pressure)
+
+.. _userguide_components:
 
 Components
 ----------
 
-A :class:`.ChemicalSystem` is composed of many :class:`.Component` objects,
-each representing a single ''piece'' of the overall system.
+A :class:`.ChemicalSystem` is composed of many 'component' objects, which together define overall system.
+
 Examples of components include:
 
-* :class:`.ProteinComponent` to represent an entire biological assembly, typically the contents of a PDB file
-* :class:`.SmallMoleculeComponent` to represent ligands and cofactors
-* :class:`.SolventComponent` to represent the solvent conditions
+* :class:`.ProteinComponent`: an entire biological assembly, typically the contents of a PDB file.
+* :class:`.SmallMoleculeComponent`: typically ligands and cofactors
+* :class:`.SolventComponent`: solvent conditions
 
 Splitting the total system into components serves three purposes:
 
-* alchemical transformations can be easily understood by comparing the differences in Components
-* components can be reused to compose different systems
-* ``Protocol`` \s can treat different components differently, for example applying different force fields
+1. alchemical transformations can be easily understood by comparing the differences in components.
+2. components can be reused to compose different systems.
+3. :class:`.Protocol`\s can have component-specific behavior. E.g. different force fields for each component.
 
 Thermodynamic Cycles
 --------------------
 
-With a language to express chemical systems piecewise, we can now also construct thermodynamic cycles based on these.
+We can now describe a thermodynamic cycle as a set of :class:`.ChemicalSystem`\s. 
 The exact end states to construct are detailed in the :ref:`pages for each specific Protocol <userguide_protocols>`.
-For example to  construct the classic relative binding free energy cycle, we will need four components, two ligands,
-a protein, and a solvent.  These four ingredients can then be combined into the four points on the thermodynamic cycle
-that we wish to sample:
+
+As an example, we can construct the classic relative binding free energy cycle by defining four components: two ligands,
+a protein, and a solvent: 
+
+.. figure:: ../protocols/img/rbfe_thermocycle.png
+   :scale: 40%
+   :alt: RBFE thermodynamic cycle
+
+   Illustration of the relative binding free energy thermodynamic cycles and the chemical systems at each end state.
 
 ::
 
@@ -71,12 +78,6 @@ that we wish to sample:
   # ligand_A + solvent
   ligand_B_solvent = openfe.ChemicalSystem(components={'ligand': ligand_B, 'solvent': solvent})
 
-.. figure:: ../protocols/img/rbfe_thermocycle.png
-   :scale: 50%
-   :alt: RBFE thermodynamic cycle
-
-   Illustration of the relative binding free energy thermodynamic cycles and the chemical systems at each end state.
-
 
 See Also
 --------