From 8df0b05ace0289cdc0d74239268c754c9e46628d Mon Sep 17 00:00:00 2001
From: richard gowers <richardjgowers@gmail.com>
Date: Mon, 11 Mar 2024 13:38:46 +0000
Subject: [PATCH] cli: docs: move docs on customising protocols

didn't render nicely via command line --help, so instead put the example code into the userguide docs
---
 docs/guide/cli/cli_yaml.rst                  | 21 +++++++-
 openfecli/parameters/plan_network_options.py | 51 ++++++++++++--------
 2 files changed, 51 insertions(+), 21 deletions(-)

diff --git a/docs/guide/cli/cli_yaml.rst b/docs/guide/cli/cli_yaml.rst
index b69493686..5a4652f91 100644
--- a/docs/guide/cli/cli_yaml.rst
+++ b/docs/guide/cli/cli_yaml.rst
@@ -15,10 +15,12 @@ as an example, the settings file which re-specifies the default behaviour would
       threed: True
       max3d: 0.95
       element_change: True
+  protocol:
+    method: RelativeHybridTopologyProtocol
 
 The name of the algorithm is given behind the ``method:`` key and the arguments to the
 algorithm are then optionally given behind the ``settings:`` key.
-Both the `network:` and `mapper:` sections are optional.
+The ``network:``, ``mapper:``, and ``protocol:`` sections are all optional.
 
 This is then provided to the ``openfe plan-rbfe-network`` command as ::
 
@@ -76,3 +78,20 @@ settings file ::
     method: generate_radial_network
     settings:
       central_ligand: '0'
+
+Customising the Protocol
+-------------------------
+
+The Settings of a Protocol can be customised.  The settings variable names map directly between the Python API and
+yaml settings files.  For example, to customise the production length of
+the RFE Protocol, from Python would require a line of code such as::
+
+   settings.simulation_settings.production_length = '5.4 ns'
+
+This would be achieved via the yaml file as::
+
+  protocol:
+    method: RelativeHybridTopologyProtocol
+    settings:
+      simulation_settings:
+        production_length: 5.4 ns
diff --git a/openfecli/parameters/plan_network_options.py b/openfecli/parameters/plan_network_options.py
index 2fb72db57..303f73ac4 100644
--- a/openfecli/parameters/plan_network_options.py
+++ b/openfecli/parameters/plan_network_options.py
@@ -136,19 +136,42 @@ def apply_onto(settings: SettingsBaseModel, options: dict) -> None:
 
 
 def resolve_protocol_choices(options: Optional[ProtocolSelection]):
-    """Turn Protocol section into a fully formed Protocol"""
-    from openfe.protocols import openmm_rfe
+    """Turn Protocol section into a fully formed Protocol
 
-    allowed = {'openmm_rfe'}
+    Returns
+    -------
+    Optional[Protocol]
 
-    if options and options.method and options.method.lower() not in allowed:
+    Raises
+    ------
+    ValueError
+      if an unsupported method name is input
+    """
+    if not options:
+        return None
+
+    # issue #644, make this selection not static
+    allowed = {'RelativeHybridTopologyProtocol',
+               # 'AbsoluteSolvationProtocol',
+               # 'PlainMDProtocol',
+               }
+    if options.method.lower() == 'relativehybridtopologyprotocol':
+        from openfe.protocols import openmm_rfe
+        protocol = openmm_rfe.RelativeHybridTopologyProtocol
+    # This wouldn't be reachable from any plan command, so leave out
+    #elif options.method.lower() == 'absolutesolvationprotocol':
+    #    from openfe.protocols import openmm_afe
+    #    protocol = openmm_afe.AbsoluteSolvationProtocol
+    #elif options.method.lower() == 'plainmdprotocol':
+    #    from openfe.protocols import openmm_md
+    #    protocol = openmm_md.PlainMDProtocol
+    else:
         raise ValueError(f"Unsupported protocol method '{options.method}'. "
                          f"Supported methods are {','.join(allowed)}")
-    # todo: we only allow one option, so this is hardcoded for now
-    protocol = openmm_rfe.RelativeHybridTopologyProtocol
+
     settings = protocol.default_settings()
     # work through the fields in yaml input and apply these onto settings
-    if options and options.settings:
+    if options.settings:
         apply_onto(settings, options.settings)
 
     return protocol(settings)
@@ -289,19 +312,7 @@ def load_yaml_planner_options(path: Optional[str], context) -> PlanNetworkOption
 
 The Settings of a Protocol can also be customised in this settings yaml file.
 To do this, the nested variable names from the Python API are directly converted
-to the nested yaml format. For example, to customise the production length of
-the RFE Protocol, from Python would require a line of code such as::
-
-   settings.simulation_settings.production_length = '5.4 ns'
-   
-This would be achieved via the yaml file as::
-
-  protocol:
-    method: RelativeHybridTopologyProtocol
-    settings:
-      simulation_settings:
-        production_length: 5.4 ns
-
+to the nested yaml format. 
 """