.. _auto_battery_cell_capacity:

*BATTERY CELL CAPACITY*
=======================

Integrates current (I·dt) and power (V·I·dt) over discharge, charge, or auto-detected segments from a BMS SSV file to produce per-segment capacity (Ah), energy (Wh), and summary KPIs including optional gravimetric and volumetric energy density. Use this worker to extract cell- or pack-level capacity analytics from lab cycling data.

When to use
-----------

Tagged: ``analytics``, ``battery``, ``bms``, ``c-rate``, ``capacity``, ``cell``, ``cycling``, ``energy-density``.

Inputs
------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20 20 20

   * - Label
     - ID
     - Type
     - Default
     - Required
     - Description
   * - BMS SSV file
     - ssv_file
     - file
     - —
     - ✓
     - Path to a BMS semicolon-separated values (SSV) file containing time, pack voltage, and pack current columns; required — the worker will throw if the file is missing or empty.
   * - Channel map
     - channel_map
     - mapper
     - —
     - 
     - Optional mapper that overrides the central channel-alias registry to specify which actual SSV column names correspond to the canonical channels (time, pack_voltage, pack_current); leave unset to use registry defaults.
   * - Segment kind
     - segment_kind
     - select
     - discharge
     - 
     - Selects which current-direction segments to accumulate into the summary KPIs: 'discharge' (default), 'charge', or 'auto-detect' (sums all segments regardless of sign).
   * - Pack mass kg
     - pack_mass_kg
     - scalar
     - —
     - 
     - Optional pack mass in kilograms (kg); when provided and > 0, enables the energy_density_wh_per_kg KPI output; leave blank to omit that KPI.
   * - Pack volume L
     - pack_volume_l
     - scalar
     - —
     - 
     - Optional pack volume in litres (L); when provided and > 0, enables the energy_density_wh_per_l KPI output; leave blank to omit that KPI.

Outputs
-------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20

   * - Label
     - ID
     - Type
     - Description
   * - Per-segment rows
     - segments_dataset
     - dataset
     - Dataset of per-segment rows conforming to output_schema.md, with columns: segment_id, segment_kind, t_start_s, t_end_s, capacity_ah, energy_wh, c_rate_avg, and nullable soc_start_pct, soc_end_pct, temperature_avg_c.
   * - Capacity KPIs
     - kpis
     - keyvalue
     - Key-value map of aggregate capacity KPIs over all matched segments: capacity_ah (Ah), energy_wh (Wh), c_rate_avg, and conditionally energy_density_wh_per_kg and energy_density_wh_per_l when mass/volume inputs are supplied.

Disciplines
-----------

- cae.postprocessing.extraction
- data.dataset.ingest
- data.statistics
- engineering.battery

.. raw:: html

   <hr style="margin-top:2em">
   <p style="font-size:11px;color:#888">
   Auto-generated from <code>platform</code> schema. Worker id: <code>battery_cell_capacity</code>. Schema hash: <code>44495804e4d9</code>. Hand-curated docs in <code>workerexamples/</code> override this page when present.
   </p>