Smartphone Battery Digital Twin

Physics-informed smartphone battery modeling for state-of-charge (SOC) estimation, component-level power analysis, and time-to-empty prediction.

Overview

This repository is a public release of a 2026 MCM Problem A project. It develops a continuous-time model of a lithium-ion smartphone battery coupled to stochastic screen, CPU, network, GPS, and background workloads.

The project preserves the original modeling direction and reported results. It does not retrain the models or redistribute the source battery files used during the study.

Research question

How do device workload, temperature, battery dynamics, and battery aging interact to determine remaining charge and usable time?

Model architecture

flowchart TD
    A[Usage scenario] --> B[Component power models]
    B --> C[Constant-power load]
    C --> D[Second-order Thevenin battery model]
    D --> E[UKF SOC estimation]
    E --> F[Time-to-empty prediction]

Loading

The battery state is represented by SOC and two polarization voltages. The terminal-voltage feedback creates the phone's constant-power load behavior: a lower battery voltage can require higher current and increase the voltage drop.

Repository structure

Problem 1/     Battery model, parameter estimation, UKF, and robustness analysis
Problem 2/     Usage scenarios and time-to-empty analysis
Problem 3/     Temperature and process-noise sensitivity analysis
Problem 4/     Module ablation and Pareto analysis
paper/         LaTeX report source and figures
docs/          Model and data-provenance notes
src/           Reusable, data-independent battery-twin package
tests/         Numerical and API regression tests

Installation

python -m pip install -e .

Install the optional research and plotting dependencies when working with the legacy analysis scripts:

python -m pip install -e ".[analysis]"

Quick start

Run the reproducible, data-independent constant-power simulation:

battery-twin --power 2.5 --hours 8 --dt 10 --csv outputs/demo.csv

The simulator analytically solves the PMIC constant-power constraint, updates the two RC polarization states, stops at voltage cutoff, and can export a trace. The circuit-diagram example also requires no private data:

python enhanced_2rc_circuits.py

Run the automated model checks with:

python -m unittest discover -s tests -v

The data-dependent scripts are retained as research scripts. Before running them, obtain the authorized battery data described in data/README.md and adapt the input paths to the local checkout.

Data

Raw CALCE/NASA battery files, large traces, Android build artifacts, third-party papers, and the official contest PDF are intentionally excluded. See data/README.md for provenance and expected input descriptions.

Main findings

• CPU and display activity dominate the modeled optimization opportunity in high-load scenarios.
• GPS, network activity, and network tail behavior materially affect navigation and social-use scenarios.
• The UKF provides a nonlinear SOC-estimation layer on top of the electrical battery model.
• Voltage cutoff can occur before chemical SOC reaches zero under high loads.
• Temperature and aging change effective capacity and resistance; low-temperature lithium plating is outside the current model.

Limitations

Scenario workloads include assumed and stochastic components, and the reported numerical results should be interpreted as model-based findings. The project contains multiple exploratory scripts from the original study; the report and problem-specific directories are the primary reference.

Citation and license

See CITATION.cff and LICENSE_REVIEW_REQUIRED.md. No open-source license is asserted in this release until the author selects one.