scine-add-ml-model

name	scine-add-ml-model
description	Add a new machine learning (ML) model as a calculator in the SCINE Parrot module. Use when integrating a new ML potential or interatomic potential (e.g., MACE, ANI, M3GNet, LMLP, NequIP, or any custom ML model) into scine_parrot. Covers creating the calculator class, registering in the calculator registry, adding CLI support, writing unit tests, and updating documentation.
argument-hint	Name of the ML model to add (e.g., MyModel)

Add a New ML Model to SCINE Parrot

When to Use

• Integrating a new ML potential or force field into scine_parrot
• Adding a new calculator class following the existing *_calculator.py pattern
• Registering a new model in the Parrot calculator registry and CLI

Existing Models to Reference

Study these before implementing:

File	Model
scine_parrot/lmlp_calculator.py	LMLP
scine_parrot/mace_calculator.py	MACE
scine_parrot/m3gnet_calculator.py	M3GNet
scine_parrot/ani_calculator.py	ANI

Base interfaces: scine_parrot/calculator.py, scine_parrot/module.py Entry point: scine_parrot/__main__.py

Files to Create / Modify

File	Action	Purpose
scine_parrot/my_model_calculator.py	Create	ML model calculator class
scine_parrot/calculator.py	Edit	Add import + register model
scine_parrot/__main__.py	Edit	Add CLI options for new model
scine_parrot/test/test_my_model.py	Create	Unit tests
README.rst	Edit	Document new model

Full reference: parrot-guide.md

---

Step 1 — Create the Calculator Class

Name: my_model_calculator.py in scine_parrot/ (pattern: MODEL_NAME_calculator.py)

Copy structure from an existing calculator. Implement at minimum:

class MyModelCalculator:
    def __init__(self, model_path, **kwargs):
        """Initialize model with parameters and weights."""
        self.model = self.load_model(model_path)

    def predict(self, elements, positions, lattice=None, **kwargs):
        """
        Predict molecular properties.

        Args:
            elements: Atomic numbers or symbols (list or numpy array)
            positions: Atomic coordinates (N×3 numpy array, Angstroms)
            lattice:   Unit cell (3×3 array, for periodic systems)

        Returns:
            dict with 'energy' (scalar) and 'forces' (N×3 array)
        """
        pass

    def load_model(self, model_path):
        """Load model weights and parameters from path."""
        pass

I/O Conventions

Direction	Field	Type	Units
Input	elements	list/array of int or str	atomic numbers or symbols
Input	positions	N×3 numpy array	Angstroms
Input	lattice	3×3 numpy array or None	Angstroms (periodic only)
Output	energy	scalar	eV or Hartree
Output	forces	N×3 numpy array	eV/Å or Hartree/Bohr

---

Step 2 — Register in Calculator Registry

scine_parrot/calculator.py:

• Add import for MyModelCalculator
• Register it in any factory functions or model selection logic
• Ensure it conforms to the same interface as existing calculators

---

Step 3 — Add CLI Support

scine_parrot/__main__.py:

• Add argument(s) to select your model
• Update argument parsing for model-specific parameters (e.g., model_path, config options)
• Provide sensible defaults

---

Step 4 — Configuration (if needed)

• Add new parameters to existing config parsers
• Document new options; provide sensible defaults
• Minimise external dependencies; add any new packages to requirements.txt

---

Step 5 — Unit Tests

scine_parrot/test/test_my_model.py — cover:

• Model loading and initialisation
• Basic energy/force prediction
• Input validation and error handling
• Output format verification (shapes, units)
• Edge cases: single atom, large system, periodic system

---

Step 6 — Documentation

• Add comprehensive docstrings to all classes and methods
• Update README.rst with model description and usage example
• Document any new configuration options

---

Quality Gates

• Calculator class follows existing *_calculator.py pattern (same method signatures and return dict keys)
• Registered in calculator.py — model is selectable at runtime
• CLI options added and tested in __main__.py
• All unit tests pass: pytest scine_parrot/test/test_my_model.py -v
• Regression tests pass: pytest scine_parrot/test/ -v (no existing tests broken)
• Docstrings complete on class and public methods
• README.rst updated