README.md

---
license: bsd-3-clause
tasks:
  - materials-simulation
  - structure-relaxation
  - property-prediction
frameworks:
  - pytorch
language:
  - en
tags:
  - OneScience
  - materials-science
  - materials-representation
  - crystal-structure
  - energy-prediction
  - force-prediction
  - stress-prediction
  - magnetic-moment-prediction
  - structure-relaxation
datasets:
  - OneScience-Sugon/pbe
---

<p align="center">
  <strong>
    <span style="font-size: 30px;">MatRIS</span>
  </strong>
</p>

# 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](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)

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

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

### Install the Runtime Environment

**DCU environment**

```bash
# 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**

```bash
# 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**

```bash
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**

```bash
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:

```python
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.