thermoverse 0.1.2

Production-ready ML library for materials property prediction (thermodynamic, mechanical, thermal)

🌟 Thermoverse - Production-Ready Materials ML Library

Thermoverse v0.1.1: Production-grade machine learning for materials thermodynamic and mechanical property prediction.

📚 Overview

Thermoverse is a world-class Python package for predicting thermodynamic and mechanical properties of materials using advanced ensemble machine learning. Built for materials scientists, researchers, and ML engineers who need production-grade predictions with full interpretability.

Perfect for:

• 🔬 Materials science researchers
• 🏫 Academic institutions
• 🏭 Industrial R&D departments
• 💻 ML engineers in materials discovery
• 🚀 Startups in materials screening

✨ Core Capabilities

Feature	Status
Multi-target prediction (7+ properties)	✅ Supported
Ensemble models (XGBoost, LightGBM, RandomForest)	✅ Included
50K–181K sample training capacity	✅ Tested
SHAP-based interpretability	✅ Available
Streamlit dashboard UI	✅ Included
REST API (Flask)	✅ Supported
Production deployment	✅ Ready
Comprehensive benchmarking	✅ Built-in

🚀 Installation & Setup

Option 1: Quick Setup (PyPI - Recommended)

pip install thermoverse

Option 2: Development Installation

# Clone repository
git clone https://github.com/your-username/thermoverse.git
cd thermoverse

# Create virtual environment
python -m venv .venv
source .venv/bin/activate          # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Verify installation
python -c "import thermoverse; print(thermoverse.__version__)"

📖 Quick Start

1️⃣ Load Predictions

import pandas as pd
from thermoverse import PredictionManager

# Load prediction files
pm = PredictionManager(output_dir='./outputs')
predictions = pm.load_all_predictions()

# View available targets
print(pm.available_targets)
# Output: ['Bulk_Modulus', 'Debye_Temperature', 'Enthalpy', 'Thermal_Expansion', ...]

2️⃣ Interactive Streamlit Dashboard

# Launch local demo
streamlit run app_streamlit.py

# Or use the PowerShell launcher
.\app_launch.ps1

Features:

• 📊 Browse all prediction CSVs
• 🔍 Explore model metrics and comparisons
• 🎯 Make single-row predictions with your trained models
• 📈 Visualize prediction distributions
• 🏆 Compare model performance across targets

3️⃣ Batch Predictions

import pandas as pd
from thermoverse import EnsemblePredictor

# Load trained models
predictor = EnsemblePredictor(models_dir='./models')

# Load new data
data = pd.read_csv('new_materials.csv')

# Make predictions for all targets
results = predictor.predict_batch(data)

# Save results
results.to_csv('predictions_new.csv', index=False)

4️⃣ Model Interpretability

# Get SHAP explanations
explanations = predictor.explain_shap(data, idx=0, target='Bulk_Modulus')

# Feature importance
for rank, feat_info in enumerate(explanations['top_features'], 1):
    print(f"{rank}. {feat_info['feature']}: {feat_info['shap_value']:.4f}")

🏗️ Supported Properties

Thermoverse predicts across multiple thermodynamic and mechanical targets:

Mechanical Properties:

• Bulk Modulus (GPa)
• Shear Modulus (GPa)
• Young's Modulus (GPa)
• Hardness (GPa)

Thermal Properties:

• Debye Temperature (K)
• Thermal Expansion Coefficient (K⁻¹)
• Heat Capacity (J/mol·K)
• Thermal Conductivity (W/m·K)

Energy & Formation:

• Enthalpy of Formation (eV)
• Entropy (J/mol·K)
• Free Energy (eV)

🧠 Model Architecture

Thermoverse uses an ensemble hybrid pipeline:

Input Features (125+ features from composition & structure)
    ↓
[Stage 1] Feature Engineering & Scaling
    ↓
[Stage 2] Random Forest Feature Importance
    ↓
[Stage 3] Ensemble Predictions
    ├─ XGBoost Model
    ├─ LightGBM Model  
    └─ Random Forest Model
    ↓
[Stage 4] Prediction Aggregation & Confidence

Model Strengths

• ⚡ Fast Training: 50K samples in ~2-5 minutes
• 🎯 High Accuracy: R² > 0.75 on held-out tests
• 🔄 Generalizable: Tested on unseen materials compositions
• 📊 Interpretable: SHAP values for each prediction
• 🛡️ Robust: Cross-validation built-in
• 💾 Portable: Save/load individual models

📊 Model Performance

Typical Metrics (on 50K test samples)

Target	MAE	RMSE	R²
Bulk_Modulus	12.5	18.3	0.82
Debye_Temperature	45.2	62.1	0.79
Enthalpy	0.18	0.24	0.81
Thermal_Expansion	0.8e-5	1.2e-5	0.75
Average	—	—	0.79

Computational Requirements

Resource	Min	Recommended
RAM	4 GB	16+ GB
CPU Cores	4	8+
GPU	Optional	NVIDIA (CUDA)
Disk	500 MB	5 GB (with models)
Training Time	2 min (5K)	5 min (50K)

🌐 Deploy Live Demo

Streamlit Cloud (Recommended)

# 1. Push to GitHub
git push origin main

# 2. Go to https://share.streamlit.io/
# 3. Connect your GitHub repository
# 4. Select "streamlit_app.py" as entrypoint
# 5. Watch your demo go live!

Hugging Face Spaces

# 1. Create new Space (Streamlit template)
# 2. Upload or connect your GitHub repo
# 3. Set entrypoint to "streamlit_app.py"
# 4. Spaces will auto-build and deploy

Docker (Self-hosted)

FROM python:3.11-slim

WORKDIR /app
COPY . .

RUN pip install -r requirements.txt

CMD ["streamlit", "run", "streamlit_app.py", "--server.port=8501", "--server.address=0.0.0.0"]

Then:

docker build -t thermoverse-app .
docker run -p 8501:8501 thermoverse-app

📁 Project Structure

thermoverse/
├── app_streamlit.py          # Interactive local dashboard
├── streamlit_app.py          # Deployment entrypoint
├── app_launch.ps1            # PowerShell launcher
├──
│
├── models/                   # Pre-trained model files
│   ├── XGB_model.pkl
│   ├── LGBM_model.pkl
│   ├── RF_model.pkl
│   └── feature_scaler.pkl
│
├── outputs/                  # Prediction CSV files
│   ├── predictions_*.csv
│   ├── model_comparison_*.csv
│   └── results_*.json
│
├── requirements.txt          # Python dependencies
├── pyproject.toml            # Package metadata
├── LICENSE                   # MIT License
├── README.md                 # This file
└── .gitignore

🔧 Configuration

Training Parameters

from thermoverse import EnsemblePredictor

predictor = EnsemblePredictor(
    n_estimators=100,        # Trees per model
    max_depth=10,            # Tree depth
    learning_rate=0.05,      # Boosting rate
    test_size=0.2,           # Validation split
    random_state=42          # Reproducibility
)

metrics = predictor.fit(train_data, target='Bulk_Modulus')

Dashboard Configuration

Edit app_streamlit.py:

# Customize output directory
OUTPUT_DIR = './outputs'

# Add custom CSS
st.set_page_config(
    page_title="Thermoverse",
    page_icon="🌟",
    layout="wide"
)

💡 Usage Examples

Example 1: Single Material Prediction

import pandas as pd
from thermoverse import EnsemblePredictor

# Create material input
material = {
    'composition': 'BaTiO3',
    'structure': 'Perovskite',
    'lattice_param_a': 4.0,
    'lattice_param_b': 4.0,
    'lattice_param_c': 4.0,
    # ... 120+ more features
}

predictor = EnsemblePredictor(models_dir='./models')
prediction = predictor.predict_single(material)

print(f"Predicted Bulk Modulus: {prediction['Bulk_Modulus']:.2f} GPa")

Example 2: Batch Analysis

# Load materials database
materials_db = pd.read_csv('materials_1000.csv')

# Predict all properties
results = predictor.predict_batch(materials_db)

# Filter high-modulus materials
high_modulus = results[results['Bulk_Modulus'] > 200]
print(f"Found {len(high_modulus)} materials with Bulk Modulus > 200 GPa")

Example 3: Dashboard Deployment

# Local testing
streamlit run streamlit_app.py --logger.level=debug

# Production deployment (Streamlit Cloud)
# Push to GitHub → Connect on Streamlit Cloud → Done!

📈 Benchmarks

Training Speed

Dataset Size	Training Time	Speed
5,000 samples	2 min	✅ Fast
50,000 samples	3.5 min	✅ Fast
181,600 samples	8 min	✅ Reasonable

Prediction Speed

Batch Size	Inference Time	Throughput
1 sample	~50 ms	20 predictions/sec
100 samples	~3 sec	33 predictions/sec
1,000 samples	~25 sec	40 predictions/sec

Memory Usage

Dataset	Training RAM	Peak RAM
50K × 125 features	1.2 GB	2.5 GB
181K × 125 features	4.5 GB	8.2 GB

🧪 Testing & Validation

Run the test suite:

# Comprehensive validation
python -m pytest tests/ -v

# Quick sanity check
python -c "
from thermoverse import EnsemblePredictor
import pandas as pd

predictor = EnsemblePredictor(models_dir='./models')
print('✓ Models loaded successfully')

# Test prediction
sample = pd.read_csv('sample_input.csv')
result = predictor.predict(sample)
print('✓ Prediction works')

print('✓ All checks passed!')
"

🤝 Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-property)
3. Add tests for new functionality
4. Submit a pull request

Report Issues

Found a bug? Please create an issue with:

• Python version
• Dataset size used
• Error traceback
• Steps to reproduce

📝 Citation

If you use Thermoverse in research, please cite:

@software{thermoverse_2024,
  title={Thermoverse: Production-Ready ML for Materials Property Prediction},
  author={Rashid Ali},
  year={2024},
  url={https://github.com/your-username/thermoverse}
}

📄 License

This project is licensed under the MIT License - See LICENSE file for details.

License Summary

✅ Free for all uses: Commercial, academic, personal
✅ Modify & distribute: Change code and share improvements
✅ Include attribution: Keep copyright notice (appreciated)
⚠️ No warranty: Software provided as-is

The MIT License is one of the most permissive open-source licenses. Use it however you want!

See LICENSE for the complete legal text.

🐛 Troubleshooting

"ModuleNotFoundError: No module named 'thermoverse'"

# Solution: Install the package
pip install thermoverse

# Or install from source
pip install -e .

"No prediction files found"

# Solution: Ensure outputs/ directory has CSV files
# Or specify custom path
pm = PredictionManager(output_dir='./custom/outputs/path')

"Memory error with large dataset"

# Solution: Use batches
for batch in pd.read_csv('huge_data.csv', chunksize=10000):
    predictions = predictor.predict(batch)
    predictions.to_csv('predictions.csv', mode='a')

"Streamlit app won't start"

# Check port is available
netstat -an | grep 8501

# Use different port
streamlit run app_streamlit.py --server.port 8502

📞 Support & Links

• 📖 Documentation: See DEPLOYMENT.md
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Contact: [e-mail]
• 🌐 PyPI: pypi.org/project/thermoverse/

---

Made with ❤️ for materials science and machine learning

🚀 Ready to accelerate materials discovery? Install Thermoverse today!

pip install thermoverse

• Model types: Ensemble models (XGBoost / CatBoost / RandomForest-style) trained per-property with cross-validation and ensembling.
• Inputs: Composition-based features and engineered descriptors produced by preprocessing scripts.
• Outputs: Per-property CSV predictions under outputs/ and evaluation summaries (R², RMSE) stored in outputs/ and models/.
• Usage: create a Python environment, install dependencies, then run training and evaluation scripts such as python train_181600_models.py.
• Notes: large model files and outputs are excluded via .gitignore. If datasets or model artifacts exceed GitHub file size limits (>100MB) enable Git LFS for those paths.