Cell Instances

A cell instance represents a single physical cell. Every instance belongs to a cell specification, which defines the cell type. Instances carry per-cell metadata such as manufacturing date and measured electrode properties, and can belong to a batch (manufacturing lot).

Batches

A batch is a manufacturing lot: one production run of one specification. It is its own record, so lot-level facts (manufacture date, notes, datasheet properties) live in one place rather than on every cell. Batch names are unique within a specification, compared case-insensitively.

batch = client.cell_batch.create_or_get(
    cell_spec.id,
    {"name": "BATCH-2024-001", "date_manufactured": "2024-01-15"},
)

batches = client.cell_batch.list(cell_spec.id)  # paginated
batch = client.cell_batch.get(batch.id)  # includes instance_count
client.cell_batch.update(batch.id, {"notes": "Passed incoming QC"})
client.cell_batch.delete(batch.id)  # unlinks its cells, keeps them

Creating an instance

Provide the parent specification ID and a metadata dictionary. Pass batch_id to file the cell under a batch of the same specification:

cell_instance = client.cell_instance.create(
    cell_spec.id,
    {
        "name": "NCM622-GR-001",
        "batch_id": batch.id,
        "date_manufactured": "2024-01-20",
        "measured_properties": {
            "cathode": {"loading": {"value": 12.1, "unit": "mg/cm**2"}},
            "anode": {"loading": {"value": 6.4, "unit": "mg/cm**2"}},
        },
    },
)
print(cell_instance.id)

As with specifications, create_or_get() avoids duplicates when re-running scripts:

cell_instance = client.cell_instance.create_or_get(
    cell_spec.id,
    {
        "name": "NCM622-GR-001",
        # ...
    },
)

Listing instances

List all instances that belong to a specification:

instances = client.cell_instance.list(cell_spec.id)
for inst in instances:
    print(inst.name, inst.batch_name)

Narrow to one batch with batch_id:

lot = client.cell_instance.list(cell_spec.id, batch_id=batch.id)

Retrieving an instance

Fetch by ID:

instance = client.cell_instance.get(instance_id)

Full details

detail() composes flat API endpoints in parallel to return the instance together with its measurements (including steps, cycles, and time-series data). Use the include_* flags to skip heavy data you don’t need:

detail = client.cell_instance.detail(instance_id)
# specification_id is a foreign key — fetch the full
# spec if needed:
spec = client.cell_spec.get(detail.specification_id)

# Skip time series for a faster response:
detail = client.cell_instance.detail(instance_id, include_time_series=False)

Listing instances with measurements

Use flat CRUD composition to list instances and their measurements:

instances = client.cell_instance.list(cell_spec.id)
for inst in instances:
    measurements = client.cell_measurement.list(inst.id)
    print(f"{inst.name}: {len(measurements)} measurements")

Updating an instance

updated = client.cell_instance.update(
    instance_id,
    {
        "batch_id": other_batch.id,
    },
)

# Remove the cell from its batch
client.cell_instance.update(instance_id, {"batch_id": None})

Deleting an instance

client.cell_instance.delete(instance_id)

Note

Deleting an instance also removes all of its measurements.

Next steps

Once you have cell instances, upload experimental data in Cell Measurements.