{
"nbformat": 4,
"nbformat_minor": 5,
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"name": "python",
"version": "3.10.0"
},
"colab": {
"provenance": []
}
},
"cells": [
{
"cell_type": "markdown",
"id": "intro",
"metadata": {},
"source": [
"# RENKIN — Retrosynthesis Engine Quickstart\n",
"\n",
"[](https://colab.research.google.com/github/kent-tokyo/renkin/blob/master/examples/renkin_quickstart.ipynb)\n",
"[](https://github.com/kent-tokyo/renkin)\n",
"\n",
"**RENKIN** is a pure-Rust retrosynthesis engine for Computer-Aided Synthesis Planning (CASP). \n",
"Given a target molecule (SMILES), it finds multi-step synthesis routes back to cheap commercial starting materials.\n",
"\n",
"- **78.0% Top-1** on USPTO-50k (4,907 molecules, depth=5, beam=100)\n",
"- Pure Rust · Zero C/C++ dependencies · Python / WASM / CLI\n",
"- [Documentation](https://kent-tokyo.github.io/renkin/) · [Playground](https://kent-tokyo.github.io/renkin/playground/)"
]
},
{
"cell_type": "markdown",
"id": "install-header",
"metadata": {},
"source": [
"## 1. Install"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "install",
"metadata": {},
"outputs": [],
"source": [
"!pip install renkin --quiet"
]
},
{
"cell_type": "markdown",
"id": "basic-header",
"metadata": {},
"source": [
"## 2. Basic Usage — Aspirin Retrosynthesis\n",
"\n",
"Find synthesis routes for aspirin (`CC(=O)Oc1ccccc1C(=O)O`)."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "basic-usage",
"metadata": {},
"outputs": [],
"source": [
"import renkin\n",
"\n",
"result = renkin.find_routes(\n",
" \"CC(=O)Oc1ccccc1C(=O)O\", # Aspirin\n",
" depth=5,\n",
" max_routes=5,\n",
" beam_width=100,\n",
")\n",
"\n",
"print(f\"Found {result['routes_found']} route(s) for: {result['target']}\\n\")\n",
"\n",
"for i, route in enumerate(result['routes'], 1):\n",
" print(f\"--- Route {i} (depth {route['depth']}) ---\")\n",
" for step in route['steps']:\n",
" precs = ' + '.join(step['precursors'])\n",
" print(f\" {step['target']}\")\n",
" print(f\" → {precs}\")\n",
" print(f\" [{step['rule']}]\")\n",
" print()"
]
},
{
"cell_type": "markdown",
"id": "molecules-header",
"metadata": {},
"source": [
"## 3. More Examples\n",
"\n",
"Try different drug-like molecules."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "molecules",
"metadata": {},
"outputs": [],
"source": [
"targets = {\n",
" \"Aspirin\": \"CC(=O)Oc1ccccc1C(=O)O\",\n",
" \"Paracetamol\": \"CC(=O)Nc1ccc(O)cc1\",\n",
" \"Biphenyl\": \"c1ccc(-c2ccccc2)cc1\",\n",
" \"4-Phenylpyridine\": \"c1ccc(-c2ccncc2)cc1\",\n",
" \"Ibuprofen\": \"CC(C)Cc1ccc(cc1)C(C)C(=O)O\",\n",
"}\n",
"\n",
"for name, smiles in targets.items():\n",
" result = renkin.find_routes(smiles, depth=5, max_routes=1, beam_width=100)\n",
" n = result['routes_found']\n",
" if n > 0:\n",
" depth = result['routes'][0]['depth']\n",
" rule = result['routes'][0]['steps'][0]['rule'] if result['routes'][0]['steps'] else 'BB'\n",
" print(f\"✓ {name:20s} depth={depth} [{rule}]\")\n",
" else:\n",
" print(f\"✗ {name:20s} no route found\")"
]
},
{
"cell_type": "markdown",
"id": "custom-header",
"metadata": {},
"source": [
"## 4. Try Your Own Molecule\n",
"\n",
"Enter any SMILES string and run retrosynthesis."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "custom",
"metadata": {},
"outputs": [],
"source": [
"# Change this SMILES to your target molecule\n",
"target_smiles = \"COc1ccc(CCN)cc1\" # 4-methoxyphenethylamine (mescaline precursor)\n",
"\n",
"result = renkin.find_routes(\n",
" target_smiles,\n",
" depth=5,\n",
" max_routes=3,\n",
" beam_width=100,\n",
")\n",
"\n",
"print(f\"Target: {result['target']}\")\n",
"print(f\"Routes found: {result['routes_found']}\\n\")\n",
"\n",
"for i, route in enumerate(result['routes'], 1):\n",
" print(f\"Route {i} (depth {route['depth']}):\")\n",
" for step in route['steps']:\n",
" print(f\" {step['target']} → {' + '.join(step['precursors'])} [{step['rule']}]\")\n",
" print()"
]
},
{
"cell_type": "markdown",
"id": "viz-header",
"metadata": {},
"source": [
"## 5. Visualize with RDKit (optional)\n",
"\n",
"Draw reaction steps as 2D structures."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "viz",
"metadata": {},
"outputs": [],
"source": [
"try:\n",
" from rdkit import Chem\n",
" from rdkit.Chem import Draw\n",
" from IPython.display import display, Image\n",
" import io\n",
"\n",
" target = \"CC(=O)Oc1ccccc1C(=O)O\" # Aspirin\n",
" result = renkin.find_routes(target, depth=5, max_routes=1, beam_width=100)\n",
"\n",
" if result['routes_found'] > 0:\n",
" route = result['routes'][0]\n",
" smiles_list = [target]\n",
" labels = [\"Target\"]\n",
" for step in route['steps']:\n",
" for prec in step['precursors']:\n",
" smiles_list.append(prec)\n",
" labels.append(step['rule'])\n",
"\n",
" mols = [Chem.MolFromSmiles(s) for s in smiles_list if Chem.MolFromSmiles(s)]\n",
" img = Draw.MolsToGridImage(\n",
" mols[:8],\n",
" molsPerRow=4,\n",
" subImgSize=(300, 200),\n",
" legends=labels[:8],\n",
" )\n",
" display(img)\n",
" else:\n",
" print(\"No route found.\")\n",
"\n",
"except ImportError:\n",
" print(\"Install rdkit for visualization: pip install rdkit\")\n",
" print(\"In Colab: !pip install rdkit\")"
]
},
{
"cell_type": "markdown",
"id": "api-header",
"metadata": {},
"source": [
"## 6. Python API Reference\n",
"\n",
"```python\n",
"renkin.find_routes(\n",
" smiles: str, # Target molecule SMILES\n",
" depth: int = 5, # Max retrosynthesis depth\n",
" max_routes: int = 5, # Max routes to return\n",
" beam_width: int = 0, # Beam width (0 = unlimited A*)\n",
" building_blocks: list[str] | None = None, # Custom stock (canonical SMILES)\n",
") -> dict\n",
"```\n",
"\n",
"**Return value:**\n",
"```python\n",
"{\n",
" \"target\": str, # Input SMILES (canonicalized)\n",
" \"routes_found\": int,\n",
" \"routes\": [\n",
" {\n",
" \"depth\": int,\n",
" \"steps\": [\n",
" {\n",
" \"rule\": str, # Reaction rule name\n",
" \"target\": str, # Molecule being disconnected\n",
" \"precursors\": [str], # Resulting fragments (SMILES)\n",
" }\n",
" ]\n",
" }\n",
" ]\n",
"}\n",
"```\n",
"\n",
"**Links:** \n",
"- [Full documentation](https://kent-tokyo.github.io/renkin/) \n",
"- [GitHub](https://github.com/kent-tokyo/renkin) \n",
"- [crates.io](https://crates.io/crates/renkin) · [PyPI](https://pypi.org/project/renkin/) \n",
"- [Live playground (WASM)](https://kent-tokyo.github.io/renkin/playground/)"
]
}
]
}