Hamilton Venus

The Venus device runs your existing Hamilton Venus methods (.hsl files) as steps in an Orca workflow. Orca moves the plates and decides when each Venus method runs. Venus does the pipetting.

Two ways to run

On the Hamilton PC. Orca runs on the same computer as Venus. Give Venus the paths in the topology:

from orca.sdk.devices import Venus

ml_star = Venus(
    "ml_star",
    site_names=["sample_site", "reagent_site", "tips_site"],
    exe_path=r"C:\Program Files (x86)\HAMILTON\Bin\HxRun.exe",
    methods_folder=r"C:\Program Files (x86)\HAMILTON\Methods",
    placed_protocol="Orca\\Placed.hsl",
    picked_protocol="Orca\\Picked.hsl",
)

Every argument after site_names is optional. The two paths default to the Hamilton install folders shown.

Through the device bridge. Orca runs elsewhere, and the device bridge runs on the Hamilton PC. The topology names the device only:

ml_star = Venus("ml_star", site_names=["sample_site", "reagent_site", "tips_site"])

The paths and hook Venus methods go in the bridge's config on the Hamilton PC, in a venus block:

{
  "type": "liquid_handler",
  "name": "ml_star",
  "driver": {
    "type": "venus",
    "venus": {
      "exe_path": "C:\\Program Files (x86)\\HAMILTON\\Bin\\HxRun.exe",
      "methods_folder": "C:\\Program Files (x86)\\HAMILTON\\Methods",
      "placed_protocol": "Orca\\Placed.hsl",
      "picked_protocol": "Orca\\Picked.hsl"
    }
  }
}

Under a bridge, Venus refuses those settings in the topology, so there is only one copy of them.

Venus method paths are relative to the methods folder. A path that leads outside it is refused.

Getting a plate onto the Venus deck

Each name in site_names is one position on the Venus deck that holds one labware. Orca does not model the Venus deck itself. Each site is a location named <location>/<site>, where <location> is the device's key in Topology(locations=...).

A transporter reaches a site through a teachpoint with the same name, for example ml_star/sample_site. A teachpoint named after the device alone (ml_star) reaches every site at one position.

deck_positions sends each of an action's inputs to a named site. An input without an entry goes to any free site:

@orca.action(
    device=ml_star,
    inputs=[sample_plate, reagent_plate],
    deck_positions={sample_plate: "sample_site", reagent_plate: "reagent_site"},
)

The pick and place hook Venus methods

Each pick or place on a Venus site can start a Venus method. You choose which one in four settings:

Setting	Runs	`action` value
`prepare_place_protocol`	before the transporter places a plate on a site	`prepare_for_place`
`placed_protocol`	after the plate is down	`notify_placed`
`prepare_pick_protocol`	before the transporter picks a plate up	`prepare_for_pick`
`picked_protocol`	after the plate is lifted	`notify_picked`

A setting left empty runs nothing. init_protocol runs one Venus method when Orca brings the device up, with action set to initialize.

For each hook, Orca starts the Venus method you set and passes it these values:

Name	Value
`action`	Which hook started it (the table above)
`labware_name`	The plate's name in Orca
`labware_type`	The plate's labware type
`site`	The Venus site, such as `sample_site`
`barcode`	The plate's barcode, or an empty string if it has none

The Venus method runs from start to finish, and Orca waits for it to end before the transporter carries on. Every hook starts the whole Venus method, never a part of it.

How you organize the Venus methods is up to you:

One Venus method per hook. Set each setting to its own .hsl file. Each Venus method does one job and can ignore action.
One Venus method for several hooks. Set several settings to the same .hsl file. That Venus method reads action and uses it to decide what to do. It still runs completely every time, for every hook it is set on.

Every Venus method Orca starts receives action, including one started by run_protocol (run). action is reserved: a value named action passed to run_protocol is replaced with run.

Running a Venus method and passing values

Call run_protocol in an action with the Venus method's path and a dictionary of values. Orca waits for the Venus method to finish before the action ends:

@orca.action(device=ml_star, inputs=[sample_plate], deck_positions={sample_plate: "sample_site"})
async def add_buffer(ctx: ActionContext):
    await ctx.device().run_protocol("MyFolder\\AddBuffer.hsl", {"vol": 50, "buffer": "PBS"})

Values can be strings, integers or floats. They go from Orca to Venus only.

On the Venus side, add the Orca submethod library to your Venus method. It is in the venus_submethod folder of orca-driver-venus.

Call ORCA::Initialize(0) at the start of the Venus method.
Read each value by name with GetConfigProperty_Integer, GetConfigProperty_Float or GetConfigProperty_String.

To run the Venus method in Venus without Orca, call ORCA::Initialize(1) instead. Each GetConfigProperty_* call then uses its default value. The hook Venus methods read their values the same way.

Tracking volumes and tips

Orca cannot see inside a Venus method. Declare what the Venus method does on the action, and Orca updates its well volumes and tip counts when the action finishes:

from orca.state.records import DeclaredTracking, DeclaredVolumeTransfer

@orca.action(
    device=ml_star,
    inputs=[reservoir, sample_plate, tips],
    deck_positions={reservoir: "reagent_site", sample_plate: "sample_site", tips: "tips_site"},
    declares=DeclaredTracking(
        volume_transferred=[DeclaredVolumeTransfer(
            source="reservoir", target="sample_plate", volume_ul=50.0,
            source_wells=["A1", "B1", "C1"], target_wells=["A1", "B1", "C1"])],
        tips_used={"tips": ["A1", "B1", "C1"]},
    ),
)
async def add_buffer(ctx: ActionContext):
    await ctx.device().run_protocol("MyFolder\\AddBuffer.hsl", {"vol": 50})

Each source well listed loses volume_ul and each target well listed gains volume_ul. To draw from one well into three, list that source well three times. List the wells explicitly. A transfer without wells is recorded, but no well volumes change. Helpers in orca.sdk.wells, such as columns_96(1, 3), build well lists for whole columns.

When a Venus method fails

If HxRun exits with an error, the action fails with HxRun's error message, and its declared volumes and tips are not recorded. By default the plate's thread pauses, and you recover it like any other paused action. An action with a different failure policy, such as ABORT, does what that policy says instead. See Recovery.

Simulation

A PURE_SIM run never starts HxRun. Orca's own simulator stands in for Venus and the declared volumes and tips are still recorded.

A DEVICE_SIM run through the bridge also uses Orca's Venus simulator, on the Hamilton PC, and never starts HxRun. Running a Venus method in Venus's own simulation mode from Orca is deferred and not supported yet.

Two ways to run​

Getting a plate onto the Venus deck​

The pick and place hook Venus methods​

Running a Venus method and passing values​

Tracking volumes and tips​

When a Venus method fails​

Simulation​