xnn.common.models.hub.card.ModelCard

class xnn.common.models.hub.card.ModelCard(name, description='', format='xnn', architecture=None, cutoff=None, species=None, heads=None, head=None, dtype=None, units=<factory>, license=None, citation=None, doi=None, url=None, filename=None, md5=None, tags=<factory>, aliases=<factory>, notes=None, unsupported=None, source=None, files=<factory>, xnn_version=None)

Bases: object

Metadata of one pre-trained model.

Variables:

• name (str) – Registry key, or the cache key of a model fetched by URL or DOI (e.g. "zenodo.18957344/mace_csfapbbri_al_5_1_stagetwo.model").

• description (str) – One-line human-readable summary.

• format (str) – On-disk format of the published file: "xnn" for a portable model directory or an xnn trainer checkpoint, "mace-torch" for a pickled upstream MACE model. Converted formats are stored as "xnn" once they are cached.

• architecture (str, optional) – Name of the registered xnn model class ("mace", "schnet", …).

• cutoff (float, optional) – Neighbor-list cutoff in angstrom.

• species (list of int, optional) – Atomic numbers the model was trained on.

• heads (list of str, optional) – Heads of a multi-head checkpoint; one must be chosen when loading.

• head (str, optional) – In a cached directory, the head that was kept.

• dtype (str, optional) – Floating-point dtype of the stored weights ("float64", …).

• units (dict of str to str) – Energy and length units of the model’s inputs and outputs.

• license (str, optional) – License identifier. "ASL" (the Academic Software License) prints its terms when the model is loaded.

• citation (str, optional) – Reference to cite when using the model.

• doi (str, optional) – Zenodo DOI the model is downloaded from.

• url (str, optional) – Direct download URL, used when there is no DOI.

• filename (str, optional) – File to take from a Zenodo record that holds several.

• md5 (str, optional) – MD5 digest of the file at url. Zenodo supplies its own.

• tags (list of str) – Free-form keywords for filtering.

• aliases (list of str) – Other names the model loads under ("aimnet2" for "aimnet2-wb97m-d3-0"); they resolve to this card and share its cache directory.

• notes (str, optional) – Anything else a user should know.

• unsupported (str, optional) – Why the model cannot be loaded yet. Set for registry entries that are listed for completeness only.

• source (str, optional) – Where a cached directory came from (a URL, DOI or file name).

• files (dict of str to str) – MD5 digest of each file of a portable directory.

• xnn_version (str, optional) – xnn version that wrote the directory.

Parameters:

• name (str)

• description (str)

• format (str)

• architecture (str | None)

• cutoff (float | None)

• species (list[int] | None)

• heads (list[str] | None)

• head (str | None)

• dtype (str | None)

• units (dict[str, str])

• license (str | None)

• citation (str | None)

• doi (str | None)

• url (str | None)

• filename (str | None)

• md5 (str | None)

• tags (list[str])

• aliases (list[str])

• notes (str | None)

• unsupported (str | None)

• source (str | None)

• files (dict[str, str])

• xnn_version (str | None)

classmethod from_dict(d)

Build a card from a mapping, ignoring keys this version does not know.

Unknown keys are dropped rather than rejected, so a card written by a newer xnn still loads.

Parameters:

d (dict) – Card fields.

Returns:

The card.

Return type:

ModelCard

to_dict()

Return the card as a JSON-ready dict, leaving out unset fields.

Returns:

Fields whose value is not None or empty.

Return type:

dict

save(path)

Write the card as JSON, atomically.

Parameters:

path (str or pathlib.Path) – Destination file (normally <model dir>/card.json).

Returns:

path.

Return type:

pathlib.Path

classmethod load(path)

Read a card from a JSON file.

Parameters:

path (str or pathlib.Path) – A card.json file.

Returns:

The card.

Return type:

ModelCard

property downloadable: bool

Whether the card names a place to download the model from.