Merge pull request #1117 from OpenFreeEnergy/charge_warning

Add a note on charge generation during CLI workflows
OpenFreeEnergy · Feb 12, 2025 · d3474c8 · d3474c8
2 parents f7b11d4 + 54a4d2b
commit d3474c8
Show file tree

Hide file tree

Showing 6 changed files with 39 additions and 2 deletions.
diff --git a/docs/guide/cli/cli_yaml.rst b/docs/guide/cli/cli_yaml.rst
@@ -1,3 +1,5 @@
+.. _userguide_cli_yaml_interface:
+
 Customising CLI planning with YAML settings
 ===========================================
 

diff --git a/docs/guide/introduction.rst b/docs/guide/introduction.rst
@@ -66,6 +66,15 @@ The commands used to generate an :class:`.AlchemicalNetwork` using the CLI are:
 * :ref:`cli_plan-rbfe-network`
 * :ref:`cli_plan-rhfe-network`
 
+.. note::
+
+   To ensure a consistent set of partial charges are used for each molecule across different transformations, the CLI
+   network planners will now automatically generate charges ahead of planning the network. The partial charge generation
+   scheme can be configured using the :ref:`YAML settings <userguide_cli_yaml_interface>`. We also provide tooling to
+   generate the partial charges as a separate CLI step which can be run before network planning, see the :ref:`tutorial <charge_molecules_cli_tutorial>`
+   for more details.
+
+
 For example, you can create a relative binding free energy (RBFE) network using
 
 .. code:: bash

diff --git a/docs/tutorials/charge_molecules_cli_tutorial.rst b/docs/tutorials/charge_molecules_cli_tutorial.rst
@@ -0,0 +1,4 @@
+.. _charge_molecules_cli_tutorial:
+
+.. include:: /ExampleNotebooks/cli_tutorials/cli_charge_molecules.md
+   :parser: myst_parser.sphinx_
diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst
@@ -9,14 +9,20 @@ OpenFE has several tutorial notebooks which are maintained on our
 Here is a list of key tutorials which cover the different aspects of the
 OpenFE tooling:
 
+Generating Partial Charges
+--------------------------
+
+The :ref:`Generating Partial Charges CLI tutorial <charge_molecules_cli_tutorial>` demonstrates
+how the command line interface can be used to assign and store partial charges for small molecules which
+can be used throughout the OpenFE ecosystem.
 
 Relative Free Energies
 ----------------------
 
 Python API Showcase
 ~~~~~~~~~~~~~~~~~~~
 
-Our :any:`shocase notebook <showcase_notebook>` walks users through
+Our :any:`showcase notebook <showcase_notebook>` walks users through
 how to use the main Python API components of OpenFE to create a
 relative binding free energy calculation.
 
@@ -62,10 +68,12 @@ to analyze (e.g. generating MLE estimates of absolute free energies)
 and plot networks of relative free energy results.
 
 
+
 .. toctree::
     :maxdepth: 1
     :hidden:
-
+
+    charge_molecules_cli_tutorial
     rbfe_cli_tutorial
     rbfe_python_tutorial
     showcase_notebook

diff --git a/openfecli/commands/plan_rbfe_network.py b/openfecli/commands/plan_rbfe_network.py
@@ -158,6 +158,13 @@ def plan_rbfe_network(
     The generated Network will be stored in a folder containing for each
     transformation a JSON file, that can be run with quickrun.
 
+    .. note::
+
+       To ensure a consistent set of partial charges are used for each molecule across different transformations, this
+       tool will automatically generate charges ahead of planning the network. ``am1bcc`` charges will be generated via
+       ``ambertools``, this can also be customized using the settings yaml file.
+
+
     By default, this tool makes the following choices:
 
     * Atom mappings performed by LOMAP, with settings max3d=1.0 and

diff --git a/openfecli/commands/plan_rhfe_network.py b/openfecli/commands/plan_rhfe_network.py
@@ -122,6 +122,13 @@ def plan_rhfe_network(molecules: List[str], yaml_settings: str, output_dir: str,
     to run the planned transformations with the quickrun tool.  For more
     sophisticated setups, please consider using the python layer of openfe.
 
+    .. note::
+
+       To ensure a consistent set of partial charges are used for each molecule across different transformations, this
+       tool will automatically generate charges ahead of planning the network. ``am1bcc`` charges will be generated via
+       ``ambertools``, this can also be customized using the settings yaml file.
+
+
     The tool will parse the input and run the rbfe network planner, which
     executes following steps: