Predictors

Predictors are machine learning models that predict material properties from structural and compositional information. They enable rapid property screening and virtual materials testing without expensive computations. All predictors implement the BasePredictor interface with a standardized predict() method.

Available Predictors

MatterSim - Materials Simulation Predictor

ID: mattersim

Comprehensive predictor for materials properties using advanced simulation techniques.

Capabilities:

  • Multi-property prediction

  • Electronic structure properties

  • Mechanical and thermal properties

  • Uncertainty quantification

Input Parameters:

  • structure: Crystal structure (CIF or POSCAR)

  • properties: List of properties to predict

  • calculation_level: Accuracy vs. speed trade-off

  • temperature: Temperature conditions (optional)

Output Properties:

  • Formation energy (eV/atom)

  • Band gap (eV)

  • Bulk modulus (GPa)

  • Density (g/cm³)

  • Thermal conductivity (W/mK)

Accuracy: DFT-level accuracy for most properties Speed: ~1-10 seconds per prediction

Use Cases:

  • High-throughput materials screening

  • Property validation for generated materials

  • Multi-property optimization

M3GNet - Materials 3D Graph Network

ID: m3gnet

Graph neural network predictor with state-of-the-art accuracy for materials properties.

Capabilities:

  • Graph-based structure representation

  • Force and energy predictions

  • Transferable across material types

  • Molecular dynamics integration

Input Parameters:

  • structure: Atomic structure

  • property_list: Target properties

  • ensemble_prediction: Use ensemble for uncertainty

  • cutoff_radius: Graph construction radius

Output Properties:

  • Total energy (eV)

  • Atomic forces (eV/Å)

  • Stress tensor (GPa)

  • Elastic constants (GPa)

  • Phonon properties

Accuracy: Near-DFT accuracy for energies and forces Speed: ~0.1-1 seconds per prediction

Use Cases:

  • Structure relaxation and optimization

  • Molecular dynamics simulations

  • Elastic property calculations

PFP - Property Fingerprint Predictor

ID: pfp

Fast predictor using structural fingerprints for rapid property estimation.

Capabilities:

  • Ultra-fast predictions

  • Wide range of properties

  • Composition and structure-based

  • Explainable predictions

Input Parameters:

  • composition: Chemical composition

  • structure: Crystal structure (optional)

  • fingerprint_type: Type of structural fingerprint

  • property_targets: Properties to predict

Output Properties:

  • Formation energy (eV/atom)

  • Band gap (eV)

  • Density (g/cm³)

  • Hardness (GPa)

  • Melting point (K)

Accuracy: Good accuracy for screening purposes Speed: ~0.01-0.1 seconds per prediction

Use Cases:

  • Rapid initial screening

  • Large-scale database analysis

  • Real-time property estimation

DeepMD - Deep Molecular Dynamics

ID: deepmd

Deep learning potential for molecular dynamics and property predictions.

Capabilities:

  • Accurate force field generation

  • Long-timescale MD simulations

  • Temperature-dependent properties

  • Phase transition studies

Input Parameters:

  • structure: Initial structure

  • simulation_time: MD simulation length

  • temperature: Simulation temperature

  • pressure: Simulation pressure

  • ensemble: MD ensemble (NVT, NPT, etc.)

Output Properties:

  • Dynamic properties (diffusion, viscosity)

  • Thermal properties (heat capacity, expansion)

  • Phase stability at conditions

  • Transport properties

Accuracy: High accuracy for dynamic properties Speed: ~minutes to hours for full MD

Use Cases:

  • Finite temperature property prediction

  • Phase diagram construction

  • Transport property calculation

SynthNN - Synthesis Neural Network

ID: synthnn

Predictor specialized in synthesizability and synthetic accessibility.

Capabilities:

  • Synthesizability scoring

  • Synthesis route prediction

  • Precursor identification

  • Reaction condition estimation

Input Parameters:

  • target_structure: Material to synthesize

  • available_precursors: List of available starting materials

  • synthesis_method: Preferred synthesis approach

  • temperature_range: Allowed temperature range

Output Properties:

  • Synthesizability score (0-1)

  • Predicted synthesis routes

  • Required precursors

  • Estimated synthesis conditions

  • Difficulty assessment

Accuracy: High accuracy for known material classes Speed: ~1-5 seconds per prediction

Use Cases:

  • Synthesis planning

  • Materials feasibility assessment

  • Precursor optimization

eSEN - Electronic Structure Estimation Network

ID: esen

Specialized predictor for electronic structure properties.

Capabilities:

  • Band structure prediction

  • Density of states (DOS)

  • Orbital analysis

  • Electronic transport properties

Input Parameters:

  • crystal_structure: Input structure

  • k_point_density: K-point mesh density

  • functional_type: Exchange-correlation functional

  • spin_polarization: Include spin effects

Output Properties:

  • Band structure (eV vs k-path)

  • Density of states (states/eV)

  • Effective masses (m*/m_e)

  • Work function (eV)

  • Dielectric constants

Accuracy: Near-DFT accuracy for electronic properties Speed: ~5-30 seconds per prediction

Use Cases:

  • Electronic device design

  • Semiconductor characterization

  • Transport property analysis

MyPred1 - Custom Predictor 1

ID: mypred1

Customizable predictor template for specialized applications.

Capabilities:

  • Domain-specific property prediction

  • Custom model architectures

  • Integration with experimental data

  • Research-oriented features

Input Parameters:

  • domain_inputs: Domain-specific parameters

  • model_configuration: Model setup parameters

  • prediction_targets: Custom property targets

Output Properties:

  • Domain-specific properties

  • Custom metrics

  • Research data

MyPred2 - Custom Predictor 2

ID: mypred2

Secondary custom predictor for alternative approaches.

Capabilities:

  • Alternative prediction methods

  • Experimental validation

  • Specialized algorithms

  • Novel property types

Input Parameters:

  • method_selection: Prediction method choice

  • validation_mode: Validation approach

  • custom_parameters: Method-specific inputs

Output Properties:

  • Method-specific predictions

  • Validation metrics

  • Research outputs

Usage Patterns

Basic Property Prediction

# Example of using a predictor in a Feature
pred_instance = predictor_factory["m3gnet"]("m3gnet", logger)
inputs = {
    'structure': crystal_structure,
    'properties': ['formation_energy', 'band_gap'],
    'ensemble_prediction': True
}
results = pred_instance.predict(inputs)

Multi-Predictor Validation

# Use multiple predictors for cross-validation
predictors = ['mattersim', 'm3gnet', 'pfp']
predictions = {}

for pred_id in predictors:
    pred_instance = predictor_factory[pred_id](pred_id, logger)
    result = pred_instance.predict(prediction_inputs)
    predictions[pred_id] = result

# Analyze consensus and uncertainty

Property Screening Workflow

# Screen large numbers of materials
materials_list = [...]  # List of candidate materials
screening_results = []

# Use fast predictor for initial screening
pfp_instance = predictor_factory["pfp"]("pfp", logger)
for material in materials_list:
    inputs = {'composition': material.composition}
    quick_props = pfp_instance.predict(inputs)
    
    # Filter based on criteria
    if meets_criteria(quick_props):
        # Use more accurate predictor for promising candidates
        m3gnet_instance = predictor_factory["m3gnet"]("m3gnet", logger)
        detailed_props = m3gnet_instance.predict({
            'structure': material.structure,
            'properties': ['formation_energy', 'band_gap', 'elastic_constants']
        })
        screening_results.append((material, detailed_props))

Best Practices

Predictor Selection

  • High-throughput screening: PFP for initial filtering

  • Accurate energetics: M3GNet or MatterSim

  • Electronic properties: eSEN for detailed electronic structure

  • Synthesis planning: SynthNN for feasibility assessment

Input Preparation

  • Ensure structure convergence and reasonable geometry

  • Use appropriate unit cells and primitive cells

  • Consider temperature and pressure conditions

  • Validate input formats and units

Result Interpretation

  • Always consider prediction uncertainty

  • Cross-validate with multiple methods when critical

  • Check for extrapolation beyond training data

  • Validate against experimental data when available

Performance Optimization

  • Use fast predictors for initial screening

  • Batch predictions when possible

  • Cache results for repeated calculations

  • Consider accuracy vs. speed trade-offs for your application