# Cell Specifications

Cell specifications sit at the top of the Ionworks data hierarchy:

1. **Cell Specification** — defines a cell *type* (manufacturer, chemistry,
   form factor, electrode properties, etc.)
2. **Cell Instance** — a specific physical cell linked to a specification
   (see {doc}`cell_instances`)
3. **Cell Measurement** — time-series data recorded from testing an instance
   (see {doc}`cell_measurements`)

Every instance and measurement traces back to a specification, so creating one
is usually the first step in any workflow.

## Creating a specification

Pass a dictionary of properties to `client.cell_spec.create()`:

```python
cell_spec = client.cell_spec.create(
    {
        "name": "NCM622/Graphite Coin Cell",
        "form_factor": "R2032",
        "manufacturer": "Custom Cells",
        "ratings": {
            "capacity": {"value": 0.002, "unit": "A.h"},
            "voltage_min": {"value": 2.5, "unit": "V"},
            "voltage_max": {"value": 4.2, "unit": "V"},
        },
        "cathode": {
            "properties": {"loading": {"value": 12.3, "unit": "mg/cm**2"}},
            "material": {"name": "NCM622", "manufacturer": "BASF"},
        },
        "anode": {
            "properties": {"loading": {"value": 6.5, "unit": "mg/cm**2"}},
            "material": {"name": "Graphite", "manufacturer": "Customcells"},
        },
    }
)
print(cell_spec.id)
```

If you are running a script that may be executed more than once,
`create_or_get()` returns the existing specification when one with the same
name already exists instead of raising a `409 Conflict` error:

```python
cell_spec = client.cell_spec.create_or_get(
    {
        "name": "NCM622/Graphite Coin Cell",
        # ...
    }
)
```

## Listing specifications

```python
specs = client.cell_spec.list()
for spec in specs:
    print(f"{spec.name} — {spec.form_factor}")
```

## Retrieving a specification

Fetch by ID:

```python
spec = client.cell_spec.get(spec_id)
```

## Updating a specification

`update()` merges the provided fields into the existing specification:

```python
updated = client.cell_spec.update(
    spec_id, {"ratings": {"capacity": {"value": 0.0025, "unit": "A.h"}}}
)
```

## Deleting a specification

```python
client.cell_spec.delete(spec_id)
```

```{note}
Deleting a specification also removes all linked instances and measurements.
```

## Next steps

With a specification in place, create physical cell records in
{doc}`cell_instances`.