readme.md

# AURELIUS Battery Optimizer

![Python](https://img.shields.io/badge/Python-3.10-blue) ![FastAPI](https://img.shields.io/badge/Framework-FastAPI-green) ![Docker](https://img.shields.io/badge/Deploy-Docker-2496ED)

## 🔬 The Problem
Traditional materials discovery is slow. Simulating the stability of a doped battery material usually requires setting up complex DFT calculations or managing messy scripts.

## 🚀 The Solution
**Aurelius** is a microservice architecture that allows researchers to screen thousands of doping strategies in seconds.

* **Universal Physics Engine:** Dynamically calculates Vegard's Law lattice strain and electronegativity mismatches for *any* host-dopant system using periodic table data (`mendeleev`).
* **Real-Time Data Integration:** Connects to the **Materials Project API** to fetch ground-truth thermodynamic properties (Band Gap, Volume) for the host material.
* **High-Entropy Support:** Capable of simulating complex co-doping recipes (mixtures of 2+ elements) to predict stability in high-entropy configurations.

## 🛠️ Engineering Architecture
This is not just a script; it is a production-ready system designed for scale.

* **Backend:** FastAPI (Python) serving an async REST API.
* **Streaming:** Implements **NDJSON Streaming** to deliver inference results row-by-row, preventing Gateway Timeouts during large batch processing.
* **Resilience:** Features a "Graceful Degradation" adapter that switches to theoretical estimation if the external Materials Project API is down or the material is novel.
* **Deployment:** Fully Dockerized container serving both the API and a lightweight static UI.

## 💻 Usage
1. Enter a host formula (e.g., `Li3PS4`).
2. Define a batch of doping recipes (JSON).
3. The system streams stability predictions back in real-time.