Merge pull request #276 from OpenFreeEnergy/consolidate_preparing_alchemical_networks

consolidate instructions for creating an alchemical network

Author: atravitz

cookbook/create_alchemical_network.ipynb

@@ -13,7 +13,12 @@
    "id": "2b11a786-0fab-4990-a2aa-242067f89287",
    "metadata": {},
    "source": [
-    "The final setup step is to compile all the different bits of information into a description of a single simulation campaign. This description takes the form of an [Alchemical Network]. Similarly to `LigandNetwork`, the `AlchemicalNetwork` class is a graph of all the transformations in the campaign; however, in an `AlchemicalNetwork`, these transformations include all the information needed to perform the transformation. By contrast, a `LigandNetwork` includes only the ligands themselves.\n",
+    "The final setup step is to compile all the different bits of information into a description of a single simulation campaign. This description takes the form of an [Alchemical Network].\n",
+    "Similar to `LigandNetwork`, the `AlchemicalNetwork` class is a graph of all the transformations in the campaign.\n",
+    "\n",
+    "However, in an `AlchemicalNetwork`, these transformations include all the information needed to perform the transformation. By contrast, a `LigandNetwork` includes only the ligands themselves.\n",
+    "\n",
+    "See the [User Guide: Alchemical Networks](https://docs.openfree.energy/en/stable/guide/setup/alchemical_network_model.html) for more background information.\n",
     "\n",
     "[Alchemical Network]: https://docs.openfree.energy/en/stable/reference/api/generated/openfe.AlchemicalNetwork.html"
    ]
@@ -28,38 +33,33 @@
     "tags": []
    },
    "source": [
-    "## Setup"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 1,
-   "id": "ba6d0d2f-03df-463f-8976-c15a2bdf65e5",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import openfe, rdkit.Chem\n",
-    "from openff.units import unit\n",
-    "from openfe.protocols.openmm_rfe import RelativeHybridTopologyProtocol"
+    "## Start with a `LigandNetwork`"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "6bfee4c7-0aaf-49a6-b35a-bdbe99444bab",
    "metadata": {},
    "source": [
-    "This cookbook assumes you've already loaded a `LigandNetwork`. For more information, see [Generate a Ligand Network Automatically]:\n",
+    "This cookbook assumes you've already loaded a `LigandNetwork`.\n",
     "\n",
-    "[Generate a Ligand Network Automatically]: https://docs.openfree.energy/en/stable/cookbook/generate_ligand_network.html"
+    "To learn how to build a `LigandNetwork`, see [Planning a Ligand Network]:\n",
+    "\n",
+    "[Planning a Ligand Network]: https://docs.openfree.energy/en/stable/cookbook/generate_ligand_network.html"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 1,
    "id": "4512c4d6-720f-4008-af53-a0b56b2ee1e9",
    "metadata": {},
    "outputs": [],
    "source": [
+    "import openfe\n",
+    "import rdkit.Chem\n",
+    "from openff.units import unit\n",
+    "from openfe.protocols.openmm_rfe import RelativeHybridTopologyProtocol\n",
+    "\n",
     "ligand_network = openfe.ligand_network_planning.generate_minimal_spanning_network(\n",
     "    ligands=[\n",
     "        openfe.SmallMoleculeComponent(mol) \n",
@@ -85,7 +85,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 2,
    "id": "940e2e19-4e7d-4853-ab5e-54626b3384d8",
    "metadata": {},
    "outputs": [],
@@ -105,7 +105,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 3,
    "id": "d3054cfc-5040-4882-b3a3-92aba7ab5d1d",
    "metadata": {
     "slideshow": {
@@ -149,7 +149,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 4,
    "id": "733dee64-d23a-4eb0-87cf-c03065b8d2a6",
    "metadata": {},
    "outputs": [],
@@ -181,27 +181,34 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 5,
    "id": "c49f36b1-c3c1-425e-b1de-24da25ed01c3",
    "metadata": {},
    "outputs": [],
    "source": [
     "# In an RBFE, each edge includes two \"legs\": \n",
     "# one for the ligand complexed to the protein, \n",
     "# and the other for the ligand free in solution\n",
+    "\n",
+    "\n",
     "legs = {\n",
-    "    \"solvent\": {\n",
-    "        # Specify the components common to all systems in this leg\n",
-    "        'solvent': solvent,\n",
-    "    },\n",
-    "    \"complex\": {\n",
-    "        # Specify the components common to all systems in this leg\n",
-    "        'solvent': solvent,\n",
-    "        'protein': protein,\n",
-    "    }\n",
-    "}\n",
-    "transformations = []\n",
+    "    # Specify the components common to all systems in this leg\n",
+    "    \"solvent\": {'solvent': solvent},\n",
+    "    # Specify the components common to all systems in this leg\n",
+    "    \"complex\": {'solvent': solvent, 'protein': protein}\n",
+    "}"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "77d71229-5dcc-40cf-a9ae-0724a7327578",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# create a list of transformations\n",
     "\n",
+    "transformations = []\n",
     "for mapping in ligand_network.edges:\n",
     "    for leg, common_components in legs.items():\n",
     "        system_a = openfe.ChemicalSystem(\n",
@@ -229,7 +236,7 @@
     "            name=f\"easy_rbfe_{system_a.name}_{system_b.name}\"\n",
     "        )\n",
     "    \n",
-    "        transformations.append(transformation)"
+    "        transformations.append(transformation)\n"
    ]
   },
   {
@@ -324,8 +331,16 @@
     "\n",
     "for n, transformation in enumerate(alchemical_network.edges):\n",
     "    transformation_name = transformation.name or transformation.key\n",
-    "    transformation.dump(transformations_dir / f\"{n}_{transformation_name}.json\")"
+    "    transformation.to_json(transformations_dir / f\"{n}_{transformation_name}.json\")"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "28d7af7c-0e8e-4379-91c2-c9d291c3923b",
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {
@@ -344,7 +359,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.6"
+   "version": "3.13.11"
   },
   "widgets": {
    "application/vnd.jupyter.widget-state+json": {