README.md

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


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

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

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


### Install the Runtime Environment

**DCU Environment**

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

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

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

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

```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)
```

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