How ilgarbaghishov/mpelectroml works
Project type and purpose
• MPElectroML is a Python library/tool for materials-science automation. It:
• Fetches electrode structures from the Materials Project via its REST API
• Substitutes working ions (Li→Na, K, Mg, Ca) in host structures
• Applies machine-learned interatomic potentials (from FAIRChem) to compute energies/forces
• Persists results in HDF5 for downstream analysis
• There is no web UI or microservice tier—it’s a data-processing pipeline wrapped in a library plus example scripts.
File structure
Top level:
• mpelectroml/ (core package)
– data_retrieval.py
– structure_manipulation.py
– calculations.py
– utils.py
• examples/
– run_analysis.py (orchestrates the end-to-end pipeline)
– run.sh
• docs/ (user/developer documentation)
• tests/ (unit tests for structure manipulation)
• CI config (.github/workflows/ci.yml)
• pyproject.toml (build/packaging)
• README.md, LICENSE
Extracted architectural insights from README
• Modules map cleanly to pipeline stages: retrieval → modification → calculation → persistence
• External dependencies:
• Materials Project API (network service)
• FAIRChem MLIP models (local Python library + GPU/PyTorch)
• Pymatgen for structure objects
• HDF5 for data storage
1. “User Script / CLI”
– examples/run_analysis.py or any client code
2. “Data Retrieval Module”
– mpelectroml.data_retrieval
– fetch_electrode_pairs(), get_structures_from_electrode_pair_ids()
3. “Structure Manipulation Module”
– mpelectroml.structure_manipulation
– create_new_working_ion_discharge_structures()
4. “MLIP Calculation Module”
– mpelectroml.calculations
– add_energy_forces_to_df()
5. “Persistence Layer”
– mpelectroml.utils (HDF5 writer/reader)
– HDF5 files on disk
6. “External Services / Libraries”
– Materials Project REST API
– FAIRChem (fairchem.core + PyTorch)
– Pymatgen
1. Script → calls Data Retrieval Module
2. Data Retrieval → HTTP GET → Materials Project API → returns JSON → Data Retrieval → Pymatgen Structure objects
3. Data Retrieval → outputs initial dataset → passed to Structure Manipulation
4. Structure Manipulation → transforms Structures → returns new structures
5. Calculation Module → takes Structures → invokes FAIRChem MLIP → PyTorch → returns energies & forces
6. Each stage → writes intermediate or final data to HDF5 via Persistence Layer
7. Script → reads final HDF5 for reporting
c. Architectural patterns & design principles
• Pipeline pattern: sequential stages (retrieve → transform → compute → store)
• Module separation: each core function in its own module (single responsibility)
• Resumable workflow: Persistence Layer checkpoints data between stages
• Extensibility: New MLIPs or ion substitutions can be added via plugin-style modules
d. Key technologies/frameworks
• Python 3.10+
• Pymatgen (structure I/O)
• Requests or MPRester (Materials Project API client)
• FAIRChem/Core (MLIP inference)
• PyTorch
• h5py or pandas HDFStore
• pytest for tests
• GitHub Actions for CI