HamiltonDeck: correct track count & rename rail->track

CHANGELOG.md

@@ -21,6 +21,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - `LinkBody` (`pylabrobot.resources.LinkBody`): one rigid member of a manipulator, an ordinary resource whose origin is a corner and which carries its `proximal_joint` and `distal_joint` as coordinates within it. The link is the line between the two joints and `length` is the distance, `None` on a member that ends the chain. A member turns about its proximal joint rather than its origin. (#1249)
 - `MechanicalGripper` (`pylabrobot.resources.MechanicalGripper`): a `LinkBody` that ends the chain, holding what it takes between two fingers. Its far end is a `tool_center_point` rather than a joint, it is sized to its body because `jaw_width` moves the fingers, and the jaws straddle the grip centre. (#1249)
 
+### Changed
+
+- `HamiltonDeck` and `HamiltonSTARDeck`: `num_tracks` replaces `num_rails` and `track=` replaces `rails=`; the old names are deprecated but keep working, as do decks saved with `num_rails`. A STAR deck counts two fewer tracks than it counted rails (STARlet 30, STAR 54) at the same positions, so a count passed positionally to `HamiltonSTARDeck` is now read as tracks.
+
 ### Fixed
 
 - Imported `unittest.mock` in `pylabrobot/centrifuge/centrifuge_tests.py` (pre-existing bug that prevented the test class from running).

docs/cookbook/star_movement_plate_to_alpaqua_core.ipynb

@@ -224,7 +224,7 @@
     "  name=\"wash_plate_0\"\n",
     ")\n",
     "\n",
-    "deck.assign_child_resource(mfx_carrier_tapped_plate_holder_example, rails=1)\n",
+    "deck.assign_child_resource(mfx_carrier_tapped_plate_holder_example, track=1)\n",
     "\n",
     "# Setup Magnet-carrying MFX Carrier\n",
     "\n",
@@ -243,7 +243,7 @@
     "# cavity_bottom of the well that is placed on top of it\n",
     "# use ztouch_probing to measure both \n",
     "\n",
-    "deck.assign_child_resource(mfx_carrier_magnet_example, rails=8)"
+    "deck.assign_child_resource(mfx_carrier_magnet_example, track=8)"
    ]
   },
   {

docs/resources/carrier/plate-carrier/plate_carrier.ipynb

@@ -211,7 +211,7 @@
     "from pylabrobot.liquid_handling import LiquidHandler, LiquidHandlerChatterboxBackend\n",
     "from pylabrobot.resources import STARDeck\n",
     "lh = LiquidHandler(backend=LiquidHandlerChatterboxBackend(), deck=STARDeck())\n",
-    "lh.deck.assign_child_resource(my_plate_carrier, rails=1)\n",
+    "lh.deck.assign_child_resource(my_plate_carrier, track=1)\n",
     "await lh.setup()"
    ]
   },

docs/user_guide/00_liquid-handling/container_no_go_zones.ipynb

@@ -776,11 +776,11 @@
     "\n",
     "tip_car = TIP_CAR_480_A00(name=\"tip_carrier\")\n",
     "tip_car[0] = hamilton_96_tiprack_1000uL_filter(name=\"tips_1000\")\n",
-    "deck.assign_child_resource(tip_car, rails=1)\n",
+    "deck.assign_child_resource(tip_car, track=1)\n",
     "\n",
     "trough_car = Trough_CAR_5R60_A00(name=\"trough_carrier\")\n",
     "trough_car[0] = hamilton_1_trough_60mL_Vb(name=\"trough_60\")\n",
-    "deck.assign_child_resource(trough_car, rails=10)\n",
+    "deck.assign_child_resource(trough_car, track=10)\n",
     "\n",
     "trough = deck.get_resource(\"trough_60\")\n",
     "print(f\"Trough: {trough.name}\")\n",

docs/user_guide/00_liquid-handling/mixing.ipynb

@@ -47,12 +47,12 @@
     "from pylabrobot.resources import TIP_CAR_480_A00, hamilton_96_tiprack_1000uL_filter\n",
     "tip_carrier = TIP_CAR_480_A00(name=\"tiprack_1\")\n",
     "tip_carrier[0] = tr0 = hamilton_96_tiprack_1000uL_filter(name=\"tiprack_1_0\")\n",
-    "lh.deck.assign_child_resource(tip_carrier, rails=1)\n",
+    "lh.deck.assign_child_resource(tip_carrier, track=1)\n",
     "\n",
     "from pylabrobot.resources import PLT_CAR_L5AC_A00, Cor_96_wellplate_360ul_Fb\n",
     "plate_carrier = PLT_CAR_L5AC_A00(name=\"plate_carrier_1\")\n",
     "plate_carrier[0] = plate = Cor_96_wellplate_360ul_Fb(name=\"plate_1\")\n",
-    "lh.deck.assign_child_resource(plate_carrier, rails=10)"
+    "lh.deck.assign_child_resource(plate_carrier, track=10)"
    ]
   },
   {

docs/user_guide/00_liquid-handling/moving-channels-around.ipynb

@@ -46,7 +46,7 @@
         "# assign a tip rack\n",
         "tip_carrier = TIP_CAR_480_A00(name=\"tip_carrier\")\n",
         "tip_carrier[0] = tip_rack = hamilton_96_tiprack_1000uL_filter(name=\"tip_rack\")\n",
-        "lh.deck.assign_child_resource(tip_carrier, rails=0)"
+        "lh.deck.assign_child_resource(tip_carrier, track=0)"
       ]
     },
     {

docs/user_guide/00_liquid-handling/tutorial_tip_inventory_consolidation.ipynb

@@ -97,7 +97,7 @@
     "tip_carrier = TIP_CAR_480_A00(name=\"tip_carrier\")\n",
     "tip_carrier[0] = tr0 = hamilton_96_tiprack_1000uL_filter(name=\"tr0\", with_tips=True)\n",
     "tip_carrier[1] = tr1 = hamilton_96_tiprack_1000uL_filter(name=\"tr1\", with_tips=False)\n",
-    "deck.assign_child_resource(tip_carrier, rails=10)"
+    "deck.assign_child_resource(tip_carrier, track=10)"
    ]
   },
   {

docs/user_guide/hamilton/star/hardware/replacing-iswap.md

@@ -63,7 +63,7 @@ await star.setup()
 input("Confirm the deck is clear and press Enter to continue...")
 await star.pip.backend.position_components_for_free_iswap_y_range()
 await star.driver.iswap.move_y(y=300)
-x = star.deck.rails_to_location(star.deck.num_rails / 2).x
+x = star.deck.track_to_location(star.deck.num_tracks // 2 + 1).x
 await star.driver.iswap.move_x(x=x)
 ```
 

docs/user_guide/machine-agnostic-features/logging-and-validation/validation.ipynb

@@ -36,7 +36,7 @@
     "from pylabrobot.resources import TIP_CAR_480_A00, hamilton_96_tiprack_1000ul\n",
     "tip_car = TIP_CAR_480_A00(name=\"tip_car\")\n",
     "tip_car[0] = tr = hamilton_96_tiprack_1000ul(name=\"ht\")\n",
-    "lh.deck.assign_child_resource(tip_car, rails=1)"
+    "lh.deck.assign_child_resource(tip_car, track=1)"
    ]
   },
   {

docs/user_guide/machine-agnostic-features/using-the-visualizer.ipynb

@@ -166,7 +166,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "lh.deck.assign_child_resource(tip_car, rails=15)"
+    "lh.deck.assign_child_resource(tip_car, track=15)"
    ]
   },
   {
@@ -189,7 +189,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "lh.deck.assign_child_resource(plt_car, rails=8)"
+    "lh.deck.assign_child_resource(plt_car, track=8)"
    ]
   },
   {

docs/user_guide/machine-agnostic-features/using-trackers.ipynb

@@ -218,7 +218,7 @@
       "metadata": {},
       "outputs": [],
       "source": [
-        "lh.deck.assign_child_resource(tip_carrier, rails=3)"
+        "lh.deck.assign_child_resource(tip_carrier, track=3)"
       ]
     },
     {
@@ -690,7 +690,7 @@
       "metadata": {},
       "outputs": [],
       "source": [
-        "lh.deck.assign_child_resource(plt_carrier, rails=9)"
+        "lh.deck.assign_child_resource(plt_carrier, track=9)"
       ]
     },
     {

pylabrobot/legacy/liquid_handling/backends/chatterbox_tests.py

@@ -20,9 +20,9 @@ def setUp(self) -> None:
     self.backend = LiquidHandlerChatterboxBackend(num_channels=8)
     self.lh = LiquidHandler(self.backend, deck=self.deck)
     self.tip_rack = hamilton_96_tiprack_1000uL_filter(name="tip_rack")
-    self.deck.assign_child_resource(self.tip_rack, rails=3)
+    self.deck.assign_child_resource(self.tip_rack, track=3)
     self.plate = cor_96_wellplate_360uL_Fb(name="plate")
-    self.deck.assign_child_resource(self.plate, rails=9)
+    self.deck.assign_child_resource(self.plate, track=9)
 
   async def asyncSetUp(self) -> None:
     await super().asyncSetUp()

pylabrobot/legacy/liquid_handling/backends/hamilton/STAR_backend.py

@@ -151,7 +151,7 @@
 )
 from pylabrobot.resources.hamilton.hamilton_decks import (
   HamiltonCoreGrippers,
-  rails_for_x_coordinate,
+  track_for_x_coordinate,
 )
 from pylabrobot.resources.liquid import Liquid
 from pylabrobot.resources.rotation import Rotation
@@ -10046,8 +10046,8 @@ async def verify_and_wait_for_carriers(
       if isinstance(child, Carrier):
         # Get x coordinate relative to deck
         carrier_x = child.get_location_wrt(self.deck).x
-        carrier_start_rail = rails_for_x_coordinate(carrier_x)
-        carrier_end_rail = rails_for_x_coordinate(carrier_x - 100.0 + child.get_absolute_size_x())
+        carrier_start_rail = track_for_x_coordinate(carrier_x)
+        carrier_end_rail = track_for_x_coordinate(carrier_x - 100.0 + child.get_absolute_size_x())
 
         # Verify rails are valid
         carrier_start_rail = max(1, min(carrier_start_rail, 54))

pylabrobot/legacy/liquid_handling/backends/hamilton/STAR_tests.py

@@ -674,7 +674,7 @@ async def asyncSetUp(self):
     self.tip_car = TIP_CAR_480_A00(name="tip carrier")
     self.tip_car[1] = self.tip_rack = hamilton_96_tiprack_300uL_filter(name="tip_rack_01")
     self.tip_car[2] = self.tip_rack2 = hamilton_96_tiprack_1000uL_filter(name="tip_rack_02")
-    self.deck.assign_child_resource(self.tip_car, rails=1)
+    self.deck.assign_child_resource(self.tip_car, track=1)
 
     self.plt_car = PLT_CAR_L5AC_A00(name="plate carrier")
     self.plt_car[0] = self.plate = cor_96_wellplate_360uL_Fb(name="plate_01")
@@ -696,7 +696,7 @@ async def asyncSetUp(self):
       nesting_z_height=10,
     )
     self.other_plate.assign_child_resource(lid)
-    self.deck.assign_child_resource(self.plt_car, rails=9)
+    self.deck.assign_child_resource(self.plt_car, track=9)
 
     class BlueBucket(Container):
       def __init__(self, name: str):
@@ -1756,7 +1756,7 @@ async def test_portrait_tip_rack_handling(self):
     tip_car[0] = tr = hamilton_96_tiprack_1000uL(name="tips_01").rotated(z=90)
     assert tr.rotation.z == 90
     assert tr.location == Coordinate(82.6, 0, 0)
-    deck.assign_child_resource(tip_car, rails=2)
+    deck.assign_child_resource(tip_car, track=2)
     await lh.setup()
 
     await lh.pick_up_tips(tr["A4:A1"])
@@ -1820,10 +1820,10 @@ async def asyncSetUp(self):
 
     self.plt_car = PLT_CAR_L5MD_A00(name="plt_car")
     self.plt_car[0] = self.plate = celltreat_96_wellplate_350uL_Ub(name="plate", with_lid=True)
-    self.deck.assign_child_resource(self.plt_car, rails=15)
+    self.deck.assign_child_resource(self.plt_car, track=15)
 
     self.plt_car2 = PLT_CAR_P3AC_A01(name="plt_car2")
-    self.deck.assign_child_resource(self.plt_car2, rails=3)
+    self.deck.assign_child_resource(self.plt_car2, track=3)
 
     self.STAR._num_channels = 8
     self.STAR._machine_conf = _DEFAULT_MACHINE_CONFIGURATION
@@ -1947,12 +1947,12 @@ async def asyncSetUp(self):
 
     tip_carrier = TIP_CAR_480_A00(name="tip_carrier")
     tip_carrier[1] = self.tip_rack = hamilton_96_tiprack_1000uL(name="tip_rack")
-    self.deck.assign_child_resource(tip_carrier, rails=1)
+    self.deck.assign_child_resource(tip_carrier, track=1)
 
     plt_carrier = PLT_CAR_L5AC_A00(name="plt_carrier")
     plt_carrier[0] = self.plate = agenbio_1_troughplate_190mL_Fl(name="plate")
     self.well = self.plate.get_well("A1")
-    self.deck.assign_child_resource(plt_carrier, rails=10)
+    self.deck.assign_child_resource(plt_carrier, track=10)
 
     self.star._num_channels = 8
     self.star._machine_conf = _DEFAULT_MACHINE_CONFIGURATION
@@ -2171,7 +2171,7 @@ async def asyncSetUp(self):
     self.lh = LiquidHandler(self.backend, deck=self.deck)
 
     self.tip_car = TIP_CAR_480_A00(name="tip_carrier")
-    self.deck.assign_child_resource(self.tip_car, rails=1)
+    self.deck.assign_child_resource(self.tip_car, track=1)
 
     await self.lh.setup()
     set_tip_tracking(enabled=False)
@@ -2392,11 +2392,11 @@ async def asyncSetUp(self):
 
     self.tip_car = TIP_CAR_480_A00(name="tip carrier")
     self.tip_car[1] = self.tip_rack = hamilton_96_tiprack_300uL_filter(name="tip_rack_01")
-    self.deck.assign_child_resource(self.tip_car, rails=1)
+    self.deck.assign_child_resource(self.tip_car, track=1)
 
     self.plt_car = PLT_CAR_L5AC_A00(name="plate carrier")
     self.plt_car[0] = self.plate = cor_96_wellplate_360uL_Fb(name="plate_01")
-    self.deck.assign_child_resource(self.plt_car, rails=9)
+    self.deck.assign_child_resource(self.plt_car, track=9)
 
     self.STAR._num_channels = 8
     self.STAR._machine_conf = _DEFAULT_MACHINE_CONFIGURATION
@@ -2615,11 +2615,11 @@ async def asyncSetUp(self):
 
     self.tip_car = TIP_CAR_480_A00(name="tip carrier")
     self.tip_car[1] = self.tip_rack = hamilton_96_tiprack_300uL_filter(name="tip_rack_01")
-    self.deck.assign_child_resource(self.tip_car, rails=1)
+    self.deck.assign_child_resource(self.tip_car, track=1)
 
     self.plt_car = PLT_CAR_L5AC_A00(name="plate carrier")
     self.plt_car[0] = self.plate = cor_96_wellplate_360uL_Fb(name="plate_01")
-    self.deck.assign_child_resource(self.plt_car, rails=9)
+    self.deck.assign_child_resource(self.plt_car, track=9)
 
     await self.lh.setup()
 

pylabrobot/legacy/liquid_handling/backends/hamilton/nimbus_backend_tests.py

@@ -699,10 +699,10 @@ async def asyncSetUp(self):
     self.backend.send_command = self.mock_send  # type: ignore[method-assign]
 
     self.tip_rack = hamilton_96_tiprack_300uL("tip_rack")
-    self.deck.assign_child_resource(self.tip_rack, rails=1)
+    self.deck.assign_child_resource(self.tip_rack, track=1)
 
     self.plate = cor_96_wellplate_360uL_Fb("plate")
-    self.deck.assign_child_resource(self.plate, rails=10)
+    self.deck.assign_child_resource(self.plate, track=10)
 
     self.tip = HamiltonTip(
       name="test_tip",
@@ -1083,7 +1083,7 @@ async def test_10uL_tips(self):
     from pylabrobot.resources.hamilton.tip_racks import hamilton_96_tiprack_10uL
 
     tip_rack = hamilton_96_tiprack_10uL("tips")
-    self.deck.assign_child_resource(tip_rack, rails=1)
+    self.deck.assign_child_resource(tip_rack, track=1)
     tip_spot = tip_rack.get_item("A1")
     tip = tip_spot.get_tip()
 
@@ -1110,7 +1110,7 @@ async def test_50uL_tips(self):
     from pylabrobot.resources.hamilton.tip_racks import hamilton_96_tiprack_50uL
 
     tip_rack = hamilton_96_tiprack_50uL("tips")
-    self.deck.assign_child_resource(tip_rack, rails=1)
+    self.deck.assign_child_resource(tip_rack, track=1)
     tip_spot = tip_rack.get_item("A1")
     tip = tip_spot.get_tip()
 
@@ -1137,7 +1137,7 @@ async def test_300uL_tips(self):
     from pylabrobot.resources.hamilton.tip_racks import hamilton_96_tiprack_300uL
 
     tip_rack = hamilton_96_tiprack_300uL("tips")
-    self.deck.assign_child_resource(tip_rack, rails=1)
+    self.deck.assign_child_resource(tip_rack, track=1)
     tip_spot = tip_rack.get_item("A1")
     tip = tip_spot.get_tip()
 
@@ -1164,7 +1164,7 @@ async def test_1000uL_tips(self):
     from pylabrobot.resources.hamilton.tip_racks import hamilton_96_tiprack_1000uL
 
     tip_rack = hamilton_96_tiprack_1000uL("tips")
-    self.deck.assign_child_resource(tip_rack, rails=1)
+    self.deck.assign_child_resource(tip_rack, track=1)
     tip_spot = tip_rack.get_item("A1")
     tip = tip_spot.get_tip()
 

pylabrobot/legacy/liquid_handling/backends/hamilton/vantage_tests.py

@@ -252,12 +252,12 @@ async def asyncSetUp(self):
     self.tip_car = TIP_CAR_480_A00(name="tip carrier")
     self.tip_car[0] = self.tip_rack = hamilton_96_tiprack_1000uL(name="tip_rack_01")
     self.tip_car[1] = self.small_tip_rack = hamilton_96_tiprack_10uL(name="tip_rack_02")
-    self.deck.assign_child_resource(self.tip_car, rails=18)
+    self.deck.assign_child_resource(self.tip_car, track=18)
 
     self.plt_car = PLT_CAR_L5AC_A00(name="plate carrier")
     self.plt_car[0] = self.plate = cor_96_wellplate_360uL_Fb(name="plate_01")
     self.plt_car[1] = self.other_plate = cor_96_wellplate_360uL_Fb(name="plate_02")
-    self.deck.assign_child_resource(self.plt_car, rails=24)
+    self.deck.assign_child_resource(self.plt_car, track=24)
 
     self.maxDiff = None
 
@@ -584,7 +584,7 @@ async def asyncSetUp(self):
     self.lh = LiquidHandler(self.backend, deck=self.deck)
 
     self.tip_car = TIP_CAR_480_A00(name="tip_carrier")
-    self.deck.assign_child_resource(self.tip_car, rails=18)
+    self.deck.assign_child_resource(self.tip_car, track=18)
 
     await self.lh.setup()
     set_tip_tracking(enabled=False)

pylabrobot/legacy/liquid_handling/backends/serializing_backend_tests.py

@@ -34,12 +34,12 @@ async def asyncSetUp(self) -> None:
 
     self.tip_car = TIP_CAR_480_A00(name="tip carrier")
     self.tip_car[0] = self.tip_rack = hamilton_96_tiprack_300uL_filter(name="tip_rack_01")
-    self.deck.assign_child_resource(self.tip_car, rails=1)
+    self.deck.assign_child_resource(self.tip_car, track=1)
 
     self.plt_car = PLT_CAR_L5AC_A00(name="plate carrier")
     self.plt_car[0] = self.plate = cor_96_wellplate_360uL_Fb(name="plate_01")
     self.plt_car[1] = self.other_plate = cor_96_wellplate_360uL_Fb(name="plate_02")
-    self.deck.assign_child_resource(self.plt_car, rails=9)
+    self.deck.assign_child_resource(self.plt_car, track=9)
 
     self.backend.send_command.reset_mock()