Replace per_atom with sample_kind everywhere.

[pfebrer]

This is to be merged once metatensor/metatomic#168 is in.

The metatomic PR deprecates per_atom in ModelOutput to substitute it for sample_kind so that there is room for other sample kinds. In particular, after the PR metatomic will be able to deal with sample_kind="atom_pair".

In this PR, I just refactor the whole metatrain to use sample_kind, without introducing atom_pair targets. In the next PR I will introduce sample_kind="atom_pair", and I think the changes there will be clearer to understand if we get this refactoring out of the way.

Ideally, this PR should be merged as soon as a new metatomic release is made, because it touches everything and it would not be fun to maintain for a long time 😅

---

📚 Documentation preview 📚: https://metatrain--1075.org.readthedocs.build/en/1075/

[Copilot]

Pull request overview

This PR refactors the entire metatrain codebase to replace the per_atom boolean parameter with a more flexible sample_kind string parameter (values: "atom" or "system") in preparation for future support of "atom_pair" targets. It includes backward compatibility handling for the deprecated per_atom key in YAML configurations.

Changes:

• Replaced all per_atom=True/False with sample_kind="atom"/"system" across models, tests, utilities, and CLI
• Added sanitize_target_hypers() in base_hypers.py to handle deprecated per_atom key with proper warnings and conflict detection
• Added sample_kind property and backward-compatible per_atom property to TargetInfo

Reviewed changes

Copilot reviewed 46 out of 46 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
pyproject.toml	Temporary git dependency on metatomic branch (must be reverted)
src/metatrain/share/base_hypers.py	Added sample_kind field, deprecated per_atom, added sanitize_target_hypers validator
src/metatrain/utils/data/target_info.py	Added sample_kind property, made per_atom backward-compatible
src/metatrain/utils/data/dataset.py	Replaced per_atom checks with sample_kind
src/metatrain/utils/omegaconf.py	Changed defaults from per_atom: False to sample_kind: "system"
src/metatrain/utils/evaluate_model.py	Updated ModelOutput construction
src/metatrain/utils/scaler/scaler.py	Updated ModelOutput construction
src/metatrain/utils/additive/*.py	Updated ModelOutput and condition checks
src/metatrain/utils/testing/*.py	Updated fixtures and assertions
src/metatrain/soap_bpnn/model.py	Updated ModelOutput construction
src/metatrain/pet/model.py	Updated ModelOutput and condition checks
src/metatrain/gap/model.py	Updated ModelOutput and validation checks
src/metatrain/llpr/model.py	Updated ModelOutput construction and conditions
src/metatrain/experimental/mace/model.py	Updated ModelOutput and conditions
src/metatrain/experimental/phace/model.py	Updated ModelOutput and conditions
src/metatrain/experimental/flashmd/model.py	Updated ModelOutput and conditions
src/metatrain/experimental/classifier/*.py	Updated ModelOutput construction
src/metatrain/cli/eval.py	Updated eval output configuration
Various test files	Replaced per_atom with sample_kind in test configurations

---

You can also share your feedback on Copilot code review. Take the survey.

[sofiia-chorna]

thanks for the fixes. sorry, one more thing, did the search by per_atom on the branch: it seems there are still some examples using ModelOutput(per_atom=... , we might want to update them. also here https://github.com/metatensor/metatrain/blob/pair_targets/src/metatrain/utils/data/readers/readers.py#L216, i suggest we replace it with entry.get("sample_kind") != "atom" to be safe...

[pfebrer]

Yess this is a work in progress, every time that I rebase there are new per_atom. I'm waiting for metatomic to merge the change before doing a final pass