smact.property_prediction.base_predictor module

Abstract base class for property predictors and the PredictionResult dataclass for returning predictions with optional uncertainty estimates.

Base class for property predictors in SMACT.

This module provides the abstract base class that all property predictors must inherit from, ensuring a consistent interface across different prediction models.

class smact.property_prediction.base_predictor.BasePropertyPredictor(property_name: str, fidelity: str | None = None, model_name: str | None = None, model_path: str | Path | None = None, device: str = 'cpu', **kwargs: Any)

Bases: ABC

Abstract base class for property predictors.

This class defines the interface for all property predictors in SMACT. Subclasses must implement the supported_properties property and the predict method for specific models.

property_name

Name of the property being predicted.

fidelity

Fidelity level for the prediction (e.g., “pbe”, “hse06”).

model_name

Name of the specific model version.

model_path

Path to a local model checkpoint.

device

Device to run the model on (“cpu” or “cuda”).

model

The loaded model instance.

property metadata: dict[str, Any]

Model metadata including training information.

abstract predict(compositions: str | list[str], return_uncertainty: bool = False) → ndarray | PredictionResult

Predict property values for given compositions.

Parameters:

• compositions – Single composition string or list of composition strings (e.g., “NaCl”, [“TiO2”, “GaN”]).

• return_uncertainty – If True, return PredictionResult with uncertainty estimates. If False, return numpy array.

Returns:

Property predictions as numpy array, or PredictionResult object if return_uncertainty is True.

abstract property supported_properties: list[str]

List of properties supported by this predictor.

class smact.property_prediction.base_predictor.PredictionResult(predictions: ~numpy.ndarray, uncertainties: ~numpy.ndarray | None = None, epistemic_std: ~numpy.ndarray | None = None, unit: str = '', compositions: list[str] = <factory>)

Bases: object

Container for prediction results with optional uncertainty estimates.

predictions

Array of predicted property values.

Type:

numpy.ndarray

uncertainties

Aleatoric (per-sample) uncertainties from robust models.

Type:

numpy.ndarray | None

epistemic_std

Epistemic uncertainty from ensemble predictions.

Type:

numpy.ndarray | None

unit

Unit string for the predicted property (e.g., “eV”, “GPa”).

Type:

str

compositions

List of composition strings that were predicted.

Type:

list[str]

compositions: list[str]

epistemic_std: ndarray | None = None

predictions: ndarray

to_dict() → dict[str, Any]

Convert to dictionary for serialisation.

uncertainties: ndarray | None = None

unit: str = ''