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 (DFN / SPMe — what Ionworks calls FPBM). 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 — ECM and the lumped/single-particle LBPM family — do not need geometry, so a spec without it is still usable for those. 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. 
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.

​
Organization-Level Resource

Each Cell Specification belongs to your Organization, making it a shared resource. Once created, a cell specification can be linked to multiple Projects.
If a Cell Specification is associated with multiple projects, all the data that belongs to the cell is available to all projects. If you create a parameterized model for your cell in one project, it will be available to all projects that have the cell associated.

​
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