OneScience-Sugon/MatRIS

MatRIS

Model Introduction

MatRIS, short for Materials Representation and Interaction Simulation, is a foundation model for material representation and interaction simulation. It predicts the energy, forces, stress, and magnetic moments of crystal structures and supports structure relaxation using ASE Atoms and pymatgen Structure objects.

Model Description

MatRIS uses a graph neural network architecture trained on materials datasets such as OMat24 and MPTrj. It supports energy, force, stress, and magnetic-moment prediction and structure optimization for crystalline materials.

Use Cases

Use case	Description
Crystal energy prediction	Predict system energy from a CIF file, pymatgen Structure, or ASE Atoms object
Force and stress prediction	Estimate forces and stress for structure relaxation, molecular dynamics, or downstream simulations
Magnetic-moment prediction	Return structure-dependent magnetic moments for the efsm task
Structure-relaxation preprocessing	Optimize atomic positions and unit cells of candidate crystals with StructOptimizer
Environment connectivity check	Use cif_file/demo.cif and a lightweight MatRIS model to verify the OneScience MatChem environment

Usage

1. Using OneCode

Try intelligent, one-click AI4S programming in the OneCode online environment:

Try intelligent, one-click AI4S programming

2. Manual Installation and Usage

Hardware requirements

• A GPU or DCU is recommended.
• A CPU can be used for module checks and small forward-pass tests, but structure relaxation will be slow and is not recommended for production batch inference.
• DCU users must install DTK in advance. DTK 25.04.2 or later, or the OneScience-recommended version matching the current cluster, is recommended.

Download the Model Package

hf download --model OneScience-Sugon/MatRIS --local-dir ./matris
cd matris

Install the Runtime Environment

DCU environment

# Activate DTK and conda first
conda create -n onescience311 python=3.11 -y
conda activate onescience311
# uv installation is also supported
pip install onescience[matchem-dcu] -i http://mirrors.onescience.ai:3141/pypi/simple/  --trusted-host mirrors.onescience.ai

GPU environment

# Activate conda first
conda create -n onescience311 python=3.11 -y libstdcxx-ng=12 libgcc-ng=12 gcc_linux-64=12 gxx_linux-64=12
conda activate onescience311
# uv installation is also supported
pip install onescience[matchem-gpu] -i http://mirrors.onescience.ai:3141/pypi/simple/  --trusted-host mirrors.onescience.ai

Trained Weights

Inference requires a pretrained model. MatRIS provides the following model keys:

Model key	Description
matris_10m_omat	Trained on the OMat24 dataset
matris_10m_oam	Trained on OMat24 and fine-tuned on sAlex+MPtrj
matris_10m_mp	Trained on the MPTrj dataset

The weight/ directory in this repository already contains pretrained weights. scripts/test_relaxation.py loads them from that directory.

Inference

Run the modularity check

python scripts/test_modularization.py

This script instantiates a lightweight MatRIS model with randomly initialized weights and runs one CPU forward pass to verify that the model modules work together.

Run structure-relaxation inference

python scripts/test_relaxation.py

This script reads cif_file/demo.cif and performs structure relaxation with StructOptimizer.

After inference, the log shows the relaxation process, while the energy, forces, stress, magnetic moments, and final structure object are available in memory.

Other inference examples

In addition to structure relaxation, you can use MatRISCalculator to predict the energy, forces, stress, and magnetic moments of a single structure:

import torch
from ase.build import bulk
from onescience.utils.matris import MatRISCalculator

device = "cuda" if torch.cuda.is_available() else "cpu"
calc = MatRISCalculator(
    model="matris_10m_oam",
    task="efsm",
    device=device,
)

atoms = bulk("Cu", a=5.43, cubic=True)
atoms.calc = calc

energy = atoms.get_potential_energy()   # Total energy (eV)
forces = atoms.get_forces()             # Forces (eV/Å)
stress = atoms.get_stress()             # Stress (eV/ų)
magmoms = atoms.get_magnetic_moments()  # Magnetic moments (μB)

Official OneScience Resources

Platform	OneScience Main Repository	Skills Repository
Gitee	https://gitee.com/onescience-ai/onescience	https://gitee.com/onescience-ai/oneskills
GitHub	https://github.com/onescience-ai/OneScience	https://github.com/onescience-ai/oneskills

Citation and License

• The upstream MatRIS materials use the BSD 3-Clause License. This repository retains source attribution and has been organized for automated execution in the OneScience Hugging Face environment.
• If you use MatRIS results in research, please cite the original MatRIS project and the relevant OneScience projects, as well as the materials datasets, structure-optimization tools, or downstream analysis tools used for your task.