.. _auto_bms_generate_synthetic_data:
*GENERATE SYNTHETIC BMS DATA*
=============================
Generates deterministic, BMS-shaped synthetic SSV files for testing and demonstration of battery workers. Select a synthetic_type (capacity_test, cell_imbalance, hppc_pulse, and future types) to emit a structured time-series file plus ground-truth expected_metrics and a generation_summary suitable for assert-against-truth validation pipelines.
When to use
-----------
Tagged: ``battery``, ``bms``, ``capacity_test``, ``cell_imbalance``, ``deterministic``, ``fca``, ``generation``, ``hppc_pulse``.
Inputs
------
.. list-table::
:header-rows: 1
:widths: 20 20 20 20 20 20
* - Label
- ID
- Type
- Default
- Required
- Description
* - Synthetic Type
- synthetic_type
- select
- capacity_test
- ✓
- Scenario to generate; choose one of capacity_test, cell_imbalance, or hppc_pulse (active) — cycle_decay, thermal_hotspot, ocv_curve, fault_injection, and mixed_drive_cycle are defined but not yet implemented and will raise an error.
* - Number of cells
- n_cells
- scalar
- 96
-
- Total number of individual battery cells in the pack (dimensionless integer); default 96 controls how many HVBatCellVlt_XX columns are emitted.
* - Number of modules
- n_modules
- scalar
- 16
-
- Number of battery modules in the pack (dimensionless integer); default 16 controls how many HVBatModT_XX temperature columns are emitted.
* - Nominal capacity Ah
- ah_nominal
- scalar
- 49.5
-
- Nominal pack capacity in ampere-hours (Ah); default 49.5 Ah — used to compute discharge current from C-rate and expected capacity in expected_metrics.
* - Nominal pack V
- voltage_nominal
- scalar
- 358.5
-
- Nominal pack voltage in volts (V); default 358.5 V — sets the mid-point of the synthetic voltage sweep across the discharge window.
* - Sample rate (Hz)
- sample_rate_hz
- scalar
- 1.0
-
- Data sampling frequency in hertz (Hz); default 1.0 Hz — determines the number of rows written and the time step between rows.
* - Duration (s, blank=auto)
- duration_s
- scalar
- —
-
- Override total test duration in seconds (s); leave blank or 0 to let the worker calculate duration automatically from scenario parameters (e.g., C-rate and SoC window for capacity_test).
* - Random seed
- random_seed
- scalar
- 42
-
- Integer seed for the mt_rand pseudo-random number generator; default 42 — fixing this value guarantees identical cell-voltage noise and module temperature offsets across runs.
* - C-rate (capacity_test)
- c_rate
- scalar
- 1.0
-
- Discharge C-rate for the capacity_test scenario (dimensionless, e.g. 1.0 = 1C); ignored by other scenario types — must be > 0.
* - SoC start % (capacity_test)
- soc_start_pct
- scalar
- 100
-
- Starting state-of-charge in percent (%) for the capacity_test scenario; default 100 % — must be strictly greater than soc_end_pct.
* - SoC end % (capacity_test)
- soc_end_pct
- scalar
- 0
-
- Ending state-of-charge in percent (%) for the capacity_test scenario; default 0 % — must be strictly less than soc_start_pct.
* - Pulse amps (hppc_pulse)
- pulse_amps
- scalar
- 200
-
- Pulse current magnitude in amperes (A) for the hppc_pulse scenario; default 200 A — ignored by other scenario types.
* - Pulse duration s (hppc_pulse)
- pulse_duration_s
- scalar
- 10
-
- Duration of each HPPC current pulse in seconds (s) for the hppc_pulse scenario; default 10 s — ignored by other scenario types.
* - Rest duration s (hppc_pulse)
- rest_duration_s
- scalar
- 60
-
- Rest period between HPPC pulses in seconds (s) for the hppc_pulse scenario; default 60 s — ignored by other scenario types.
* - SoC levels % (hppc_pulse)
- soc_levels_pct
- text
- 20,50,80
-
- Comma-separated list of SoC levels in percent (%) at which HPPC pulses are applied for the hppc_pulse scenario; default '20,50,80' — ignored by other scenario types.
* - Drift cell id (cell_imbalance)
- drift_cell_id
- scalar
- 42
-
- 1-based index of the cell that receives a deliberate voltage offset in the cell_imbalance scenario; default 42 — must be between 1 and n_cells; ignored by other scenario types.
* - Drift mV (cell_imbalance)
- drift_mv
- scalar
- 50
-
- Magnitude of the voltage drift applied to the drift cell in millivolts (mV) for the cell_imbalance scenario; default 50 mV — ignored by other scenario types.
* - Output format
- output_format
- select
- ssv
-
- File format of the emitted synthetic data file; default 'ssv' produces an FCA BMS SSV file compatible with physicaltest_import_bms_data — additional formats may be available via the select list.
* - Output filename (blank=tmp)
- output_filename
- text
- —
-
- Absolute path and filename for the output file; leave blank to auto-generate a temp-directory path of the form synth_{type}_{seed}.ssv.
Outputs
-------
.. list-table::
:header-rows: 1
:widths: 20 20 20 20
* - Label
- ID
- Type
- Description
* - Synthetic file
- synthetic_file
- file
- Generated synthetic BMS data file (SSV or selected format) containing time-series pack voltage, current, SoC, SoH, per-cell voltages, and module temperatures — ready to feed directly into physicaltest_import_bms_data.
* - Expected metrics
- expected_metrics
- keyvalue
- Key-value map of ground-truth KPIs computed analytically during generation (e.g., capacity_ah, energy_wh, c_rate_avg) — use these values in downstream assert-against-truth test steps.
* - Generation summary
- generation_summary
- keyvalue
- Key-value map of generation provenance metadata including rows_emitted, columns_emitted, seed_used, synthetic_type, and file_size_bytes — useful for logging and audit trails.
Disciplines
-----------
- data.dataset.ingest
- data.io.file
- engineering.battery
.. raw:: html
Auto-generated from platform schema. Worker id: bms_generate_synthetic_data. Schema hash: 8e00246a29e6. Hand-curated docs in workerexamples/ override this page when present.