# chueh-ermon/battery-fast-charging-optimization architecture

> Architecture diagram of the GitHub repository chueh-ermon/battery-fast-charging-optimization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chueh-ermon/battery-fast-charging-optimization
- Repository: https://github.com/chueh-ermon/battery-fast-charging-optimization

## Overview

##### Project type and purpose
- This is a Python-based research codebase for closed-loop experimental design and machine-learning-driven optimization of fast-charging protocols for lithium-ion batteries.
- It provides command-line scripts to (a) enumerate protocol (“policy”) spaces, (b) simulate battery lifetimes under a given protocol, (c) run closed-loop optimization (CLO) to propose the next round of experiments, and (d) generate all figures for the associated paper.

##### File structure
Top-level components:
- policies.py            – Defines/generates the policy space
- sim_with_seed.py       – Stochastic lifetime simulator
- closed_loop_oed.py     – Main closed-loop optimization driver
- data/                  – File-based datastore for experimental/simulation results
├─ batch/            – Proposed protocols per round
├─ bounds/           – Model uncertainty/bounds pickle files
└─ pred/             – Early predictions
- figures/               – All code and data to recreate paper figures
- README.md              – Project overview and usage examples
- .gitignore             – Excludes environment/build artifacts

Patterns & architecture choices:
– A CLI-driven, file-based pipeline.
– Scripts communicate by reading/writing CSVs and pickles under data/.
– A closed-loop control flow: define policies → simulate/observe → optimize → repeat.
– Separate “compute” (simulator, optimizer) from “visualization” (figures/).

##### README for additional insights
- Describes three core user workflows:
1. `python policies.py` (policy generation)
2. `python sim_with_seed.py` (simulation)
3. `python closed_loop_oed.py` (closed-loop optimization)
- All figure code lives in figures/, organized by paper figure and supplementary figures.
- Dependencies: Python 3.7, standard ML/data libs (NumPy, pandas, scikit-learn, matplotlib, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Compute"
    Policies["Policy Generator\n(policies.py)"]:::compute
    Surface["Policy Space Visualizer\n(surface_points.py)"]:::compute
    Simulator["Stochastic Simulator\n(sim_with_seed.py)"]:::compute
    CLOE["Closed-Loop OED Engine\n(closed_loop_oed.py)"]:::compute
  end

  DS["Data Store"]:::datastore

  Figure["Figure Generator\n(figures/)"]:::viz

  External["External Lab\n(Experimental Predictions)"]:::external

  Policies -->|new protocols| DS
  Surface -->|visualize/sample policies| DS
  Simulator -->|sim outputs & logs| DS
  CLOE -->|next protocols| DS
  External -->|early predictions| DS

  DS -->|data for OED| CLOE
  DS -->|data for figures| Figure

  click Policies "https://github.com/chueh-ermon/battery-fast-charging-optimization/blob/master/policies.py"
  click Surface "https://github.com/chueh-ermon/battery-fast-charging-optimization/blob/master/surface_points.py"
  click Simulator "https://github.com/chueh-ermon/battery-fast-charging-optimization/blob/master/sim_with_seed.py"
  click CLOE "https://github.com/chueh-ermon/battery-fast-charging-optimization/blob/master/closed_loop_oed.py"
  click DS "https://github.com/chueh-ermon/battery-fast-charging-optimization/tree/master/data/"
  click Figure "https://github.com/chueh-ermon/battery-fast-charging-optimization/tree/master/figures/"
  click External "https://github.com/chueh-ermon/battery-fast-charging-optimization/tree/master/data/pred/"

  classDef compute fill:#D6EAF8,stroke:#21618C,color:#1B4F72
  classDef datastore fill:#FADBD8,stroke:#943126,color:#641E16
  classDef viz fill:#D5F5E3,stroke:#1D8348,color:#145A32
  classDef external fill:#F9E79F,stroke:#B9770E,color:#7E5109
```
