Upload README.md

README.md

@@ -0,0 +1,279 @@
+---
+title: "MoMa: Modular Deep Learning Framework for Material Property Prediction"
+emoji: 🧪
+colorFrom: blue
+colorTo: purple
+sdk: static
+pinned: false
+license: mit
+tags:
+- materials-science
+- deep-learning
+- modular-framework
+- property-prediction
+- pytorch
+---
+
+# 🧪 MoMa: Modular Deep Learning Framework for Material Property Prediction
+
+<div align="center">
+
+[![arXiv](https://img.shields.io/badge/arXiv-2502.15483-b31b1b.svg)](https://arxiv.org/abs/2502.15483)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-ee4c2c.svg)](https://pytorch.org/)
+[![HuggingFace Models](https://img.shields.io/badge/🤗-Models-yellow)](https://huggingface.co/yuanhangtangle-air/moma-modules)
+
+**[📄 Paper](https://arxiv.org/abs/2502.15483) | [🌐 Project Page](https://yuanhangtangle-air.github.io/moma-modules/) | [💻 Code](https://github.com/your-repo) | [📊 Datasets](https://huggingface.co/datasets/your-datasets)**
+
+</div>
+
+## 🚀 Overview
+
+MoMa introduces a revolutionary **modular approach** to material property prediction that fundamentally shifts from traditional pre-training paradigms. Instead of using a single pre-trained model fine-tuned for each task, MoMa trains specialized modules across diverse material properties and adaptively composes them for downstream applications.
+
+### 🎯 Key Achievements
+- **🏆 State-of-the-art performance** on 17 material property prediction datasets
+- **📈 14% average improvement** over strongest baselines
+- **🔧 107 specialized modules** covering major material property domains
+- **⚡ Superior few-shot** and continual learning capabilities
+
+### 🧠 Why MoMa?
+
+| Traditional Approach | MoMa Framework |
+|---------------------|----------------|
+| Single pre-trained model → Fine-tune | Multiple specialized modules → Adaptive composition |
+| Limited task specificity | Task-specific optimization |
+| Poor generalization to new properties | Enhanced generalization through modularity |
+| High computational cost for each task | Efficient module reuse and composition |
+
+## 📦 Available Modules (107 Total)
+
+Our repository contains **107 pre-trained modules** spanning **6 major domains** of material science:
+
+### 📊 Module Distribution by Domain
+
+| Domain | Count | Description |
+|--------|-------|-------------|
+| **🔬 Electronic Structure** | 28 | Band gaps, HOMO-LUMO, DOS, dielectric properties |
+| **🌡️ Thermodynamics** | 20 | Formation energy, Gibbs free energy, stability |
+| **⚗️ Spectroscopy** | 24 | EXAFS, XANES spectral features |
+| **🧲 Mechanical** | 8 | Elastic moduli, piezoelectric properties |
+| **🔋 Photovoltaic** | 8 | Solar cell performance metrics |
+| **🌊 Adsorption** | 8 | Gas adsorption in MOFs |
+| **⚡ Thermoelectric** | 8 | Seebeck coefficients, thermal conductivity |
+| **🔍 Other Properties** | 3 | Specialized material characteristics |
+
+### 🔍 Featured Modules
+
+<details>
+<summary><strong>🔬 Electronic Structure Modules</strong></summary>
+
+| Module | Property | Description |
+|--------|----------|-------------|
+| `HL_Gap.pt` | HOMO-LUMO Gap | Electronic band gap prediction |
+| `HOMO_Energy.pt` | HOMO Energy | Highest occupied molecular orbital energy |
+| `LUMO_Energy.pt` | LUMO Energy | Lowest unoccupied molecular orbital energy |
+| `Polarizability.pt` | Polarizability | Electron cloud deformation under external field |
+| `jarvis_bandgap.pt` | Band Gap | Fundamental electronic property |
+| `mp_bandgap.pt` | Material Band Gap | Electronic structure parameter |
+
+</details>
+
+<details>
+<summary><strong>🌡️ Thermodynamics Modules</strong></summary>
+
+| Module | Property | Description |
+|--------|----------|-------------|
+| `jarvis_eform.pt` | Formation Energy | Thermodynamic stability indicator |
+| `mp_eform.pt` | Formation Energy | Energy of formation from elements |
+| `gibbs_free_energy.pt` | Gibbs Free Energy | Chemical reaction spontaneity |
+| `surface_energy.pt` | Surface Energy | Cost of creating new surfaces |
+| `mp_energy_above_hull.pt` | Energy Above Hull | Phase stability metric |
+
+</details>
+
+<details>
+<summary><strong>⚗️ Spectroscopy Modules</strong></summary>
+
+| Module | Property | Description |
+|--------|----------|-------------|
+| `spec_EXAFS_Fe_EdgeEnergy.pt` | EXAFS Edge Energy | Iron K-edge absorption |
+| `spec_XANES_Co_PeakHeight.pt` | XANES Peak Height | Cobalt absorption intensity |
+| `spec_EXAFS_Cu_WhiteLineHeight.pt` | White Line Height | Copper spectral feature |
+
+</details>
+
+## 🛠️ Installation & Usage
+
+### Quick Start
+
+```bash
+# Install required packages
+pip install torch huggingface_hub pandas tqdm
+
+# Clone or download the modules
+git clone https://huggingface.co/yuanhangtangle-air/moma-modules
+```
+
+### 📥 Download Individual Modules
+
+```python
+import shutil
+from huggingface_hub import hf_hub_download
+
+# Download a specific module
+cached_file = hf_hub_download(
+    repo_id="yuanhangtangle-air/moma-modules",
+    filename="Dipole_M.pt",  # Replace with desired module
+    repo_type="model"
+)
+
+# Copy to your local directory
+save_path = "./moma-hub/"
+shutil.copy(cached_file, save_path)
+```
+
+### 📦 Download All Modules
+
+```python
+import shutil
+import pandas as pd
+from huggingface_hub import hf_hub_download
+from tqdm import tqdm
+
+# Load module list
+module_info_url = "https://huggingface.co/yuanhangtangle-air/moma-modules/resolve/main/domain-dataset-concept-en.csv"
+df = pd.read_csv(module_info_url)
+module_list = df['Dataset']
+
+# Download all modules
+cached_files = []
+for module_name in tqdm(module_list, desc="Downloading modules"):
+    cached_file = hf_hub_download(
+        repo_id="yuanhangtangle-air/moma-modules",
+        filename=f"{module_name}.pt",
+        repo_type="model"
+    )
+    cached_files.append(cached_file)
+
+# Copy to local directory
+save_path = "./moma-hub/"
+for cached_file in cached_files:
+    shutil.copy(cached_file, save_path)
+```
+
+### 🚀 Using MoMa Framework
+
+```python
+# Import the framework (pseudo-code - actual implementation may vary)
+from moma import MaterialPropertyPredictor, ModularNetwork
+
+# Initialize with pre-trained modules
+model = MaterialPropertyPredictor(
+    network=ModularNetwork.from_pretrained('material-property-base'),
+    modules=['structure_encoder', 'property_decoder']
+)
+
+# Load your material data
+materials = load_material_dataset('your_dataset.csv')
+
+# Train the model
+model.train(materials, epochs=100, batch_size=32)
+
+# Make predictions
+predictions = model.predict(new_materials)
+
+# Evaluate performance
+metrics = model.evaluate(test_materials)
+print(f"Accuracy: {metrics['accuracy']:.3f}")
+```
+
+## 📊 Performance Results
+
+Our experimental evaluation across **17 datasets** demonstrates MoMa's superior performance:
+
+- 🥇 **Rank 1.35** average ranking among 5 competing methods
+- 🏆 **14/17 tasks** achieve state-of-the-art performance  
+- 📈 **14% average improvement** over strongest baseline
+- ⚡ **Superior few-shot learning** capabilities
+- 🔄 **Excellent continual learning** performance
+
+## 📁 Module File Structure
+
+```
+moma-modules/
+├── README.md                           # This file
+├── domain-dataset-concept-en.csv       # Module descriptions
+├── Electronic_Structure/               # 28 modules
+│   ├── HL_Gap.pt
+│   ├── HOMO_Energy.pt
+│   ├── LUMO_Energy.pt
+│   └── ...
+├── Thermodynamics/                     # 20 modules
+│   ├── jarvis_eform.pt
+│   ├── gibbs_free_energy.pt
+│   └── ...
+├── Spectroscopy/                       # 24 modules
+│   ├── spec_EXAFS_Fe_EdgeEnergy.pt
+│   ├── spec_XANES_Co_PeakHeight.pt
+│   └── ...
+└── Other_Domains/                      # 35 modules
+    ├── Mechanical/
+    ├── Photovoltaic/
+    ├── Adsorption/
+    ├── Thermoelectric/
+    └── ...
+```
+
+## 🔬 Research Impact
+
+### 📝 Citation
+
+If you use MoMa in your research, please cite our paper:
+
+```bibtex
+@article{wang2025moma,
+  title={MoMa: A Modular Deep Learning Framework for Material Property Prediction},
+  author={Wang, Botian and Ouyang, Yawen and Li, Yaohui and Wang, Yiqun and Cui, Haorui and Zhang, Jianbing and Wang, Xiaonan and Ma, Wei-Ying and Zhou, Hao},
+  journal={arXiv preprint arXiv:2502.15483},
+  year={2025}
+}
+```
+
+### 🌟 Key Contributions
+
+1. **Novel Modular Paradigm**: First framework to replace pre-training with specialized module composition
+2. **Comprehensive Evaluation**: Extensive benchmarking across 17 diverse material property datasets
+3. **Open Science**: All 107 modules freely available to accelerate materials discovery
+4. **Superior Performance**: Consistent improvements over traditional approaches
+
+## 🤝 Community & Support
+
+- 📧 **Contact**: [Your contact information]
+- 🐛 **Issues**: [Report bugs or request features]
+- 💬 **Discussions**: [Community discussions]
+- 📚 **Documentation**: [Detailed documentation]
+
+## 📜 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+We gratefully acknowledge the materials science community and the datasets that made this research possible. Special thanks to:
+
+- Materials Project (MP)
+- Open Quantum Materials Database (OQMD)
+- Joint Automated Repository for Various Integrated Simulations (JARVIS)
+- And all other data contributors
+
+---
+
+<div align="center">
+
+**🌟 Star this repository if you find it useful! 🌟**
+
+**🚀 Accelerating Materials Discovery Through Modular AI 🚀**
+
+</div>