Materials Discovery Agent 🔬

A tiered computational pipeline for discovering novel solid-state electrolytes.

This agent generates, screens, and validates candidate materials for next-generation battery electrolytes using a multi-fidelity simulation approach.

---

🎯 What It Does

1. Generates candidate structures by modifying known electrolytes (substitutions, doping)
2. Screens candidates through increasingly accurate (and expensive) simulations:
   • Level 0: Heuristic rules
   • Level 1: ML potentials (M3GNet-style)
   • Level 2: Semi-empirical QM (xTB-style)
   • Level 3: DFT (exports VASP/QE inputs)
3. Outputs ranked candidates with predicted properties and ready-to-run DFT files

---

🚀 Quick Start

# 1. Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# 2. Install dependencies
pip install -r requirements.txt

# 3. Run the discovery pipeline
python main.py

# 4. Check results
ls discovery_results/

---

📁 Project Structure

materials_agent/
├── main.py                 # Entry point - run this!
├── requirements.txt        # Python dependencies
├── README.md              # This file
│
├── src/
│   ├── __init__.py        # Package exports
│   ├── types.py           # Data structures (CrystalStructure, MaterialCandidate, etc.)
│   ├── constants.py       # Physical constants, reference electrolytes, substitution rules
│   ├── generator.py       # Structure generation (substitutions, doping)
│   ├── screening.py       # Tiered screening pipeline (Levels 0-3)
│   └── visualization.py   # Plotting and reports
│
├── data/                  # Input data (if any)
└── outputs/               # Generated results

---

🔧 Usage Options

# Basic run
python main.py

# Custom output directory
python main.py --output my_results

# Set conductivity target (S/cm)
python main.py --min-conductivity 1e-3

# Exclude expensive elements
python main.py --exclude-elements Ge La In

# Export DFT input files for top candidates
python main.py --export-dft

# Skip plot generation (faster)
python main.py --no-plots

# Full example
python main.py \
    --output discovery_2024 \
    --min-conductivity 1e-3 \
    --max-hull-energy 0.05 \
    --exclude-elements Ge In Ga \
    --export-dft

---

📊 Output Files

After running, you'll find:

discovery_results/
├── screening_report.txt      # Human-readable summary
├── final_candidates.json     # Structured data for all candidates
│
├── structures/               # Crystal structures
│   ├── CAND-00001.cif
│   ├── CAND-00002.cif
│   └── ...
│
├── plots/                    # Visualizations
│   ├── screening_funnel.png
│   ├── pareto_front.png
│   └── composition_analysis.png
│
└── dft_inputs/               # (if --export-dft)
    ├── CAND-00001/
    │   ├── vasp/
    │   │   ├── POSCAR
    │   │   ├── INCAR
    │   │   ├── KPOINTS
    │   │   └── POTCAR_README
    │   └── qe/
    │       └── pw.in
    └── ...

---

🧪 Upgrading to Real Simulations

The current implementation uses heuristic approximations. To use actual computational methods:

Level 1: ML Potentials (M3GNet)

pip install m3gnet matgl

# Then modify src/screening.py MLPotentialScreener to use:
from matgl.ext.ase import M3GNetCalculator
# ... actual structure relaxation and energy calculation

Level 2: Semi-empirical (xTB)

pip install xtb-python

# Then modify src/screening.py SemiempiricalScreener to use:
from xtb.interface import Calculator
# ... actual xTB calculations

Level 3: DFT

The DFT exporter already generates valid VASP and Quantum ESPRESSO input files. Submit these to your HPC cluster or cloud service:

# VASP
cd dft_inputs/CAND-00001/vasp
# Add POTCAR files
mpirun -np 16 vasp_std

# Quantum ESPRESSO
cd dft_inputs/CAND-00001/qe
mpirun -np 16 pw.x < pw.in > pw.out

---

🔋 Target: Solid-State Electrolytes

We focus on solid-state electrolytes because they're:

• Critical for next-gen batteries (EVs, grid storage)
• Computationally tractable (ionic conductivity is simulatable)
• High impact (major R&D investment from Toyota, QuantumScape, etc.)

Reference Materials

Material	Formula	σ (S/cm)	Notes
LGPS	Li₁₀GeP₂S₁₂	12 mS/cm	Best conductivity, expensive Ge
LLZO	Li₇La₃Zr₂O₁₂	0.5 mS/cm	Stable vs Li metal
Argyrodite	Li₆PS₅Cl	3 mS/cm	Good balance
NASICON	LiZr₂P₃O₁₂	0.1 mS/cm	Air stable

---

🧬 How Candidates Are Generated

1. Substitutions: Replace elements with similar ones

   • Ge → Si, Sn (cost reduction!)
   • S → Se, O (stability tuning)
   • Cl → Br, I (conductivity tuning)

2. Doping: Partial substitution to create vacancies/disorder

   • Al doping in LLZO stabilizes cubic phase
   • Ta doping increases conductivity

3. Compositional variations: Systematic exploration around known phases

---

📈 Interpreting Results

Key Properties

Property	Good Value	Why It Matters
Ionic conductivity	>1 mS/cm	Fast Li transport
Activation energy	<0.3 eV	Low T dependence
Energy above hull	<0.05 eV/atom	Thermodynamic stability
Band gap	>3 eV	Electronic insulator

Pareto Front

The Pareto plot shows the tradeoff between conductivity and stability. Points on the front are "optimal" — you can't improve one without sacrificing the other.

---

🛠️ Extending the Agent

Add New Reference Structures

Edit src/constants.py:

REFERENCE_ELECTROLYTES["my_new_material"] = {
    "formula": "Li3PS4",
    "structure_type": "orthorhombic",
    "lattice": {"a": 13.07, "b": 8.01, "c": 6.13, ...},
    "ionic_conductivity": 0.16e-3,
    ...
}

Add New Substitution Rules

Edit src/constants.py:

SUBSTITUTION_RULES["Zr"] = ["Ti", "Hf", "Sn", "Ce"]  # Add Ce as option

Custom Screening Criteria

Edit src/types.py DiscoveryConfig:

@dataclass
class DiscoveryConfig:
    min_ionic_conductivity: float = 1e-3  # More aggressive target
    max_cost_index: float = 5.0           # Add cost constraint
    ...

---

🤝 Integration with External Tools

Materials Project API

from mp_api.client import MPRester

with MPRester("your_api_key") as mpr:
    # Fetch real structures
    docs = mpr.summary.search(
        elements=["Li", "P", "S"],
        fields=["structure", "formation_energy_per_atom"]
    )

ASE (Atomic Simulation Environment)

from ase.io import read, write
from ase.optimize import BFGS

# Convert CIF to ASE Atoms
atoms = read("CAND-00001.cif")

# Attach calculator and optimize
atoms.calc = your_calculator
opt = BFGS(atoms)
opt.run(fmax=0.01)

---

📜 License

MIT License - Use freely for research and commercial purposes.

---

🔮 Roadmap

• Integration with Materials Project API for real structure data
• M3GNet/CHGNet integration for Level 1
• xTB integration for Level 2
• Autonomous hypothesis-test loop (LLM-guided)
• Active learning for efficient exploration
• Web interface for interactive discovery

---

📚 References

1. M3GNet: Chen et al., Nature Computational Science (2022)
2. ALIGNN: Choudhary et al., npj Computational Materials (2021)
3. Materials Project: Jain et al., APL Materials (2013)
4. Solid-state electrolytes review: Janek & Zeier, Nature Energy (2016)

---

Built with 🔬 by the Materials Discovery Agent