Skip to main content

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

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

​
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