Model Introduction

MatRIS is a foundation model for materials representation and interaction simulation, short for Materials Representation and Interaction Simulation. It can predict energy, forces, stress, and magnetic moments for crystal structures, and supports structure relaxation based on ASE and pymatgen structure objects.

Model Description

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

Applicable Scenarios

Scenario	Description
Crystal energy prediction	Input a CIF, pymatgen Structure, or ASE Atoms object and predict the system energy
Force and stress prediction	Provide force and stress estimates for structure relaxation, molecular dynamics, or downstream simulation
Magnetic moment prediction	Output structure-related magnetic-moment results under the `efsm` task
Structure relaxation pre-processing	Use `StructOptimizer` to optimize atomic positions and unit cells of candidate crystal structures
Environment connectivity check	Use `cif_file/demo.cif` and a lightweight MatRIS model to check whether the OneScience matchem environment is available

Usage Instructions

1. Using OneCode

You can try out intelligent one-click AI4S programming in the OneCode online environment:

Try intelligent one-click AI4S programming

2. Manual Installation and Usage

Hardware Requirements

GPU or DCU is recommended.
CPU can be used for module verification and small-scale forward checks, but structure relaxation will be slow. CPU is not recommended for formal batch inference.
DCU users need to install DTK in advance. DTK 25.04.2 or above, or the OneScience-recommended version matching the current cluster, is suggested.

Download the Model Package

modelscope download --model OneScience/MatRIS --local_dir ./matris
cd matris

Install the Runtime Environment

DCU Environment

# Please 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

# Please 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

Training Weights

Inference testing requires a pre-trained 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 pre-trained weights. scripts/test_relaxation.py will load them from weight/ when run.

Inference

Run Modular Verification

python scripts/test_modularization.py

This script instantiates a lightweight MatRIS model (randomly initialized weights) and completes one CPU forward pass to verify the connectivity of model modules.

Run Structure Relaxation Inference

python scripts/test_relaxation.py

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

After inference completes, the log will output the relaxation process, and energy, forces, stress, magnetic moments, and the final structure object will be obtained in memory.

Other Inference Examples

Besides structure relaxation, you can also use MatRISCalculator to predict energy, forces, stress, and magnetic moments for 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)

OneScience Official Information

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

MatRIS upstream materials are released under the BSD-3-Clause License. This repository retains the source attribution and is organized for OneScience ModelScope automatic execution scenarios.
If you use MatRIS results in scientific research, we recommend citing the original MatRIS project, the relevant OneScience project information, and adding citations for the materials datasets, structure optimization tools, or downstream analysis tools used according to the actual task.