Scaling: Resource: remember which names a tree holds instead of re-reading it

[BioCam]

Problem

_check_naming_conflicts enforces tree-wide name uniqueness by recursing over the whole tree, and assign_child_resource calls it on get_root() for every resource assigned. An assignment costs the size of everything already in the tree rather than the size of what is arriving, so building n resources costs n² - measured between n^1.9 and n^2.0 - and every later assignment still walks all of it.

A loaded STARlet deck is around 2 000 resources. One plate move on it, an unassign and a re-assign, already costs 47 ms. Put several instruments in one tree and the cost grows with all of them, not with the plate:

resources	instruments	before	after
2 001	1	47.0 ms	0.0 ms
4 002	2	93.1 ms	0.0 ms
8 004	4	186.7 ms	0.0 ms
16 008	8	379.3 ms	0.0 ms

Changes

• Resource._name_index holds the names in a tree, kept only by the root, built the first time _names_in_tree asks for it.
• _subtree_names returns the names at or beneath a resource; assign_child_resource unions the arriving ones in, unassign_child_resource subtracts them.
• _check_naming_conflicts walks the arriving subtree against that set instead of recursing over both trees. It reads the index off get_root(), where it was already called from, so it still covers the whole tree.

Behaviour: unchanged, and an assignment now costs the size of what is arriving. Carrying the index forward is safe because a name cannot change while a resource is assigned - the setter refuses - and a tree only changes shape in the two methods that maintain it.

Scope: cheaper, not narrower. The check still runs before the branch that detaches an already-attached resource, so a move within one tree is still refused and callers still unassign first. Excluding the arriving resource's own names would fix that, and is a follow-up since it changes behaviour the tests pin.

Tests

TestNameIndex (a duplicate name, one buried in the arriving subtree, unassigning freeing a name, a subtree carrying its names into whatever tree takes it, and the order a move has to happen in). Checked separately against the recursion it replaces over 4 000 generated tree shapes, and the index against a fresh walk after each step of 300 assign and unassign sequences. ruff format, ruff check --select I, ruff check and mypy pylabrobot --check-untyped-defs are clean; the full suite passes (2 450 passed, 2 skipped, 206 subtests).

[rickwierenga]

let's remove the stuff from the Deck class in this case

[rickwierenga]

imo _name_index should be called _subtree_names and _subtree_names should be named _get_subtree_names or something

[rickwierenga]

it would be clean to use the will/did assign child resource

• will: check name as it currently does
• did: update cache (so no _names_in_tree cache checking needed)

[BioCam]

let's remove the stuff from the Deck class in this case

@rickwierenga - Done.
_resources, _register_resource, _deregister_resource, get_resource, has_resource and the _check_naming_conflicts override are all removed, so Deck no longer keeps its own copy of the tree.

get_all_resources is public and has callers, so I kept it and only changed the body:
it was reading the private dict, and now delegates to get_all_children(). Happy to deprecate it separately if you would rather it went too.

One behaviour change I think is worth flagging:
the old override compared only resource.name, so assigning a carrier that already held a resource named like one on the deck was accepted, and put a duplicate name in the tree.
The Resource version checks the whole arriving subtree, so that case now raises.

That behaviour is what prompted me to generate #1228 .
A name is meant to be an identifier: unique across the tree, and fixed for the life of the resource.
Neither was true.
It could be duplicated on assignment, as above, and it could still be reassigned after the resource existed, which left anything already named after it out of step.
#1228 makes name immutable after instantiation; this check closes the other half.

[BioCam]

I have made a couple of changes to build a stronger root-based index ledger that fixes a naming bug and improves the performance (needed for scaling of the PLR resource model, including the upcoming change of Tip to be a resource).
So here is a (hopefully more) concise summary:

What main does today

The naming check runs on self.get_root(), so which implementation you get depends on what the root is -> i.e is inconsistent.
Deck overrides it with a single dict lookup, docstringed "overwrite for speed". Everything else uses Resource's recursive version, whose cost grows with the tree.

So main is fast in one shape: a Deck on the path, asked about itself.
That is the liquid handler shape we are removing in v1, and it is the shape Deck was built for.
Outside it, the fast path was never available.

The bug that inconsistency causes

Deck's version compares only the arriving resource's own name, so a clash buried inside what is arriving is never looked at:

deck=STARLetDeck()
car_1=TIP_CAR_480_A00(name="car_1")
car_1[0] =hamilton_96_tiprack_1000uL_filter(name="tips_01")
deck.assign_child_resource(car_1, rails=1)
car_2=TIP_CAR_480_A00(name="car_2")
car_2[0] =hamilton_96_tiprack_1000uL_filter(name="tips_01") # same namedeck.assign_child_resource(car_2, rails=10) # accepted on main

Two resources called tips_01 in one tree, and the consequences are silent:

• deck.get_resource("tips_01") returns the one on car_2. The rack on car_1 is unreachable by name at all.
• serialize_all_state() produces 97 keys for the 194 resources across the two racks, so one rack's state overwrites the other's.

The equivalent tree under a non-Deck root is refused, because Resource's version checks the whole arriving subtree.
This PR refuses it everywhere.

What this PR changes

Deck stops being a privileged resource. Its ledger and its check become properties of whatever is currently the root.
assign_child_resource merges an arriving subtree into the new root and clears the child's.
unassign_child_resource pops the departing names off and hands them back, so a detached subtree heads a tree of its own again.
Everything that is not a root holds None.

A lookup is then two steps: hash the name in the root's ledger, then walk up the parent pointers to check the hit is inside the subtree that was asked.
Both are bounded by depth rather than size, so a resource still finds only what is at or beneath it, at the same cost wherever it is asked from.
And because the first step knows the name exists before the second rejects it, asking the wrong resource now says where it actually is.

Performance

The naming check is quadratic in the size of whatever you are building, because every child assigned re-walks everything already there.
That is invisible at 96 wells and not at 1536.
Building one DeepWell_Greiner_1536_Well from the standard library:

	main	this PR
_check_naming_conflicts calls	1,180,416	1,536
time per plate	~150 ms	~13 ms
96-well plate, for comparison	1.48 ms	1.20 ms

1,180,416 is exactly 1536 * 1537 / 2. The timings vary about 20% run to run, the call count does not.

A plate builds its own wells before it has ever met a deck, so the Deck ledger never covered the part that costs.

Where a Deck does apply, main is fine and in one case faster:

tree	operation	main	this PR
Deck at the root, 2,612 resources	ask the deck	0.09 us	0.23 us
Deck at the root, 2,612 resources	ask a carrier	29.64 us	0.23 us
facility, a Deck per device, 98,221	build it	1.01 s	0.83 s

Build that same facility with no decks in it and main takes 499 s against 0.50 s here.

The ledger costs one map: 3.84 MB for 98,221 resources, about 3% of the tree, holding references to resources that already exist.

Why now

This matters for v1 because there is no liquid handler concept any more.
A workcell or facility don't need to contain a deck at all, so "there is a Deck at the root" is no longer a safe assumption to hang the resource model's performance on.
Tip becoming a resource pushes the same way: it roughly doubles every tip rack, from 97 resources to 193, and tip racks are built standalone, which is exactly where the fast path never applied.

[BioCam]

I'm a very visual person, so here a visual aid to root updating subtree ledger dict across resource tree mergers and separation:

FacilityAssignmentScene.mp4

[BioCam]

lookup before and after - from different levels:

GetResourceScene.mp4

[rickwierenga]

ship it

[rickwierenga]

please

[BioCam]

Problem

_check_naming_conflicts enforces tree-wide name uniqueness by recursing over the whole tree, and assign_child_resource calls it on get_root() for every resource assigned. An assignment costs the size of everything already in the tree rather than the size of what is arriving, so building n resources costs n² - measured between n^1.9 and n^2.0 - and every later assignment still walks all of it.

A loaded STARlet deck is around 2 000 resources. One plate move on it, an unassign and a re-assign, already costs 47 ms. Put several instruments in one tree and the cost grows with all of them, not with the plate:

resources	instruments	before	after
2 001	1	47.0 ms	0.0 ms
4 002	2	93.1 ms	0.0 ms
8 004	4	186.7 ms	0.0 ms
16 008	8	379.3 ms	0.0 ms

Changes

• Resource._name_index holds the names in a tree, kept only by the root, built the first time _names_in_tree asks for it.
• _subtree_names returns the names at or beneath a resource; assign_child_resource unions the arriving ones in, unassign_child_resource subtracts them.
• _check_naming_conflicts walks the arriving subtree against that set instead of recursing over both trees. It reads the index off get_root(), where it was already called from, so it still covers the whole tree.

Behaviour: unchanged, and an assignment now costs the size of what is arriving. Carrying the index forward is safe because a name cannot change while a resource is assigned - the setter refuses - and a tree only changes shape in the two methods that maintain it.

Scope: cheaper, not narrower. The check still runs before the branch that detaches an already-attached resource, so a move within one tree is still refused and callers still unassign first. Excluding the arriving resource's own names would fix that, and is a follow-up since it changes behaviour the tests pin.

Tests

TestNameIndex (a duplicate name, one buried in the arriving subtree, unassigning freeing a name, a subtree carrying its names into whatever tree takes it, and the order a move has to happen in). Checked separately against the recursion it replaces over 4 000 generated tree shapes, and the index against a fresh walk after each step of 300 assign and unassign sequences. ruff format, ruff check --select I, ruff check and mypy pylabrobot --check-untyped-defs are clean; the full suite passes (2 450 passed, 2 skipped, 206 subtests).

[rickwierenga]

let's remove the stuff from the Deck class in this case

[rickwierenga]

imo _name_index should be called _subtree_names and _subtree_names should be named _get_subtree_names or something

[rickwierenga]

it would be clean to use the will/did assign child resource

• will: check name as it currently does
• did: update cache (so no _names_in_tree cache checking needed)

[BioCam]

let's remove the stuff from the Deck class in this case

@rickwierenga - Done.
_resources, _register_resource, _deregister_resource, get_resource, has_resource and the _check_naming_conflicts override are all removed, so Deck no longer keeps its own copy of the tree.

get_all_resources is public and has callers, so I kept it and only changed the body:
it was reading the private dict, and now delegates to get_all_children(). Happy to deprecate it separately if you would rather it went too.

One behaviour change I think is worth flagging:
the old override compared only resource.name, so assigning a carrier that already held a resource named like one on the deck was accepted, and put a duplicate name in the tree.
The Resource version checks the whole arriving subtree, so that case now raises.

That behaviour is what prompted me to generate #1228 .
A name is meant to be an identifier: unique across the tree, and fixed for the life of the resource.
Neither was true.
It could be duplicated on assignment, as above, and it could still be reassigned after the resource existed, which left anything already named after it out of step.
#1228 makes name immutable after instantiation; this check closes the other half.

[BioCam]

I have made a couple of changes to build a stronger root-based index ledger that fixes a naming bug and improves the performance (needed for scaling of the PLR resource model, including the upcoming change of Tip to be a resource).
So here is a (hopefully more) concise summary:

What main does today

The naming check runs on self.get_root(), so which implementation you get depends on what the root is -> i.e is inconsistent.
Deck overrides it with a single dict lookup, docstringed "overwrite for speed". Everything else uses Resource's recursive version, whose cost grows with the tree.

So main is fast in one shape: a Deck on the path, asked about itself.
That is the liquid handler shape we are removing in v1, and it is the shape Deck was built for.
Outside it, the fast path was never available.

The bug that inconsistency causes

Deck's version compares only the arriving resource's own name, so a clash buried inside what is arriving is never looked at:

deck=STARLetDeck()
car_1=TIP_CAR_480_A00(name="car_1")
car_1[0] =hamilton_96_tiprack_1000uL_filter(name="tips_01")
deck.assign_child_resource(car_1, rails=1)
car_2=TIP_CAR_480_A00(name="car_2")
car_2[0] =hamilton_96_tiprack_1000uL_filter(name="tips_01") # same namedeck.assign_child_resource(car_2, rails=10) # accepted on main

Two resources called tips_01 in one tree, and the consequences are silent:

• deck.get_resource("tips_01") returns the one on car_2. The rack on car_1 is unreachable by name at all.
• serialize_all_state() produces 97 keys for the 194 resources across the two racks, so one rack's state overwrites the other's.

The equivalent tree under a non-Deck root is refused, because Resource's version checks the whole arriving subtree.
This PR refuses it everywhere.

What this PR changes

Deck stops being a privileged resource. Its ledger and its check become properties of whatever is currently the root.
assign_child_resource merges an arriving subtree into the new root and clears the child's.
unassign_child_resource pops the departing names off and hands them back, so a detached subtree heads a tree of its own again.
Everything that is not a root holds None.

A lookup is then two steps: hash the name in the root's ledger, then walk up the parent pointers to check the hit is inside the subtree that was asked.
Both are bounded by depth rather than size, so a resource still finds only what is at or beneath it, at the same cost wherever it is asked from.
And because the first step knows the name exists before the second rejects it, asking the wrong resource now says where it actually is.

Performance

The naming check is quadratic in the size of whatever you are building, because every child assigned re-walks everything already there.
That is invisible at 96 wells and not at 1536.
Building one DeepWell_Greiner_1536_Well from the standard library:

	main	this PR
_check_naming_conflicts calls	1,180,416	1,536
time per plate	~150 ms	~13 ms
96-well plate, for comparison	1.48 ms	1.20 ms

1,180,416 is exactly 1536 * 1537 / 2. The timings vary about 20% run to run, the call count does not.

A plate builds its own wells before it has ever met a deck, so the Deck ledger never covered the part that costs.

Where a Deck does apply, main is fine and in one case faster:

tree	operation	main	this PR
Deck at the root, 2,612 resources	ask the deck	0.09 us	0.23 us
Deck at the root, 2,612 resources	ask a carrier	29.64 us	0.23 us
facility, a Deck per device, 98,221	build it	1.01 s	0.83 s

Build that same facility with no decks in it and main takes 499 s against 0.50 s here.

The ledger costs one map: 3.84 MB for 98,221 resources, about 3% of the tree, holding references to resources that already exist.

Why now

This matters for v1 because there is no liquid handler concept any more.
A workcell or facility don't need to contain a deck at all, so "there is a Deck at the root" is no longer a safe assumption to hang the resource model's performance on.
Tip becoming a resource pushes the same way: it roughly doubles every tip rack, from 97 resources to 193, and tip racks are built standalone, which is exactly where the fast path never applied.

[BioCam]

I'm a very visual person, so here a visual aid to root updating subtree ledger dict across resource tree mergers and separation:

FacilityAssignmentScene.mp4

[BioCam]

lookup before and after - from different levels:

GetResourceScene.mp4

[rickwierenga]

ship it

[rickwierenga]

please

[BioCam]

Problem

_check_naming_conflicts enforces tree-wide name uniqueness by recursing over the whole tree, and assign_child_resource calls it on get_root() for every resource assigned. An assignment costs the size of everything already in the tree rather than the size of what is arriving, so building n resources costs n² - measured between n^1.9 and n^2.0 - and every later assignment still walks all of it.

A loaded STARlet deck is around 2 000 resources. One plate move on it, an unassign and a re-assign, already costs 47 ms. Put several instruments in one tree and the cost grows with all of them, not with the plate:

resources	instruments	before	after
2 001	1	47.0 ms	0.0 ms
4 002	2	93.1 ms	0.0 ms
8 004	4	186.7 ms	0.0 ms
16 008	8	379.3 ms	0.0 ms

Changes

• Resource._name_index holds the names in a tree, kept only by the root, built the first time _names_in_tree asks for it.
• _subtree_names returns the names at or beneath a resource; assign_child_resource unions the arriving ones in, unassign_child_resource subtracts them.
• _check_naming_conflicts walks the arriving subtree against that set instead of recursing over both trees. It reads the index off get_root(), where it was already called from, so it still covers the whole tree.

Behaviour: unchanged, and an assignment now costs the size of what is arriving. Carrying the index forward is safe because a name cannot change while a resource is assigned - the setter refuses - and a tree only changes shape in the two methods that maintain it.

Scope: cheaper, not narrower. The check still runs before the branch that detaches an already-attached resource, so a move within one tree is still refused and callers still unassign first. Excluding the arriving resource's own names would fix that, and is a follow-up since it changes behaviour the tests pin.

Tests

TestNameIndex (a duplicate name, one buried in the arriving subtree, unassigning freeing a name, a subtree carrying its names into whatever tree takes it, and the order a move has to happen in). Checked separately against the recursion it replaces over 4 000 generated tree shapes, and the index against a fresh walk after each step of 300 assign and unassign sequences. ruff format, ruff check --select I, ruff check and mypy pylabrobot --check-untyped-defs are clean; the full suite passes (2 450 passed, 2 skipped, 206 subtests).

[rickwierenga]

let's remove the stuff from the Deck class in this case

[rickwierenga]

imo _name_index should be called _subtree_names and _subtree_names should be named _get_subtree_names or something

[rickwierenga]

it would be clean to use the will/did assign child resource

• will: check name as it currently does
• did: update cache (so no _names_in_tree cache checking needed)

[BioCam]

let's remove the stuff from the Deck class in this case

@rickwierenga - Done.
_resources, _register_resource, _deregister_resource, get_resource, has_resource and the _check_naming_conflicts override are all removed, so Deck no longer keeps its own copy of the tree.

get_all_resources is public and has callers, so I kept it and only changed the body:
it was reading the private dict, and now delegates to get_all_children(). Happy to deprecate it separately if you would rather it went too.

One behaviour change I think is worth flagging:
the old override compared only resource.name, so assigning a carrier that already held a resource named like one on the deck was accepted, and put a duplicate name in the tree.
The Resource version checks the whole arriving subtree, so that case now raises.

That behaviour is what prompted me to generate #1228 .
A name is meant to be an identifier: unique across the tree, and fixed for the life of the resource.
Neither was true.
It could be duplicated on assignment, as above, and it could still be reassigned after the resource existed, which left anything already named after it out of step.
#1228 makes name immutable after instantiation; this check closes the other half.

[BioCam]

I have made a couple of changes to build a stronger root-based index ledger that fixes a naming bug and improves the performance (needed for scaling of the PLR resource model, including the upcoming change of Tip to be a resource).
So here is a (hopefully more) concise summary:

What main does today

The naming check runs on self.get_root(), so which implementation you get depends on what the root is -> i.e is inconsistent.
Deck overrides it with a single dict lookup, docstringed "overwrite for speed". Everything else uses Resource's recursive version, whose cost grows with the tree.

So main is fast in one shape: a Deck on the path, asked about itself.
That is the liquid handler shape we are removing in v1, and it is the shape Deck was built for.
Outside it, the fast path was never available.

The bug that inconsistency causes

Deck's version compares only the arriving resource's own name, so a clash buried inside what is arriving is never looked at:

deck=STARLetDeck()
car_1=TIP_CAR_480_A00(name="car_1")
car_1[0] =hamilton_96_tiprack_1000uL_filter(name="tips_01")
deck.assign_child_resource(car_1, rails=1)
car_2=TIP_CAR_480_A00(name="car_2")
car_2[0] =hamilton_96_tiprack_1000uL_filter(name="tips_01") # same namedeck.assign_child_resource(car_2, rails=10) # accepted on main

Two resources called tips_01 in one tree, and the consequences are silent:

• deck.get_resource("tips_01") returns the one on car_2. The rack on car_1 is unreachable by name at all.
• serialize_all_state() produces 97 keys for the 194 resources across the two racks, so one rack's state overwrites the other's.

The equivalent tree under a non-Deck root is refused, because Resource's version checks the whole arriving subtree.
This PR refuses it everywhere.

What this PR changes

Deck stops being a privileged resource. Its ledger and its check become properties of whatever is currently the root.
assign_child_resource merges an arriving subtree into the new root and clears the child's.
unassign_child_resource pops the departing names off and hands them back, so a detached subtree heads a tree of its own again.
Everything that is not a root holds None.

A lookup is then two steps: hash the name in the root's ledger, then walk up the parent pointers to check the hit is inside the subtree that was asked.
Both are bounded by depth rather than size, so a resource still finds only what is at or beneath it, at the same cost wherever it is asked from.
And because the first step knows the name exists before the second rejects it, asking the wrong resource now says where it actually is.

Performance

The naming check is quadratic in the size of whatever you are building, because every child assigned re-walks everything already there.
That is invisible at 96 wells and not at 1536.
Building one DeepWell_Greiner_1536_Well from the standard library:

	main	this PR
_check_naming_conflicts calls	1,180,416	1,536
time per plate	~150 ms	~13 ms
96-well plate, for comparison	1.48 ms	1.20 ms

1,180,416 is exactly 1536 * 1537 / 2. The timings vary about 20% run to run, the call count does not.

A plate builds its own wells before it has ever met a deck, so the Deck ledger never covered the part that costs.

Where a Deck does apply, main is fine and in one case faster:

tree	operation	main	this PR
Deck at the root, 2,612 resources	ask the deck	0.09 us	0.23 us
Deck at the root, 2,612 resources	ask a carrier	29.64 us	0.23 us
facility, a Deck per device, 98,221	build it	1.01 s	0.83 s

Build that same facility with no decks in it and main takes 499 s against 0.50 s here.

The ledger costs one map: 3.84 MB for 98,221 resources, about 3% of the tree, holding references to resources that already exist.

Why now

This matters for v1 because there is no liquid handler concept any more.
A workcell or facility don't need to contain a deck at all, so "there is a Deck at the root" is no longer a safe assumption to hang the resource model's performance on.
Tip becoming a resource pushes the same way: it roughly doubles every tip rack, from 97 resources to 193, and tip racks are built standalone, which is exactly where the fast path never applied.

[BioCam]

I'm a very visual person, so here a visual aid to root updating subtree ledger dict across resource tree mergers and separation:

FacilityAssignmentScene.mp4

[BioCam]

lookup before and after - from different levels:

GetResourceScene.mp4

[rickwierenga]

ship it

[rickwierenga]

please

[BioCam]

Problem

_check_naming_conflicts enforces tree-wide name uniqueness by recursing over the whole tree, and assign_child_resource calls it on get_root() for every resource assigned. An assignment costs the size of everything already in the tree rather than the size of what is arriving, so building n resources costs n² - measured between n^1.9 and n^2.0 - and every later assignment still walks all of it.

A loaded STARlet deck is around 2 000 resources. One plate move on it, an unassign and a re-assign, already costs 47 ms. Put several instruments in one tree and the cost grows with all of them, not with the plate:

resources	instruments	before	after
2 001	1	47.0 ms	0.0 ms
4 002	2	93.1 ms	0.0 ms
8 004	4	186.7 ms	0.0 ms
16 008	8	379.3 ms	0.0 ms

Changes

• Resource._name_index holds the names in a tree, kept only by the root, built the first time _names_in_tree asks for it.
• _subtree_names returns the names at or beneath a resource; assign_child_resource unions the arriving ones in, unassign_child_resource subtracts them.
• _check_naming_conflicts walks the arriving subtree against that set instead of recursing over both trees. It reads the index off get_root(), where it was already called from, so it still covers the whole tree.

Behaviour: unchanged, and an assignment now costs the size of what is arriving. Carrying the index forward is safe because a name cannot change while a resource is assigned - the setter refuses - and a tree only changes shape in the two methods that maintain it.

Scope: cheaper, not narrower. The check still runs before the branch that detaches an already-attached resource, so a move within one tree is still refused and callers still unassign first. Excluding the arriving resource's own names would fix that, and is a follow-up since it changes behaviour the tests pin.

Tests

TestNameIndex (a duplicate name, one buried in the arriving subtree, unassigning freeing a name, a subtree carrying its names into whatever tree takes it, and the order a move has to happen in). Checked separately against the recursion it replaces over 4 000 generated tree shapes, and the index against a fresh walk after each step of 300 assign and unassign sequences. ruff format, ruff check --select I, ruff check and mypy pylabrobot --check-untyped-defs are clean; the full suite passes (2 450 passed, 2 skipped, 206 subtests).

[rickwierenga]

let's remove the stuff from the Deck class in this case

[rickwierenga]

imo _name_index should be called _subtree_names and _subtree_names should be named _get_subtree_names or something

[rickwierenga]

it would be clean to use the will/did assign child resource

• will: check name as it currently does
• did: update cache (so no _names_in_tree cache checking needed)

[BioCam]

let's remove the stuff from the Deck class in this case

@rickwierenga - Done.
_resources, _register_resource, _deregister_resource, get_resource, has_resource and the _check_naming_conflicts override are all removed, so Deck no longer keeps its own copy of the tree.

get_all_resources is public and has callers, so I kept it and only changed the body:
it was reading the private dict, and now delegates to get_all_children(). Happy to deprecate it separately if you would rather it went too.

One behaviour change I think is worth flagging:
the old override compared only resource.name, so assigning a carrier that already held a resource named like one on the deck was accepted, and put a duplicate name in the tree.
The Resource version checks the whole arriving subtree, so that case now raises.

That behaviour is what prompted me to generate #1228 .
A name is meant to be an identifier: unique across the tree, and fixed for the life of the resource.
Neither was true.
It could be duplicated on assignment, as above, and it could still be reassigned after the resource existed, which left anything already named after it out of step.
#1228 makes name immutable after instantiation; this check closes the other half.

[BioCam]

I have made a couple of changes to build a stronger root-based index ledger that fixes a naming bug and improves the performance (needed for scaling of the PLR resource model, including the upcoming change of Tip to be a resource).
So here is a (hopefully more) concise summary:

What main does today

The naming check runs on self.get_root(), so which implementation you get depends on what the root is -> i.e is inconsistent.
Deck overrides it with a single dict lookup, docstringed "overwrite for speed". Everything else uses Resource's recursive version, whose cost grows with the tree.

So main is fast in one shape: a Deck on the path, asked about itself.
That is the liquid handler shape we are removing in v1, and it is the shape Deck was built for.
Outside it, the fast path was never available.

The bug that inconsistency causes

Deck's version compares only the arriving resource's own name, so a clash buried inside what is arriving is never looked at:

deck=STARLetDeck()
car_1=TIP_CAR_480_A00(name="car_1")
car_1[0] =hamilton_96_tiprack_1000uL_filter(name="tips_01")
deck.assign_child_resource(car_1, rails=1)
car_2=TIP_CAR_480_A00(name="car_2")
car_2[0] =hamilton_96_tiprack_1000uL_filter(name="tips_01") # same namedeck.assign_child_resource(car_2, rails=10) # accepted on main

Two resources called tips_01 in one tree, and the consequences are silent:

• deck.get_resource("tips_01") returns the one on car_2. The rack on car_1 is unreachable by name at all.
• serialize_all_state() produces 97 keys for the 194 resources across the two racks, so one rack's state overwrites the other's.

The equivalent tree under a non-Deck root is refused, because Resource's version checks the whole arriving subtree.
This PR refuses it everywhere.

What this PR changes

Deck stops being a privileged resource. Its ledger and its check become properties of whatever is currently the root.
assign_child_resource merges an arriving subtree into the new root and clears the child's.
unassign_child_resource pops the departing names off and hands them back, so a detached subtree heads a tree of its own again.
Everything that is not a root holds None.

A lookup is then two steps: hash the name in the root's ledger, then walk up the parent pointers to check the hit is inside the subtree that was asked.
Both are bounded by depth rather than size, so a resource still finds only what is at or beneath it, at the same cost wherever it is asked from.
And because the first step knows the name exists before the second rejects it, asking the wrong resource now says where it actually is.

Performance

The naming check is quadratic in the size of whatever you are building, because every child assigned re-walks everything already there.
That is invisible at 96 wells and not at 1536.
Building one DeepWell_Greiner_1536_Well from the standard library:

	main	this PR
_check_naming_conflicts calls	1,180,416	1,536
time per plate	~150 ms	~13 ms
96-well plate, for comparison	1.48 ms	1.20 ms

1,180,416 is exactly 1536 * 1537 / 2. The timings vary about 20% run to run, the call count does not.

A plate builds its own wells before it has ever met a deck, so the Deck ledger never covered the part that costs.

Where a Deck does apply, main is fine and in one case faster:

tree	operation	main	this PR
Deck at the root, 2,612 resources	ask the deck	0.09 us	0.23 us
Deck at the root, 2,612 resources	ask a carrier	29.64 us	0.23 us
facility, a Deck per device, 98,221	build it	1.01 s	0.83 s

Build that same facility with no decks in it and main takes 499 s against 0.50 s here.

The ledger costs one map: 3.84 MB for 98,221 resources, about 3% of the tree, holding references to resources that already exist.

Why now

This matters for v1 because there is no liquid handler concept any more.
A workcell or facility don't need to contain a deck at all, so "there is a Deck at the root" is no longer a safe assumption to hang the resource model's performance on.
Tip becoming a resource pushes the same way: it roughly doubles every tip rack, from 97 resources to 193, and tip racks are built standalone, which is exactly where the fast path never applied.

[BioCam]

I'm a very visual person, so here a visual aid to root updating subtree ledger dict across resource tree mergers and separation:

FacilityAssignmentScene.mp4

[BioCam]

lookup before and after - from different levels:

GetResourceScene.mp4

[rickwierenga]

ship it

[rickwierenga]

please

[BioCam]

Problem

_check_naming_conflicts enforces tree-wide name uniqueness by recursing over the whole tree, and assign_child_resource calls it on get_root() for every resource assigned. An assignment costs the size of everything already in the tree rather than the size of what is arriving, so building n resources costs n² - measured between n^1.9 and n^2.0 - and every later assignment still walks all of it.

A loaded STARlet deck is around 2 000 resources. One plate move on it, an unassign and a re-assign, already costs 47 ms. Put several instruments in one tree and the cost grows with all of them, not with the plate:

resources	instruments	before	after
2 001	1	47.0 ms	0.0 ms
4 002	2	93.1 ms	0.0 ms
8 004	4	186.7 ms	0.0 ms
16 008	8	379.3 ms	0.0 ms

Changes

• Resource._name_index holds the names in a tree, kept only by the root, built the first time _names_in_tree asks for it.
• _subtree_names returns the names at or beneath a resource; assign_child_resource unions the arriving ones in, unassign_child_resource subtracts them.
• _check_naming_conflicts walks the arriving subtree against that set instead of recursing over both trees. It reads the index off get_root(), where it was already called from, so it still covers the whole tree.

Behaviour: unchanged, and an assignment now costs the size of what is arriving. Carrying the index forward is safe because a name cannot change while a resource is assigned - the setter refuses - and a tree only changes shape in the two methods that maintain it.

Scope: cheaper, not narrower. The check still runs before the branch that detaches an already-attached resource, so a move within one tree is still refused and callers still unassign first. Excluding the arriving resource's own names would fix that, and is a follow-up since it changes behaviour the tests pin.

Tests

TestNameIndex (a duplicate name, one buried in the arriving subtree, unassigning freeing a name, a subtree carrying its names into whatever tree takes it, and the order a move has to happen in). Checked separately against the recursion it replaces over 4 000 generated tree shapes, and the index against a fresh walk after each step of 300 assign and unassign sequences. ruff format, ruff check --select I, ruff check and mypy pylabrobot --check-untyped-defs are clean; the full suite passes (2 450 passed, 2 skipped, 206 subtests).

[rickwierenga]

let's remove the stuff from the Deck class in this case

[rickwierenga]

imo _name_index should be called _subtree_names and _subtree_names should be named _get_subtree_names or something

[rickwierenga]

it would be clean to use the will/did assign child resource

• will: check name as it currently does
• did: update cache (so no _names_in_tree cache checking needed)

[BioCam]

let's remove the stuff from the Deck class in this case

@rickwierenga - Done.
_resources, _register_resource, _deregister_resource, get_resource, has_resource and the _check_naming_conflicts override are all removed, so Deck no longer keeps its own copy of the tree.

get_all_resources is public and has callers, so I kept it and only changed the body:
it was reading the private dict, and now delegates to get_all_children(). Happy to deprecate it separately if you would rather it went too.

One behaviour change I think is worth flagging:
the old override compared only resource.name, so assigning a carrier that already held a resource named like one on the deck was accepted, and put a duplicate name in the tree.
The Resource version checks the whole arriving subtree, so that case now raises.

That behaviour is what prompted me to generate #1228 .
A name is meant to be an identifier: unique across the tree, and fixed for the life of the resource.
Neither was true.
It could be duplicated on assignment, as above, and it could still be reassigned after the resource existed, which left anything already named after it out of step.
#1228 makes name immutable after instantiation; this check closes the other half.

[BioCam]

I have made a couple of changes to build a stronger root-based index ledger that fixes a naming bug and improves the performance (needed for scaling of the PLR resource model, including the upcoming change of Tip to be a resource).
So here is a (hopefully more) concise summary:

What main does today

The naming check runs on self.get_root(), so which implementation you get depends on what the root is -> i.e is inconsistent.
Deck overrides it with a single dict lookup, docstringed "overwrite for speed". Everything else uses Resource's recursive version, whose cost grows with the tree.

So main is fast in one shape: a Deck on the path, asked about itself.
That is the liquid handler shape we are removing in v1, and it is the shape Deck was built for.
Outside it, the fast path was never available.

The bug that inconsistency causes

Deck's version compares only the arriving resource's own name, so a clash buried inside what is arriving is never looked at:

deck=STARLetDeck()
car_1=TIP_CAR_480_A00(name="car_1")
car_1[0] =hamilton_96_tiprack_1000uL_filter(name="tips_01")
deck.assign_child_resource(car_1, rails=1)
car_2=TIP_CAR_480_A00(name="car_2")
car_2[0] =hamilton_96_tiprack_1000uL_filter(name="tips_01") # same namedeck.assign_child_resource(car_2, rails=10) # accepted on main

Two resources called tips_01 in one tree, and the consequences are silent:

• deck.get_resource("tips_01") returns the one on car_2. The rack on car_1 is unreachable by name at all.
• serialize_all_state() produces 97 keys for the 194 resources across the two racks, so one rack's state overwrites the other's.

The equivalent tree under a non-Deck root is refused, because Resource's version checks the whole arriving subtree.
This PR refuses it everywhere.

What this PR changes

Deck stops being a privileged resource. Its ledger and its check become properties of whatever is currently the root.
assign_child_resource merges an arriving subtree into the new root and clears the child's.
unassign_child_resource pops the departing names off and hands them back, so a detached subtree heads a tree of its own again.
Everything that is not a root holds None.

A lookup is then two steps: hash the name in the root's ledger, then walk up the parent pointers to check the hit is inside the subtree that was asked.
Both are bounded by depth rather than size, so a resource still finds only what is at or beneath it, at the same cost wherever it is asked from.
And because the first step knows the name exists before the second rejects it, asking the wrong resource now says where it actually is.

Performance

The naming check is quadratic in the size of whatever you are building, because every child assigned re-walks everything already there.
That is invisible at 96 wells and not at 1536.
Building one DeepWell_Greiner_1536_Well from the standard library:

	main	this PR
_check_naming_conflicts calls	1,180,416	1,536
time per plate	~150 ms	~13 ms
96-well plate, for comparison	1.48 ms	1.20 ms

1,180,416 is exactly 1536 * 1537 / 2. The timings vary about 20% run to run, the call count does not.

A plate builds its own wells before it has ever met a deck, so the Deck ledger never covered the part that costs.

Where a Deck does apply, main is fine and in one case faster:

tree	operation	main	this PR
Deck at the root, 2,612 resources	ask the deck	0.09 us	0.23 us
Deck at the root, 2,612 resources	ask a carrier	29.64 us	0.23 us
facility, a Deck per device, 98,221	build it	1.01 s	0.83 s

Build that same facility with no decks in it and main takes 499 s against 0.50 s here.

The ledger costs one map: 3.84 MB for 98,221 resources, about 3% of the tree, holding references to resources that already exist.

Why now

This matters for v1 because there is no liquid handler concept any more.
A workcell or facility don't need to contain a deck at all, so "there is a Deck at the root" is no longer a safe assumption to hang the resource model's performance on.
Tip becoming a resource pushes the same way: it roughly doubles every tip rack, from 97 resources to 193, and tip racks are built standalone, which is exactly where the fast path never applied.

[BioCam]

I'm a very visual person, so here a visual aid to root updating subtree ledger dict across resource tree mergers and separation:

FacilityAssignmentScene.mp4

[BioCam]

lookup before and after - from different levels:

GetResourceScene.mp4

[rickwierenga]

ship it

[rickwierenga]

please

[BioCam]

Problem

_check_naming_conflicts enforces tree-wide name uniqueness by recursing over the whole tree, and assign_child_resource calls it on get_root() for every resource assigned. An assignment costs the size of everything already in the tree rather than the size of what is arriving, so building n resources costs n² - measured between n^1.9 and n^2.0 - and every later assignment still walks all of it.

A loaded STARlet deck is around 2 000 resources. One plate move on it, an unassign and a re-assign, already costs 47 ms. Put several instruments in one tree and the cost grows with all of them, not with the plate:

resources	instruments	before	after
2 001	1	47.0 ms	0.0 ms
4 002	2	93.1 ms	0.0 ms
8 004	4	186.7 ms	0.0 ms
16 008	8	379.3 ms	0.0 ms

Changes

• Resource._name_index holds the names in a tree, kept only by the root, built the first time _names_in_tree asks for it.
• _subtree_names returns the names at or beneath a resource; assign_child_resource unions the arriving ones in, unassign_child_resource subtracts them.
• _check_naming_conflicts walks the arriving subtree against that set instead of recursing over both trees. It reads the index off get_root(), where it was already called from, so it still covers the whole tree.

Behaviour: unchanged, and an assignment now costs the size of what is arriving. Carrying the index forward is safe because a name cannot change while a resource is assigned - the setter refuses - and a tree only changes shape in the two methods that maintain it.

Scope: cheaper, not narrower. The check still runs before the branch that detaches an already-attached resource, so a move within one tree is still refused and callers still unassign first. Excluding the arriving resource's own names would fix that, and is a follow-up since it changes behaviour the tests pin.

Tests

TestNameIndex (a duplicate name, one buried in the arriving subtree, unassigning freeing a name, a subtree carrying its names into whatever tree takes it, and the order a move has to happen in). Checked separately against the recursion it replaces over 4 000 generated tree shapes, and the index against a fresh walk after each step of 300 assign and unassign sequences. ruff format, ruff check --select I, ruff check and mypy pylabrobot --check-untyped-defs are clean; the full suite passes (2 450 passed, 2 skipped, 206 subtests).

[rickwierenga]

let's remove the stuff from the Deck class in this case

[rickwierenga]

imo _name_index should be called _subtree_names and _subtree_names should be named _get_subtree_names or something

[rickwierenga]

it would be clean to use the will/did assign child resource

• will: check name as it currently does
• did: update cache (so no _names_in_tree cache checking needed)

[BioCam]

let's remove the stuff from the Deck class in this case

@rickwierenga - Done.
_resources, _register_resource, _deregister_resource, get_resource, has_resource and the _check_naming_conflicts override are all removed, so Deck no longer keeps its own copy of the tree.

get_all_resources is public and has callers, so I kept it and only changed the body:
it was reading the private dict, and now delegates to get_all_children(). Happy to deprecate it separately if you would rather it went too.

One behaviour change I think is worth flagging:
the old override compared only resource.name, so assigning a carrier that already held a resource named like one on the deck was accepted, and put a duplicate name in the tree.
The Resource version checks the whole arriving subtree, so that case now raises.

That behaviour is what prompted me to generate #1228 .
A name is meant to be an identifier: unique across the tree, and fixed for the life of the resource.
Neither was true.
It could be duplicated on assignment, as above, and it could still be reassigned after the resource existed, which left anything already named after it out of step.
#1228 makes name immutable after instantiation; this check closes the other half.

[BioCam]

I have made a couple of changes to build a stronger root-based index ledger that fixes a naming bug and improves the performance (needed for scaling of the PLR resource model, including the upcoming change of Tip to be a resource).
So here is a (hopefully more) concise summary:

What main does today

The naming check runs on self.get_root(), so which implementation you get depends on what the root is -> i.e is inconsistent.
Deck overrides it with a single dict lookup, docstringed "overwrite for speed". Everything else uses Resource's recursive version, whose cost grows with the tree.

So main is fast in one shape: a Deck on the path, asked about itself.
That is the liquid handler shape we are removing in v1, and it is the shape Deck was built for.
Outside it, the fast path was never available.

The bug that inconsistency causes

Deck's version compares only the arriving resource's own name, so a clash buried inside what is arriving is never looked at:

deck=STARLetDeck()
car_1=TIP_CAR_480_A00(name="car_1")
car_1[0] =hamilton_96_tiprack_1000uL_filter(name="tips_01")
deck.assign_child_resource(car_1, rails=1)
car_2=TIP_CAR_480_A00(name="car_2")
car_2[0] =hamilton_96_tiprack_1000uL_filter(name="tips_01") # same namedeck.assign_child_resource(car_2, rails=10) # accepted on main

Two resources called tips_01 in one tree, and the consequences are silent:

• deck.get_resource("tips_01") returns the one on car_2. The rack on car_1 is unreachable by name at all.
• serialize_all_state() produces 97 keys for the 194 resources across the two racks, so one rack's state overwrites the other's.

The equivalent tree under a non-Deck root is refused, because Resource's version checks the whole arriving subtree.
This PR refuses it everywhere.

What this PR changes

Deck stops being a privileged resource. Its ledger and its check become properties of whatever is currently the root.
assign_child_resource merges an arriving subtree into the new root and clears the child's.
unassign_child_resource pops the departing names off and hands them back, so a detached subtree heads a tree of its own again.
Everything that is not a root holds None.

A lookup is then two steps: hash the name in the root's ledger, then walk up the parent pointers to check the hit is inside the subtree that was asked.
Both are bounded by depth rather than size, so a resource still finds only what is at or beneath it, at the same cost wherever it is asked from.
And because the first step knows the name exists before the second rejects it, asking the wrong resource now says where it actually is.

Performance

The naming check is quadratic in the size of whatever you are building, because every child assigned re-walks everything already there.
That is invisible at 96 wells and not at 1536.
Building one DeepWell_Greiner_1536_Well from the standard library:

	main	this PR
_check_naming_conflicts calls	1,180,416	1,536
time per plate	~150 ms	~13 ms
96-well plate, for comparison	1.48 ms	1.20 ms

1,180,416 is exactly 1536 * 1537 / 2. The timings vary about 20% run to run, the call count does not.

A plate builds its own wells before it has ever met a deck, so the Deck ledger never covered the part that costs.

Where a Deck does apply, main is fine and in one case faster:

tree	operation	main	this PR
Deck at the root, 2,612 resources	ask the deck	0.09 us	0.23 us
Deck at the root, 2,612 resources	ask a carrier	29.64 us	0.23 us
facility, a Deck per device, 98,221	build it	1.01 s	0.83 s

Build that same facility with no decks in it and main takes 499 s against 0.50 s here.

The ledger costs one map: 3.84 MB for 98,221 resources, about 3% of the tree, holding references to resources that already exist.

Why now

This matters for v1 because there is no liquid handler concept any more.
A workcell or facility don't need to contain a deck at all, so "there is a Deck at the root" is no longer a safe assumption to hang the resource model's performance on.
Tip becoming a resource pushes the same way: it roughly doubles every tip rack, from 97 resources to 193, and tip racks are built standalone, which is exactly where the fast path never applied.

[BioCam]

I'm a very visual person, so here a visual aid to root updating subtree ledger dict across resource tree mergers and separation:

FacilityAssignmentScene.mp4

[BioCam]

lookup before and after - from different levels:

GetResourceScene.mp4

[rickwierenga]

ship it

[rickwierenga]

please

[BioCam]

Problem

_check_naming_conflicts enforces tree-wide name uniqueness by recursing over the whole tree, and assign_child_resource calls it on get_root() for every resource assigned. An assignment costs the size of everything already in the tree rather than the size of what is arriving, so building n resources costs n² - measured between n^1.9 and n^2.0 - and every later assignment still walks all of it.

A loaded STARlet deck is around 2 000 resources. One plate move on it, an unassign and a re-assign, already costs 47 ms. Put several instruments in one tree and the cost grows with all of them, not with the plate:

resources	instruments	before	after
2 001	1	47.0 ms	0.0 ms
4 002	2	93.1 ms	0.0 ms
8 004	4	186.7 ms	0.0 ms
16 008	8	379.3 ms	0.0 ms

Changes

• Resource._name_index holds the names in a tree, kept only by the root, built the first time _names_in_tree asks for it.
• _subtree_names returns the names at or beneath a resource; assign_child_resource unions the arriving ones in, unassign_child_resource subtracts them.
• _check_naming_conflicts walks the arriving subtree against that set instead of recursing over both trees. It reads the index off get_root(), where it was already called from, so it still covers the whole tree.

Behaviour: unchanged, and an assignment now costs the size of what is arriving. Carrying the index forward is safe because a name cannot change while a resource is assigned - the setter refuses - and a tree only changes shape in the two methods that maintain it.

Scope: cheaper, not narrower. The check still runs before the branch that detaches an already-attached resource, so a move within one tree is still refused and callers still unassign first. Excluding the arriving resource's own names would fix that, and is a follow-up since it changes behaviour the tests pin.

Tests

TestNameIndex (a duplicate name, one buried in the arriving subtree, unassigning freeing a name, a subtree carrying its names into whatever tree takes it, and the order a move has to happen in). Checked separately against the recursion it replaces over 4 000 generated tree shapes, and the index against a fresh walk after each step of 300 assign and unassign sequences. ruff format, ruff check --select I, ruff check and mypy pylabrobot --check-untyped-defs are clean; the full suite passes (2 450 passed, 2 skipped, 206 subtests).

[rickwierenga]

let's remove the stuff from the Deck class in this case

[rickwierenga]

imo _name_index should be called _subtree_names and _subtree_names should be named _get_subtree_names or something

[rickwierenga]

it would be clean to use the will/did assign child resource

• will: check name as it currently does
• did: update cache (so no _names_in_tree cache checking needed)

[BioCam]

let's remove the stuff from the Deck class in this case

@rickwierenga - Done.
_resources, _register_resource, _deregister_resource, get_resource, has_resource and the _check_naming_conflicts override are all removed, so Deck no longer keeps its own copy of the tree.

get_all_resources is public and has callers, so I kept it and only changed the body:
it was reading the private dict, and now delegates to get_all_children(). Happy to deprecate it separately if you would rather it went too.

One behaviour change I think is worth flagging:
the old override compared only resource.name, so assigning a carrier that already held a resource named like one on the deck was accepted, and put a duplicate name in the tree.
The Resource version checks the whole arriving subtree, so that case now raises.

That behaviour is what prompted me to generate #1228 .
A name is meant to be an identifier: unique across the tree, and fixed for the life of the resource.
Neither was true.
It could be duplicated on assignment, as above, and it could still be reassigned after the resource existed, which left anything already named after it out of step.
#1228 makes name immutable after instantiation; this check closes the other half.

[BioCam]

I have made a couple of changes to build a stronger root-based index ledger that fixes a naming bug and improves the performance (needed for scaling of the PLR resource model, including the upcoming change of Tip to be a resource).
So here is a (hopefully more) concise summary:

What main does today

The naming check runs on self.get_root(), so which implementation you get depends on what the root is -> i.e is inconsistent.
Deck overrides it with a single dict lookup, docstringed "overwrite for speed". Everything else uses Resource's recursive version, whose cost grows with the tree.

So main is fast in one shape: a Deck on the path, asked about itself.
That is the liquid handler shape we are removing in v1, and it is the shape Deck was built for.
Outside it, the fast path was never available.

The bug that inconsistency causes

Deck's version compares only the arriving resource's own name, so a clash buried inside what is arriving is never looked at:

deck=STARLetDeck()
car_1=TIP_CAR_480_A00(name="car_1")
car_1[0] =hamilton_96_tiprack_1000uL_filter(name="tips_01")
deck.assign_child_resource(car_1, rails=1)
car_2=TIP_CAR_480_A00(name="car_2")
car_2[0] =hamilton_96_tiprack_1000uL_filter(name="tips_01") # same namedeck.assign_child_resource(car_2, rails=10) # accepted on main

Two resources called tips_01 in one tree, and the consequences are silent:

• deck.get_resource("tips_01") returns the one on car_2. The rack on car_1 is unreachable by name at all.
• serialize_all_state() produces 97 keys for the 194 resources across the two racks, so one rack's state overwrites the other's.

The equivalent tree under a non-Deck root is refused, because Resource's version checks the whole arriving subtree.
This PR refuses it everywhere.

What this PR changes

Deck stops being a privileged resource. Its ledger and its check become properties of whatever is currently the root.
assign_child_resource merges an arriving subtree into the new root and clears the child's.
unassign_child_resource pops the departing names off and hands them back, so a detached subtree heads a tree of its own again.
Everything that is not a root holds None.

A lookup is then two steps: hash the name in the root's ledger, then walk up the parent pointers to check the hit is inside the subtree that was asked.
Both are bounded by depth rather than size, so a resource still finds only what is at or beneath it, at the same cost wherever it is asked from.
And because the first step knows the name exists before the second rejects it, asking the wrong resource now says where it actually is.

Performance

The naming check is quadratic in the size of whatever you are building, because every child assigned re-walks everything already there.
That is invisible at 96 wells and not at 1536.
Building one DeepWell_Greiner_1536_Well from the standard library:

	main	this PR
_check_naming_conflicts calls	1,180,416	1,536
time per plate	~150 ms	~13 ms
96-well plate, for comparison	1.48 ms	1.20 ms

1,180,416 is exactly 1536 * 1537 / 2. The timings vary about 20% run to run, the call count does not.

A plate builds its own wells before it has ever met a deck, so the Deck ledger never covered the part that costs.

Where a Deck does apply, main is fine and in one case faster:

tree	operation	main	this PR
Deck at the root, 2,612 resources	ask the deck	0.09 us	0.23 us
Deck at the root, 2,612 resources	ask a carrier	29.64 us	0.23 us
facility, a Deck per device, 98,221	build it	1.01 s	0.83 s

Build that same facility with no decks in it and main takes 499 s against 0.50 s here.

The ledger costs one map: 3.84 MB for 98,221 resources, about 3% of the tree, holding references to resources that already exist.

Why now

This matters for v1 because there is no liquid handler concept any more.
A workcell or facility don't need to contain a deck at all, so "there is a Deck at the root" is no longer a safe assumption to hang the resource model's performance on.
Tip becoming a resource pushes the same way: it roughly doubles every tip rack, from 97 resources to 193, and tip racks are built standalone, which is exactly where the fast path never applied.

[BioCam]

I'm a very visual person, so here a visual aid to root updating subtree ledger dict across resource tree mergers and separation:

FacilityAssignmentScene.mp4

[BioCam]

lookup before and after - from different levels:

GetResourceScene.mp4

[rickwierenga]

ship it

[rickwierenga]

please

[BioCam]

Problem

_check_naming_conflicts enforces tree-wide name uniqueness by recursing over the whole tree, and assign_child_resource calls it on get_root() for every resource assigned. An assignment costs the size of everything already in the tree rather than the size of what is arriving, so building n resources costs n² - measured between n^1.9 and n^2.0 - and every later assignment still walks all of it.

A loaded STARlet deck is around 2 000 resources. One plate move on it, an unassign and a re-assign, already costs 47 ms. Put several instruments in one tree and the cost grows with all of them, not with the plate:

resources	instruments	before	after
2 001	1	47.0 ms	0.0 ms
4 002	2	93.1 ms	0.0 ms
8 004	4	186.7 ms	0.0 ms
16 008	8	379.3 ms	0.0 ms

Changes

• Resource._name_index holds the names in a tree, kept only by the root, built the first time _names_in_tree asks for it.
• _subtree_names returns the names at or beneath a resource; assign_child_resource unions the arriving ones in, unassign_child_resource subtracts them.
• _check_naming_conflicts walks the arriving subtree against that set instead of recursing over both trees. It reads the index off get_root(), where it was already called from, so it still covers the whole tree.

Behaviour: unchanged, and an assignment now costs the size of what is arriving. Carrying the index forward is safe because a name cannot change while a resource is assigned - the setter refuses - and a tree only changes shape in the two methods that maintain it.

Scope: cheaper, not narrower. The check still runs before the branch that detaches an already-attached resource, so a move within one tree is still refused and callers still unassign first. Excluding the arriving resource's own names would fix that, and is a follow-up since it changes behaviour the tests pin.

Tests

TestNameIndex (a duplicate name, one buried in the arriving subtree, unassigning freeing a name, a subtree carrying its names into whatever tree takes it, and the order a move has to happen in). Checked separately against the recursion it replaces over 4 000 generated tree shapes, and the index against a fresh walk after each step of 300 assign and unassign sequences. ruff format, ruff check --select I, ruff check and mypy pylabrobot --check-untyped-defs are clean; the full suite passes (2 450 passed, 2 skipped, 206 subtests).

[rickwierenga]

let's remove the stuff from the Deck class in this case

[rickwierenga]

imo _name_index should be called _subtree_names and _subtree_names should be named _get_subtree_names or something

[rickwierenga]

it would be clean to use the will/did assign child resource

• will: check name as it currently does
• did: update cache (so no _names_in_tree cache checking needed)

[BioCam]

let's remove the stuff from the Deck class in this case

@rickwierenga - Done.
_resources, _register_resource, _deregister_resource, get_resource, has_resource and the _check_naming_conflicts override are all removed, so Deck no longer keeps its own copy of the tree.

get_all_resources is public and has callers, so I kept it and only changed the body:
it was reading the private dict, and now delegates to get_all_children(). Happy to deprecate it separately if you would rather it went too.

One behaviour change I think is worth flagging:
the old override compared only resource.name, so assigning a carrier that already held a resource named like one on the deck was accepted, and put a duplicate name in the tree.
The Resource version checks the whole arriving subtree, so that case now raises.

That behaviour is what prompted me to generate #1228 .
A name is meant to be an identifier: unique across the tree, and fixed for the life of the resource.
Neither was true.
It could be duplicated on assignment, as above, and it could still be reassigned after the resource existed, which left anything already named after it out of step.
#1228 makes name immutable after instantiation; this check closes the other half.

[BioCam]

I have made a couple of changes to build a stronger root-based index ledger that fixes a naming bug and improves the performance (needed for scaling of the PLR resource model, including the upcoming change of Tip to be a resource).
So here is a (hopefully more) concise summary:

What main does today

The naming check runs on self.get_root(), so which implementation you get depends on what the root is -> i.e is inconsistent.
Deck overrides it with a single dict lookup, docstringed "overwrite for speed". Everything else uses Resource's recursive version, whose cost grows with the tree.

So main is fast in one shape: a Deck on the path, asked about itself.
That is the liquid handler shape we are removing in v1, and it is the shape Deck was built for.
Outside it, the fast path was never available.

The bug that inconsistency causes

Deck's version compares only the arriving resource's own name, so a clash buried inside what is arriving is never looked at:

deck=STARLetDeck()
car_1=TIP_CAR_480_A00(name="car_1")
car_1[0] =hamilton_96_tiprack_1000uL_filter(name="tips_01")
deck.assign_child_resource(car_1, rails=1)
car_2=TIP_CAR_480_A00(name="car_2")
car_2[0] =hamilton_96_tiprack_1000uL_filter(name="tips_01") # same namedeck.assign_child_resource(car_2, rails=10) # accepted on main

Two resources called tips_01 in one tree, and the consequences are silent:

• deck.get_resource("tips_01") returns the one on car_2. The rack on car_1 is unreachable by name at all.
• serialize_all_state() produces 97 keys for the 194 resources across the two racks, so one rack's state overwrites the other's.

The equivalent tree under a non-Deck root is refused, because Resource's version checks the whole arriving subtree.
This PR refuses it everywhere.

What this PR changes

Deck stops being a privileged resource. Its ledger and its check become properties of whatever is currently the root.
assign_child_resource merges an arriving subtree into the new root and clears the child's.
unassign_child_resource pops the departing names off and hands them back, so a detached subtree heads a tree of its own again.
Everything that is not a root holds None.

A lookup is then two steps: hash the name in the root's ledger, then walk up the parent pointers to check the hit is inside the subtree that was asked.
Both are bounded by depth rather than size, so a resource still finds only what is at or beneath it, at the same cost wherever it is asked from.
And because the first step knows the name exists before the second rejects it, asking the wrong resource now says where it actually is.

Performance

The naming check is quadratic in the size of whatever you are building, because every child assigned re-walks everything already there.
That is invisible at 96 wells and not at 1536.
Building one DeepWell_Greiner_1536_Well from the standard library:

	main	this PR
_check_naming_conflicts calls	1,180,416	1,536
time per plate	~150 ms	~13 ms
96-well plate, for comparison	1.48 ms	1.20 ms

1,180,416 is exactly 1536 * 1537 / 2. The timings vary about 20% run to run, the call count does not.

A plate builds its own wells before it has ever met a deck, so the Deck ledger never covered the part that costs.

Where a Deck does apply, main is fine and in one case faster:

tree	operation	main	this PR
Deck at the root, 2,612 resources	ask the deck	0.09 us	0.23 us
Deck at the root, 2,612 resources	ask a carrier	29.64 us	0.23 us
facility, a Deck per device, 98,221	build it	1.01 s	0.83 s

Build that same facility with no decks in it and main takes 499 s against 0.50 s here.

The ledger costs one map: 3.84 MB for 98,221 resources, about 3% of the tree, holding references to resources that already exist.

Why now

This matters for v1 because there is no liquid handler concept any more.
A workcell or facility don't need to contain a deck at all, so "there is a Deck at the root" is no longer a safe assumption to hang the resource model's performance on.
Tip becoming a resource pushes the same way: it roughly doubles every tip rack, from 97 resources to 193, and tip racks are built standalone, which is exactly where the fast path never applied.

[BioCam]

I'm a very visual person, so here a visual aid to root updating subtree ledger dict across resource tree mergers and separation:

FacilityAssignmentScene.mp4

[BioCam]

lookup before and after - from different levels:

GetResourceScene.mp4

[rickwierenga]

ship it

[rickwierenga]

please