Equipment

Ionworks Studio can track the physical lab equipment your measurements came from — sites, cyclers, and channels — so you can link a cell measurement directly to the channel it ran on. That gives you an end-to-end link from a data point back to the hardware that produced it, and it is what the Lab view renders.

When to use it

Recording equipment is optional — measurements work fine without a channel_id. Set up sites, cyclers, and channels when you want to:

Compare data collected across cyclers or labs.
Isolate a suspect channel when a subset of measurements looks off.
Keep long-term provenance for regulated or published data.
See at a glance which channels are free, in use, or out of service.

If you just have a single cycler and don’t need this level of detail, keep using the free-text test_setup fields on each measurement instead.

Equipment hierarchy

Test equipment mirrors the cell data hierarchy:

Organization
└── Site           (a lab or facility — org-scoped, shared)
    └── Cycler     (a battery cycler — belongs to one project)
        └── Channel  (a single test channel — inherits its cycler's project)
             └── linked to a Cell Measurement via channel_id

Resource	Scope	Description
`site`	Organization	A physical lab or facility. Names are unique within an organization (case-insensitive).
`cycler`	Project	Battery cycling equipment installed at a site. Owned by a single project, set at creation.
`channel`	Project (inherited)	A single test channel on a cycler. Inherits its parent cycler’s project — you never set `project_id` yourself.

Only cell measurements from the same project as the channel can be linked to it. Deleting a site cascades to its cyclers, and deleting a cycler cascades to its channels.

Sites

A site is a lab or facility that owns cyclers. Sites are organization-scoped — a physical lab is shared infrastructure, not tied to a single project.

Field	Description
`name`	Name of the site (required, unique within the org)
`location`	Physical location (e.g. address or lab name)
`notes`	Free-text notes

Cyclers

A cycler is a piece of cycling equipment installed at exactly one site. Cyclers are project-scoped: each cycler is owned by one project, passed at create time. Cycler names are unique within a project (case-insensitive), so two different projects can each have a cycler named "Maccor-1". The owning project is fixed at creation. If the same physical machine is used across two projects, create one cycler row per project.

Field	Description
`name`	Name of the cycler (required, unique within the project)
`project_id`	Project that owns the cycler (required)
`manufacturer`	e.g. `"Arbin"`, `"Maccor"`, `"Biologic"`
`model`	e.g. `"S4000"`
`notes`	Free-text notes

Channels

A channel is a physical channel on a cycler. A channel belongs to exactly one cycler and inherits that cycler’s project. Channel names are unique within a cycler (case-insensitive), so two different cyclers can each have a channel named "CH1".

Field	Description
`name`	Name of the channel (required, unique within the cycler)
`notes`	Free-text notes

Channels also carry optional electrical ratings and an out_of_commission flag — see Channel ratings below.

Building the equipment tree

Create the site, cycler, and channels once per lab. In steady state, you’ll only touch channels — flipping out_of_commission, adjusting ratings, or linking measurements to them.

from ionworks import Ionworks

client = Ionworks(project_id="your-project-id")

# 1. Create (or fetch) the site — org-scoped, shared across projects.
site = client.site.create_or_get({
    "name": "Main lab",
    "location": "Building 3, Room 210",
})

# 2. Create a cycler under the site. project_id is required — the cycler
#    is owned by that project.
cycler = client.cycler.create_or_get(
    site.id,
    {
        "name": "Cycler-01",
        "manufacturer": "Arbin",
        "model": "LBT-5V-6A",
        "project_id": client.project_id,
    },
)

# 3. Create channels on the cycler with optional electrical ratings.
for i in range(1, 9):
    client.channel.create_or_get(
        cycler.id,
        {
            "name": f"Ch-{i:02d}",
            "max_amps": 6.0,
            "min_volts": 0.0,
            "max_volts": 5.0,
        },
    )

Names are unique per org (sites) or per project (cyclers) or per cycler (channels), case-insensitively — but create_or_get only resolves a conflict back to the existing record when the name matches exactly. Calling it again with a differently-cased name that already exists (e.g. "boston lab" when "Boston Lab" exists) raises ValueError instead of returning the existing record. Reuse the exact name you created it with.

Update and delete work the same way for all three resources:

# Update (partial). Passing a new site_id moves a cycler to another site in
# the same organization; the owning project cannot change. Passing a new
# cycler_id reparents a channel — but only to another cycler in the same
# project.
client.cycler.update(cycler.id, {"model": "S4000M"})

# Delete — cascades down the hierarchy (site -> cyclers -> channels).
# Deleting a channel sets channel_id back to NULL on any measurements that
# referenced it; the measurements themselves are not deleted.
client.cycler.delete(cycler.id)

Delete	Effect
Site	Deletes all its cyclers and their channels
Cycler	Deletes all its channels
Channel	Sets `channel_id = NULL` on any measurements that referenced it; the measurements are preserved

Linking a measurement to a channel

Every cell measurement has an optional, nullable channel_id recording the physical channel a test ran on. Set it when creating a measurement or attach it later with an update. The channel must belong to the same project as the measurement (a measurement inherits its project from its cell instance). Pointing at a channel in another project raises an error (HTTP 400). The link is loose on purpose: deleting the channel later sets channel_id back to NULL and leaves the measurement intact.

channels = client.channel.list(cycler.id)
ch01 = next(c for c in channels if c.name == "Ch-01")

bundle = client.cell_measurement.create(
    cell_instance.id,
    {
        "measurement": {
            "name": "Formation Cycle 1",
            "channel_id": ch01.id,
        },
        "time_series": time_series,
    },
)

# Attach or move the channel on an existing measurement
client.cell_measurement.update(bundle.id, {"channel_id": ch01.id})

# Detach without deleting the measurement
client.cell_measurement.update(bundle.id, {"channel_id": None})

While the test is running, leave the measurement’s end_time unset and continue uploading fresh data — the channel reads as occupied. When the test finishes, patch the measurement with an end_time and the channel returns to free.

Showing when a channel will free up

Set estimated_end_time on the measurement to advertise when the running test is expected to finish. The Lab view surfaces it on the channel card while the channel is occupied or stale, so you can plan the next test without opening the measurement.

from datetime import datetime, timedelta, timezone

client.cell_measurement.update(
    measurement_id,
    {
        "estimated_end_time": (
            datetime.now(timezone.utc) + timedelta(hours=18)
        ).isoformat(),
    },
)

estimated_end_time is informational only — it doesn’t change the channel’s occupancy state or the 48-hour staleness window. A partial update only sets the fields you include, so patching just end_time leaves the stored estimate in place — explicitly set estimated_end_time to None in that same update to clear it.

Channel ratings

Channels have optional electrical ratings you can set to describe what the hardware can do. The Lab UI uses them to filter channels when picking one for a new test.

Field	Type	Description
`max_amps`	`float \| null`	Maximum rated current in A. `null` means unrated.
`min_volts`	`float \| null`	Minimum rated voltage in V. `null` means unrated.
`max_volts`	`float \| null`	Maximum rated voltage in V. `null` means unrated.
`out_of_commission`	`bool`	`true` marks the channel out of service. Overrides the derived occupancy state. Defaults to `false`.

Ratings are set via the API or SDK, not the UI.

Filtering, pagination, and resolving by name

Site, cycler, and channel list endpoints share the same filtering shape used across the rest of the API — case-insensitive substring match on name, exact match with name_exact, ISO datetime range filters (created_after / updated_before / …), and order_by / order for sort.

# All cyclers in a site owned by the current project
cyclers = client.cycler.list(site.id, project_id=client.project_id)

# One-page walk of every channel on a cycler
channels = client.channel.list(cycler.id, limit=100)
print(channels.total)

For sites and cyclers, client.site.detail(site_id) and client.cycler.detail(cycler_id) return the resource together with all of its children in a single response, walking pagination for you. Use name_exact for a case-sensitive server-side match — it’s the easiest way to walk from a human-readable site name down to a channel id:

site = client.site.list(name_exact="Boston Lab")[0]
cycler = client.cycler.list(site.id, name_exact="Cycler-01")[0]
channel = client.channel.list(cycler.id, name_exact="Ch-01")[0]

print(site.id, cycler.id, channel.id)

Each list() returns a PaginatedList even when you use name_exact, so handle the empty case if the name may not exist.

Get Started

Core Concepts

Operate

Data

Build

Pipelines

Simulate

Optimize

When to use it

Equipment hierarchy

Sites

Cyclers

Channels

Building the equipment tree

Linking a measurement to a channel

Showing when a channel will free up

Channel ratings

Next steps

Lab view

Channel service

​When to use it

​Equipment hierarchy

​Sites

​Cyclers

​Channels

​Building the equipment tree

​Linking a measurement to a channel

​Showing when a channel will free up

​Channel ratings

​Filtering, pagination, and resolving by name

​Next steps

Lab view

Channel service

When to use it

Equipment hierarchy

Sites

Cyclers

Channels

Building the equipment tree

Linking a measurement to a channel

Showing when a channel will free up

Channel ratings

Filtering, pagination, and resolving by name

Next steps