diff --git a/docs/guide/cli/cli_basics.rst b/docs/guide/cli/cli_basics.rst index eddd89152..15e3faa6a 100644 --- a/docs/guide/cli/cli_basics.rst +++ b/docs/guide/cli/cli_basics.rst @@ -13,30 +13,30 @@ To get a list of the subcommands and their descriptions, call ``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. - + 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. - + JSON files for the quickrun command. + plan-rbfe-network Plan a relative binding free energy network, saved as + JSON files for the quickrun command. + view-ligand-network Visualize a ligand network + 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. + fetch Fetch tutorial or other resource. charge-molecules Generate partial charges for a set of molecules. - test Run the OpenFE test suite + 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. @@ -47,26 +47,28 @@ 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. - + Simulation JSON files can be created with the :ref:`cli_plan-rbfe-network` - or from Python a :class:`.Transformation` can be saved using its ``to_json`` + or from Python a :class:`.Transformation` can be saved using its to_json method:: - + transformation.to_json("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 + -d, --work-dir DIRECTORY Directory in which to store files in (defaults to + current directory). If the directory does not + exist, it will be created at runtime. + -o PATH Filepath at which to create and write the JSON- + formatted results. -h, --help Show this message and exit. For more details on various commands, see the :ref:`cli-reference`. diff --git a/docs/guide/cli/cli_yaml.rst b/docs/guide/cli/cli_yaml.rst index 9cde7dbe5..84825ef72 100644 --- a/docs/guide/cli/cli_yaml.rst +++ b/docs/guide/cli/cli_yaml.rst @@ -89,16 +89,16 @@ Customising the partial charge generation There are a range of partial charge generation schemes available, including - - ``am1bcc`` - - ``am1bccelf10`` (only possible if ``off_toolkit_backend`` in settings is set to ``openeye``) - - ``nagl`` (must have ``openff-nagl`` installed) - - ``espaloma`` (must have ``espaloma_charge`` installed) +* ``am1bcc`` +* ``am1bccelf10`` (only possible if ``off_toolkit_backend`` in settings is set to ``openeye``) +* ``nagl`` (must have ``openff-nagl`` installed) +* ``espaloma`` (must have ``espaloma_charge`` installed) The following settings can also be set - - ``off_toolkit_backend`` The backend to use for partial charge generation. Choose from ``ambertools`` (default), ``openeye`` or ``rdkit``. - - ``number_of_conformers`` The number of conformers to use for partial charge generation. If unset (default), the input conformer will be used. - - ``nagl_model``: The NAGL model to use. If unset (default), the latest available production charge model will be used. +* ``off_toolkit_backend`` The backend to use for partial charge generation. Choose from ``ambertools`` (default), ``openeye`` or ``rdkit``. +* ``number_of_conformers`` The number of conformers to use for partial charge generation. If unset (default), the input conformer will be used. +* ``nagl_model``: The NAGL model to use. If unset (default), the latest available production charge model will be used. For example, to generate the partial charges using the ``am1bccelf10`` method from ``openeye`` the following should be added to the YAML settings file :: diff --git a/docs/guide/index.rst b/docs/guide/index.rst index 8399cc65c..82db2830d 100644 --- a/docs/guide/index.rst +++ b/docs/guide/index.rst @@ -2,6 +2,7 @@ User Guide ========== .. toctree:: + :maxdepth: 2 introduction setup/index diff --git a/docs/reference/cli/index.rst b/docs/reference/cli/index.rst index 5df4af57e..4d8b473bd 100644 --- a/docs/reference/cli/index.rst +++ b/docs/reference/cli/index.rst @@ -6,8 +6,8 @@ CLI Reference .. toctree:: :maxdepth: 1 + charge_molecules plan_rhfe_network plan_rbfe_network quickrun gather - charge_molecules diff --git a/openfecli/commands/generate_partial_charges.py b/openfecli/commands/generate_partial_charges.py index 63de13601..b61326e1c 100644 --- a/openfecli/commands/generate_partial_charges.py +++ b/openfecli/commands/generate_partial_charges.py @@ -4,6 +4,27 @@ from openfecli import OFECommandPlugin from openfecli.parameters import MOL_DIR, YAML_OPTIONS, OUTPUT_FILE_AND_EXT, NCORES, OVERWRITE +YAML_HELP = """ +Path to a YAML file specifying the method to use to charge the molecules +(any atom mapper or network generation options will be ignored). + +Supported partial charge method choices are: + - ``am1bcc`` + - ``am1bccelf10`` (only possible if ``off_toolkit_backend`` is ``openeye``) + - ``nagl`` (must have openff-nagl installed) + - ``espaloma`` (must have espaloma_charge installed) + +``settings`` allows for passing in any keyword arguments of the method's corresponding Python API. + +For example: +:: + + partial_charge: + method: am1bcc + settings: + off_toolkit_backend: ambertools + +""" @click.command( "charge-molecules", @@ -14,7 +35,7 @@ ) @YAML_OPTIONS.parameter( multiple=False, required=False, default=None, - help=YAML_OPTIONS.kwargs["help"], + help=YAML_HELP, ) @OUTPUT_FILE_AND_EXT.parameter( help="The name of the SDF file the charged ligands should be written to.", diff --git a/openfecli/commands/plan_rhfe_network.py b/openfecli/commands/plan_rhfe_network.py index e88b62d4d..88fe80039 100644 --- a/openfecli/commands/plan_rhfe_network.py +++ b/openfecli/commands/plan_rhfe_network.py @@ -132,13 +132,13 @@ def plan_rhfe_network(molecules: List[str], yaml_settings: str, output_dir: str, The tool will parse the input and run the rbfe network planner, which executes following steps: - 1. generate an atom mapping for all possible ligand pairs. (default: - Lomap) + 1. generate an atom mapping for all possible ligand pairs. (default: + Lomap) - 2. score all atom mappings. (default: Lomap default score) + 2. score all atom mappings. (default: Lomap default score) - 3. build network form all atom mapping scores (default: minimal - spanning graph) + 3. build network form all atom mapping scores (default: minimal + spanning graph) The generated Network will be stored in a folder containing for each transformation a JSON file, that can be run with quickrun (or other diff --git a/openfecli/commands/quickrun.py b/openfecli/commands/quickrun.py index 16b982328..be0fe0c93 100644 --- a/openfecli/commands/quickrun.py +++ b/openfecli/commands/quickrun.py @@ -27,8 +27,8 @@ def _format_exception(exception) -> str: type=click.Path(dir_okay=True, file_okay=False, writable=True, path_type=pathlib.Path), help=( - "Directory in which to store files in (defaults to current directory).\ - If the directory does not exist, it will be created at runtime." + "Directory in which to store files in (defaults to current directory). " + "If the directory does not exist, it will be created at runtime." ), ) @click.option( diff --git a/openfecli/parameters/misc.py b/openfecli/parameters/misc.py index 54ab482ec..b4bda47a8 100644 --- a/openfecli/parameters/misc.py +++ b/openfecli/parameters/misc.py @@ -4,10 +4,10 @@ N_PROTOCOL_REPEATS = Option( "--n-protocol-repeats", type=click.INT, - help="Number of independent repeats(s) to be run per execution of a transformation using the `openfe quickrun` command.\n\n" - "For example:\n\n `--n-protocol-repeats=3` means `openfe quickrun` will execute 3 repeats in serial.\n\n" - " `--n-protocol-repeats=1` means `openfe quickrun` will execute only 1 repeat per call, " - "which allows for individual repeats to be submitted in parallel by calling `openfe quickrun` on the same input JSON file multiple times.", + help="Number of independent repeats(s) to be run per execution of a transformation using the ``openfe quickrun`` command.\n\n" + "For example:\n\n ``--n-protocol-repeats=3`` means ``openfe quickrun`` will execute 3 repeats in serial.\n\n" + " ``--n-protocol-repeats=1`` means ``openfe quickrun`` will execute only 1 repeat per call, " + "which allows for individual repeats to be submitted in parallel by calling ``openfe quickrun`` on the same input JSON file multiple times.", ) NCORES = Option( diff --git a/openfecli/parameters/plan_network_options.py b/openfecli/parameters/plan_network_options.py index 6a5cf4fa5..7ff8999ed 100644 --- a/openfecli/parameters/plan_network_options.py +++ b/openfecli/parameters/plan_network_options.py @@ -213,7 +213,27 @@ def load_yaml_planner_options(path: Optional[str], context) -> PlanNetworkOption solvent, partial_charge_settings, ) - +# TODO: do we want this in the docs anywhere? +DEFAULT_YAML=""" + mapper: LomapAtomMapper + settings: + time: 20 + threed: True + max3d: 1.0 + element_change: true + seed: '' + shift: false + + network: + method: generate_minimal_spanning_network + + partial_charge: + method: am1bcc + settings: + off_toolkit_backend: ambertools + number_of_conformers: None + nagl_model: None +""" _yaml_help = """ Path to a YAML file specifying the atom mapper (``mapper``), network planning algorithm (``network``), @@ -221,17 +241,17 @@ def load_yaml_planner_options(path: Optional[str], context) -> PlanNetworkOption \b Supported atom mapper choices are: - - ``LomapAtomMapper`` + - ``LomapAtomMapper`` (default) - ``KartografAtomMapper`` \b Supported network planning algorithms include (but are not limited to): - - ``generate_minimal_spanning_tree`` + - ``generate_minimal_spanning_network`` (default) - ``generate_minimal_redundant_network`` - ``generate_radial_network`` - ``generate_lomap_network`` \b Supported partial charge method choices are: - - ``am1bcc`` + - ``am1bcc`` (default) - ``am1bccelf10`` (only possible if ``off_toolkit_backend`` is ``openeye``) - ``nagl`` (must have openff-nagl installed) - ``espaloma`` (must have espaloma_charge installed)