---
title: 'Metatomic: Portable Atomistic ML Models'
url: https://www.emergentmind.com/topics/metatomic
type: topic
---

# Metatomic: Portable Atomistic ML Models

Searching arXiv for papers on “metatomic” to ground the article in published sources.
Metatomic is a term used in distinct technical contexts. In contemporary atomistic machine learning, it denotes a library and model format for packaging atomistic ML models in a portable, simulation-engine-agnostic way, introduced alongside metatensor as part of an interoperability stack for atomic-scale modeling [2508.15704]. In other areas, closely related terminology appears in regular-language theory through maximally atomic languages, where “atomic” refers to non-empty intersections of complemented and uncomplemented quotients of a regular language [1308.4368], and in nonlinear photonics through photonic meta-atoms, composite solitary waves whose internal trapped-state structure mimics atomic spectra [2603.17748]. In current technical usage, however, “metatomic” most specifically refers to the software layer that standardizes model packaging, runtime interfaces, and metadata for atomistic ML deployment across heterogeneous simulation environments [2508.15704].

## 1. Definition and scope

Metatomic is a library and model format for storing an atomistic ML model together with metadata about that model in a portable way, facilitating the implementation, training, distribution, and use of models across different simulation packages [2508.15704]. It occupies the model-interface layer in an ecosystem where metatensor standardizes data representation and metatomic standardizes code, parameters, capabilities, and deployment metadata.

The motivating problem is combinatorial interoperability. If there are \(M\) model architectures and \(N\) simulation engines, direct pairwise integrations scale as \(\mathcal{O}(M\times N)\). Metatomic replaces this with an “hourglass” architecture in which each model implements the metatomic interface and each engine implements the same interface, reducing integration effort to \(\mathcal{O}(M+N)\) [2508.15704]. This suggests that metatomic is best understood not as a single model family, but as a narrow middle layer that decouples model development from simulation-engine development.

The underlying assumption is deliberately minimal: inputs must be representable as atomic-like data, namely decorated point clouds in 3D, optionally periodic [2508.15704]. Within that constraint, metatomic is intended to support interatomic potentials, property predictors, trajectory predictors, and collective-variable models.

## 2. Representation of models and metadata

A metatomic model is conceptually a container comprising serialized model code, learned parameters, and structured metadata [2508.15704]. In the current implementation described in the literature, the code is primarily represented as TorchScript exported from PyTorch, enabling execution from C/C++ without a Python interpreter. The learned parameters reside inside the exported TorchScript object and are opaque from the simulation engine’s point of view.

Metatomic metadata has both human-readable and technically operational roles. Human-readable fields include authors, citations, descriptions, and intended domains of applicability. Technical metadata records supported inputs, supported outputs, units, species, and required neighbor lists. The model also carries a capability description: named outputs such as `"energy"`, `"forces"`, `"stress"`, `"dipole"`, or `"features"`, together with conventions on structure and metadata, for example whether an output is scalar per structure or vector per atom, and whether gradients are available [2508.15704].

Input requirements are likewise explicit. At minimum, a metatomic model may request atomic species, positions, and the simulation cell; it may additionally request one or more neighbor lists with specified cutoffs and criteria. Future extensions discussed in the source include charges, spins, and external fields [2508.15704]. Training details such as optimizer state and loss history are not part of the runtime metatomic interface; those remain in training checkpoints such as `model.ckpt`.

All actual numerical inputs and outputs are represented using metatensor’s `TensorMap` format, a sparse, metadata-rich tensor container [2508.15704]. This allows metatomic to remain agnostic to the internal architecture while still transporting structured physical quantities, gradients, and higher-order derivatives.

## 3. Relation to metatensor and the interoperability architecture

Metatensor and metatomic are complementary rather than redundant. Metatensor defines the tensor containers—`TensorMap`, `TensorBlock`, and `Labels`—that carry numerical values together with metadata about samples, components, properties, sparsity, and gradients. Metatomic defines the model interface that consumes and produces these containers [2508.15704].

This division of responsibilities is central to the interoperability design. A model implemented in PyTorch with metatensor-based inputs and outputs can be exported to TorchScript, wrapped with metatomic metadata, and then invoked from simulation engines written in C, C++, or Fortran. Because outputs are always returned as `TensorMap`s, models may expose not only standard scalar energies and Cartesian forces but also more complex quantities such as local densities on spherical bases, Hamiltonians, dipoles, stresses, non-conservative forces, or learned features, all without inventing engine-specific data structures [2508.15704].

A plausible implication is that metatomic’s abstraction boundary is intentionally physical rather than architectural. Simulation engines need not know whether a model is a PET architecture, an equivariant GNN, a descriptor-based network, or a trajectory predictor; they only need to understand the declared inputs, outputs, and metatensor conventions for the quantities they consume.

## 4. Runtime workflow, APIs, and file formats

The typical metatomic workflow begins with training in Python using tools such as metatensor, metatensor-learn, featomic, torch-spex, or torch-pme. The trained network is saved in a checkpoint, then exported via `mtt export` into TorchScript and wrapped into a metatomic-compatible model artifact, often a `.pt` file that contains both executable model code and metatomic metadata [2508.15704].

At runtime, a simulation engine equipped with a metatomic driver loads the model artifact and interacts with it in three stages [2508.15704]:

1. **Capability query**: the engine asks which outputs the model can produce and what their shapes and metadata are.
2. **Input requirements**: the model specifies which standard inputs and additional data it requires, including neighbor lists and their parameters.
3. **Evaluation**: the engine prepares the requested inputs, calls the model’s `evaluate` function, and receives outputs as metatensor `TensorMap`s.

The conceptual evaluation pattern is described as follows:

```pseudo
outputs = model.evaluate(
    species=...,
    positions=...,
    cell=...,
    neighbor_lists=...,
    requested_outputs=["energy", "forces", "stress"]
)
```

The runtime artifact is usually a TorchScript file with added metatomic metadata [2508.15704]. The design is described as future-proof in two senses: TorchScript provides a stable executable representation, and tensor data plus metadata use metatensor serialization based on NumPy’s `npz`, so the raw data remain readable even independently of a specific library implementation [2508.15704].

Versioning is handled through model metadata indicating the supported interface version. The interface is intentionally minimal and extensible: new output types may be added without breaking existing engines, and engines may ignore outputs they do not recognize [2508.15704].

## 5. Physical quantities, atomistic assumptions, and mathematical formulation

Metatomic does not impose a single model equation, but it is designed around standard atomistic-ML formulations. For a generic interatomic ML potential, the literature describes the energy as

$$
E(\{\mathbf{R}_i\}) = \sum_i E_i(\mathcal{D}_i),
$$

where \(\mathbf{R}_i\) are atomic positions, \(\mathcal{D}_i\) are local descriptors or learned features, and \(E_i(\mathcal{D}_i)\) are per-atom energy contributions [2508.15704]. Forces then follow as

$$
\mathbf{F}_i = -\nabla_{\mathbf{R}_i} E(\{\mathbf{R}_j\}).
$$

Metatomic supports both conservative and non-conservative outputs [2508.15704]. Conservative forces may be obtained as gradients of an energy within the model through automatic differentiation or analytic formulas. Non-conservative forces may instead be directly predicted, and trajectory models may emit quantities such as `"delta_positions"` or updated momenta rather than energies and gradients.

The framework pays particular attention to species, geometry, units, and neighbor lists. Inputs always include atomic species, positions, and cell information. Many atomistic models depend on local neighborhoods, and metatomic allows the model to request neighbor lists from the simulation engine rather than rebuild them internally [2508.15704]. The engine can then compute those lists using optimized routines, for example in LAMMPS or via vesin for ASE and eOn, and pass them back as part of the model input.

Units are documented in model metadata rather than enforced through a universal formal unit schema in the cited source [2508.15704]. This design supports engine-side consistency checks and conversions when needed.

## 6. Software ecosystem and integrations

Metatomic is described as the center of a growing ecosystem that spans training tools, descriptor libraries, long-range interaction modules, simulation engines, and visualization software [2508.15704]. The main components explicitly mentioned in the literature are summarized below.

| Category | Examples | Role |
|---|---|---|
| Training/export | metatrain | `mtt train`, `mtt export`, `mtt eval` |
| Descriptors/features | featomic, torch-spex, sphericart | SOAP, ACE, spherical expansions, harmonics |
| Long-range terms | torch-pme | PME, P3M, Ewald in PyTorch |
| Simulation/analysis | LAMMPS, ASE, i-PI, PLUMED, TorchSim, eOn, chemiscope | Runtime execution, sampling, dynamics, visualization |

Metatrain is the principal model-creation tool described alongside metatomic. It supports YAML-configured training workflows and exports a range of architectures—including GAP, Behler–Parrinello neural networks, modern invariant and equivariant GNNs, PET, and FlashMD networks—into metatomic format [2508.15704].

The simulation-engine integrations are diverse. LAMMPS has two interfaces, including a Kokkos GPU interface in which atomic data remain on the GPU. i-PI uses a metatomic driver in path integral molecular dynamics. ASE exposes metatomic through a calculator interface for energies, forces, stresses, and arbitrary custom outputs. eOn uses metatomic models for off-lattice kinetic Monte Carlo and saddle searches. TorchSim integrates them directly in a GPU-accelerated PyTorch simulation environment. PLUMED uses metatomic models to compute ML-based collective variables in enhanced-sampling workflows. chemiscope can use a metatomic model as a featurizer through `chemiscope.explore` [2508.15704].

The recurrent pattern across these integrations is simulation-engine agnosticism combined with physically structured I/O. This suggests that metatomic’s chief contribution is not a novel learning algorithm, but a deployment protocol that regularizes model execution across heterogeneous codes.

## 7. Demonstrated use cases, performance considerations, and broader meanings of the term

The literature reports several case studies demonstrating the range of model classes that can be packaged as metatomic models [2508.15704]. PET-MAD was trained with metatrain, exported to metatomic, and used in LAMMPS, ASE, and i-PI. ShiftML3, a committee of PET models for chemical shielding prediction, was exported to metatomic and used through the ASE interface in NMR crystallography workflows. FlashMD trajectory-prediction networks were exported and integrated in ASE and i-PI. A q-TIP4P/F water model implemented with torch-pme was packaged as a metatomic model, with radial distribution functions from the LAMMPS plus metatomic implementation matching the native LAMMPS potential. In PLUMED plus LAMMPS, a custom collective variable based on coordination-number histograms was implemented as a metatomic model for LJ38 metadynamics [2508.15704].

Performance discussions in the source focus on GPU execution, sparse representations, and the trade-off between conservative and direct-force models [2508.15704]. TorchScript plus PyTorch enables CPU and GPU execution from the same artifact. Kokkos-based LAMMPS integration reduces host-device transfer overhead by keeping atomic data on the GPU. Metatensor’s sparse block format reduces memory footprint for large systems and structured outputs such as spherical tensors or Hamiltonians. Conservative forces are more expensive but energy-conserving; direct force outputs are cheaper per step but may introduce sampling errors. Hybrid schemes such as multiple-time-stepping and ring-polymer contraction are presented as compatible with the metatomic plus metatensor stack.

Beyond atomistic ML, the word family surrounding “metatomic” has established meanings in other fields. In automata theory, “maximally atomic languages” are regular languages that attain the maximal number of atoms and the maximal quotient complexities of all atoms, characterized in terms of set-transitive permutation subgroups of the transition semigroup and the presence of a transformation of rank \(n-1\) [1308.4368]. In nonlinear photonics, “photonic meta-atoms” are composite solitary waves in nonlinear waveguides governed by a higher-order nonlinear Schrödinger equation and an induced Schrödinger-type bound-state problem, exhibiting discrete trapped states, isotopic and isomeric resonance shifts, and Zeeman-like line splitting [2603.17748]. These usages are conceptually independent of the software library.

In present research practice, however, metatomic most commonly denotes the runtime glue that turns atomistic ML models into portable, reusable simulation components by standardizing capabilities, input requirements, and tensor-based data exchange across software ecosystems [2508.15704].

Source: https://www.emergentmind.com/topics/metatomic