diff --git a/openfecli/commands/gather.py b/openfecli/commands/gather.py index 9e6aa42f3..85b7f4624 100644 --- a/openfecli/commands/gather.py +++ b/openfecli/commands/gather.py @@ -311,7 +311,9 @@ def gather(rootdir, output, report, allow_partial): \b * 'dg' (default) reports the ligand, its absolute free energy, and the associated uncertainty as the maximum likelihood estimate obtained - from DDG replica averages and standard deviations. + from DDG replica averages and standard deviations. These MLE estimates + are centred around 0.0, and when plotted can be shifted to match + experimental values. * 'ddg' reports pairs of ligand_i and ligand_j, the calculated relative free energy DDG(i->j) = DG(j) - DG(i) and its uncertainty. * 'raw' reports the raw results, which each repeat simulation given diff --git a/openfecli/commands/plan_rbfe_network.py b/openfecli/commands/plan_rbfe_network.py index 997f4db23..2c2d13fdd 100644 --- a/openfecli/commands/plan_rbfe_network.py +++ b/openfecli/commands/plan_rbfe_network.py @@ -2,11 +2,10 @@ # For details, see https://github.com/OpenFreeEnergy/openfe import click -from typing import List from openfecli.utils import write, print_duration from openfecli import OFECommandPlugin from openfecli.parameters import ( - MOL_DIR, PROTEIN, MAPPER, OUTPUT_DIR, COFACTORS, YAML_OPTIONS, + MOL_DIR, PROTEIN, OUTPUT_DIR, COFACTORS, YAML_OPTIONS, ) from openfecli.plan_alchemical_networks_utils import plan_alchemical_network_output @@ -88,7 +87,7 @@ def plan_rbfe_network_main( ) @print_duration def plan_rbfe_network( - molecules: List[str], protein: str, cofactors: tuple[str], + molecules: list[str], protein: str, cofactors: tuple[str], yaml_settings: str, output_dir: str, ): @@ -98,22 +97,24 @@ def plan_rbfe_network( This tool is an easy way to set up a RBFE calculation campaign. The JSON files this outputs can be used to run each leg of the campaign. - For customized setups, please consider using the Python layer of - openfe. This tool makes the following choices: + openfe. + The generated Network will be stored in a folder containing for each + transformation a JSON file, that can be run with quickrun. + + By default, this tool makes the following choices: * Atom mappings performed by LOMAP, with settings max3d=1.0 and element_change=False - * Minimal spanning network as the network planner, with LOMAP default score as the weight function - - * Water as solvent, with NaCl at 0.15 M. - + * Water as solvent, with NaCl counter ions at 0.15 M concentration. * Protocol is the OpenMM-based relative hybrid topology protocol, with default settings. - The generated Network will be stored in a folder containing for each - transformation a JSON file, that can be run with quickrun. + These choices can be customized by creating a settings yaml file, + which is passed in via the ``-s settings.yaml`` option, + which is detailed in the Options section. + For more advanced setups, please consider using the Python layer of openfe. """ write("RBFE-NETWORK PLANNER") write("______________________") diff --git a/openfecli/commands/quickrun.py b/openfecli/commands/quickrun.py index b8f6dc5e0..8be380352 100644 --- a/openfecli/commands/quickrun.py +++ b/openfecli/commands/quickrun.py @@ -40,14 +40,21 @@ def _format_exception(exception) -> str: ) @print_duration def quickrun(transformation, work_dir, output): - """Run the transformation (edge) in the given JSON file in serial. + """Run the transformation (edge) in the given JSON file. - A transformation can be saved as JSON using from Python using its dump + 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). """ import gufe import os diff --git a/openfecli/parameters/plan_network_options.py b/openfecli/parameters/plan_network_options.py index c89ec9ec9..3bd4c1d4b 100644 --- a/openfecli/parameters/plan_network_options.py +++ b/openfecli/parameters/plan_network_options.py @@ -174,9 +174,39 @@ def load_yaml_planner_options(path: Optional[str], context) -> PlanNetworkOption ) +_yaml_help = """\ +Path to planning settings yaml file + +Currently it can contain sections for customising the +atom mapper and network planning algorithm, +these are addressed using a `mapper:` or `network:` key in the yaml file. +The algorithm to be used for these sections is then specified by the `method:` key. +For choosing mappers, either the LomapAtomMapper or KartografAtomMapper are allowed choices, +while for the network planning algorithm either the generate_minimal_spanning_tree or +generate_minimal_redundant_network options are allowed. +Finally, a `settings:` key can be given to customise the algorithm, +with allowable options corresponding to the keyword arguments of the Python API for these algorithms. + +For example, this is a valid settings yaml file to specify that +the Lomap atom mapper should be used forbidding element changes, +while the generate_minimal_redundant_network function used to plan the network +:: + + mapper: + method: LomapAtomMapper + settings: + element_change: false + + network: + method: generate_minimal_redundant_network + settings: + mst_num: 3 +""" + + YAML_OPTIONS = Option( '-s', "--settings", "yaml_settings", type=click.Path(exists=True, dir_okay=False), - help="Path to planning settings yaml file.", + help=_yaml_help, getter=load_yaml_planner_options, )