Add thermocycler quickstart notebook

docs/user_guide/01_material-handling/thermocycling/thermocycler-quickstart.ipynb

@@ -0,0 +1,198 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Thermocycler quickstart\n",
+    "\n",
+    "This notebook shows the basic thermocycler workflow in PyLabRobot using the `ThermocyclerChatterboxBackend`. The chatterbox backend prints actions instead of controlling real hardware, which makes it useful for learning and testing examples.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Create a thermocycler\n",
+    "\n",
+    "A thermocycler combines the high-level `Thermocycler` resource with a backend. For this quickstart, we use `ThermocyclerChatterboxBackend` so the notebook can run without physical hardware.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pylabrobot.resources import Coordinate\n",
+    "from pylabrobot.thermocycling import Thermocycler, ThermocyclerChatterboxBackend\n",
+    "from pylabrobot.thermocycling.standard import Protocol, Stage, Step\n",
+    "\n",
+    "tc = Thermocycler(\n",
+    "  name=\"tc\",\n",
+    "  size_x=1,\n",
+    "  size_y=1,\n",
+    "  size_z=1,\n",
+    "  backend=ThermocyclerChatterboxBackend(),\n",
+    "  child_location=Coordinate.zero(),\n",
+    ")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Lid control\n",
+    "\n",
+    "Use `open_lid` and `close_lid` to control the thermocycler lid.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "await tc.open_lid()\n",
+    "await tc.close_lid()\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Temperature control\n",
+    "\n",
+    "Set the block and lid temperatures. Temperatures are passed as lists because some thermocyclers support multiple temperature zones.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "await tc.set_block_temperature([95.0])\n",
+    "await tc.set_lid_temperature([105.0])\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Query status\n",
+    "\n",
+    "You can query temperatures, lid state, block status, lid status, and profile progress.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "block_temperature = await tc.get_block_current_temperature()\n",
+    "lid_temperature = await tc.get_lid_current_temperature()\n",
+    "lid_open = await tc.get_lid_open()\n",
+    "block_status = await tc.get_block_status()\n",
+    "lid_status = await tc.get_lid_status()\n",
+    "\n",
+    "block_temperature, lid_temperature, lid_open, block_status, lid_status\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Run a custom protocol\n",
+    "\n",
+    "A protocol contains one or more stages. Each stage contains one or more steps and a repeat count.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "protocol = Protocol(\n",
+    "  stages=[\n",
+    "    Stage(\n",
+    "      steps=[\n",
+    "        Step(temperature=[95.0], hold_seconds=10),\n",
+    "        Step(temperature=[55.0], hold_seconds=20),\n",
+    "      ],\n",
+    "      repeats=1,\n",
+    "    )\n",
+    "  ]\n",
+    ")\n",
+    "\n",
+    "await tc.run_protocol(protocol, block_max_volume=25.0)\n",
+    "await tc.wait_for_profile_completion(poll_interval=0.01)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Run a PCR profile\n",
+    "\n",
+    "`run_pcr_profile` builds a standard PCR-style protocol from denaturation, annealing, extension, and optional storage parameters.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "await tc.run_pcr_profile(\n",
+    "  denaturation_temp=[98.0],\n",
+    "  denaturation_time=15.0,\n",
+    "  annealing_temp=[60.0],\n",
+    "  annealing_time=15.0,\n",
+    "  extension_temp=[72.0],\n",
+    "  extension_time=20.0,\n",
+    "  num_cycles=2,\n",
+    "  block_max_volume=25.0,\n",
+    "  lid_temperature=[105.0],\n",
+    "  storage_temp=[4.0],\n",
+    "  storage_time=1.0,\n",
+    ")\n",
+    "await tc.wait_for_profile_completion(poll_interval=0.01)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Shut down heaters\n",
+    "\n",
+    "Deactivate the block and lid heaters when they are no longer needed.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "await tc.deactivate_block()\n",
+    "await tc.deactivate_lid()\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/user_guide/01_material-handling/thermocycling/thermocycling.md

@@ -18,5 +18,6 @@ Thermocyclers are essential for temperature-controlled processes like PCR (Polym
 ```{toctree}
 :maxdepth: 1
 
+Thermocycler quickstart <thermocycler-quickstart>
 Inheco ODTC <inheco-odtc>
 ```