diff --git a/docs/guide/execution/quickrun_execution.rst b/docs/guide/execution/quickrun_execution.rst index 30987a096..f306696d6 100644 --- a/docs/guide/execution/quickrun_execution.rst +++ b/docs/guide/execution/quickrun_execution.rst @@ -44,6 +44,72 @@ The ``quickrun`` command can be integrated into as: openfe quickrun transformation.json -o results.json +Parallel execution of repeats with Quickrun +=========================================== + +Serial execution of multiple repeats of a transformation can be inefficient when simulation times are long. +Higher throughput can be achieved with parallel execution by running one repeat per HPC job. Most protocols are set up to +run three repeats in serial by default, but this can be changed by either: + + 1. Defining the protocol setting ``protocol_repeats`` - see the :ref:`protocol configuration guide ` for more details. + 2. Using the ``openfe plan-rhfe-network`` (or ``plan-rbfe-network``) command line flag ``--n-protocol-repeats``. + +Each transformation can then be executed multiple times via the +``openfe quickrun`` command to produce a set of repeats, however, you need to ensure to use unique results +files for each repeat to ensure they don't overwrite each other. We recommend using folders named ``results_x`` where x is 0-2 +to store the repeated calculations as our :ref:`openfe gather ` command also supports this file structure. + +Here is an example of a simple script that will create and submit a separate job script (``\*.job`` named file) +for every alchemical transformation (for the simplest SLURM use case) in a network running each repeat in parallel and writing the +results to a unique folder: + +.. code-block:: bash + + for file in network_setup/transformations/*.json; do + relpath="${file:30}" # strip off "network_setup/" + dirpath=${relpath%.*} # strip off final ".json" + jobpath="network_setup/transformations/${dirpath}.job" + if [ -f "${jobpath}" ]; then + echo "${jobpath} already exists" + exit 1 + fi + for repeat in {0..2}; do + cmd="openfe quickrun ${file} -o results_${repeat}/${relpath} -d results_${repeat}/${dirpath} --n-protocol-repeats 1" + echo -e "#!/usr/bin/env bash\n${cmd}" > "${jobpath}" + sbatch "${jobpath}" + done + done + +This should result in the following file structure after execution: + +:: + + results_parallel/ + ├── results_0 + │   ├── easy_rbfe_lig_ejm_31_complex_lig_ejm_42_complex + │   │   └── shared_RelativeHybridTopologyProtocolUnit-79c279f04ec84218b7935bc0447539a9_attempt_0 + │   │   ├── checkpoint.nc + │   │   ├── simulation.nc + │   ├── easy_rbfe_lig_ejm_31_complex_lig_ejm_42_complex.json + ├── results_1 + │   ├── easy_rbfe_lig_ejm_31_complex_lig_ejm_42_complex + │   │   └── shared_RelativeHybridTopologyProtocolUnit-a3cef34132aa4e9cbb824fcbcd043b0e_attempt_0 + │   │   ├── checkpoint.nc + │   │   ├── simulation.nc + │   ├── easy_rbfe_lig_ejm_31_complex_lig_ejm_42_complex.json + └── results_2 + ├── easy_rbfe_lig_ejm_31_complex_lig_ejm_42_complex + │   └── shared_RelativeHybridTopologyProtocolUnit-abb2b104151c45fc8b0993fa0a7ee0af_attempt_0 + │   ├── checkpoint.nc + │   ├── simulation.nc + └── easy_rbfe_lig_ejm_31_complex_lig_ejm_42_complex.json + +The results of which can be gathered from the CLI using the ``openfe gather`` command, in this case you should direct +it to the root directory which includes the repeat results and it will automatically collate the information + +:: + + openfe gather results_parallel See Also --------