---
title: Materials Project Trajectory Dataset (MPtrj)
url: https://www.emergentmind.com/topics/materials-project-trajectory-dataset-mptrj
type: topic
---

# Materials Project Trajectory Dataset (MPtrj)

The Materials Project Trajectory Dataset (MPtrj) refers to the curated collection of density functional theory (DFT) relaxation trajectories originally generated by the Materials Project and systematically standardized, filtered, and harmonized within the LeMat-Traj framework. MPtrj provides structured, high-quality atomic configuration sequences suitable for development and benchmarking of machine learning interatomic potentials (MLIPs), addressing challenges of data fragmentation and format inconsistency that have previously hampered MLIP transferability and accuracy [2508.20875].

## 1. Collection and Preprocessing of Materials Project Trajectories

Acquisition of MPtrj data proceeds through an automated pipeline built around LeMaterial-Fetcher, which interfaces with the Materials Project REST API via pymatgen’s `MPRester`. All non-deprecated geometry-optimization (relaxation) tasks available at the time of LeMat-Traj's assembly (approximately 1.5 million) are queried, ensuring each initial Materials Project material identifier (MP-ID) contributes its full trajectory, i.e., every intermediate ionic configuration from the geometry-optimization procedure.

Each candidate trajectory undergoes a sequence of stringent filters:

- **Completeness**: Frames missing either total DFT energy or atomic forces are immediately dropped.
- **Convergence**: Trajectories are rejected if the difference between final and penultimate step energies exceeds $2\times10^{-2}$ eV:
  $$
  \Delta E = |E^{(T)} - E^{(T-1)}| > 2\times10^{-2}~\mathrm{eV}
  $$
- **Force-norm ceiling**: Trajectories with a final-step maximum atomic force greater than $0.2~\mathrm{eV/\AA}$ are excluded:
  $$
  \max_i \|\mathbf{F}_i\| > 0.2~\mathrm{eV/\AA}
  $$
- **Schema validation**: Every frame must comply with the (extended) OPTIMADE schema, ensuring structural and metadata consistency.

Standardization in LeMat-Traj involves harmonizing all units (energies in eV, forces in eV/Å, lengths in Å) and augmenting the OPTIMADE schema by introducing two fields: `relaxation_step` (index) and `relaxation_number` (unique per multi-stage relaxation event). Metadata such as DFT functional, k-point mesh, and pseudopotentials are extracted where available.

## 2. Quantitative Overview: Functional Splits and Trajectory Characteristics

The MPtrj subset in LeMat-Traj is organized by DFT exchange–correlation functional, as shown below:

| Functional | #Trajectories | #Configurations |
|:-----------|:-------------|:---------------|
| PBE        | 195,721      | 3,649,785      |
| PBESol     | 39,981       |   309,873      |
| SCAN       | 7,756        |   180,528      |
| r2SCAN     | 37,888       |   516,576      |

Each trajectory corresponds predominantly to a unique chemical composition.

Time-step analysis reveals that MPtrj trajectories are typically short:
- Median length of $\approx 15$ frames
- Over 90% of trajectories contain fewer than 50 ionic steps
- There is a pronounced spike at very short trajectories ($<$10 steps), a consequence of rapid convergence in many Materials Project relaxations.

## 3. Data Schema and Atomic Configuration Structure

Every frame in MPtrj—standardized as part of LeMat-Traj—encapsulates the following fields:

- `trajectory_id`: Unique string representing the trajectory
- `relaxation_step` and `relaxation_number`: Step index and multi-stage identifier, respectively
- `atomic_numbers`: List of nuclear charges $[Z_1,\dots,Z_N]$
- `cell`: $3\times3$ array of lattice vectors (Å)
- `positions`: Cartesian coordinates $\{\mathbf{r}_i\}_{i=1,\ldots,N}$, shape $(N,3)$ (Å)
- `energy`: Total DFT energy per cell (eV)
- `forces`: Atomic forces $\{\mathbf{F}_i\}_{i=1,\ldots,N}$, shape $(N,3)$ (eV/Å)
- `functional`: DFT functional label (e.g., "PBE")
- `kpoints`: Tuple $(n_x,n_y,n_z)$ specifying k-point grid
- `pseudopotentials`: List of labels for pseudopotential types

Standard DFT relationships are observed: total energy is additive (usually written as $E = \sum_{n=1}^N E_n$), and forces satisfy $\mathbf{F}_i = -\frac{\partial E}{\partial \mathbf{r}_i}$.

## 4. Functional Harmonization and Data Quality Controls

The LeMat-Traj framework segregates data by DFT functional via the `functional` field, supporting both functional-specific and multi-fidelity MLIP training workflows. Pseudopotential and parameter alignment are performed according to methodology established by Siron et al. (ICLR 2025), with materials (e.g., Yb) filtered for cross-dataset compatibility.

Key filtering criteria—replicated here for clarity—require:
- $\left|E_T - E_{T-1}\right| \leq 2\times10^{-2}$ eV (final convergence)
- $\max_i\|\mathbf{F}_i\| \leq 0.2$ eV/Å (physical reasonableness of relaxed structures)

These standards ensure only well-converged, physically meaningful configurations are retained.

## 5. Access Methods and Example Usage

LeMat-Traj provides modular access, with MPtrj subsets programmatically fetchable via LeMaterial-Fetcher or directly from HuggingFace Datasets. The following code illustrates data retrieval and iteration for the MP PBE subset:

```python
from lemater ial_fetcher.fetchers import MaterialsProjectFetcher

mp_fetcher = MaterialsProjectFetcher(
    functional="PBE",
    min_energy_diff=2e-2,   # eV threshold between final steps
    max_final_force=0.2     # eV/Å threshold
)
mp_rdataset = mp_fetcher.fetch()
for frame in mp_rdataset:
    # Access frame fields such as positions, energy, forces
    pass
```

Alternatively, via HuggingFace Datasets:

```python
from datasets import load_dataset
ds_mp = load_dataset("LeMaterial/LeMat-Traj", split="train", subset="materials_project/PBE")
for example in ds_mp:
    pass
```

This infrastructure enables reproducible, scalable data access for downstream MLIP workflows [2508.20875].

## 6. Benchmarking and Impact on MLIP Performance

Quantitative evaluation underscores substantial benefit from including harmonized MPtrj data within LeMat-Traj for MLIP development. Notably, when the MACE model is trained solely on the standalone MPtrj split, energy and force mean absolute errors (MAEs) on test relaxations are 250.2 meV and 187.5 meV/Å, respectively. Utilizing the harmonized LeMat-Traj PBE subset decreases these errors to 20.2 meV / 63.3 meV/Å. Fine-tuning models initially trained on high-force OMat24 data with the curated LeMat-Traj further reduces errors, demonstrating the complementarity of the datasets.

On Matbench Discovery Stability benchmarks:
- MACE trained with only MPtrj achieves F1 = 0.694, MAE = 47.2 meV, RMSE = 83.9 meV.
- Substituting LeMat-Traj raises F1 to 0.768 and lowers MAE and RMSE by $\sim$10 meV per atom.

Embedding Materials Project relaxations within the harmonized LeMat-Traj context is thus essential for state-of-the-art MLIP performance in the low-force, near-equilibrium regime critical for reliable structure relaxation [2508.20875].

Source: https://www.emergentmind.com/topics/materials-project-trajectory-dataset-mptrj