ElectroTwin-Control

ElectroTwin-Control is a self-contained scientific computing project that models a lithium-ion cell as a compact digital twin for estimation and charging control. It is designed as a reproducible computational experiment: the full workflow runs on a normal laptop, requires no hardware, and uses only the Python standard library.

The project combines:

• electrochemistry-inspired battery modeling
• state estimation with an Extended Kalman Filter
• safety-aware charging control driven by one-step model prediction
• electrochemical impedance spectroscopy (EIS) synthesis
• automated report generation with SVG figures and HTML

Scientific and engineering scope

This project connects four technical layers that usually appear separately in battery-system studies:

• Physics and mathematics: nonlinear dynamics, state estimation, system identification, and constrained control
• Chemistry: lithium-ion open-circuit voltage behavior, diffusion-inspired impedance, and aging stress factors
• Electronics and automation: a realistic battery-management-system style workflow with monitoring, estimation, and safe charging logic
• Engineering software: reproducible CLI, tests, data export, documentation, and report artifacts

Project capabilities

• Simulate a Li-ion cell using a two-RC equivalent circuit plus thermal and aging dynamics
• Generate pulse-test data and identify ECM parameters from noisy measurements
• Estimate state of charge (SOC) online with an EKF
• Run an adaptive charging session that respects voltage and temperature limits
• Generate EIS spectra and Nyquist plots from the identified twin
• Export CSV logs, SVG figures, JSON metrics, and an HTML report

Quick start

Run the full demo:

python3 -m electrotwin.cli demo --output docs/demo

Run tests:

python3 -m unittest discover -s tests -v

Repository structure

electrotwin/
  cli.py
  control.py
  estimation.py
  experiments.py
  model.py
  reporting.py
tests/
docs/

Method summary

1. Digital twin model

The cell is modeled with:

• SOC state
• two transient RC branches
• lumped temperature dynamics
• slow capacity fade / resistance growth via an aging proxy

Terminal voltage is computed from:

V = OCV(SOC, T, SOH) - I*R0 - V_rc1 - V_rc2

2. Identification

The project generates a pulse-test current profile, synthesizes noisy voltage measurements, and fits the twin's RC parameters by direct simulation and deterministic random-local search.

3. Online estimation

An EKF estimates SOC and polarization voltages from measured current and terminal voltage.

4. Charging control

The charging controller evaluates candidate currents against the twin and selects the strongest charging action that still respects future voltage and thermal limits.

Outputs

The demo command writes:

• summary.json
• pulse_identification.csv
• ekf_drive_cycle.csv
• charging_session.csv
• pulse_identification.svg
• soc_estimation.svg
• charging_session.svg
• eis_nyquist.svg
• report.html

Current demo snapshot

The current checked-in demo under docs/demo/ produces:

• parameter identification RMSE: about 4.0 mV
• SOC estimation RMSE: about 3.72 %
• charge time from 18% to 92%: about 47.9 min
• peak simulated temperature during charge: about 25.9 C

Open these artifacts after running the demo:

• docs/demo/report.html
• docs/demo/pulse_identification.svg
• docs/demo/soc_estimation.svg
• docs/demo/charging_session.svg
• docs/demo/eis_nyquist.svg

Realism notes

This is not a full Doyle-Fuller-Newman electrochemical solver. It is a compact engineering twin intended for:

• BMS algorithm prototyping
• teaching and reproducible simulation studies
• model-based estimation and control experiments

What is realistic:

• the separation between ohmic drop, polarization dynamics, and thermal behavior
• online SOC estimation from noisy voltage/current data
• the control trade-off between charging speed and safety margins
• impedance trends across frequencies

What is simplified:

• no spatial PDE over electrode thickness
• no real laboratory parameter set
• aging is stress-proxy based rather than chemistry-resolved
• diffusion behavior is approximated for readability and runtime speed

For a blunt engineering assessment of what is realistic, what is synthetic, and how to push this toward real BMS work, see docs/feasibility_and_accuracy.md.

Suggested repository presentation

If you push this repo to GitHub, pin these sections near the top:

• one screenshot of report.html
• a short demo GIF or screen recording of the generated figures
• one paragraph on why this matters for BMS, EV charging, or energy storage automation

License

MIT