Merge branch 'main' into add-api-breaking-detection

.github/workflows/docker-cron.yaml

@@ -90,4 +90,4 @@ jobs:
           docker run --rm ${{ steps.fqirp.outputs.FQIRP }} openfe --version
           docker run --rm ${{ steps.fqirp.outputs.FQIRP }} python -c "import gufe; print(gufe.__version__)"
           docker run --rm ${{ steps.fqirp.outputs.FQIRP }} pytest --pyargs gufe -v
-          docker run --rm ${{ steps.fqirp.outputs.FQIRP }} pytest --pyargs openfe --pyargs openfecli -v
+          docker run --rm ${{ steps.fqirp.outputs.FQIRP }} pytest --pyargs openfe -v

.github/workflows/docker.yaml

@@ -96,7 +96,7 @@ jobs:
           docker run --rm ${{ steps.fqirp.outputs.FQIRP }} openfe --version
           docker run --rm ${{ steps.fqirp.outputs.FQIRP }} python -c "import gufe; print(gufe.__version__)"
           docker run --rm ${{ steps.fqirp.outputs.FQIRP }} pytest --pyargs gufe -v
-          docker run --rm ${{ steps.fqirp.outputs.FQIRP }} pytest --pyargs openfecli --pyargs openfe -v
+          docker run --rm ${{ steps.fqirp.outputs.FQIRP }} pytest --pyargs openfe -v
 
       - name: Push Docker image
         uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc
@@ -123,7 +123,7 @@ jobs:
           cd test_apptainer
           singularity run ../openfe_${{ steps.latest-version.outputs.VERSION }}.sif --help
           singularity run ../openfe_${{ steps.latest-version.outputs.VERSION }}.sif --version
-          singularity run ../openfe_${{ steps.latest-version.outputs.VERSION }}.sif pytest --pyargs openfecli --pyargs openfe -v -n auto
+          singularity run ../openfe_${{ steps.latest-version.outputs.VERSION }}.sif pytest --pyargs openfe -v -n auto
           echo ${{ secrets.GITHUB_TOKEN }} | singularity remote login -u ${{ secrets.GHCR_USERNAME }} --password-stdin oras://ghcr.io
           singularity push ../openfe_${{ steps.latest-version.outputs.VERSION }}.sif oras://${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.latest-version.outputs.VERSION }}-apptainer
           singularity push ../openfe_${{ steps.latest-version.outputs.VERSION }}.sif oras://${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest-apptainer

.github/workflows/installer.yaml

@@ -5,7 +5,7 @@ on:
 
 defaults:
   run:
-    shell: bash -l {0}
+    shell: bash -leo pipefail {0}
 
 jobs:
   test:

.github/workflows/mypy.yaml

@@ -36,6 +36,7 @@ jobs:
           cache-downloads-key: downloads-${{ steps.date.outputs.date }}
           create-args: >-
             python=3.9
+            rdkit=2023.09.5
           init-shell: bash
 
       - name: "Install steps"

devtools/data/fix_rbfe_results.py

@@ -0,0 +1,57 @@
+"""A script to fix up rbfe_results.tar.gz
+
+Useful if Settings are ever changed in a backwards-incompatible way
+
+Will expect "rbfe_results.tar.gz" in this directory, will overwrite this file
+"""
+from gufe.tokenization import JSON_HANDLER
+import glob
+import json
+from openfe.protocols import openmm_rfe
+import os.path
+import tarfile
+
+
+def untar(fn):
+    """extract tarfile called *fn*"""
+    with tarfile.open(fn) as f:
+        f.extractall()
+
+
+def retar(loc, name):
+    """create tar.gz called *name* of directory *loc*"""
+    with tarfile.open(name, mode='w:gz') as f:
+        f.add(loc, arcname=os.path.basename(loc))
+
+
+def replace_settings(fn, new_settings):
+    """replace settings instances in *fn* with *new_settings*"""
+    with open(fn, 'r') as f:
+        data = json.load(f)
+
+    for k in data['protocol_result']['data']:
+        data['protocol_result']['data'][k][0]['inputs']['settings'] = new_settings
+
+    for k in data['unit_results']:
+        data['unit_results'][k]['inputs']['settings'] = new_settings
+
+    with open(fn, 'w') as f:
+        json.dump(data, f, cls=JSON_HANDLER.encoder)
+
+
+def fix_rbfe_results():
+    untar('rbfe_results.tar.gz')
+
+    # generate valid settings as defaults
+    new_settings = openmm_rfe.RelativeHybridTopologyProtocol.default_settings()
+
+    # walk over all result jsons
+    for fn in glob.glob('./results/*json'):
+        # replace instances of settings within with valid settings
+        replace_settings(fn, new_settings)
+
+    retar('results', 'rbfe_results.tar.gz')
+
+
+if __name__ == '__main__':
+    fix_rbfe_results()

docs/conf.py

@@ -186,17 +186,19 @@
         f"Getting ExampleNotebooks failed in {filename} line {lineno}: {e}"
     )
 
+
+# First, create links at top of notebook pages
+# All notebooks are in ExampleNotebooks repo, so link to that
+# Finally, add sphinx reference anchor in prolog so that we can make refs
 nbsphinx_prolog = cleandoc(r"""
-    {%- set path = env.doc2path(env.docname, base="ExampleNotebooks") -%}
-    {%- set gh_repo = "OpenFreeEnergy/openfe" -%}
+    {%- set gh_repo = "OpenFreeEnergy/ExampleNotebooks" -%}
     {%- set gh_branch = "main" -%}
     {%- set path = env.doc2path(env.docname, base=None) -%}
     {%- if path.endswith(".nblink") -%}
         {%- set path = env.metadata[env.docname]["nbsphinx-link-target"] -%}
     {%- endif -%}
-    {%- if path.startswith("docs/ExampleNotebooks") -%}
-        {%- set path = path.replace("docs/ExampleNotebooks/", "", 1) -%}
-        {%- set gh_repo = "OpenFreeEnergy/ExampleNotebooks" -%}
+    {%- if path.startswith("ExampleNotebooks/") -%}
+        {%- set path = path.replace("ExampleNotebooks/", "", 1) -%}
     {%- endif -%}
     {%- set gh_url =
         "https://www.github.com/"
@@ -246,4 +248,5 @@
 
             :octicon:`rocket` Run in Colab
 
+    .. _{{ env.doc2path(env.docname, base=None) }}:
 """)

docs/cookbook/index.rst

@@ -1,3 +1,5 @@
+.. _cookbooks:
+
 Cookbook
 ========
 
@@ -150,10 +152,10 @@ List of Cookbooks
     :maxdepth: 1
 
     loading_molecules
-    creating_atom_mappings
     dumping_transformation
     choose_protocol
     generate_ligand_network
+    rfe_alchemical_planners
     network_from_orion_fepp
     hand_write_ligand_network
     ligandnetwork_vis

docs/cookbook/rfe_alchemical_planners.nblink

@@ -0,0 +1,3 @@
+{
+   "path": "../ExampleNotebooks/cookbook/rfe_alchemical_planners.ipynb"
+}

docs/guide/cli/cli_basics.rst

@@ -12,26 +12,29 @@ subcommands and a brief description of them, use ``openfe (or
 .. code:: none
 
     Usage: openfe [OPTIONS] COMMAND [ARGS]...
-
+    
       This is the command line tool to provide easy access to functionality from
       the OpenFE Python library.
-
+    
     Options:
       --version   Show the version and exit.
       --log PATH  logging configuration file
       -h, --help  Show this message and exit.
-
-    Setup Commands:
-      plan-rhfe-network  Plan a relative hydration free energy network, saved in a
-                         dir with multiple JSON files
-      atommapping        Check the atom mapping of a given pair of ligands
-      plan-rbfe-network  Plan a relative binding free energy network, saved in a
-                         dir with multiple JSON files.
-
-    Simulation Commands:
-      gather    Gather DAG result jsons for network of RFE results into single TSV
-                file
+    
+    Network Planning Commands:
+      view-ligand-network  Visualize a ligand network
+      plan-rbfe-network    Plan a relative binding free energy network, saved as
+                           JSON files for the quickrun command.
+      plan-rhfe-network    Plan a relative hydration free energy network, saved as
+                           JSON files for the quickrun command.
+    
+    Quickrun Executor Commands:
+      gather    Gather result jsons for network of RFE results into a TSV file
       quickrun  Run a given transformation, saved as a JSON file
+    
+    Miscellaneous Commands:
+      fetch  Fetch tutorial or other resource.
+      test   Run the OpenFE test suite
 
 The ``--log`` option takes a logging configuration file and sets that
 logging behavior. If you use it, it must come before the subcommand name.
@@ -42,17 +45,26 @@ the subcommand name, e.g., ``openfe quickrun --help``, which returns
 .. code:: none
 
     Usage: openfe quickrun [OPTIONS] TRANSFORMATION
-
-      Run the transformation (edge) in the given JSON file in serial.
-
-      To save a transformation as JSON, create the transformation and then save it
-      with transformation.dump(filename).
-
+    
+      Run the transformation (edge) in the given JSON file.
+    
+      Simulation JSON files can be created with the :ref:`cli_plan-rbfe-network`
+      or from Python a :class:`.Transformation` can be saved using its dump
+      method::
+    
+          transformation.dump("filename.json")
+    
+      That will save a JSON file suitable to be input for this command.
+    
+      Running this command will execute the simulation defined in the JSON file,
+      creating a directory for each individual task (``Unit``) in the workflow.
+      For example, when running the OpenMM HREX Protocol a directory will be
+      created for each repeat of the sampling process (by default 3).
+    
     Options:
       -d, --work-dir DIRECTORY  directory to store files in (defaults to current
                                 directory)
       -o FILE                   output file (JSON format) for the final results
       -h, --help                Show this message and exit.
 
-
 For more details on various commands, see the :ref:`cli-reference`.

docs/guide/cli/index.rst

@@ -1,3 +1,5 @@
+.. _userguide_cli_interface:
+
 CLI Interface
 =============
 

docs/guide/models/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,14 +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::
+   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/guide/index.rst

@@ -4,8 +4,8 @@ User Guide
 .. toctree::
 
     introduction
-    models/index
     setup/index
     execution/index
     results/index
     cli/index
+    protocols/index