From d7941fab701390d187e5d5c652026c9bfcc27bf4 Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Thu, 29 Oct 2026 16:43:48 +0100 Subject: [PATCH 01/17] Re-structure the cookbooks --- docs/cookbook/index.rst | 88 ++++++++++++++++++++++++---------- docs/guide/cli/index.rst | 2 + docs/guide/execution/index.rst | 2 + docs/guide/results/index.rst | 7 +++ docs/guide/setup/index.rst | 24 ++++++++++ 5 files changed, 97 insertions(+), 26 deletions(-) diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index 882900a18..340a52901 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -1,17 +1,75 @@ .. _cookbooks: -Cookbook -======== +How-to guides +============= -This section describes common tasks involving the OpenFE Python API. +These guides show how to carry out specific tasks with **openfe**, mostly using the Python API. +For the concepts behind each step, see the :doc:`User Guide `. +To run a transformation with ``openfe quickrun``, see :ref:`userguide_quickrun`. -The :any:`OpenFE CLI` provides a simple way to perform the most common procedures for free energy calculations, but does not provide much flexibility for fine-tuning your approach or combining OpenFE with other tools. The :any:`Python API` allows that flexibility, but using it is more complex. This cookbook breaks down common steps that would be implemented in Python to help navigate that complexity. +.. TODO: remove the quickrun sentence above once the "Running calculations" group exists. +.. TODO: remove the work-in-progress note and rename the "Cookbooks" labels in the + protocol pages once all content is moved. .. note:: This section is a work-in-progress. .. module:: openfe :noindex: +.. toctree:: + :maxdepth: 1 + :caption: Setup + + loading_molecules + user_charges + bespoke_parameters + +.. TODO: add "Load protein, ligands and cofactors" (merge cofactors_rbfe into loading_molecules), + "Create a ChemicalSystem", "Specify custom force fields", membrane packmol-memgen and OpenFold3 notebooks. + +.. toctree:: + :maxdepth: 1 + :caption: Ligand networks + + generate_ligand_network + hand_write_ligand_network + network_from_orion_fepp + ligandnetwork_vis + repairing_broken_networks + +.. TODO: add howto on scorers + +.. toctree:: + :maxdepth: 1 + :caption: Protocols and alchemical networks + + choose_protocol + rfe_alchemical_planners + create_alchemical_network + +.. TODO: add "Customize CLI planning with YAML" (from guide/cli/cli_yaml) and move the + how-to parts of guide/setup/defining_protocols into choose_protocol. + +.. toctree:: + :maxdepth: 1 + :caption: Running calculations + +.. TODO: add: run a transformation with quickrun, + run repeats in parallel, run on a SLURM cluster, resume interrupted calculations and + share a GPU using NVIDIA MPS (from guide/execution/quickrun_execution), and task-based + execution. + +.. toctree:: + :maxdepth: 1 + :caption: Working with results + + dumping_transformation + jq_inspection + +.. TODO: add "Gather free energy results" and "Load results in Python" (from + guide/results/working_with_results), "Analyze an RBFE network with cinnabar" (from + guide/results/working_with_networks) and "Visualize trajectories with openfe_analysis". + The Basic Workflow ------------------ @@ -144,25 +202,3 @@ The typical way to use the Python API is to load a number of molecules you want * Gather - :any:`openfe gather ` OpenFE recommends using the ``openfe gather`` CLI command to collect the results of a transformation. - -List of Cookbooks ------------------ - -.. toctree:: - :maxdepth: 1 - - loading_molecules - dumping_transformation - jq_inspection - choose_protocol - generate_ligand_network - rfe_alchemical_planners - network_from_orion_fepp - hand_write_ligand_network - ligandnetwork_vis - create_alchemical_network - user_charges - bespoke_parameters - repairing_broken_networks - - diff --git a/docs/guide/cli/index.rst b/docs/guide/cli/index.rst index 481492eb4..5d5c3024e 100644 --- a/docs/guide/cli/index.rst +++ b/docs/guide/cli/index.rst @@ -13,3 +13,5 @@ into non-Python workflows. .. toctree:: cli_basics cli_yaml + +.. TODO: add a "How-to guides" box listing the CLI YAML how-to. diff --git a/docs/guide/execution/index.rst b/docs/guide/execution/index.rst index 2cda1264a..0f38d28fa 100644 --- a/docs/guide/execution/index.rst +++ b/docs/guide/execution/index.rst @@ -13,3 +13,5 @@ then :ref:`reading on the available Python functions`. quickrun_execution task_based_execution execution_theory + +.. TODO: add a "How-to guides" box listing the Running calculations how-tos. diff --git a/docs/guide/results/index.rst b/docs/guide/results/index.rst index 931027218..28b843263 100644 --- a/docs/guide/results/index.rst +++ b/docs/guide/results/index.rst @@ -10,3 +10,10 @@ and entire networks of results analysed. .. toctree:: working_with_results working_with_networks + +.. admonition:: How-to guides + + * :doc:`/cookbook/dumping_transformation` + * :doc:`/cookbook/jq_inspection` + +.. TODO: add the gather, load results, cinnabar and openfe_analysis how-tos diff --git a/docs/guide/setup/index.rst b/docs/guide/setup/index.rst index 636bb800a..895e2346d 100644 --- a/docs/guide/setup/index.rst +++ b/docs/guide/setup/index.rst @@ -40,3 +40,27 @@ instructions can be found in the following sections: To set up your alchemical network using the Python interface, but run it using the CLI, you will need to export the network in the same format used by the CLI. See :ref:`dumping transformations ` for more details. + +.. admonition:: How-to guides + + **Setup** + + * :doc:`/cookbook/loading_molecules` + * :doc:`/cookbook/user_charges` + * :doc:`/cookbook/bespoke_parameters` + + **Ligand networks** + + * :doc:`/cookbook/generate_ligand_network` + * :doc:`/cookbook/hand_write_ligand_network` + * :doc:`/cookbook/network_from_orion_fepp` + * :doc:`/cookbook/ligandnetwork_vis` + * :doc:`/cookbook/repairing_broken_networks` + + **Protocols and alchemical networks** + + * :doc:`/cookbook/choose_protocol` + * :doc:`/cookbook/rfe_alchemical_planners` + * :doc:`/cookbook/create_alchemical_network` + +.. TODO: add the new Setup and Planning how-tos to this box as they are added. From 151eff10fefc78d54f109bf2c4055ff8930f6e5b Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Thu, 29 Oct 2026 17:01:00 +0100 Subject: [PATCH 02/17] Remove workflow chart from how to and move it to user guide instead --- docs/cookbook/index.rst | 135 +----------------------------------- docs/guide/introduction.rst | 130 +++++++++++++++++++++++++++++++++- 2 files changed, 128 insertions(+), 137 deletions(-) diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index 340a52901..6d8e3366c 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -7,7 +7,7 @@ These guides show how to carry out specific tasks with **openfe**, mostly using For the concepts behind each step, see the :doc:`User Guide `. To run a transformation with ``openfe quickrun``, see :ref:`userguide_quickrun`. -.. TODO: remove the quickrun sentence above once the "Running calculations" group exists. +.. TODO: remove the quickrun sentence above once moved to "Running calculations" .. TODO: remove the work-in-progress note and rename the "Cookbooks" labels in the protocol pages once all content is moved. @@ -69,136 +69,3 @@ To run a transformation with ``openfe quickrun``, see :ref:`userguide_quickrun`. .. TODO: add "Gather free energy results" and "Load results in Python" (from guide/results/working_with_results), "Analyze an RBFE network with cinnabar" (from guide/results/working_with_networks) and "Visualize trajectories with openfe_analysis". - -The Basic Workflow ------------------- - -The typical way to use the Python API is to load a number of molecules you want to calculate free energies of, construct a :class:`LigandNetwork` connecting them in an efficient way, and then combine that with information for how each ligand should be simulated to construct an :class:`AlchemicalNetwork`, which specifies the entire simulation campaign. This provides a lot of flexibility in how molecules are specified, mapped, connected, and simulated, without exposing a great deal of complexity. OpenFE recommends this workflow for most users. - -.. container:: deflist-flowchart - - * Setup - - .. container:: flowchart-sidebyside - - - - - .. rst-class:: flowchart-spacer - - - - .. rst-class:: arrow-down arrow-from-nothing - - :any:`choose_protocol` - - - :class:`Protocol` - Simulation procedure for an alchemic mutation. - - .. rst-class:: arrow-down arrow-tail arrow-combine-right - - - - - - - .. rst-class:: width-8 - - Chemical component definition - SDF, PDB, RDKit, OpenFF Molecule, solvent spec, etc. - - - .. container:: flowchart-sidebyside - - - .. rst-class:: width-3 - - - - - .. rst-class:: arrow-down arrow-multiple - - :any:`Loading proteins`, :any:`Defining solvents` - - - :class:`SolventComponent` and :class:`ProteinComponent` - Other chemical components needed to simulate the ligand. - - .. rst-class:: arrow-down arrow-multiple arrow-tail arrow-combine - - - - - - .. container:: flowchart-sidebyside - - - .. rst-class:: width-5 - - - - .. rst-class:: arrow-down arrow-multiple - - :any:`Loading small molecules` - - - - :class:`SmallMoleculeComponent` - The ligands that will be mutated. - - - .. rst-class:: width-3 - - - - .. rst-class:: flowchart-spacer - - - - - Orion/FEP+ - Network from another tool. - - - - .. container:: flowchart-sidebyside - - - .. rst-class:: width-2 - - - - .. rst-class:: arrow-down arrow-multiple - - :any:`generate_ligand_network` - - - .. rst-class:: width-2 - - - - .. rst-class:: arrow-down arrow-multiple - - :any:`hand_write_ligand_network` - - - .. rst-class:: width-1 - - - - .. rst-class:: arrow-down arrow-tail arrow-multiple arrow-combine-right - - - - .. rst-class:: flowchart-spacer - - - - - .. rst-class:: width-3 - - - - .. rst-class:: arrow-down arrow-tail arrow-combine-left - - - - .. rst-class:: arrow-down arrow-head flowchart-spacer - - :any:`network_from_orion_fepp` - - - :class:`LigandNetwork ` - A network of ligand transformations. - - - .. container:: flowchart-sidebyside - - - - - .. rst-class:: arrow-down arrow-tail arrow-combine-left width-4 - - - - - - - .. rst-class:: arrow-cycle width-4 - - - - - :any:`ligandnetwork_vis` - - - .. rst-class:: arrow-down arrow-head - - :any:`create_alchemical_network` - - - :class:`AlchemicalNetwork` - A complete simulation campaign. - - .. rst-class:: arrow-down - * :any:`dumping_transformations` - - * Run - - :any:`openfe quickrun ` - OpenFE recommends using the ``openfe quickrun`` CLI command to execute a transformation. - - .. rst-class:: arrow-down - * - - * Gather - - :any:`openfe gather ` - OpenFE recommends using the ``openfe gather`` CLI command to collect the results of a transformation. diff --git a/docs/guide/introduction.rst b/docs/guide/introduction.rst index d74486560..265836097 100644 --- a/docs/guide/introduction.rst +++ b/docs/guide/introduction.rst @@ -24,9 +24,133 @@ 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 defined output which is then the input for the next stage: -.. TODO make figure -.. .. figure:: ??? - :alt: Setup -> (AlchemicalNetwork) -> Execution -> (ProtocolResults) -> Gather +.. container:: deflist-flowchart + + * Setup + - .. container:: flowchart-sidebyside + + - - + .. rst-class:: flowchart-spacer + - + + .. rst-class:: arrow-down arrow-from-nothing + - :any:`choose_protocol` + + - :class:`Protocol` + Simulation procedure for an alchemic mutation. + + .. rst-class:: arrow-down arrow-tail arrow-combine-right + - + + - - + .. rst-class:: width-8 + - Chemical component definition + SDF, PDB, RDKit, OpenFF Molecule, solvent spec, etc. + + - .. container:: flowchart-sidebyside + + - .. rst-class:: width-3 + + - + + .. rst-class:: arrow-down arrow-multiple + - :any:`Loading proteins`, :any:`Defining solvents` + + - :class:`SolventComponent` and :class:`ProteinComponent` + Other chemical components needed to simulate the ligand. + + .. rst-class:: arrow-down arrow-multiple arrow-tail arrow-combine + - + + - - .. container:: flowchart-sidebyside + + - .. rst-class:: width-5 + + - + .. rst-class:: arrow-down arrow-multiple + - :any:`Loading small molecules` + + + - :class:`SmallMoleculeComponent` + The ligands that will be mutated. + + - .. rst-class:: width-3 + + - + .. rst-class:: flowchart-spacer + - + + - Orion/FEP+ + Network from another tool. + + + - .. container:: flowchart-sidebyside + + - .. rst-class:: width-2 + + - + .. rst-class:: arrow-down arrow-multiple + - :any:`generate_ligand_network` + + - .. rst-class:: width-2 + + - + .. rst-class:: arrow-down arrow-multiple + - :any:`hand_write_ligand_network` + + - .. rst-class:: width-1 + + - + .. rst-class:: arrow-down arrow-tail arrow-multiple arrow-combine-right + - + + .. rst-class:: flowchart-spacer + - + + - .. rst-class:: width-3 + + - + .. rst-class:: arrow-down arrow-tail arrow-combine-left + - + + .. rst-class:: arrow-down arrow-head flowchart-spacer + - :any:`network_from_orion_fepp` + + - :class:`LigandNetwork ` + A network of ligand transformations. + + - .. container:: flowchart-sidebyside + + - - + .. rst-class:: arrow-down arrow-tail arrow-combine-left width-4 + - + + - - + .. rst-class:: arrow-cycle width-4 + - + + - :any:`ligandnetwork_vis` + + + .. rst-class:: arrow-down arrow-head + - :any:`create_alchemical_network` + + - :class:`AlchemicalNetwork` + A complete simulation campaign. + + .. rst-class:: arrow-down + * :any:`dumping_transformations` + + * Run + - :any:`openfe quickrun ` + OpenFE recommends using the ``openfe quickrun`` CLI command to execute a transformation. + + .. rst-class:: arrow-down + * + + * Gather + - :any:`openfe gather ` + OpenFE recommends using the ``openfe gather`` CLI command to collect the results of a transformation. The main stages of a free energy calculation in OpenFE, and the intermediates between them. From 23d38a103278d7f9abe3b817f2ea75a6fa467cb2 Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Thu, 29 Oct 2026 17:08:26 +0100 Subject: [PATCH 03/17] Small change --- docs/cookbook/index.rst | 4 ++-- docs/guide/setup/index.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index 6d8e3366c..9b8226fe7 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -29,7 +29,7 @@ To run a transformation with ``openfe quickrun``, see :ref:`userguide_quickrun`. .. toctree:: :maxdepth: 1 - :caption: Ligand networks + :caption: Planning: Ligand networks generate_ligand_network hand_write_ligand_network @@ -41,7 +41,7 @@ To run a transformation with ``openfe quickrun``, see :ref:`userguide_quickrun`. .. toctree:: :maxdepth: 1 - :caption: Protocols and alchemical networks + :caption: Planning: Protocols and alchemical networks choose_protocol rfe_alchemical_planners diff --git a/docs/guide/setup/index.rst b/docs/guide/setup/index.rst index 895e2346d..b2239a92e 100644 --- a/docs/guide/setup/index.rst +++ b/docs/guide/setup/index.rst @@ -49,7 +49,7 @@ See :ref:`dumping transformations ` for more details. * :doc:`/cookbook/user_charges` * :doc:`/cookbook/bespoke_parameters` - **Ligand networks** + **Planning: Ligand networks** * :doc:`/cookbook/generate_ligand_network` * :doc:`/cookbook/hand_write_ligand_network` @@ -57,7 +57,7 @@ See :ref:`dumping transformations ` for more details. * :doc:`/cookbook/ligandnetwork_vis` * :doc:`/cookbook/repairing_broken_networks` - **Protocols and alchemical networks** + **Planning: Protocols and alchemical networks** * :doc:`/cookbook/choose_protocol` * :doc:`/cookbook/rfe_alchemical_planners` From 8bf26b22a6b43251d5b513a42edc399db3732f8b Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Fri, 30 Oct 2026 09:37:31 +0100 Subject: [PATCH 04/17] move one cookbook --- docs/cookbook/index.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index 9b8226fe7..d6dc652ba 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -54,6 +54,8 @@ To run a transformation with ``openfe quickrun``, see :ref:`userguide_quickrun`. :maxdepth: 1 :caption: Running calculations + dumping_transformation + .. TODO: add: run a transformation with quickrun, run repeats in parallel, run on a SLURM cluster, resume interrupted calculations and share a GPU using NVIDIA MPS (from guide/execution/quickrun_execution), and task-based @@ -63,7 +65,6 @@ To run a transformation with ``openfe quickrun``, see :ref:`userguide_quickrun`. :maxdepth: 1 :caption: Working with results - dumping_transformation jq_inspection .. TODO: add "Gather free energy results" and "Load results in Python" (from From e9df9e04749342978d270bc3b962c7a08bcff01c Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Fri, 30 Oct 2026 16:22:16 +0100 Subject: [PATCH 05/17] Try out something --- docs/guide/introduction.rst | 149 ++++++++++++------------------------ 1 file changed, 51 insertions(+), 98 deletions(-) diff --git a/docs/guide/introduction.rst b/docs/guide/introduction.rst index 265836097..3d14b7348 100644 --- a/docs/guide/introduction.rst +++ b/docs/guide/introduction.rst @@ -24,135 +24,88 @@ 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 defined output which is then the input for the next stage: -.. container:: deflist-flowchart +.. rubric:: Setup - * Setup - - .. container:: flowchart-sidebyside +.. grid:: 1 1 2 2 + :gutter: 2 - - - - .. rst-class:: flowchart-spacer - - + .. grid-item-card:: Choose a protocol + :shadow: none - .. rst-class:: arrow-down arrow-from-nothing - - :any:`choose_protocol` + :any:`choose_protocol` - - :class:`Protocol` - Simulation procedure for an alchemic mutation. + A :class:`Protocol` specifies how each alchemical + transformation will be simulated. - .. rst-class:: arrow-down arrow-tail arrow-combine-right - - + .. grid-item-card:: Load molecular components + :shadow: none - - - - .. rst-class:: width-8 - - Chemical component definition - SDF, PDB, RDKit, OpenFF Molecule, solvent spec, etc. + :any:`Loading small molecules`, :any:`Loading proteins`, + and :any:`Defining solvents`. - - .. container:: flowchart-sidebyside + Build :class:`SmallMoleculeComponent` objects for ligands, + together with :class:`ProteinComponent` and + :class:`SolventComponent` objects as needed. - - .. rst-class:: width-3 +.. rst-class:: sd-text-center - - +:octicon:`arrow-down;1.5em` - .. rst-class:: arrow-down arrow-multiple - - :any:`Loading proteins`, :any:`Defining solvents` +.. card:: Plan the ligand network + :shadow: none - - :class:`SolventComponent` and :class:`ProteinComponent` - Other chemical components needed to simulate the ligand. + :any:`generate_ligand_network`, + :any:`hand_write_ligand_network`, or + :any:`network_from_orion_fepp` to create a + :class:`LigandNetwork `. - .. rst-class:: arrow-down arrow-multiple arrow-tail arrow-combine - - + Optionally, :any:`ligandnetwork_vis`. - - - .. container:: flowchart-sidebyside +.. rst-class:: sd-text-center - - .. rst-class:: width-5 +:octicon:`arrow-down;1.5em` - - - .. rst-class:: arrow-down arrow-multiple - - :any:`Loading small molecules` +.. card:: Create an alchemical network + :shadow: none + :any:`create_alchemical_network` using the protocol, + chemical components, and ligand network. - - :class:`SmallMoleculeComponent` - The ligands that will be mutated. + The resulting :class:`AlchemicalNetwork` defines the + complete simulation campaign. - - .. rst-class:: width-3 +.. rst-class:: sd-text-center - - - .. rst-class:: flowchart-spacer - - +:octicon:`arrow-down;1.5em` - - Orion/FEP+ - Network from another tool. +.. card:: Export transformations + :shadow: none + :any:`dumping_transformations` to JSON files for execution. - - .. container:: flowchart-sidebyside +.. rst-class:: sd-text-center - - .. rst-class:: width-2 +:octicon:`arrow-down;1.5em` - - - .. rst-class:: arrow-down arrow-multiple - - :any:`generate_ligand_network` +.. rubric:: Run - - .. rst-class:: width-2 +.. card:: Execute transformations + :shadow: none - - - .. rst-class:: arrow-down arrow-multiple - - :any:`hand_write_ligand_network` + Use :any:`openfe quickrun ` to run each + transformation. - - .. rst-class:: width-1 +.. rst-class:: sd-text-center - - - .. rst-class:: arrow-down arrow-tail arrow-multiple arrow-combine-right - - +:octicon:`arrow-down;1.5em` - .. rst-class:: flowchart-spacer - - +.. rubric:: Gather - - .. rst-class:: width-3 +.. card:: Gather results + :shadow: none - - - .. rst-class:: arrow-down arrow-tail arrow-combine-left - - - - .. rst-class:: arrow-down arrow-head flowchart-spacer - - :any:`network_from_orion_fepp` - - - :class:`LigandNetwork ` - A network of ligand transformations. - - - .. container:: flowchart-sidebyside - - - - - .. rst-class:: arrow-down arrow-tail arrow-combine-left width-4 - - - - - - - .. rst-class:: arrow-cycle width-4 - - - - - :any:`ligandnetwork_vis` - - - .. rst-class:: arrow-down arrow-head - - :any:`create_alchemical_network` - - - :class:`AlchemicalNetwork` - A complete simulation campaign. - - .. rst-class:: arrow-down - * :any:`dumping_transformations` - - * Run - - :any:`openfe quickrun ` - OpenFE recommends using the ``openfe quickrun`` CLI command to execute a transformation. - - .. rst-class:: arrow-down - * - - * Gather - - :any:`openfe gather ` - OpenFE recommends using the ``openfe gather`` CLI command to collect the results of a transformation. - - The main stages of a free energy calculation in OpenFE, and the intermediates between them. + Use :any:`openfe gather ` to collect the + results of the transformations. The output of the :ref:`simulation 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 From b84e3f1ffd74354b5f07a122d2667303f558bafb Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Fri, 30 Oct 2026 16:26:27 +0100 Subject: [PATCH 06/17] revert back --- docs/guide/introduction.rst | 154 ++++++++++++++++++++++++------------ 1 file changed, 103 insertions(+), 51 deletions(-) diff --git a/docs/guide/introduction.rst b/docs/guide/introduction.rst index 3d14b7348..4de088d1f 100644 --- a/docs/guide/introduction.rst +++ b/docs/guide/introduction.rst @@ -24,88 +24,140 @@ 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 defined output which is then the input for the next stage: -.. rubric:: Setup +.. container:: deflist-flowchart -.. grid:: 1 1 2 2 - :gutter: 2 + * Setup + - .. container:: flowchart-sidebyside - .. grid-item-card:: Choose a protocol - :shadow: none + - - + .. rst-class:: flowchart-spacer + - - :any:`choose_protocol` + - :class:`Protocol` + Simulation procedure for an alchemic mutation. - A :class:`Protocol` specifies how each alchemical - transformation will be simulated. + .. rst-class:: arrow-down arrow-tail arrow-combine-right + - - .. grid-item-card:: Load molecular components - :shadow: none + - - Chemical component definition + SDF, PDB, RDKit, OpenFF Molecule, solvent spec, etc. - :any:`Loading small molecules`, :any:`Loading proteins`, - and :any:`Defining solvents`. + .. rst-class:: arrow-down arrow-tail + - :any:`Loading Molecules` - Build :class:`SmallMoleculeComponent` objects for ligands, - together with :class:`ProteinComponent` and - :class:`SolventComponent` objects as needed. + - .. container:: flowchart-sidebyside -.. rst-class:: sd-text-center + - - + .. rst-class:: arrow-down arrow-head arrow-combine-right + - -:octicon:`arrow-down;1.5em` + - :class:`SmallMoleculeComponent` + The ligands that will be mutated. -.. card:: Plan the ligand network - :shadow: none + .. rst-class:: arrow-down + - :any:`Creating Atom Mappings` - :any:`generate_ligand_network`, - :any:`hand_write_ligand_network`, or - :any:`network_from_orion_fepp` to create a - :class:`LigandNetwork `. + - :class:`LigandAtomMapping` + Corresponds atoms in one small molecule to those in another. - Optionally, :any:`ligandnetwork_vis`. + .. rst-class:: arrow-down arrow-tail arrow-combine + - -.. rst-class:: sd-text-center + - - + .. rst-class:: arrow-down arrow-head arrow-combine-left + - -:octicon:`arrow-down;1.5em` + - :class:`SmallMoleculeComponent`, :class:`SolventComponent` and :class:`ProteinComponent` + The components that make up the chemical system. -.. card:: Create an alchemical network - :shadow: none + .. rst-class:: arrow-down arrow-multiple-combine + - :any:`Assembling into ChemicalSystems` - :any:`create_alchemical_network` using the protocol, - chemical components, and ligand network. + - :class:`ChemicalSystem` + Each of the chemical systems, composed of components, that the :class:`Transformation` mutates between. - The resulting :class:`AlchemicalNetwork` defines the - complete simulation campaign. + .. rst-class:: arrow-down arrow-tail arrow-combine-left arrow-multiple + - -.. rst-class:: sd-text-center + .. rst-class:: arrow-down arrow-head + - -:octicon:`arrow-down;1.5em` + - :class:`Transformation` + A single alchemic mutation from one chemical system to another. -.. card:: Export transformations - :shadow: none + .. rst-class:: arrow-down + * - :any:`dumping_transformations` to JSON files for execution. + * Run + - :class:`Transformation` + A single alchemic mutation from one chemical system to another. -.. rst-class:: sd-text-center + .. rst-class:: arrow-down + - -:octicon:`arrow-down;1.5em` + - :class:`ProtocolDAG` + A directed acyclic graph describing how to compute a :class:`Transformation`. -.. rubric:: Run + - .. container:: flowchart-sidebyside -.. card:: Execute transformations - :shadow: none + - + - + .. rst-class:: arrow-down arrow-multiple + - - Use :any:`openfe quickrun ` to run each - transformation. + - :class:`ProtocolUnit` + A single unit of computation within a :class:`ProtocolDAG` -.. rst-class:: sd-text-center + .. rst-class:: arrow-down + - -:octicon:`arrow-down;1.5em` + - :class:`ProtocolUnitResult` + The result of a completed :class:`ProtocolUnit` -.. rubric:: Gather + .. rst-class:: arrow-down arrow-multiple-combine + - -.. card:: Gather results - :shadow: none + - + - + .. rst-class:: arrow-down + - :any:`executors` - Use :any:`openfe gather ` to collect the - results of the transformations. + - :class:`ProtocolDAGResult` + A completed transformation. + + .. rst-class:: arrow-down + * + + * Gather + - .. container:: flowchart-sidebyside + + - + + - :class:`Transformation` + The specification for the alchemic mutation. + + .. rst-class:: arrow-down + - + + - :class:`Protocol` + A completed single run of a transformation. + + .. rst-class:: arrow-down arrow-combine-right arrow-tail + - + + - + + - :class:`ProtocolResult` + A completed single run of a transformation. + + .. rst-class:: arrow-down arrow-combine-left arrow-multiple arrow-tail + - + + .. rst-class:: arrow-down arrow-head + - + + - :class:`ProtocolDAGResult` + A completed transformation with multiple user-defined replicas. The output of the :ref:`simulation 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 From 11c962498d92c43648ad241e2a853d1d4407c011 Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Fri, 30 Oct 2026 16:31:34 +0100 Subject: [PATCH 07/17] Some fixes --- docs/guide/under_the_hood.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/guide/under_the_hood.rst b/docs/guide/under_the_hood.rst index ddd821adb..0cb928080 100644 --- a/docs/guide/under_the_hood.rst +++ b/docs/guide/under_the_hood.rst @@ -118,21 +118,21 @@ If you want to implement your own atom mapper or free energy procedure, or you w - - :class:`Transformation` - The specification for the alchemic mutation. + The specification for the alchemical mutation. .. rst-class:: arrow-down - - :class:`Protocol` - A completed single run of a transformation. + Its ``gather`` method combines the results of each repeat. .. rst-class:: arrow-down arrow-combine-right arrow-tail - - - - :class:`ProtocolResult` - A completed single run of a transformation. + - :class:`ProtocolDAGResult` + One completed repeat of the transformation. .. rst-class:: arrow-down arrow-combine-left arrow-multiple arrow-tail - @@ -140,6 +140,5 @@ If you want to implement your own atom mapper or free energy procedure, or you w .. rst-class:: arrow-down arrow-head - - - :class:`ProtocolDAGResult` - A completed transformation with multiple user-defined replicas. - + - :class:`ProtocolResult` + The free energy estimate aggregated over all repeats. From 4872a934c9417fb0c944442e022c8653ed7848a1 Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Mon, 2 Nov 2026 10:39:02 +0100 Subject: [PATCH 08/17] Rename refs to cookbooks to how-to guides --- docs/guide/protocols/absolutebinding.rst | 4 ++-- docs/guide/protocols/absolutesolvation.rst | 4 ++-- docs/guide/protocols/relativehybridtopology.rst | 4 ++-- docs/guide/protocols/septop.rst | 4 ++-- docs/guide/setup/alchemical_network_model.rst | 2 +- .../guide/setup/chemical_systems_and_thermodynamic_cycles.rst | 2 +- 6 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/guide/protocols/absolutebinding.rst b/docs/guide/protocols/absolutebinding.rst index 98dee6579..efc91077f 100644 --- a/docs/guide/protocols/absolutebinding.rst +++ b/docs/guide/protocols/absolutebinding.rst @@ -153,9 +153,9 @@ See Also * :any:`Absolute Binding Free Energies tutorial <../../tutorials/abfe_tutorial>` -**Cookbooks** +**How-to guides** -:ref:`Cookbooks ` +:ref:`How-to guides ` **API Documentation** diff --git a/docs/guide/protocols/absolutesolvation.rst b/docs/guide/protocols/absolutesolvation.rst index fb7693562..b87d0fbf8 100644 --- a/docs/guide/protocols/absolutesolvation.rst +++ b/docs/guide/protocols/absolutesolvation.rst @@ -145,9 +145,9 @@ See Also * :any:`Absolute Hydration Free Energies tutorial <../../tutorials/ahfe_tutorial>` -**Cookbooks** +**How-to guides** -:ref:`Cookbooks ` +:ref:`How-to guides ` **API Documentation** diff --git a/docs/guide/protocols/relativehybridtopology.rst b/docs/guide/protocols/relativehybridtopology.rst index 15ad4a0f0..c7de68fe9 100644 --- a/docs/guide/protocols/relativehybridtopology.rst +++ b/docs/guide/protocols/relativehybridtopology.rst @@ -271,9 +271,9 @@ See Also * :any:`Relative Free Energies with the OpenFE CLI ` * :any:`Relative Free Energies with the OpenFE Python API ` -**Cookbooks** +**How-to guides** -:ref:`Cookbooks ` +:ref:`How-to guides ` **API Documentation** diff --git a/docs/guide/protocols/septop.rst b/docs/guide/protocols/septop.rst index 9a544fa13..c23a80b3a 100644 --- a/docs/guide/protocols/septop.rst +++ b/docs/guide/protocols/septop.rst @@ -156,9 +156,9 @@ See Also * :any:`Separated Topologies Free Energies tutorial <../../tutorials/septop_tutorial>` -**Cookbooks** +**How-to guides** -:ref:`Cookbooks ` +:ref:`How-to guides ` **API Documentation** diff --git a/docs/guide/setup/alchemical_network_model.rst b/docs/guide/setup/alchemical_network_model.rst index d1e78451b..615ecbea1 100644 --- a/docs/guide/setup/alchemical_network_model.rst +++ b/docs/guide/setup/alchemical_network_model.rst @@ -82,4 +82,4 @@ For more CLI details, see :ref:`RBFE CLI tutorial ` and the : See Also -------- * :ref:`Alchemical Network API reference ` -* :ref:`Chemical Systems UserGuide entry ` \ No newline at end of file +* :ref:`Chemical Systems User Guide entry ` \ No newline at end of file diff --git a/docs/guide/setup/chemical_systems_and_thermodynamic_cycles.rst b/docs/guide/setup/chemical_systems_and_thermodynamic_cycles.rst index 966bf8b77..7abf9ee1a 100644 --- a/docs/guide/setup/chemical_systems_and_thermodynamic_cycles.rst +++ b/docs/guide/setup/chemical_systems_and_thermodynamic_cycles.rst @@ -243,5 +243,5 @@ is required: See Also -------- -* To see how to construct a :class:`.ChemicalSystem` from your files, see :ref:`the cookbook entry on loading molecules ` +* To see how to construct a :class:`.ChemicalSystem` from your files, see :ref:`the How-to guide on loading molecules ` * For details of which thermodynamic cycles to construct, consult the :ref:`pages for each specific Protocol ` From 6c31121433d5da51015e375be57b52898a6419ad Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Mon, 2 Nov 2026 12:55:28 +0100 Subject: [PATCH 09/17] Add packmol-memgen prep cookbook --- docs/cookbook/packmol_memgen_setup.nblink | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 docs/cookbook/packmol_memgen_setup.nblink diff --git a/docs/cookbook/packmol_memgen_setup.nblink b/docs/cookbook/packmol_memgen_setup.nblink new file mode 100644 index 000000000..91faf983c --- /dev/null +++ b/docs/cookbook/packmol_memgen_setup.nblink @@ -0,0 +1,3 @@ +{ + "path": "../ExampleNotebooks/membranes/packmol_memgen_setup.ipynb" +} From 01112ce6f3d3b7dc6dc9921a8ac567a11e9e8b55 Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Mon, 2 Nov 2026 12:55:55 +0100 Subject: [PATCH 10/17] Add packmol-memgen prep cookbook --- docs/cookbook/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index d6dc652ba..4c5bb323e 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -23,6 +23,7 @@ To run a transformation with ``openfe quickrun``, see :ref:`userguide_quickrun`. loading_molecules user_charges bespoke_parameters + packmol_memgen_setup .. TODO: add "Load protein, ligands and cofactors" (merge cofactors_rbfe into loading_molecules), "Create a ChemicalSystem", "Specify custom force fields", membrane packmol-memgen and OpenFold3 notebooks. From 41f48112ac4fc33a88cb926e30b70d2d7dda9fa7 Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Mon, 2 Nov 2026 13:01:40 +0100 Subject: [PATCH 11/17] Test against ExampleNotebooks change titles --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 9a471e9a2..62e460339 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -195,7 +195,7 @@ else: repo = git.Repo.clone_from( "https://github.com/OpenFreeEnergy/ExampleNotebooks.git", - branch="main", + branch="update-cookbook-titles", to_path=example_notebooks_path, ) except Exception as e: From 063ec0d35d2c37ec7f0f016e3769a2654b9878f8 Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Mon, 2 Nov 2026 13:26:18 +0100 Subject: [PATCH 12/17] reparing in its own section --- docs/cookbook/index.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index 4c5bb323e..bd32e9e56 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -36,7 +36,6 @@ To run a transformation with ``openfe quickrun``, see :ref:`userguide_quickrun`. hand_write_ligand_network network_from_orion_fepp ligandnetwork_vis - repairing_broken_networks .. TODO: add howto on scorers @@ -62,6 +61,12 @@ To run a transformation with ``openfe quickrun``, see :ref:`userguide_quickrun`. share a GPU using NVIDIA MPS (from guide/execution/quickrun_execution), and task-based execution. +.. toctree:: + :maxdepth: 1 + :caption: Repairing and extending networks + + repairing_broken_networks + .. toctree:: :maxdepth: 1 :caption: Working with results From b3eff3d56bc9675614142a21cff73973a41854c2 Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Mon, 2 Nov 2026 13:35:06 +0100 Subject: [PATCH 13/17] Update todo --- docs/cookbook/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index bd32e9e56..1d0a261f2 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -25,8 +25,8 @@ To run a transformation with ``openfe quickrun``, see :ref:`userguide_quickrun`. bespoke_parameters packmol_memgen_setup -.. TODO: add "Load protein, ligands and cofactors" (merge cofactors_rbfe into loading_molecules), - "Create a ChemicalSystem", "Specify custom force fields", membrane packmol-memgen and OpenFold3 notebooks. +.. TODO: merge cofactors_rbfe into loading_molecules, + "Create a ChemicalSystem", "Specify custom force fields", OpenFold3 notebooks. .. toctree:: :maxdepth: 1 From 927df697f94dc58802f8f63d18cdc8dc78a68d1b Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Mon, 2 Nov 2026 15:52:51 +0100 Subject: [PATCH 14/17] Address review comments --- docs/cookbook/index.rst | 2 ++ docs/guide/execution/index.rst | 7 ++++++- docs/guide/introduction.rst | 6 +++--- docs/guide/results/index.rst | 6 +++++- 4 files changed, 16 insertions(+), 5 deletions(-) diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index 1d0a261f2..d8e218a46 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -76,3 +76,5 @@ To run a transformation with ``openfe quickrun``, see :ref:`userguide_quickrun`. .. TODO: add "Gather free energy results" and "Load results in Python" (from guide/results/working_with_results), "Analyze an RBFE network with cinnabar" (from guide/results/working_with_networks) and "Visualize trajectories with openfe_analysis". +.. TODO: merge dumping_transformation and jq_inspection into a single + "Save and inspect OpenFE JSON files" how-to. diff --git a/docs/guide/execution/index.rst b/docs/guide/execution/index.rst index 0f38d28fa..61afed989 100644 --- a/docs/guide/execution/index.rst +++ b/docs/guide/execution/index.rst @@ -14,4 +14,9 @@ then :ref:`reading on the available Python functions`. task_based_execution execution_theory -.. TODO: add a "How-to guides" box listing the Running calculations how-tos. +.. admonition:: How-to guides + + * :doc:`/cookbook/dumping_transformation` + +.. TODO: add the Running calculations how-tos (quickrun, repeats in parallel, SLURM, + resuming, NVIDIA MPS, task-based execution) to this box. diff --git a/docs/guide/introduction.rst b/docs/guide/introduction.rst index 4de088d1f..68c45c636 100644 --- a/docs/guide/introduction.rst +++ b/docs/guide/introduction.rst @@ -26,7 +26,7 @@ is then the input for the next stage: .. container:: deflist-flowchart - * Setup + * Simulation setup - .. container:: flowchart-sidebyside - - @@ -88,7 +88,7 @@ is then the input for the next stage: .. rst-class:: arrow-down * - * Run + * Execution - :class:`Transformation` A single alchemic mutation from one chemical system to another. @@ -128,7 +128,7 @@ is then the input for the next stage: .. rst-class:: arrow-down * - * Gather + * Gather results - .. container:: flowchart-sidebyside - diff --git a/docs/guide/results/index.rst b/docs/guide/results/index.rst index 28b843263..10a30fb7c 100644 --- a/docs/guide/results/index.rst +++ b/docs/guide/results/index.rst @@ -16,4 +16,8 @@ and entire networks of results analysed. * :doc:`/cookbook/dumping_transformation` * :doc:`/cookbook/jq_inspection` -.. TODO: add the gather, load results, cinnabar and openfe_analysis how-tos +.. admonition:: How-to guides + + * :doc:`/cookbook/jq_inspection` + +.. TODO: add the gather, load results, cinnabar and openfe_analysis how-tos. From cab30f7198cdd00544ac0a149803f947cbaabcd0 Mon Sep 17 00:00:00 2001 From: Hannah Baumann <43765638+hannahbaumann@users.noreply.github.com> Date: Tue, 3 Nov 2026 08:51:28 +0100 Subject: [PATCH 15/17] Update docs/cookbook/index.rst Co-authored-by: Alyssa Travitz <31974495+atravitz@users.noreply.github.com> --- docs/cookbook/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index d8e218a46..443137ee8 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -1,6 +1,6 @@ .. _cookbooks: -How-to guides +How-To Guides ============= These guides show how to carry out specific tasks with **openfe**, mostly using the Python API. From 6a0437682c59c6bb7978f5e428923f4c27e2c436 Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Tue, 3 Nov 2026 08:57:40 +0100 Subject: [PATCH 16/17] address review comments --- docs/cookbook/dumping_transformation.rst | 4 ++-- docs/cookbook/index.rst | 19 ++++++++----------- docs/cookbook/jq_inspection.rst | 5 +++-- 3 files changed, 13 insertions(+), 15 deletions(-) diff --git a/docs/cookbook/dumping_transformation.rst b/docs/cookbook/dumping_transformation.rst index 79e5d9703..6214f8a6f 100644 --- a/docs/cookbook/dumping_transformation.rst +++ b/docs/cookbook/dumping_transformation.rst @@ -1,7 +1,7 @@ .. _dumping_transformations: -Dumping a ``Transformation`` to JSON -==================================== +Dump a ``Transformation`` to JSON +================================= If you're trying to run a full campaign of simulations representing an alchemical network, we generally recommend saving objects using our storage diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index 443137ee8..a20d37fcc 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -8,17 +8,13 @@ For the concepts behind each step, see the :doc:`User Guide `. To run a transformation with ``openfe quickrun``, see :ref:`userguide_quickrun`. .. TODO: remove the quickrun sentence above once moved to "Running calculations" -.. TODO: remove the work-in-progress note and rename the "Cookbooks" labels in the - protocol pages once all content is moved. - -.. note:: This section is a work-in-progress. .. module:: openfe :noindex: .. toctree:: :maxdepth: 1 - :caption: Setup + :caption: Setting up chemical systems loading_molecules user_charges @@ -61,12 +57,6 @@ To run a transformation with ``openfe quickrun``, see :ref:`userguide_quickrun`. share a GPU using NVIDIA MPS (from guide/execution/quickrun_execution), and task-based execution. -.. toctree:: - :maxdepth: 1 - :caption: Repairing and extending networks - - repairing_broken_networks - .. toctree:: :maxdepth: 1 :caption: Working with results @@ -78,3 +68,10 @@ To run a transformation with ``openfe quickrun``, see :ref:`userguide_quickrun`. guide/results/working_with_networks) and "Visualize trajectories with openfe_analysis". .. TODO: merge dumping_transformation and jq_inspection into a single "Save and inspect OpenFE JSON files" how-to. + +.. toctree:: + :maxdepth: 1 + :caption: Repairing and extending networks + + repairing_broken_networks + diff --git a/docs/cookbook/jq_inspection.rst b/docs/cookbook/jq_inspection.rst index 3df27299a..f7c320941 100644 --- a/docs/cookbook/jq_inspection.rst +++ b/docs/cookbook/jq_inspection.rst @@ -1,7 +1,8 @@ .. _jq_inspection: -Using ``jq`` to inspect OpenFE JSONs -============================================== +Use ``jq`` to inspect OpenFE JSONs +================================== + Sometimes you may want to get a sense of the contents of JSON files, but the files are too unwieldy to inspect one-by-one in a code editor. `jq `_ is a helpful command-line tool that we recommend for for quickly inspecting JSON files. From 1a0904ea8a858ef2c5044daef4dfadbd60107e12 Mon Sep 17 00:00:00 2001 From: Hannah Baumann <43765638+hannahbaumann@users.noreply.github.com> Date: Wed, 4 Nov 2026 08:29:28 +0100 Subject: [PATCH 17/17] Apply suggestion from @hannahbaumann --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 62e460339..9a471e9a2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -195,7 +195,7 @@ else: repo = git.Repo.clone_from( "https://github.com/OpenFreeEnergy/ExampleNotebooks.git", - branch="update-cookbook-titles", + branch="main", to_path=example_notebooks_path, ) except Exception as e: