Skip to content

Commit b367c87

Browse files
knc6knc6
authored
Merge pull request #13 from atomgptlab/develop
Develop
2 parents 87ee85a + 48ebef8 commit b367c87

55 files changed

Lines changed: 6322 additions & 1149 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/apps/apply/battery.md‎

Lines changed: 166 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -4,58 +4,196 @@ title: Battery Explorer
44

55
# Battery Explorer
66

7-
Battery cathode voltage profile and theoretical capacity predictor. Supports model selection: default_path or wt01_path. Uses ALIGNN-FF for intercalation energy calculations.
7+
Predict battery cathode voltage profiles and theoretical capacity using ALIGNN force-field. Sequentially removes intercalating ions from a supercell, computes energy at each step with ALIGNN-FF, and builds the voltage vs. ion-fraction curve. Supports 6 ion types (Li, Na, K, Mg, Ca, Zn) and 2 ALIGNN-FF models (default, wt01).
88

99
[:material-open-in-new: Open App](https://atomgpt.org/battery){ .md-button .md-button--primary }
1010

1111
---
1212

1313
## Overview
1414

15-
Battery cathode voltage profile and theoretical capacity predictor. Supports model selection: default_path or wt01_path. Uses ALIGNN-FF for intercalation energy calculations.
15+
The Battery Explorer takes a cathode POSCAR structure, creates a supercell (enforced ~8 Å c-axis), identifies all intercalating ion sites, then sequentially removes ions one at a time. At each step, the total energy is computed with ALIGNN-FF (`AlignnAtomwiseCalculator`). The voltage at each step is:
16+
17+
**V = E(n+1) − E(n) + μ_element**
18+
19+
where μ_element is the per-atom energy of the elemental reference (e.g., BCC Li). Theoretical gravimetric (mAh/g) and volumetric (mAh/cm³) capacities are computed from the composition and Faraday's constant.
1620

1721
!!! info "Data Source"
18-
**ALIGNN-FF battery models**
22+
**ALIGNN-FF** (`default_path` or `wt01_path`) for energy calculations.
23+
**JARVIS-DFT** elemental reference energies from `jarvis.analysis.thermodynamics.energetics.get_optb88vdw_energy()`.
1924

2025
## Endpoints
2126

22-
- `GET /battery`
23-
- `POST /battery/predict`
24-
25-
**Request Models:** `BatteryPredictRequest`
27+
### `POST /battery/predict` — Voltage profile + capacity
2628

27-
!!! note "Authentication"
28-
All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
29+
Predict the full voltage profile and theoretical capacity for a cathode material. Takes a POSCAR structure, intercalating ion, and model selection.
2930

30-
## API Example
31+
```bash
32+
curl -X POST "https://atomgpt.org/battery/predict" \
33+
-H "Authorization: Bearer sk-XYZ" \
34+
-H "Content-Type: application/json" \
35+
-H "accept: application/json" \
36+
-d '{
37+
"poscar": "LiO2Co\n1.0\n2.719 -0.003 4.091\n1.234 2.423 4.091\n-0.004 -0.003 4.913\nLi Co O\n1 1 2\nCartesian\n1.974 1.209 6.548\n0.0 0.0 0.0\n1.027 0.629 3.405\n2.922 1.789 9.690",
38+
"element": "Li",
39+
"model": "default"
40+
}'
41+
```
3142

32-
```python
33-
import requests
34-
35-
response = requests.post(
36-
"https://atomgpt.org/battery/predict",
37-
headers={
38-
"Authorization": "Bearer sk-XYZ",
39-
"accept": "application/json",
40-
"Content-Type": "application/json",
41-
},
42-
json={"jid": "JVASP-1002"},
43-
)
44-
data = response.json()
45-
print(data)
43+
Na-ion battery example:
44+
45+
```bash
46+
curl -X POST "https://atomgpt.org/battery/predict" \
47+
-H "Authorization: Bearer sk-XYZ" \
48+
-H "Content-Type: application/json" \
49+
-H "accept: application/json" \
50+
-d '{
51+
"poscar": "NaCoO2\n1.0\n2.89 0.0 0.0\n-1.445 2.502 0.0\n0.0 0.0 10.83\nNa Co O\n1 1 2\nDirect\n0.0 0.0 0.25\n0.0 0.0 0.0\n0.0 0.0 0.117\n0.0 0.0 0.883",
52+
"element": "Na",
53+
"model": "default"
54+
}'
4655
```
4756

48-
## AGAPI Agent
57+
| Field | Type | Default | Description |
58+
|-------|------|---------|-------------|
59+
| `poscar` | string | required | VASP POSCAR of cathode structure (must contain the intercalating ion) |
60+
| `element` | string | `"Li"` | Intercalating ion: `"Li"`, `"Na"`, `"K"`, `"Mg"`, `"Ca"`, or `"Zn"` |
61+
| `model` | string | `"default"` | ALIGNN-FF model: `"default"` or `"wt01"` |
62+
63+
**Response:**
64+
65+
| Field | Description |
66+
|-------|-------------|
67+
| `compositions` | Ion fraction array (normalized 0→1) |
68+
| `voltages` | Cell voltage at each step (eV) |
69+
| `energies` | Total energy at each step (eV) |
70+
| `n_steps` | Number of ion removal steps |
71+
| `gravimetric_capacity` | Theoretical gravimetric capacity (mAh/g) |
72+
| `volumetric_capacity` | Theoretical volumetric capacity (mAh/cm³) |
73+
| `density` | Material density (g/cm³) |
74+
| `molar_mass` | Molar mass (g/mol) |
75+
| `formula` | Reduced chemical formula |
76+
| `spacegroup` | Space group |
77+
| `charge` | Ion oxidation state |
78+
| `result_text` | Human-readable summary with CSV data |
79+
80+
---
81+
82+
## Python Examples
83+
84+
=== "Li-ion cathode"
85+
86+
```python
87+
import requests
88+
89+
LICOO2 = """LiO2Co
90+
1.0
91+
2.719 -0.003 4.091
92+
1.234 2.423 4.091
93+
-0.004 -0.003 4.913
94+
Li Co O
95+
1 1 2
96+
Cartesian
97+
1.974 1.209 6.548
98+
0.0 0.0 0.0
99+
1.027 0.629 3.405
100+
2.922 1.789 9.690"""
101+
102+
response = requests.post(
103+
"https://atomgpt.org/battery/predict",
104+
headers={
105+
"Authorization": "Bearer sk-XYZ",
106+
"accept": "application/json",
107+
"Content-Type": "application/json",
108+
},
109+
json={
110+
"poscar": LICOO2,
111+
"element": "Li",
112+
"model": "default",
113+
},
114+
)
115+
data = response.json()
116+
if data["success"]:
117+
print(f"{data['formula']} — {data['element']}+ cathode")
118+
print(f" Gravimetric: {data['gravimetric_capacity']} mAh/g")
119+
print(f" Volumetric: {data['volumetric_capacity']} mAh/cm³")
120+
print(f" Steps: {data['n_steps']}")
121+
for c, v in zip(data["compositions"], data["voltages"]):
122+
print(f" x={c:.3f} V={v:.3f} eV")
123+
```
124+
125+
=== "Plot voltage profile"
126+
127+
```python
128+
import requests
129+
import matplotlib.pyplot as plt
130+
131+
response = requests.post(
132+
"https://atomgpt.org/battery/predict",
133+
headers={
134+
"Authorization": "Bearer sk-XYZ",
135+
"accept": "application/json",
136+
"Content-Type": "application/json",
137+
},
138+
json={
139+
"poscar": open("LiCoO2.vasp").read(),
140+
"element": "Li",
141+
},
142+
)
143+
data = response.json()
144+
145+
plt.figure(figsize=(8, 5))
146+
plt.plot(data["compositions"], data["voltages"], "o-", color="#f59e0b", lw=2)
147+
plt.xlabel("Li fraction")
148+
plt.ylabel("Voltage (eV)")
149+
plt.title(f"{data['formula']} — {data['gravimetric_capacity']} mAh/g")
150+
plt.grid(alpha=0.3)
151+
plt.tight_layout()
152+
plt.savefig("voltage_profile.png")
153+
```
154+
155+
=== "Compare ions"
156+
157+
```python
158+
import requests
159+
160+
POSCAR = open("cathode.vasp").read()
161+
162+
for ion in ["Li", "Na", "K"]:
163+
response = requests.post(
164+
"https://atomgpt.org/battery/predict",
165+
headers={
166+
"Authorization": "Bearer sk-XYZ",
167+
"accept": "application/json",
168+
"Content-Type": "application/json",
169+
},
170+
json={"poscar": POSCAR, "element": ion},
171+
)
172+
data = response.json()
173+
if data["success"]:
174+
avg_v = sum(data["voltages"]) / len(data["voltages"])
175+
print(f"{ion}: {data['gravimetric_capacity']} mAh/g, avg V={avg_v:.2f} eV")
176+
```
177+
178+
## AGAPI Agent [WIP]
49179

50180
```python
51181
from agapi.agents import AGAPIAgent
52182
import os
53183

54184
agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
55-
response = agent.query_sync("Show battery explorer for Silicon")
185+
186+
# Predict voltage profile
187+
response = agent.query_sync("Predict the Li-ion voltage profile for LiCoO2")
188+
print(response)
189+
190+
# Compare models
191+
response = agent.query_sync("Compare default and wt01 ALIGNN-FF for LiCoO2 battery cathode")
56192
print(response)
57193
```
58194

59-
## Reference
195+
## References
60196

61-
- Comp. Mat. Sci. 259, 114063 (2025)
197+
- K. Choudhary, Digital Discovery 2(2), 346 (2023) — ALIGNN-FF [:material-link: DOI](https://doi.org/10.1039/D2DD00096B)
198+
- K. Choudhary, Comp. Mat. Sci. 259, 114063 (2025) [:material-link: DOI](https://doi.org/10.1016/j.commatsci.2025.114063)
199+
- [atomgptlab/alignn](https://github.com/atomgptlab/alignn)

0 commit comments

Comments
 (0)