PropertyPredictor

Included in QATK.MLFF

class PropertyPredictor(filename, device=None, dtype='float64')

Property predictor for loading and using trained models to predict properties from atomic configurations.

Parameters:

  • filename (str) – Path to the property prediction model file (.qatkpt)

  • device (str) – Device to use for computation, either ‘cpu’, ‘cuda’ or None for automatic selection

  • dtype (str) – Precision to use, either ‘float32’ or ‘float64’

predict(configuration)

Predict property for a given configuration.

Parameters:

configuration (AtomicConfiguration) – Atomic configuration

Returns:

The predicted property. If the model has metadata (property_key and unit), returns a single value (PhysicalQuantity if unit is valid, otherwise raw value). If no metadata, returns a dict of all properties.

Return type:

PhysicalQuantity | float | dict

propertyName()

Get the property key that this model was trained to predict.

Returns:

The property key, or None if not available

Return type:

str | None

propertyUnit()

Get the unit of the property that this model was trained to predict.

Returns:

The property unit as a string, or None if not available

Return type:

str | None

Usage Examples

Basic usage of PropertyPredictor to load a trained property prediction model and make predictions on atomic configurations:

# Path to trained model file
model_path = 'path/to/property_model.qatkpt'

# Set up the PropertyPredictor on a GPU with float32 precision
predictor = PropertyPredictor(model_path, device='cuda', dtype='float32')

# Get information about what property the model predicts
property_name = predictor.propertyName()
property_unit = predictor.propertyUnit()

print(f"Model predicts: {property_name}")
if property_unit:
    print(f"Unit: {property_unit}")

configuration = ...  # Load or define your atomic configuration here

# Predict property for a given atomic configuration
result = predictor.predict(configuration)
print("Predicted property value:", result)

property_predictor_example.py

Notes

Output Format

The predict() method returns different formats depending on the property type and units:

  • Configuration-level properties: Returns a scalar value (or PhysicalQuantity if trained with units)

  • Atom-wise properties: Returns an array with one value per atom (or PhysicalQuantity array if trained with units)

For atom-wise properties (e.g., atomic charges), the output is an array with one value per atom. For configuration-level properties (e.g., band gap), the output is a scalar value.