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 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.

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.

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.

Default parameterized model

Each cell specification can designate one of its own parameterized models as the default model for the spec. Downstream workflows and UI surfaces that need to pick a parameterized model for the cell — for example, when opening the spec detail page or starting a new simulation from the cell — treat the default as the natural starting point.

The default is auto-populated: the first parameterized model created for a spec (from either the API or an ECM fit) becomes its default. If a default is already set, later creations do not override it. You can change the default (or clear it) at any time from the spec’s Parameterized models tab, from the parameterized model detail page, or through the API.

Setting the default from the UI

• On a cell spec’s Parameterized models tab, the current default shows a Default chip next to its name. Open the 3-dot menu on any other row and click Set as default to move the chip.
• On a parameterized model’s detail page, the default shows a Default model badge in the header. Non-default models show a Set as default button in the same place.

Setting the default through the API

Update the spec with the ID of one of its parameterized models. The parameterized model must belong to the same spec — the service rejects foreign models with a 400.

client.cell_spec.update(
    spec_id,
    {"default_parameterized_model_id": pm_id},
)

To clear the default, pass None (JSON null):

client.cell_spec.update(
    spec_id,
    {"default_parameterized_model_id": None},
)

The current default is available on the spec as default_parameterized_model_id, which is None when unset.

If the default parameterized model is deleted, the spec’s default_parameterized_model_id is automatically cleared — you don’t have to unset it manually before deleting.

Project ownership

Each Cell Specification belongs to a single Project within your Organization. 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.

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.

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.

Finding specs by material

You can search in the other direction too — from a material to the specs that use it, or from one spec to others sharing a component material. See Finding which cells use a material.

Next Steps

• Upload experimental data for your cells - see Data Overview
• Learn about Models to define the mathematical framework for simulations
• Explore Parameterized Models to create ready-to-run simulation engines