Issue 801 execution quickrun

docs/guide/execution/execution.rst → docs/guide/execution/execution_theory.rst

@@ -1,5 +1,7 @@
-Protocols and the Execution Model
-=================================
+.. _userguide_execution_theory:
+
+Protocols and the Execution Model Theory
+========================================
 
 Protocols in OpenFE are built on a flexible execution model. 
 Result objects are shaped by this model, and therefore some basic

docs/guide/execution/index.rst

@@ -1,17 +1,14 @@
 .. _userguide_execution:
 
 Execution
----------
+=========
 
-Given a :class:`.Transformation`, the easiest way to run it is to use the
-:func:`.execute_DAG` method. This will take the `.Transformation` object
-and execute its `.ProtocolUnit` instances serially. Once complete it will
-return a  :class:`.ProtocolDAGResult`. Multiple ProtocolDAGResults from a given
-transformation can be analyzed together with :meth:`.Protocol.gather` to
-create a :class:`.ProtocolResult`.
-
-
-.. TODO: add information about failures etc...
+With a :class:`.Transformation` defined, the next step is to execute this.
+The easiest way to run it is to use the :ref:`quickrun CLI tool <userguide_quickrun>`.
+More advanced options are available through first considering the
+:ref:`theory of the execution model<userguide_execution_theory>`
+then :ref:`reading on the available Python functions<reference_execution>`.
 
 .. toctree::
-   execution
+   quickrun_execution
+   execution_theory

docs/guide/execution/quickrun_execution.rst

@@ -0,0 +1,51 @@
+.. _userguide_quickrun:
+
+Execution with Quickrun
+=======================
+
+The planning and preparation of a campaign of alchemical simulations using the ``openfe`` package is intended to be
+achievable on a local workstation in a matter of minutes.
+The **execution** of these simulations however requires a large amount of computational power,
+and beyond running single calculations locally,
+is intended to be distributed across a HPC environment.
+Doing this requires storing and sending the details of the simulation from the local workstation to a HPC environment,
+this can be done via the :func:`.Transformation.dump` function which
+:ref:`creates a saved "json" version of the data<dumping_transformations>`.
+These serialised "json" files are the currency of executing a campaign of simulations,
+and contain all the information required to execute a single simulation.
+
+To read this information and execute the simulation, the command line interface provides a ``quickrun`` command,
+the full details of which are given in :ref:`the CLI reference section<cli_quickrun>`.
+Briefly, this command takes a "json" simulation as an input and will then execute the simulation contained within,
+therefore this command would execute a simulation saved to a file called "transformation.json".
+
+::
+
+  openfe quickrun transformation.json -o results.json
+
+
+Which will produce a results file called ``results.json``.
+
+Executing within a job submission script
+----------------------------------------
+
+It is likely that computational jobs will be submitted to a queueing engine, such as slurm.
+The ``quickrun`` command can be integrated into as:
+
+::
+
+  #!/bin/bash
+
+  #SBATCH --job-name="openfe job"
+  #SBATCH --mem-per-cpu=2G
+
+  # activate an appropriate conda environment, or any "module load" commands required to
+  conda activate openfe_env
+
+  openfe quickrun transformation.json -o results.json
+
+
+See Also
+--------
+
+For details on inspecting these results, refer to :ref:`userguide_results`.

docs/reference/api/defining_and_executing_simulations.rst

@@ -1,3 +1,5 @@
+.. _reference_execution:
+
 Defining and Executing Simulations
 ==================================