Lab view

The Lab view is a project-scoped dashboard over the equipment tree that shows every channel in your test equipment and whether it is currently in use. Use it to answer “what is running right now, and when does a channel free up?”.

Channel occupancy

The Lab view derives each channel’s state from the measurements linked to it — there’s no live telemetry. A channel is in one of four states:

State	Meaning
`free`	No linked measurement, or every linked measurement has an `end_time` set. The channel is available for a new test.
`occupied`	A linked measurement has no `end_time` and was updated within the staleness window. A cell is on test now.
`stale`	A linked measurement has no `end_time` but hasn’t been updated within the staleness window. Likely a stopped or silently failed test, or one someone forgot to mark complete.
`out_of_commission`	The channel is deliberately out of service (broken or under maintenance). Overrides the derived state above.

The staleness window is fixed at 48 hours. This is comfortably larger than a typical daily cycler upload cadence, so a channel only flips to stale after it has skipped roughly two expected updates — the real “stopped or forgotten” signal, not a briefly-late update. To free a stale channel, set an end_time on the linked measurement (mark the test complete) or delete the measurement.

Viewing channels as a table

The Lab view can be switched between the default card layout (channels grouped under their cycler) and a table view that renders one row per channel across every cycler in the project. Use the layout toggle at the top of the Lab view to switch modes. The choice is not saved — the view resets to cards on refresh or navigation. Use the table view when you want to:

Scan every channel in the project on a single flat list rather than a per-cycler grid.
Filter or compare channels across cyclers — for example, show all stale channels or compare their electrical ratings.
Copy a channel-by-channel snapshot of what the lab is doing right now.

Each row shows the same information the channel card does — site, cycler, channel name, occupancy state, electrical ratings, the active measurement (if any) and its estimated_end_time, and the out_of_commission flag — so nothing is hidden by switching layouts. Clicking a row opens the same channel page as clicking a card, and the same channel:read permission gates access. The table reads from the same aggregation client.lab.status() exposes, so for the equivalent flat, one-row-per-channel view from Python, flatten the tree yourself:

status = client.lab.status(client.project_id)

for site in status.sites:
    for cycler in site.cyclers:
        for channel in cycler.channels:
            print(site.name, cycler.name, channel.name, channel.state)

Inspecting a channel

Click a channel in the Lab view to open its channel page — a dedicated view of everything that’s on (and has ever been on) that piece of hardware. The page pulls together the same data other parts of Ionworks Studio already show, so you don’t need to jump between measurements to see what a channel is doing. The channel page shows:

The channel’s current state (free, occupied, stale, or out_of_commission) and its electrical ratings.
The active measurement, if any — the cell, protocol, start time, and estimated end time — with a Mark complete action that sets end_time on the measurement and frees the channel.
Recent data for the active measurement, split into two tabs:
- Time series — a trailing window of raw signals (voltage by default; add current, temperature, or any other column via the plot’s own selectors). The x-axis is a calendar-date axis anchored to the measurement’s start_time, so the plot reads in real dates rather than elapsed seconds.
- Cycles — per-cycle summary metrics across the whole measurement.
The history of the 100 most recent measurements that have run on this channel, ordered by start time, with links back to each measurement’s own detail page.

The time-series window is user-controlled — set the number of days (default 7) and click Refresh to re-fetch. Nothing polls on its own, so the plot only changes when you ask for it; the “as of” stamp shows when the plotted snapshot was fetched. Only channels with an occupied or stale active measurement have data to plot — a free or out_of_commission channel shows the state badge and history but no chart. Marking a measurement complete from the channel page is equivalent to patching its end_time — the same operation you can do from the SDK — and moves the channel back to free immediately:

from datetime import datetime, timezone

client.cell_measurement.update(
    measurement_id,
    {"end_time": datetime.now(timezone.utc).isoformat()},
)

Access to the channel page respects the channel:read permission — users without it see the equipment tree in the Lab view but can’t drill into a channel.

Querying occupancy from the SDK

client.lab wraps the same aggregation the Lab view renders from and answers the common “what’s my lab doing right now?” questions from Python. It’s read-only — use client.site, client.cycler, and client.channel to mutate equipment.

Method	Answers
`client.lab.status(project_id)`	The full sites → cyclers → channels tree with each channel’s derived state and on-test measurement, plus project-level occupancy counts.
`client.lab.utilization(project_id)`	Headline busy percent (`occupied` + `stale`, out-of-commission included in the denominator) plus the raw counts. Matches the number on the Lab wall.
`client.lab.free_channels(project_id, *, min_amps, min_volts, max_volts)`	Free channels, optionally filtered by required electrical ratings. Answers “where can I run this cell?”.
`client.lab.stale_channels(project_id)`	Channels whose linked test has gone quiet — likely stopped, silently failed, or forgotten tests tying up equipment.
`client.lab.on_channel(project_id, channel_id)`	The measurement currently on test on a channel, or `None` when it’s free, out of commission, or not in the project.

Only status() hits the network. The other methods are pure client-side views over that payload — each fetches its own snapshot by default, so a single call is always internally consistent.

util = client.lab.utilization(project_id)
print(f"{util.percent}% busy — {util.occupied}/{util.total} channels running")

# 4 A cell needing a 0–5 V window
candidates = client.lab.free_channels(
    project_id,
    min_amps=4.0,
    min_volts=0.0,
    max_volts=5.0,
)
for fc in candidates:
    print(f"{fc.site_name} / {fc.cycler_name} / {fc.channel.name}")

for fc in client.lab.stale_channels(project_id):
    m = fc.channel.measurement
    print(f"Stale: {fc.cycler_name}/{fc.channel.name} — last update {m.updated_at}")

Two separate calls fetch two snapshots and can disagree if equipment changes in between. When you need several views of the same instant — for example utilization alongside the free-channel list — fetch one snapshot and pass it in via the status keyword:

snapshot = client.lab.status(project_id)
util = client.lab.utilization(project_id, status=snapshot)
free = client.lab.free_channels(project_id, status=snapshot)  # same instant

Channels missing a rating are excluded from free_channels when that rating is used as a filter — an unrated channel can’t be shown to satisfy the requirement. Drop the filter to include unrated channels.

Watching a channel

Watch a channel to follow the test that’s currently running on it. Engineers typically watch the handful of channels running their own cells; from the Lab wall you can then flip a Only watched filter to hide everything else and drill straight into the runs you care about. A watch is tied to the specific cell measurement currently on the channel, not to the channel itself — so the moment that measurement finishes (an end_time is set), the watch clears itself automatically. Starting a new test on the same channel does not silently re-enter it into your watchlist; opt in again when a new run begins. Set watches from the channel page or the Lab wall — a Watch toggle appears next to any channel that has a live occupied or stale measurement (a free or out_of_commission channel has nothing to watch). Watches are per-user: each teammate curates their own watchlist without affecting anyone else.

Scheduling invariants

The server enforces a small set of scheduling invariants so the Lab view and your equipment records stay consistent. Requests that violate time-ordering or type rules are rejected with HTTP 400, while channel scheduling conflicts (overlap, out-of-commission) return HTTP 409. Nothing is written and the channel state is unchanged.

Invariant	When it triggers	Status
One active measurement per channel	You try to link a measurement (create or update `channel_id`) to a channel that already has another linked measurement without an `end_time`.	409
No scheduling on `out_of_commission` channels	You try to set `channel_id` on a measurement to a channel whose `out_of_commission` is `true`. Existing links on channels flipped out of service later are preserved.	409
Only `time_series` measurements can reference a channel	A `properties` or `file` measurement (no physical channel occupancy) supplies a `channel_id`.	400
`end_time` must not precede `start_time`	You patch a measurement so its `end_time` falls before its `start_time`. This check predates channel scheduling and applies to every measurement, linked or not.	400

The overlap check counts only measurements without an end_time — a completed test never blocks a new one. To reschedule a busy channel, first close the running measurement (patch its end_time) or move it to a different channel, then link the new measurement.

from datetime import datetime, timezone

# Free the channel before starting the next test on it.
client.cell_measurement.update(
    previous_measurement_id,
    {"end_time": datetime.now(timezone.utc).isoformat()},
)

client.cell_measurement.update(new_measurement_id, {"channel_id": ch01.id})

If you need to bring a channel back into service, clear out_of_commission before assigning a new measurement:

client.channel.update(channel_id, {"out_of_commission": False})
client.cell_measurement.update(measurement_id, {"channel_id": channel_id})

Get Started

Core Concepts

Operate

Data

Build

Pipelines

Simulate

Optimize

Channel occupancy

Viewing channels as a table

Inspecting a channel

Querying occupancy from the SDK

Watching a channel

Scheduling invariants

Next steps

Channel service

Planned measurements

​Channel occupancy

​Viewing channels as a table

​Inspecting a channel

​Querying occupancy from the SDK

​Watching a channel

​Scheduling invariants

​Next steps

Channel service

Planned measurements

Channel occupancy

Viewing channels as a table

Inspecting a channel

Querying occupancy from the SDK

Watching a channel

Scheduling invariants

Next steps