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 882900a18..a20d37fcc 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -1,168 +1,77 @@ .. _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. - -.. note:: This section is a work-in-progress. +.. TODO: remove the quickrun sentence above once moved to "Running calculations" .. module:: openfe :noindex: -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 - - +.. toctree:: + :maxdepth: 1 + :caption: Setting up chemical systems - - .. rst-class:: width-3 + loading_molecules + user_charges + bespoke_parameters + packmol_memgen_setup - - - .. rst-class:: arrow-down arrow-tail arrow-combine-left - - +.. TODO: merge cofactors_rbfe into loading_molecules, + "Create a ChemicalSystem", "Specify custom force fields", OpenFold3 notebooks. - .. rst-class:: arrow-down arrow-head flowchart-spacer - - :any:`network_from_orion_fepp` +.. toctree:: + :maxdepth: 1 + :caption: Planning: Ligand networks - - :class:`LigandNetwork ` - A network of ligand transformations. + generate_ligand_network + hand_write_ligand_network + network_from_orion_fepp + ligandnetwork_vis - - .. container:: flowchart-sidebyside +.. TODO: add howto on scorers - - - - .. rst-class:: arrow-down arrow-tail arrow-combine-left width-4 - - +.. toctree:: + :maxdepth: 1 + :caption: Planning: Protocols and alchemical networks - - - - .. rst-class:: arrow-cycle width-4 - - + choose_protocol + rfe_alchemical_planners + create_alchemical_network - - :any:`ligandnetwork_vis` +.. 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 - .. rst-class:: arrow-down arrow-head - - :any:`create_alchemical_network` + dumping_transformation - - :class:`AlchemicalNetwork` - A complete simulation campaign. +.. 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. - .. rst-class:: arrow-down - * :any:`dumping_transformations` +.. toctree:: + :maxdepth: 1 + :caption: Working with results - * Run - - :any:`openfe quickrun ` - OpenFE recommends using the ``openfe quickrun`` CLI command to execute a transformation. + jq_inspection - .. rst-class:: arrow-down - * +.. 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. - * Gather - - :any:`openfe gather ` - OpenFE recommends using the ``openfe gather`` CLI command to collect the results of a transformation. +.. toctree:: + :maxdepth: 1 + :caption: Repairing and extending networks -List of Cookbooks ------------------ + repairing_broken_networks -.. 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/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. 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" +} 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..61afed989 100644 --- a/docs/guide/execution/index.rst +++ b/docs/guide/execution/index.rst @@ -13,3 +13,10 @@ then :ref:`reading on the available Python functions`. quickrun_execution task_based_execution execution_theory + +.. 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 d74486560..68c45c636 100644 --- a/docs/guide/introduction.rst +++ b/docs/guide/introduction.rst @@ -24,11 +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: -.. TODO make figure -.. .. figure:: ??? - :alt: Setup -> (AlchemicalNetwork) -> Execution -> (ProtocolResults) -> Gather +.. container:: deflist-flowchart + + * Simulation setup + - .. container:: flowchart-sidebyside + + - - + .. rst-class:: flowchart-spacer + - + + - :class:`Protocol` + Simulation procedure for an alchemic mutation. + + .. rst-class:: arrow-down arrow-tail arrow-combine-right + - + + - - Chemical component definition + SDF, PDB, RDKit, OpenFF Molecule, solvent spec, etc. + + .. rst-class:: arrow-down arrow-tail + - :any:`Loading Molecules` + + - .. container:: flowchart-sidebyside + + - - + .. rst-class:: arrow-down arrow-head arrow-combine-right + - + + - :class:`SmallMoleculeComponent` + The ligands that will be mutated. + + .. rst-class:: arrow-down + - :any:`Creating Atom Mappings` + + - :class:`LigandAtomMapping` + Corresponds atoms in one small molecule to those in another. + + .. rst-class:: arrow-down arrow-tail arrow-combine + - + + - - + .. rst-class:: arrow-down arrow-head arrow-combine-left + - + + - :class:`SmallMoleculeComponent`, :class:`SolventComponent` and :class:`ProteinComponent` + The components that make up the chemical system. + + .. rst-class:: arrow-down arrow-multiple-combine + - :any:`Assembling into ChemicalSystems` + + - :class:`ChemicalSystem` + Each of the chemical systems, composed of components, that the :class:`Transformation` mutates between. + + .. rst-class:: arrow-down arrow-tail arrow-combine-left arrow-multiple + - + + .. rst-class:: arrow-down arrow-head + - + + - :class:`Transformation` + A single alchemic mutation from one chemical system to another. + + .. rst-class:: arrow-down + * + + * Execution + - :class:`Transformation` + A single alchemic mutation from one chemical system to another. + + .. rst-class:: arrow-down + - + + - :class:`ProtocolDAG` + A directed acyclic graph describing how to compute a :class:`Transformation`. + + - .. container:: flowchart-sidebyside + + - + - + .. rst-class:: arrow-down arrow-multiple + - + + - :class:`ProtocolUnit` + A single unit of computation within a :class:`ProtocolDAG` + + .. rst-class:: arrow-down + - + + - :class:`ProtocolUnitResult` + The result of a completed :class:`ProtocolUnit` + + .. rst-class:: arrow-down arrow-multiple-combine + - + + - + - + .. rst-class:: arrow-down + - :any:`executors` + + - :class:`ProtocolDAGResult` + A completed transformation. + + .. rst-class:: arrow-down + * + + * Gather results + - .. 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 + - - The main stages of a free energy calculation in OpenFE, and the intermediates between them. + - :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 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/results/index.rst b/docs/guide/results/index.rst index 931027218..10a30fb7c 100644 --- a/docs/guide/results/index.rst +++ b/docs/guide/results/index.rst @@ -10,3 +10,14 @@ 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` + +.. admonition:: How-to guides + + * :doc:`/cookbook/jq_inspection` + +.. TODO: add the gather, load results, cinnabar and openfe_analysis how-tos. 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 ` diff --git a/docs/guide/setup/index.rst b/docs/guide/setup/index.rst index 7866e6314..7741cc186 100644 --- a/docs/guide/setup/index.rst +++ b/docs/guide/setup/index.rst @@ -42,3 +42,27 @@ More detailed guidance is available 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` + + **Planning: 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` + + **Planning: 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. 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.