Upload 9 files

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+static/favicon.png filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,35 @@
+FROM python:3.10-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies if needed
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY src/ ./src/
+
+# Copy static files for UI
+COPY static/ ./static/
+
+# Create __init__.py if it doesn't exist (for proper Python package structure)
+RUN touch src/__init__.py
+
+# Expose port (Hugging Face Spaces uses 7860 by default, but can use PORT env var)
+EXPOSE 7860
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+ENV PORT=7860
+
+# Run the application
+# Hugging Face Spaces will set the PORT environment variable
+CMD uvicorn src.app:app --host 0.0.0.0 --port ${PORT:-7860}

readme.md

@@ -0,0 +1,26 @@
+# 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.

requirements.txt

@@ -0,0 +1,10 @@
+fastapi
+uvicorn
+pydantic
+mendeleev
+mp-api
+numpy
+scikit-learn
+scipy
+python-dotenv
+typing_extensions

src/__init__.py

@@ -0,0 +1,2 @@
+# Project Aurelius: Material Architect
+# Generative Design API for Solid State Batteries

src/api.py

@@ -0,0 +1,55 @@
+import os
+import sys
+from typing import Dict, Any
+
+# Workaround for Python 3.10: Add NotRequired to typing module
+if sys.version_info < (3, 11):
+    try:
+        from typing_extensions import NotRequired
+        import typing
+        if not hasattr(typing, 'NotRequired'):
+            typing.NotRequired = NotRequired
+    except ImportError:
+        pass
+
+# Try to import MPRester, handle case where key is missing/invalid gracefully
+try:
+    from mp_api.client import MPRester
+except ImportError:
+    MPRester = None
+
+class MaterialsProjectAdapter:
+    def __init__(self, api_key: str = None):
+        self.api_key = api_key
+        self.has_key = api_key is not None and len(api_key) > 10 and MPRester is not None
+
+    def get_material_properties(self, formula: str) -> Dict[str, Any]:
+        print(f"CONTACTING MATERIALS PROJECT: {formula}...")
+
+        if self.has_key:
+            try:
+                with MPRester(self.api_key) as mpr:
+                    docs = mpr.materials.summary.search(
+                        formula=[formula],
+                        fields=["band_gap", "volume", "formation_energy_per_atom"]
+                    )
+                    if docs:
+                        best_match = min(docs, key=lambda x: x.formation_energy_per_atom)
+                        return {
+                            "source": "Materials Project (Real Data)",
+                            "band_gap": float(best_match.band_gap),
+                            "volume": float(best_match.volume),
+                            "is_estimated": False
+                        }
+            except Exception as e:
+                print(f"❌ API ERROR: {str(e)}. Switching to fallback.")
+        # Fallback if no key or API fails
+        return self._generate_fallback(formula)
+
+    def _generate_fallback(self, formula: str) -> Dict[str, Any]:
+        return {
+            "source": "Theoretical Estimation (Fallback)",
+            "band_gap": 2.0,
+            "volume": 200.0,
+            "is_estimated": True
+        }

src/app.py

@@ -0,0 +1,118 @@
+import os
+import json
+from fastapi import FastAPI
+from fastapi.responses import StreamingResponse, FileResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel, Field
+from typing import Dict, List
+from src.doper import UniversalMaterialsOptimizer
+from dotenv import load_dotenv
+
+app = FastAPI(
+    title="AURELIUS Battery Optimizer",
+    description="Generative Design API for Co-Doped Solid State Batteries with Streaming Support",
+    version="4.0"
+)
+
+# Load environment variables from .env file
+load_dotenv()
+
+# Get API Key from Hugging Face Secrets (Environment Variable)
+MP_API_KEY = os.getenv("MP_API_KEY") or os.getenv("MP_API")
+
+# --- SERVE THE UI ---
+# This makes the "static" folder accessible
+app.mount("/static", StaticFiles(directory="static"), name="static")
+
+# --- NEW INPUT MODEL ---
+class MultiDopantRequest(BaseModel):
+    host_formula: str = Field(..., example="Li3PS4")
+    host_site_element: str = Field(..., example="S")
+    
+    # Now we accept a list of RECIPES to test
+    # Example: Check "Just Cl" AND "Cl + Br mixed"
+    recipes: List[Dict[str, float]] = Field(..., example=[
+        {"Cl": 0.2},              # Pure Cl doping
+        {"Cl": 0.1, "Br": 0.1},   # Co-doping (High Entropy)
+        {"I": 0.05, "F": 0.05}    # Exotic mix
+    ])
+
+@app.get("/")
+async def read_index():
+    # When user hits the homepage, send the HTML file
+    return FileResponse('static/index.html')
+
+# --- THE GENERATOR FUNCTION ---
+# This function doesn't run all at once. It pauses and resumes.
+async def run_simulation_stream(job: MultiDopantRequest):
+    
+    # 1. Initialize Engine (Once)
+    optimizer = UniversalMaterialsOptimizer(
+        host_formula=job.host_formula,
+        host_element_symbol=job.host_site_element,
+        api_key=MP_API_KEY
+    )
+
+    # 2. First, stream the metadata header
+    # This tells the client "I am ready, here is the context"
+    metadata = {
+        "type": "meta",
+        "host_system": job.host_formula,
+        "base_properties": optimizer.props
+    }
+    yield json.dumps(metadata) + "\n"
+
+    # 3. Stream results one by one
+    for recipe in job.recipes:
+        try:
+            result = optimizer.analyze_mixture(recipe)
+            # Add a type tag so client knows this is a data row
+            result["type"] = "data"
+            
+            # Send this chunk immediately!
+            yield json.dumps(result) + "\n"
+            
+        except Exception as e:
+            error_msg = {"type": "error", "recipe": recipe, "msg": str(e)}
+            yield json.dumps(error_msg) + "\n"
+
+@app.post("/simulate_stream")
+def simulate_mixture_stream(job: MultiDopantRequest):
+    """
+    Returns a StreamingResponse. 
+    The client will receive line-by-line JSON as calculations finish.
+    Ideally, use this endpoint for large numbers of recipes.
+    For small numbers of recipes, use /simulate_mix instead.
+    """
+    return StreamingResponse(
+        run_simulation_stream(job), 
+        media_type="application/x-ndjson"
+    )
+
+@app.post("/simulate_mix")
+def simulate_mixture(job: MultiDopantRequest):
+    """
+    Non-streaming endpoint for backward compatibility.
+    Returns all results at once after all calculations complete.
+    Use this endpoint if there are relatively few recipes to test.
+    For large numbers of recipes, use /simulate_stream instead.
+    """
+    optimizer = UniversalMaterialsOptimizer(
+        host_formula=job.host_formula,
+        host_element_symbol=job.host_site_element,
+        api_key=MP_API_KEY
+    )
+
+    results = []
+    for recipe in job.recipes:
+        try:
+            res = optimizer.analyze_mixture(recipe)
+            results.append(res)
+        except Exception as e:
+            results.append({"recipe": recipe, "error": str(e)})
+
+    return {
+        "host_system": job.host_formula,
+        "base_properties": optimizer.props,
+        "results": results
+    }

src/doper.py

@@ -0,0 +1,97 @@
+from src.api import MaterialsProjectAdapter
+from mendeleev import element
+
+class UniversalMaterialsOptimizer:
+    def __init__(self, host_formula: str, host_element_symbol: str, api_key: str = None):
+        self.adapter = MaterialsProjectAdapter(api_key)
+        self.props = self.adapter.get_material_properties(host_formula)
+        self.base_voltage = self.props['band_gap']
+        
+        host = element(host_element_symbol)
+        self.host_radius = host.ionic_radii[0].ionic_radius
+        self.host_en = host.en_pauling
+        self.host_symbol = host_element_symbol
+
+    def analyze_dopant(self, dopant_symbol: str, concentration: float):
+        dopant = element(dopant_symbol)
+        
+        # 1. Physics Calculations
+        delta_en = dopant.en_pauling - self.host_en
+        # Simple ionic radius lookup (using first available radius for simplicity)
+        dop_rad = dopant.ionic_radii[0].ionic_radius if dopant.ionic_radii else self.host_radius
+        radius_diff = dop_rad - self.host_radius
+        
+        voltage_gain = 1.5 * concentration * delta_en
+        predicted_voltage = self.base_voltage + voltage_gain
+        strain_energy = (radius_diff ** 2) * concentration * 100
+
+        # 2. Verdict Logic
+        status = "Stable"
+        if strain_energy > 500: status = "Critical Strain - Phase Separation"
+        elif predicted_voltage < 1.0: status = "Voltage Collapse"
+
+        return {
+            "dopant": dopant_symbol,
+            "concentration": concentration,
+            "predicted_voltage": round(predicted_voltage, 3),
+            "lattice_strain": round(strain_energy, 2),
+            "stability_status": status,
+            "data_confidence": "Low (Estimated)" if self.props['is_estimated'] else "High (Real Data)"
+        }
+
+    def analyze_mixture(self, dopant_recipe: dict):
+        """
+        Analyzes a mixture of dopants (Co-doping).
+        Input: {"Cl": 0.1, "Br": 0.1} -> implies 0.2 total doping
+        """
+        total_conc = sum(dopant_recipe.values())
+        
+        # 1. Edge Case: Empty Recipe
+        if total_conc == 0:
+            return {"error": "Recipe is empty. Please add at least one dopant."}
+
+        # 2. Calculate Weighted Properties (Vegard's Law)
+        weighted_radius = 0.0
+        weighted_en = 0.0
+        
+        detailed_breakdown = []
+
+        for symbol, amount in dopant_recipe.items():
+            atom = element(symbol)
+            
+            # Get radius (default to host radius if data missing to prevent crash)
+            r = atom.ionic_radii[0].ionic_radius if atom.ionic_radii else self.host_radius
+            en = atom.en_pauling if atom.en_pauling else self.host_en
+            
+            # Contribution to the average
+            fraction = amount / total_conc
+            weighted_radius += r * fraction
+            weighted_en += en * fraction
+            
+            detailed_breakdown.append(f"{symbol} ({amount*100:.1f}%)")
+
+        # 3. Compare 'Virtual Dopant' vs Host
+        radius_diff = weighted_radius - self.host_radius
+        delta_en = weighted_en - self.host_en
+        
+        # 4. Physics Engine
+        # Voltage is boosted by the total amount of dopant * average electronegativity gain
+        voltage_gain = 1.5 * total_conc * delta_en
+        predicted_voltage = self.base_voltage + voltage_gain
+        
+        # Strain is proportional to the mismatch squared * total concentration
+        strain_energy = (radius_diff ** 2) * total_conc * 100
+
+        # 5. Verdict
+        status = "Stable"
+        if strain_energy > 500: status = "Critical Strain - Phase Separation"
+        elif predicted_voltage < 1.0: status = "Voltage Collapse"
+
+        return {
+            "recipe_description": ", ".join(detailed_breakdown),
+            "total_doping_level": round(total_conc, 3),
+            "predicted_voltage": round(predicted_voltage, 3),
+            "lattice_strain": round(strain_energy, 2),
+            "stability_status": status,
+            "data_confidence": "Low (Estimated)" if self.props['is_estimated'] else "High (Real Data)"
+        }

static/index.html

@@ -0,0 +1,213 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>AURELIUS | BATTERY OPTIMIZER</title>
+    <link rel="icon" type="image/png" href="/static/favicon.png">
+    <style>
+        /* "Cyberpunk Lab" Aesthetic */
+        body { font-family: 'Courier New', monospace; background-color: #0d1117; color: #c9d1d9; max-width: 950px; margin: 40px auto; padding: 20px; font-size: 16px; }
+        h1 { border-bottom: 1px solid #30363d; padding-bottom: 10px; color: #58a6ff; letter-spacing: 2px;}
+        
+        .control-panel { background: #161b22; padding: 25px; border: 1px solid #30363d; border-radius: 6px; margin-bottom: 25px; box-shadow: 0 4px 12px rgba(0,0,0,0.5); }
+        
+        label { display: block; margin-top: 15px; margin-bottom: 5px; color: #8b949e; font-size: 15px; text-transform: uppercase; letter-spacing: 1px; }
+        input, textarea, button { width: 100%; box-sizing: border-box; background: #0d1117; border: 1px solid #30363d; color: #c9d1d9; font-family: inherit; font-size: 16px; }
+        
+        input { padding: 10px; }
+        textarea { padding: 10px; resize: vertical; font-size: 16px; }
+        textarea:focus { outline: none; border-color: #58a6ff; }
+        
+        /* Action Buttons */
+        .btn-group { display: flex; gap: 10px; margin-bottom: 10px; }
+        .btn-small { width: auto; padding: 5px 15px; font-size: 14px; background: #21262d; cursor: pointer; border-radius: 4px; transition: all 0.2s; }
+        .btn-small:hover { background: #30363d; border-color: #8b949e; }
+        
+        .btn-primary { margin-top: 20px; padding: 15px; background: #238636; color: white; cursor: pointer; font-weight: bold; border: none; font-size: 14px; text-transform: uppercase; letter-spacing: 1px; }
+        .btn-primary:hover { background: #2ea043; }
+
+        /* Results Table */
+        table { width: 100%; border-collapse: collapse; margin-top: 30px; font-size: 16px; }
+        th, td { text-align: left; padding: 12px; border-bottom: 1px solid #21262d; }
+        th { color: #8b949e; text-transform: uppercase; font-size: 14px; }
+        
+        /* Status Indicators */
+        .status-stable { color: #3fb950; font-weight: bold; }
+        .status-critical { color: #f85149; font-weight: bold; }
+        .status-warn { color: #d29922; }
+        
+        /* Animation */
+        .log-entry { opacity: 0; animation: fadeIn 0.4s forwards; }
+        @keyframes fadeIn { from { opacity: 0; transform: translateY(-10px); } to { opacity: 1; transform: translateY(0); } }
+    </style>
+</head>
+<body>
+
+    <h1>AURELIUS // BATTERY OPTIMIZER</h1>
+
+    <div class="control-panel">
+        <div style="display: flex; gap: 20px;">
+            <div style="flex: 1;">
+                <label>Host Formula</label>
+                <input type="text" id="host" value="Li3PS4">
+            </div>
+            <div style="flex: 1;">
+                <label>Substitution Site</label>
+                <input type="text" id="site" value="S">
+            </div>
+        </div>
+
+        <label>Doping Strategies (JSON Batch)</label>
+        
+        <div class="btn-group">
+            <button class="btn-small" onclick="loadExample('simple')">LOAD: Single Dopants</button>
+            <button class="btn-small" onclick="loadExample('complex')">LOAD: High-Entropy Mix</button>
+            <button class="btn-small" onclick="loadExample('stress')">LOAD: Stress Test (Solubility)</button>
+        </div>
+
+        <textarea id="jsonInput" rows="8"></textarea>
+        
+        <button class="btn-primary" onclick="startSimulation()">>> INITIATE SIMULATION STREAM</button>
+    </div>
+
+    <div id="statusLine" style="color: #8b949e; margin-bottom: 10px; font-size: 15px; min-height: 20px;">SYSTEM READY. AWAITING INPUT.</div>
+
+    <table id="resultsTable">
+        <thead>
+            <tr>
+                <th style="width: 30%">Composition Strategy</th>
+                <th>Pred. Voltage</th>
+                <th>Lattice Strain</th>
+                <th>Stability Verdict</th>
+            </tr>
+        </thead>
+        <tbody></tbody>
+    </table>
+
+    <script>
+        // --- 1. PRE-LOAD DATA FUNCTION ---
+        function loadExample(type) {
+            const data = {
+                simple: `[
+  {"Cl": 0.1}, 
+  {"Br": 0.1}, 
+  {"I": 0.05}
+]`,
+                complex: `[
+  {"Cl": 0.1, "Br": 0.1}, 
+  {"I": 0.05, "F": 0.05},
+  {"Cl": 0.2, "I": 0.02},
+  {"Br": 0.15, "Cl": 0.05}
+]`,
+                stress: `[
+  {"Cl": 0.9}, 
+  {"I": 0.5},
+  {"F": 0.5, "Cl": 0.5} 
+]`
+            };
+            document.getElementById("jsonInput").value = data[type];
+            document.getElementById("jsonInput").style.borderColor = "#30363d"; // Reset color
+        }
+
+        // Initialize with simple data
+        loadExample('simple');
+
+        // --- 2. MAIN SIMULATION LOGIC ---
+        async function startSimulation() {
+            const tableBody = document.querySelector("#resultsTable tbody");
+            const statusLine = document.getElementById("statusLine");
+            const inputArea = document.getElementById("jsonInput");
+
+            // UX: Reset
+            tableBody.innerHTML = "";
+            statusLine.innerText = "PARSING BATCH INSTRUCTIONS...";
+            inputArea.style.borderColor = "#30363d";
+
+            // A. VALIDATE JSON
+            let parsedRecipes;
+            try {
+                parsedRecipes = JSON.parse(inputArea.value);
+            } catch (e) {
+                statusLine.innerHTML = `<span style="color: #f85149">⚠️ SYNTAX ERROR: ${e.message}</span>`;
+                inputArea.style.borderColor = "#f85149";
+                return;
+            }
+
+            if (!Array.isArray(parsedRecipes)) {
+                statusLine.innerHTML = `<span style="color: #f85149">⚠️ FORMAT ERROR: Root must be a list [...]</span>`;
+                return;
+            }
+
+            // B. CONNECT TO STREAM
+            statusLine.innerText = "ESTABLISHING UPLINK TO PHYSICS ENGINE...";
+            
+            try {
+                const payload = {
+                    host_formula: document.getElementById("host").value,
+                    host_site_element: document.getElementById("site").value,
+                    recipes: parsedRecipes
+                };
+
+                const response = await fetch("/simulate_stream", {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify(payload)
+                });
+
+                if (!response.ok) throw new Error(await response.text());
+
+                // C. READ THE STREAM
+                const reader = response.body.getReader();
+                const decoder = new TextDecoder();
+                statusLine.innerText = "RECEIVING TELEMETRY STREAM...";
+
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done) break;
+
+                    const chunk = decoder.decode(value, { stream: true });
+                    const lines = chunk.split("\n");
+
+                    for (const line of lines) {
+                        if (!line.trim()) continue;
+                        try {
+                            const data = JSON.parse(line);
+                            
+                            if (data.type === "meta") {
+                                const source = data.base_properties.source.includes("Real") ? "REAL" : "ESTIMATED";
+                                statusLine.innerText = `CONNECTED: ${data.host_system} | DATA SOURCE: ${source}`;
+                            } 
+                            else if (data.type === "data") {
+                                addRow(data);
+                            }
+                        } catch (e) { console.error(e); }
+                    }
+                }
+                statusLine.innerText = "BATCH PROCESSING COMPLETE.";
+
+            } catch (err) {
+                statusLine.innerHTML = `<span style="color: #f85149">❌ SYSTEM FAILURE: ${err.message}</span>`;
+            }
+        }
+
+        function addRow(data) {
+            const tableBody = document.querySelector("#resultsTable tbody");
+            const row = document.createElement("tr");
+            row.className = "log-entry";
+            
+            let statusClass = "status-warn";
+            if (data.stability_status.includes("Stable")) statusClass = "status-stable";
+            if (data.stability_status.includes("Critical") || data.stability_status.includes("Collapse")) statusClass = "status-critical";
+
+            row.innerHTML = `
+                <td><strong style="color: #c9d1d9">${data.recipe_description}</strong></td>
+                <td>${data.predicted_voltage.toFixed(3)} V</td>
+                <td>${data.lattice_strain.toFixed(1)} MJ</td>
+                <td class="${statusClass}">${data.stability_status}</td>
+            `;
+            tableBody.appendChild(row);
+        }
+    </script>
+</body>
+</html>