{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Looping through tip racks\n",
    "\n",
    "In the `pylabrobot.resources.functional` module, we have utilities for looping through tip spots in one or more tip racks. They support caching to disk, so that you can resume where you left off if your script is interrupted."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# instantiate some hamilton tip racks as an example\n",
    "from pylabrobot.resources.ml_star import HT # an example tip rack\n",
    "tip_rack_0 = HT(name='tip_rack_0')\n",
    "tip_rack_1 = HT(name='tip_rack_1')\n",
    "tip_racks = [tip_rack_0, tip_rack_1]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Tip spot generators take a list of tip spots (`list[TipSpot]`) as an argument. With `F.get_all_tip_spots`, you can get all tip spots in one or more tip racks. The tip spots will be column-first, i.e. the first tip spot is the top left corner, the second tip spot is the one below it, and so on."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "TipSpot(name=tip_rack_0_tipspot_0_0, location=(007.200, 068.300, -83.500), size_x=9.0, size_y=9.0, size_z=0, category=tip_spot)"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import pylabrobot.resources.functional as F\n",
    "tip_spots = F.get_all_tip_spots(tip_racks)\n",
    "tip_spots[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Basic linear generator \n",
    "\n",
    "The linear generator will loop through all tip spots in the order they are given, with the option to repeat."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "linear_generator = F.linear_tip_spot_generator(\n",
    "  tip_spots=tip_spots,                      # the list of tip spots to use\n",
    "  cache_file_path=\"./linear_cache.json\",    # load/save tip spot cache for state in between runs\n",
    "  repeat=False,                             # don't repeat the tip spots if they run out\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Tip spot generators are asynchronous, so use `await` and `__anext__` to get the next tip spot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "TipSpot(name=tip_rack_0_tipspot_0_0, location=(007.200, 068.300, -83.500), size_x=9.0, size_y=9.0, size_z=0, category=tip_spot)"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "await linear_generator.__anext__()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To get multiple tip spots, call `__anext__` multiple times."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['tip_rack_0_tipspot_0_1', 'tip_rack_0_tipspot_0_2', 'tip_rack_0_tipspot_0_3']"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "N = 3\n",
    "tip_spots = [await linear_generator.__anext__() for _ in range(N)]\n",
    "[ts.name for ts in tip_spots]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Randomized generator\n",
    "\n",
    "The randomized generator will loop through all tip spots in a random order, with the option to repeat. If repeating, set the parameter `K` to not sample a tip spot that has been sampled in the last `K` samples."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "random_generator = F.randomized_tip_spot_generator(\n",
    "  tip_spots=tip_spots,                      # the list of tip spots to use\n",
    "  cache_file_path=\"./random_cache.json\",    # load/save tip spot cache for state in between runs\n",
    "  K=10,                                     # don't sample tip spots that have been used in the last K samples\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "TipSpot(name=tip_rack_0_tipspot_0_2, location=(007.200, 050.300, -83.500), size_x=9.0, size_y=9.0, size_z=0, category=tip_spot)"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "await random_generator.__anext__()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "env",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.19"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}