optixcel 3.0.0

Optixcel v3.0: 4 GOD-Level Intelligence Features for Optical Property Prediction

OptixCel v2.0 - Advanced Optical Material Prediction

🧠 Revolution in Optical Property Prediction

OptixCel v2.0 is a production-ready machine learning library for fast and accurate optical property prediction of materials. It features 4 revolutionary GOD-level intelligence systems that NO other ML model in the world has.

⚡ Key Features

1. 🎯 Ensemble Disagreement Intelligence

Analyzes prediction disagreement across all wavelength-specific ensemble models to detect boundary cases and uncertain predictions. Physics-aware weighting ensures reliable confidence scoring.

• Detects boundary cases automatically
• Provides confidence scores for each optical property
• Recommends DFT validation when needed
• Energy-dependent wavelength trust weighting

2. 💰 DFT Cost Estimator

Compares computational expense of DFT methods vs OptixCel speedup. Provides cost breakdown and real-time computational savings.

• Supports PBE, HSE06, G0W0, PBE+SOC functionals
• Calculates CPU hours, wall time, and USD cost
• Shows speedup factors (often 100,000x or more)
• Recommends when to use OptixCel vs DFT

3. ⚛️ Kramers-Kronig Physics Validator

Enforces fundamental physics laws on optical spectra using Hilbert transform-based validation. Auto-corrects violations to ensure physics consistency.

• Validates Kramers-Kronig relations
• Detects physics violations
• Auto-corrects predictions with blended approach
• Provides KK consistency scores

4. 🧠 Master Advanced Predictor (OptixCelAdvanced)

Integrates all features above with wavelength-specific ensemble models. Generates comprehensive optical property predictions with automated error handling.

• 80 wavelength-specific RandomForest models
• Supports 8+ optical properties: absorption, dielectric, reflectivity, etc.
• Generates predictions across visible-to-IR spectrum (300nm-2000nm)
• Production-ready error handling and validation

---

📦 Installation

pip install optixcel

Or from source:

git clone https://github.com/wajdan/optixcel
cd optixcel
pip install -e .

---

🚀 Quick Start

Basic Usage

import numpy as np
from optixcel import OptixCelAdvanced

# Initialize model
model = OptixCelAdvanced(
    models_dir="./models",
    base_model_path="./optixcel_fast_model.pkl"
)

# Prepare input (27 material features)
X = np.random.randn(1, 27) * 0.5 + 2.0

# Energy array for wavelength coverage
energy = np.linspace(0.5, 6.0, 50)

# Run prediction with all GOD-level features
result = model.predict_advanced(
    X=X,
    material_formula="MAPbI3",
    num_atoms=12,
    energy_array=energy,
    dft_functional="HSE06",
    run_kk_check=True,        # Enable physics validation
    run_disagreement=True,     # Enable ensemble analysis
    run_cost_estimate=True     # Enable DFT cost calculation
)

# Display results
print(result.summary())

Feature 1: Ensemble Disagreement Analysis

if result.disagreement:
    for property_name, analysis in result.disagreement.items():
        print(f"{property_name}:")
        print(f"  Confidence: {analysis.confidence_score:.1f}%")
        print(f"  Is boundary case: {analysis.is_boundary_case}")
        print(f"  DFT recommended: {analysis.dft_recommended}")

Feature 2: DFT Cost Estimation

if result.dft_cost:
    print(f"CPU hours needed: {result.dft_cost.cpu_hours:.0f}")
    print(f"Estimated cost: ${result.dft_cost.usd_cost:.2f}")
    print(f"Speedup vs OptixCel: {result.dft_cost.speedup_factor:.0f}x")
    print(f"Recommendation: {result.dft_cost.recommendation}")

Feature 3: Kramers-Kronig Validation

if result.kk_validation:
    print(f"Physics consistent: {result.kk_validation.is_consistent}")
    print(f"KK score: {result.kk_validation.kk_score:.4f}")
    print(f"Auto-correction applied: {result.kk_validation.auto_correction_applied}")
    if result.kk_validation.physics_violations:
        print(f"Violations detected: {result.kk_validation.physics_violations}")

Feature 4: Advanced Predictions

predictions = result.predictions
for wavelength_nm, properties in predictions.items():
    for prop_name, value in properties.items():
        print(f"{prop_name} @ {wavelength_nm}: {value:.6f}")

---

📊 Supported Optical Properties

OptixCel predicts the following optical properties across UV-Vis-IR spectrum:

Property	Range	Unit
absorption_coeff	0-10000	cm⁻¹
dielectric_real	1-15	-
dielectric_imag	0-5	-
extinction_k	0-2	-
refractivity_n	1-4	-
reflectivity	0-1	-
optical_conductivity	0-10000	S/cm
energy_loss_function	0-1	-

---

📈 Performance Benchmarks

Prediction Speed

• Per sample (27 features): ~5-10 milliseconds
• 100 samples: ~0.5-1 second
• DFT equivalent: 8-14 CPU hours per sample

Accuracy

• Mean Absolute Error: 5-15% across properties
• R² Score: 0.85-0.95 depending on property
• Physics compliance: 95%+ after KK correction

---

🔧 Configuration

Input Requirements

X : array-like, shape (n_samples, 27)
    Material features (normalized to mean=0, std=1 recommended)

material_formula : str
    Chemical formula (e.g., 'MAPbI3', 'CsPbBr3')

num_atoms : int
    Total number of atoms in unit cell

energy_array : array-like
    Energy values in eV for wavelength mapping

dft_functional : str, optional
    DFT functional: 'PBE', 'HSE06', 'G0W0', 'PBE+SOC'
    Default: 'HSE06'

Optional Parameters

run_kk_check : bool, default=True
    Enable Kramers-Kronig physics validation

run_disagreement : bool, default=True
    Enable ensemble disagreement analysis

run_cost_estimate : bool, default=True
    Enable DFT cost estimation

verbose : bool, default=False
    Print detailed debug information

---

📚 API Reference

OptixCelAdvanced

Class: optixcel.predict_advanced.OptixCelAdvanced

OptixCelAdvanced(
    models_dir: str = "models",
    base_model_path: str = "optixcel_fast_model.pkl",
    verbose: bool = False
)

Methods:

• predict_advanced(X, material_formula, num_atoms, energy_array, ...) → AdvancedPredictionResult
• predict(X) → ndarray (base model only)
• load_models() → None

EnsembleDisagreementAnalyzer

Class: optixcel.intelligence.EnsembleDisagreementAnalyzer

analyzer = EnsembleDisagreementAnalyzer(
    models_dict: dict,
    energy_range: tuple = (0.5, 6.0)
)

DFTCostEstimator

Class: optixcel.intelligence.DFTCostEstimator

estimator = DFTCostEstimator(material_formula: str, num_atoms: int)
cost = estimator.estimate_cost(dft_functional: str = "HSE06")

KramersKronigValidator

Class: optixcel.physics.KramersKronigValidator

validator = KramersKronigValidator(energy_array: ndarray)
result = validator.validate_and_correct(
    epsilon_real: ndarray,
    epsilon_imag: ndarray
)

---

🎯 Use Cases

Materials Science

• Predicting optical bandgap
• Estimating absorption coefficients
• Designing solar cells and LEDs

Computational Chemistry

• Fast pre-screening before DFT calculations
• Identifying promising materials for experimental synthesis
• Material property optimization

Industry Applications

• Photovoltaic materials screening
• Optical coating design
• LED phosphor development

---

⚖️ License

MIT License - See LICENSE file for details

---

📧 Support & Contact

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• Email: [e-mail]

---

🙏 Acknowledgments

OptixCel v2.0 builds on advances in:

• Ensemble machine learning methods
• Physics-informed neural networks
• Kramers-Kronig relations in condensed matter physics
• Optical materials database compilation

---

📝 Citation

If you use OptixCel in your research, please cite:

@software{optixcel2024,
  author = {Optixcel Development Team},
  title = {OptixCel v2.0: Advanced Optical Material Prediction with GOD-Level Intelligence},
  year = {2024},
  url = {https://github.com/wajdan/optixcel}
}

---

🚀 Version History

v2.0.0 (Current) - April 2024

• 4 GOD-level intelligence features
• Ensemble disagreement analysis
• DFT cost estimation
• Kramers-Kronig validation
• Master advanced predictor
• Full type hints and error handling

v1.x

• Basic fast ensemble model
• Wavelength-specific RandomForest models
• Standard optical property prediction

---

OptixCel: Making optical materials research faster, smarter, and more intelligent. 🧠✨