Support grouped structure records

[Ramlaoui]

Motivation

Some atomistic datasets need to keep several related structures together as one training/evaluation example rather than as independent flat records.

A concrete example is surface learning / adsorption-energy workflows where one logical example may contain:

• an adsorbate slab structure
• the corresponding clean slab structure
• optionally a precursor / molecule / intermediate structure
• per-member labels such as final energy, forces, fmax, or trajectory endpoint metadata
• pair-level labels such as adsorption energy or other deltas

Today this kind of relationship has to live in external sidecar files. That is fragile because the relationship can drift from the .atp records, and downstream loaders need custom join logic.

Requested capability

Support grouped examples such as pairs, triplets, or variable-size collections of structures.

For example, an API could represent something like:

example = {
    "members": {
        "adslab": adslab_molecule,
        "slab": slab_molecule,
        "precursor": precursor_molecule,
    },
    "metadata": {
        "pair_id": "...",
        "adslab_uuid": "...",
        "slab_uuid": "...",
        "adsorption_energy_ev": -1.23,
    },
}

The exact API does not need to look like this, but the key requirement is that related structures can be stored, retrieved, and sampled together without relying on external joins.

Why this matters

This would make AtomPack more useful for reference-aware training and evaluation datasets where the label depends on relationships between structures, not only on one structure at a time.

Related

Dataset-level metadata should be handled separately in a smaller PR/issue.