diff --git a/docs/user_guide/01_material-handling/thermocycling/thermocycler-quickstart.ipynb b/docs/user_guide/01_material-handling/thermocycling/thermocycler-quickstart.ipynb new file mode 100644 index 00000000000..6ecd49ec52b --- /dev/null +++ b/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 +} diff --git a/docs/user_guide/01_material-handling/thermocycling/thermocycling.md b/docs/user_guide/01_material-handling/thermocycling/thermocycling.md index 9d76b3231a5..78c1f68d1f6 100644 --- a/docs/user_guide/01_material-handling/thermocycling/thermocycling.md +++ b/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 Inheco ODTC ```