Add battery energy-density screening descriptors

quanshengwu · quanshengwu · commit 48649342cd26 · 2026-03-11T06:03:15.000+08:00
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 [![CI](https://img.shields.io/github/actions/workflow/status/chatmaterials/battery-analysis/ci.yml?branch=main&label=CI)](https://github.com/chatmaterials/battery-analysis/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/chatmaterials/battery-analysis?display_name=tag)](https://github.com/chatmaterials/battery-analysis/releases)
 
-Standalone skill for battery-relevant DFT result analysis, including automatic inserted-ion inference, cross-backend NEB support, and candidate screening.
+Standalone skill for battery-relevant DFT result analysis, including automatic inserted-ion inference, cross-backend NEB support, energy-density/breathing descriptors, and candidate screening.
 
 Supports VASP, QE, and ABINIT-style host/lithiated inputs for voltage and volume analysis.
 
@@ -24,7 +24,7 @@ python3 scripts/analyze_volume_change.py fixtures/battery/host/POSCAR fixtures/b
 python3 scripts/analyze_neb_barrier.py fixtures/neb --json
 python3 scripts/analyze_neb_barrier.py fixtures/qe/neb --json
 python3 scripts/analyze_neb_barrier.py fixtures/abinit/neb --json
-python3 scripts/compare_battery_candidates.py fixtures/battery fixtures/candidates/high-strain --reference-energy -1.50 --voltage-min 0.5 --voltage-max 3.0 --max-expansion-percent 10.0 --max-barrier 0.8 --json
+python3 scripts/compare_battery_candidates.py fixtures/battery fixtures/candidates/high-strain fixtures/candidates/low-voltage-safe --reference-energy -1.50 --voltage-min 0.5 --voltage-max 3.0 --max-expansion-percent 10.0 --max-barrier 0.8 --json
 python3 scripts/export_battery_report.py fixtures/battery/host fixtures/battery/lithiated --reference-energy -1.50 --neb-path fixtures/neb
 python3 scripts/run_regression.py
 ```
diff --git a/SKILL.md b/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: "battery-analysis"
-description: "Use when the task is to analyze battery-relevant quantities from DFT results, including average insertion voltage, automatic inserted-ion counting, host-to-lithiated volume change, migration barriers from NEB images, candidate ranking, and compact markdown reports from finished calculations. Supports VASP, QE, and ABINIT-style host and lithiated inputs."
+description: "Use when the task is to analyze battery-relevant quantities from DFT results, including average insertion voltage, automatic inserted-ion counting, host-to-lithiated volume change, migration barriers from NEB images, specific-energy and breathing descriptors, candidate ranking, and compact markdown reports from finished calculations. Supports VASP, QE, and ABINIT-style host and lithiated inputs."
 ---
 
 # Battery Analysis
@@ -13,6 +13,7 @@ Use this skill for battery-material post-processing rather than generic workflow
 - infer the inserted ion and inserted-ion count from host and lithiated structures
 - quantify structural or volume change upon insertion or extraction
 - summarize migration barriers from NEB image sets
+- derive compact energy-density and breathing descriptors for battery screening
 - rank multiple battery candidates with a compact voltage-plus-volume-plus-barrier heuristic
 - write a compact battery-analysis report from existing calculations
 
diff --git a/fixtures/candidates/low-voltage-safe/host/OUTCAR b/fixtures/candidates/low-voltage-safe/host/OUTCAR
@@ -0,0 +1 @@
+ free  energy   TOTEN  =      -25.000000 eV
diff --git a/fixtures/candidates/low-voltage-safe/host/POSCAR b/fixtures/candidates/low-voltage-safe/host/POSCAR
@@ -0,0 +1,11 @@
+Host
+1.0
+5.000000 0.000000 0.000000
+0.000000 5.000000 0.000000
+0.000000 0.000000 5.000000
+Fe O
+1 2
+Direct
+0.000000 0.000000 0.000000
+0.500000 0.500000 0.000000
+0.500000 0.000000 0.500000
diff --git a/fixtures/candidates/low-voltage-safe/lithiated/OUTCAR b/fixtures/candidates/low-voltage-safe/lithiated/OUTCAR
@@ -0,0 +1 @@
+ free  energy   TOTEN  =      -26.700000 eV
diff --git a/fixtures/candidates/low-voltage-safe/lithiated/POSCAR b/fixtures/candidates/low-voltage-safe/lithiated/POSCAR
@@ -0,0 +1,12 @@
+Lithiated
+1.0
+5.020000 0.000000 0.000000
+0.000000 5.020000 0.000000
+0.000000 0.000000 5.020000
+Li Fe O
+1 1 2
+Direct
+0.250000 0.250000 0.250000
+0.000000 0.000000 0.000000
+0.500000 0.500000 0.000000
+0.500000 0.000000 0.500000
diff --git a/fixtures/candidates/low-voltage-safe/neb/00/OUTCAR b/fixtures/candidates/low-voltage-safe/neb/00/OUTCAR
@@ -0,0 +1 @@
+ free  energy   TOTEN  =      -120.000000 eV
diff --git a/fixtures/candidates/low-voltage-safe/neb/01/OUTCAR b/fixtures/candidates/low-voltage-safe/neb/01/OUTCAR
@@ -0,0 +1 @@
+ free  energy   TOTEN  =      -119.700000 eV
diff --git a/fixtures/candidates/low-voltage-safe/neb/02/OUTCAR b/fixtures/candidates/low-voltage-safe/neb/02/OUTCAR
@@ -0,0 +1 @@
+ free  energy   TOTEN  =      -119.600000 eV
diff --git a/fixtures/candidates/low-voltage-safe/neb/03/OUTCAR b/fixtures/candidates/low-voltage-safe/neb/03/OUTCAR
@@ -0,0 +1 @@
+ free  energy   TOTEN  =      -119.750000 eV
diff --git a/fixtures/candidates/low-voltage-safe/neb/04/OUTCAR b/fixtures/candidates/low-voltage-safe/neb/04/OUTCAR
@@ -0,0 +1 @@
+ free  energy   TOTEN  =      -119.900000 eV
diff --git a/references/battery.md b/references/battery.md
@@ -3,3 +3,4 @@
 - Average voltage from two endpoints is a compact thermodynamic descriptor, not a replacement for a full voltage-composition curve.
 - Volume-change screening is useful for cycling stability triage, but local distortions and anisotropic strain can still matter.
 - Migration barriers and endpoint voltages should be discussed together; a good battery candidate generally needs both acceptable thermodynamics and acceptable kinetics.
+- Specific-energy proxies are useful for screening, but they are not a substitute for a full cell-level energy-density analysis.
diff --git a/scripts/analyze_insertion_voltage.py b/scripts/analyze_insertion_voltage.py
@@ -31,6 +31,13 @@ def analyze(
     voltage = -(e_lithiated - e_host - delta * reference_energy) / delta
     host_mass = formula_mass(host_comp)
     capacity = FARADAY_MAH_PER_MOL * delta / host_mass if host_mass is not None and host_mass > 0.0 else None
+    specific_energy = voltage * capacity if capacity is not None else None
+    if voltage < 1.0:
+        voltage_class = "low-voltage"
+    elif voltage <= 3.5:
+        voltage_class = "working-window"
+    else:
+        voltage_class = "high-voltage"
     return {
         "backend": backend_host,
         "host": str(host),
@@ -43,6 +50,8 @@ def analyze(
         "average_voltage_V": voltage,
         "host_formula_mass_g_mol": host_mass,
         "theoretical_capacity_mAh_g": capacity,
+        "specific_energy_Wh_kg": specific_energy,
+        "voltage_class": voltage_class,
         "observations": ["Average insertion voltage estimated from total-energy differences."],
     }
 
diff --git a/scripts/analyze_neb_barrier.py b/scripts/analyze_neb_barrier.py
@@ -9,6 +9,14 @@
 from battery_io import read_energy
 
 
+def kinetic_class(barrier: float) -> str:
+    if barrier <= 0.5:
+        return "fast-like"
+    if barrier <= 1.0:
+        return "moderate-like"
+    return "slow-like"
+
+
 def analyze(root: Path) -> dict[str, object]:
     image_dirs = sorted(path for path in root.iterdir() if path.is_dir() and path.name.isdigit())
     if not image_dirs:
@@ -32,6 +40,7 @@ def analyze(root: Path) -> dict[str, object]:
         "reverse_barrier_eV": highest_rel - reaction_energy,
         "reaction_energy_eV": reaction_energy,
         "highest_image": highest["image"],
+        "kinetic_class": kinetic_class(highest_rel),
         "observations": ["Barrier and reaction energy estimated from image energies relative to the initial state."],
     }
 
diff --git a/scripts/analyze_volume_change.py b/scripts/analyze_volume_change.py
@@ -16,6 +16,12 @@ def analyze(initial: Path, final: Path) -> dict[str, object]:
         raise SystemExit("Initial and final structures must use the same backend for direct comparison")
     inserted_species, delta = infer_ion_change(initial, final)
     change = (vol_b - vol_a) / vol_a * 100.0
+    if abs(change) < 5.0:
+        breathing_class = "small-breathing"
+    elif abs(change) < 15.0:
+        breathing_class = "moderate-breathing"
+    else:
+        breathing_class = "severe-breathing"
     return {
         "backend": backend_a,
         "initial": str(initial),
@@ -26,6 +32,7 @@ def analyze(initial: Path, final: Path) -> dict[str, object]:
         "inserted_species": inserted_species,
         "delta_ion": delta,
         "volume_change_per_inserted_ion_A3": (vol_b - vol_a) / delta if delta > 0 else None,
+        "breathing_class": breathing_class,
         "observations": ["Volume change estimated from the lattice vectors in the two structures."],
     }
 
diff --git a/scripts/compare_battery_candidates.py b/scripts/compare_battery_candidates.py
@@ -35,19 +35,26 @@ def analyze_case(
         voltage_penalty = 0.0
     expansion_penalty = max(0.0, abs(float(volume["relative_volume_change_percent"])) - max_expansion_percent) / 10.0
     barrier_penalty = max(0.0, float(neb_payload["forward_barrier_eV"]) - max_barrier_eV) if neb_payload is not None else 0.25
-    score = voltage_penalty + expansion_penalty + barrier_penalty
+    specific_energy = float(voltage["specific_energy_Wh_kg"]) if voltage["specific_energy_Wh_kg"] is not None else 0.0
+    energy_density_penalty = max(0.0, 250.0 - specific_energy) / 100.0
+    score = voltage_penalty + expansion_penalty + barrier_penalty + energy_density_penalty
     return {
         "case": root.name,
         "path": str(root),
         "backend": voltage["backend"],
         "inserted_species": voltage["inserted_species"],
         "average_voltage_V": voltage["average_voltage_V"],
         "theoretical_capacity_mAh_g": voltage["theoretical_capacity_mAh_g"],
+        "specific_energy_Wh_kg": voltage["specific_energy_Wh_kg"],
+        "voltage_class": voltage["voltage_class"],
         "relative_volume_change_percent": volume["relative_volume_change_percent"],
+        "breathing_class": volume["breathing_class"],
         "forward_barrier_eV": neb_payload["forward_barrier_eV"] if neb_payload is not None else None,
+        "kinetic_class": neb_payload["kinetic_class"] if neb_payload is not None else None,
         "voltage_penalty": voltage_penalty,
         "expansion_penalty": expansion_penalty,
         "barrier_penalty": barrier_penalty,
+        "energy_density_penalty": energy_density_penalty,
         "screening_score": score,
     }
 
@@ -70,7 +77,7 @@ def analyze_cases(
         "target_voltage_window_V": [voltage_min, voltage_max],
         "max_expansion_percent": max_expansion_percent,
         "max_barrier_eV": max_barrier_eV,
-        "ranking_basis": "screening_score = voltage_penalty + expansion_penalty + barrier_penalty",
+        "ranking_basis": "screening_score = voltage_penalty + expansion_penalty + barrier_penalty + energy_density_penalty",
         "cases": ranked,
         "best_case": ranked[0]["case"] if ranked else None,
         "observations": [
diff --git a/scripts/export_battery_report.py b/scripts/export_battery_report.py
@@ -32,16 +32,19 @@ def render_markdown(voltage: dict[str, object], volume: dict[str, object], neb:
         "## Average Voltage",
         f"- Backend: `{voltage['backend']}`",
         f"- Average insertion voltage (V): `{voltage['average_voltage_V']:.4f}`",
+        f"- Voltage class: `{voltage['voltage_class']}`",
         f"- Inserted species: `{voltage['inserted_species']}`",
         f"- Inserted ions per host cell: `{voltage['delta_ion']}`",
         f"- Host energy (eV): `{voltage['host_energy_eV']:.6f}`",
         f"- Lithiated energy (eV): `{voltage['lithiated_energy_eV']:.6f}`",
         f"- Theoretical capacity (mAh/g): `{voltage['theoretical_capacity_mAh_g']:.2f}`" if voltage["theoretical_capacity_mAh_g"] is not None else "- Theoretical capacity (mAh/g): `n/a`",
+        f"- Specific energy (Wh/kg): `{voltage['specific_energy_Wh_kg']:.2f}`" if voltage["specific_energy_Wh_kg"] is not None else "- Specific energy (Wh/kg): `n/a`",
         "",
         "## Volume Change",
         f"- Initial volume (A^3): `{volume['volume_initial_A3']:.4f}`",
         f"- Final volume (A^3): `{volume['volume_final_A3']:.4f}`",
         f"- Relative volume change (%): `{volume['relative_volume_change_percent']:.4f}`",
+        f"- Breathing class: `{volume['breathing_class']}`",
         f"- Volume change per inserted ion (A^3): `{volume['volume_change_per_inserted_ion_A3']:.4f}`" if volume["volume_change_per_inserted_ion_A3"] is not None else "- Volume change per inserted ion (A^3): `n/a`",
     ]
     if neb is not None:
@@ -51,6 +54,7 @@ def render_markdown(voltage: dict[str, object], volume: dict[str, object], neb:
                 "## Migration Barrier",
                 f"- Parsed backends: `{', '.join(neb['backends'])}`",
                 f"- Forward barrier (eV): `{neb['forward_barrier_eV']:.4f}`",
+                f"- Kinetic class: `{neb['kinetic_class']}`",
                 f"- Reverse barrier (eV): `{neb['reverse_barrier_eV']:.4f}`",
                 f"- Reaction energy (eV): `{neb['reaction_energy_eV']:.4f}`",
                 f"- Highest image: `{neb['highest_image']}`",
diff --git a/scripts/run_regression.py b/scripts/run_regression.py
@@ -32,9 +32,12 @@ def main() -> None:
     ensure(voltage["inserted_species"] == "Li", "battery-analysis should infer the inserted ion species")
     ensure(voltage["delta_ion"] == 1, "battery-analysis should infer the inserted ion count")
     ensure(voltage["theoretical_capacity_mAh_g"] is not None and voltage["theoretical_capacity_mAh_g"] > 0, "battery-analysis should estimate a theoretical capacity")
+    ensure(voltage["specific_energy_Wh_kg"] is not None and voltage["specific_energy_Wh_kg"] > 300, "battery-analysis should estimate a specific-energy proxy")
+    ensure(voltage["voltage_class"] == "working-window", "battery-analysis should classify the voltage scale")
     volume = run_json("scripts/analyze_volume_change.py", "fixtures/battery/host/POSCAR", "fixtures/battery/lithiated/POSCAR", "--json")
     ensure(volume["relative_volume_change_percent"] > 0, "battery-analysis should detect positive volume expansion")
     ensure(volume["volume_change_per_inserted_ion_A3"] is not None, "battery-analysis should estimate the volume change per inserted ion")
+    ensure(volume["breathing_class"] == "moderate-breathing", "battery-analysis should classify the breathing scale")
     qe_voltage = run_json("scripts/analyze_insertion_voltage.py", "fixtures/qe/host", "fixtures/qe/lithiated", "--reference-energy", "-1.50", "--json")
     ensure(abs(qe_voltage["average_voltage_V"] - 1.0) < 1e-6, "battery-analysis should parse a QE-based average insertion voltage")
     abinit_voltage = run_json("scripts/analyze_insertion_voltage.py", "fixtures/abinit/host", "fixtures/abinit/lithiated", "--reference-energy", "-1.50", "--json")
@@ -46,6 +49,7 @@ def main() -> None:
     neb = run_json("scripts/analyze_neb_barrier.py", "fixtures/neb", "--json")
     ensure(abs(neb["forward_barrier_eV"] - 0.7) < 1e-6, "battery-analysis should parse the forward NEB barrier")
     ensure(neb["highest_image"] == "02", "battery-analysis should identify the highest-energy image")
+    ensure(neb["kinetic_class"] == "moderate-like", "battery-analysis should classify the migration barrier scale")
     qe_neb = run_json("scripts/analyze_neb_barrier.py", "fixtures/qe/neb", "--json")
     ensure(abs(qe_neb["forward_barrier_eV"] - 0.7) < 1e-3, "battery-analysis should support QE NEB-like image sets")
     abinit_neb = run_json("scripts/analyze_neb_barrier.py", "fixtures/abinit/neb", "--json")
@@ -54,6 +58,7 @@ def main() -> None:
         "scripts/compare_battery_candidates.py",
         "fixtures/battery",
         "fixtures/candidates/high-strain",
+        "fixtures/candidates/low-voltage-safe",
         "--reference-energy",
         "-1.50",
         "--voltage-min",
