From 24670cf9ade2a12b2ff7e337dd34c4af19fe3da3 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 29 Apr 2025 16:52:40 -0700 Subject: [PATCH 1/7] fix cli quickrun help message formatting --- openfecli/commands/quickrun.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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( From fdbc4c5ca10f9b5a8a4a51d08caa7bc7459e62e1 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 29 Apr 2025 16:52:51 -0700 Subject: [PATCH 2/7] updating cli docs --- docs/guide/cli/cli_basics.rst | 44 ++++++++++++++++++----------------- docs/guide/index.rst | 1 + 2 files changed, 24 insertions(+), 21 deletions(-) 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/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 From 9199ffd5395f086a5a336a5fc401455f3d1e3e62 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 29 Apr 2025 16:59:19 -0700 Subject: [PATCH 3/7] fix list formatting --- docs/guide/cli/cli_yaml.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) 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 :: From 055809f9c13d2e16254cc087de03b82cc8643250 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 29 Apr 2025 17:31:44 -0700 Subject: [PATCH 4/7] put charge-molecules at top of index --- docs/reference/cli/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 From bb115687f02103a1714d74ad3bd7aa24a38437f2 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 29 Apr 2025 17:32:27 -0700 Subject: [PATCH 5/7] making partial charge specific help message --- .../commands/generate_partial_charges.py | 23 ++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/openfecli/commands/generate_partial_charges.py b/openfecli/commands/generate_partial_charges.py index 63de13601..a6f2cb436 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.", From b898ce3edfddc1ce861f204ad13e54e7a362e309 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Wed, 30 Apr 2025 10:25:50 -0700 Subject: [PATCH 6/7] formatting fixes --- openfecli/commands/generate_partial_charges.py | 4 ++-- openfecli/commands/plan_rhfe_network.py | 10 +++++----- openfecli/parameters/misc.py | 8 ++++---- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/openfecli/commands/generate_partial_charges.py b/openfecli/commands/generate_partial_charges.py index a6f2cb436..b61326e1c 100644 --- a/openfecli/commands/generate_partial_charges.py +++ b/openfecli/commands/generate_partial_charges.py @@ -5,7 +5,7 @@ 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. +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: @@ -14,7 +14,7 @@ - ``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. +``settings`` allows for passing in any keyword arguments of the method's corresponding Python API. For example: :: 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/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( From ed09189aa64d570b6f9bfa4fbaf77c29d6a8feae Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Wed, 30 Apr 2025 12:07:53 -0700 Subject: [PATCH 7/7] indicating defaults --- openfecli/parameters/plan_network_options.py | 28 +++++++++++++++++--- 1 file changed, 24 insertions(+), 4 deletions(-) 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)