> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cells

> Define cell specifications with chemistry, capacity, voltage limits, electrode materials, and provenance metadata as the blueprint for your batteries

## Cell Specifications

A **Cell Specification** is the blueprint for a cell in Ionworks. It defines the fundamental properties of a cell, acting as a central record for its design and characteristics. Think of it as a master template for a particular type of cell you are working with - the kind of information that would be available in a datasheet.

All experimental data and simulations are ultimately linked back to a Cell Specification. It serves as the primary container for organizing all information related to a specific cell chemistry and design.

### Key Properties

When you create a Cell Specification, you define:

**Basic Information**

* **Name** - A unique, descriptive name for your cell specification
* **Form Factor** - Physical format (e.g., R2032, 18650, 21700, pouch, prismatic)
* **Manufacturer** - Who assembled or manufactured the cell

**Electrical Ratings**

* **Capacity** - Rated capacity (e.g., 5 Ah). Used to convert C-rate to current in simulations.
* **Voltage Min/Max** - Operating voltage limits. Used as default cutoffs in simulations.
* **Nominal Voltage** - Nominal cell voltage (optional)
* **Energy** - Rated energy (optional)
* **Energy Density** - Gravimetric and/or volumetric (optional)
* **Max Charge/Discharge Rates** - Maximum C-rates (optional)

**Components**

* **Anode** - Anode material and properties
* **Cathode** - Cathode material and properties
* **Electrolyte** - Electrolyte material and properties
* **Separator** - Separator material and properties
* **Case** - Case type and properties

**Source/Provenance**

* **DOI** - Digital object identifier for reference papers
* **Citation** - Publication citation
* **Creator** - Name and ORCID of the data creator
* **License** - Data license

**Additional Fields**

* **Properties** - Custom non-electrical properties (dimensions, assembly method, etc.)
* **Notes** - Free-form notes about the cell

## Electrode geometry (teardown data)

Electrode geometry — layer thicknesses, porosities, particle
radii, active-material volume fractions, and maximum
concentrations — is **design metadata stored on the cell
specification**, not on a measurement. It lives on the spec's
linked component records (`anode`, `cathode`, `electrolyte`,
`separator`, `case`) and in the spec-level `properties` field
for design-level values that aren't tied to a single component.

### When you need it

Geometry is required to build a **full physics-based model**
(what Ionworks calls the **FPBM**), which builds on the
Doyle–Fuller–Newman (DFN) or Single Particle Model with
Electrolyte (SPMe) equations. These values are
structural inputs to the equations; without them the model
cannot be assembled, and the build raises an error before any
solve. Simpler models — the equivalent circuit model (ECM) and
the lumped physics-based model (**LPBM**) family — do not need
geometry, so a spec without it is still usable for those. See
[Models](/build/models) for the full model catalog.

A practical check: if a spec's component records are all
unset and `properties` is empty, treat the spec as having **no
geometry on the platform** and DFN/SPMe simulations will fail
to build. The fix is to attach geometry to the spec (below),
not to add another measurement.

### Where it can come from

The model only needs the numbers — it does not care how they
were obtained. Valid sources include:

* A physical teardown of the cell
* Direct metrology (caliper/micrometer thickness, mercury
  porosimetry, SEM particle sizing)
* The vendor datasheet
* Published literature for the same chemistry

Record the source and confidence alongside the values (for
example as a `source` key inside each component's `properties`)
so downstream consumers know whether a number was measured or
assumed.

### Attaching geometry to a spec

Geometry is attached by updating the spec's components. Use
Quantity dicts (`{"value": ..., "unit": ...}`) with
human-readable units — `um`, `percent`, `mm`, `mol.m-3` are
all parsed automatically. Units use PyBaMM notation (`.`-separated
atoms with signed integer exponents); Pint-style strings like
`mol/m**3` are also accepted and normalized to PyBaMM notation.

```python theme={null}
client.cell_spec.update(
    spec_id,
    {
        "anode": {
            "material": {"name": "NK-SC", "manufacturer": "Novonix"},
            "properties": {
                "thickness": {"value": 70, "unit": "um"},
                "porosity": {"value": 33.6, "unit": "percent"},
                "particle_radius": {"value": 5.05, "unit": "um"},
                "active_material_volume_fraction": {
                    "value": 62.7,
                    "unit": "percent",
                },
                "current_collector_thickness": {"value": 10, "unit": "um"},
                "source": "vendor datasheet",
            },
        },
        "cathode": {
            "material": {"name": "M83E300"},
            "properties": {
                "thickness": {"value": 65, "unit": "um"},
                "porosity": {"value": 30.0, "unit": "percent"},
                "particle_radius": {"value": 3.8, "unit": "um"},
                "active_material_volume_fraction": {
                    "value": 66.0,
                    "unit": "percent",
                },
                "source": "teardown",
            },
        },
        "separator": {
            "material": {"name": "Celgard 2325"},
            "properties": {
                "thickness": {"value": 25, "unit": "um"},
                "porosity": {"value": 39.0, "unit": "percent"},
            },
        },
    },
)
```

After the update, the spec's `anode_id`, `cathode_id`, and
`separator_id` are populated and the geometry is available to
any parameterized model that resolves parameters from the
spec.

<Note>
  Geometry attached to the **spec** describes the design
  target. If a specific physical cell deviates from that
  design — for instance, a measured electrode loading from a
  particular build — record the deviation on the cell instance
  via `measured_properties`. See
  [Uploading data](/data/uploading).
</Note>

## Project ownership

Each Cell Specification belongs to a single [Project](/core-concepts/projects-studies) within your [Organization](/core-concepts/organizations). All cell instances, measurements, and parameterized models derived from that specification live inside the same project.

The spec's electrode, electrolyte, separator, and case **components** — and
the **materials** they reference — are also scoped to the same project.
Editing a component or its material on one project's spec doesn't mutate
another project's copy, even when the material has the same name,
manufacturer, and product ID.

<Note>
  If you need to use the same cell design in another project, create a new Cell
  Specification in that project. Its components and materials become
  independent copies inside the new project. This keeps each project's cell
  data, measurements, and parameterized models cleanly scoped.
</Note>

<Note>
  Components and materials without a project — created directly rather than
  through a cell specification, or predating per-project scoping — remain
  organization-wide. If specs in different projects reference one of these
  shared records, editing it affects every spec that references it.
</Note>

## Next Steps

* Upload experimental data for your cells - see [Data Overview](/data/overview)
* Learn about [Models](/build/models) to define the mathematical framework for simulations
* Explore [Parameterized Models](/build/parameterized-models) to create ready-to-run simulation engines