rapmat

Rapid materials discovery in the terminal.

Layout
Installation
Test run
Concepts
Using the TUI
Troubleshooting
License

Layout

Path	Contents
`rapmat/core/`	Search, deduplication, phonons, validation, export
`rapmat/calculators/`	MLIP and DFT backends
`rapmat/storage/`	Database access layer and schema migrations
`rapmat/tui/`	Terminal user interface
`rapmat/utils/`	Hardware detection, crash-safe spglib calls, other helpers
`tests/`	pytest suite
`examples/`	Expected output of the test run
`pyproject.toml`	Package metadata, dependencies and optional calculator extras
`alembic.ini`	Migration tooling config, developers only
`.github/workflows/`	PyPI release workflow

Installation

Requirement
OS	Linux (recommended) runs every calculator. On Windows, use WSL2, or stay on native Windows for MatterSim and UPET only
Python	3.12, in a conda environment
GPU	An NVIDIA GPU is highly recommended. Some MLIPs also run on the CPU, much slower
Disk space	About 8 GB for the environment with CUDA PyTorch and all calculators, 5 GB more for the CUDA toolkit (NequIP only), plus the models downloaded on first use up to a few GB

rapmat requires Python 3.12 or later, but it pins PyTorch 2.9, which does not fully support Python 3.14 (it disables torch.compile there), so building the NequIP model fails on it. MatterSim is published pre-built only for Linux and macOS on Apple silicon, and only for Python 3.12 and 3.13.

Platform-specific steps:

Native Windows: install the C++ Build Tools
WSL2: set up WSL first.
Linux: for NequIP, install the NequIP prerequisites.

1. Install conda

Miniforge is recommended, miniconda also works.

Linux and WSL:

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

Accept the license and the install location, answer yes when asked to update your shell profile, then open a new terminal.

Windows: run Miniforge3-Windows-x86_64.exe, or

winget install CondaForge.Miniforge3

use the Miniforge Prompt from the Start menu. To use conda from PowerShell instead, run conda init powershell once in the Miniforge Prompt.

2. Create the environment

conda create -n rapmat python=3.12
conda activate rapmat

Activate the environment in every new terminal before installing or running rapmat.

3. Install PyTorch

Install it before rapmat, otherwise pip takes the default build from PyPI, which on Windows is CPU-only. With an NVIDIA GPU:

pip install torch==2.9.1 torchvision==0.24.1 torchaudio==2.9.1 --index-url https://download.pytorch.org/whl/cu126

Without an NVIDIA GPU, or with an RTX 50 series card, replace cu126 in the URL with the index from this table:

Index	For
`cu126`	NVIDIA GPUs from the GTX 900 series (Maxwell) to the RTX 40 series and H100
`cu128`	RTX 50 series (Blackwell) and newer, which `cu126` does not support
`cpu`	No NVIDIA GPU

4. Install rapmat

From a clone of this repository or its source archive:

pip install ".[mattersim,upet]"

Or the latest release from PyPI:

pip install "rapmat[all-calculators]"

Extra	Adds	Platforms
none	Only VASP	All
`mattersim`	MatterSim 5M	Linux, WSL, Windows (compiled during install)
`nequip`	NequIP OAM-L	Linux, WSL
`upet`	UPET OAM-XL	Linux, WSL, Windows
`all-calculators`	All	Linux, WSL

Combine extras with commas.

5. Check the installation

rapmat

The header shows CUDA when PyTorch finds a GPU and CPU otherwise, and the Home screen shows the GPU name under Hardware. Press i (Status) and check that the installed calculators are listed as installed. The TUI also works with the mouse in most terminals.

Windows (native)

Install the NVIDIA driver.
MatterSim has no pre-built Windows package, so pip compiles it, which needs the Microsoft C++ Build Tools. Download Build Tools for Visual Studio and select the Desktop development with C++ workload (MSVC and the Windows SDK), or run:
```
winget install --id Microsoft.VisualStudio.BuildTools --override "--passive --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
```
Open a new terminal afterwards.
Follow steps 1 to 5.

WSL2

NVIDIA's CUDA on WSL guide and Ubuntu's WSL GPU guide have more detail.

On Windows:

Install the NVIDIA driver for Windows. WSL uses this driver. Do not install an NVIDIA driver inside WSL!
Enable WSL and install Ubuntu, restart if asked (run as admin):
```
wsl --install
```
If WSL is already enabled:
```
wsl --install -d Ubuntu-24.04
```
To update:
```
wsl --update
```
Start Ubuntu with wsl from a normal terminal and create your Linux user.

Inside WSL (Ubuntu):

Check that the GPU is visible:
```
nvidia-smi
```
For NequIP, install the NequIP prerequisites.
Follow steps 1 to 5 with the Linux commands.

Under /mnt/c file access is slower, keep things in ~ if possible.

NequIP prerequisites (Linux and WSL)

On first use, it needs a C/C++ compiler and the CUDA toolkit, whose version should match the PyTorch build (12.6 for cu126, 12.8 for cu128). On Ubuntu in WSL:

sudo apt update
sudo apt install -y build-essential
wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update
sudo apt install -y cuda-toolkit-12-6

On native Ubuntu, replace wsl-ubuntu with your release, such as ubuntu2404 or ubuntu2204. Note, that cuda-toolkit-12-6 installs only the toolkit, without a driver.

The compile also links against the CUDA driver library, so add the toolkit's stub library to the linker path:

echo 'export LIBRARY_PATH=/usr/local/cuda/lib64/stubs:$LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

VASP (optional)

Point VASP_PP_PATH at the directory that contains the POTCAR sets:

echo 'export VASP_PP_PATH=$HOME/vasp/pp' >> ~/.bashrc
source ~/.bashrc

Each POTCAR is found at $VASP_PP_PATH/<set>/<name>/POTCAR.

Test run

The mattersim and upet extras are necessary. The models are downloaded on first use. This run takes about 1.5 h, depending on the hardware.

Home -> s (Studies) -> n (New): System Si, a Study Name of your choice, Domain bulk, Calculator MATTERSIM, Force conv. crit 0.01 (the default is 0.005). Leave Default symprec at 0.01. Move to Create Study and press Enter, then OK.
Enter on the new study -> n (New Run): Formula Si, Formula units min 1 and max 8, Candidates/group 2, Seed 1. F5 (Start Run) queues 8 x 230 x 2 = 3680 candidates. Wait for rapmat to generate and relax them.
Answer Yes to View results?. Structures are sorted by energy per atom. Diamond Si comes first: the leading rows are cells of different size of the same structure, with Final SG Fd-3m (227) (if symprec is kept loose enough) and an energy of about -5.4095 eV/atom.
Esc twice, back to the study -> d (Dedup) on the run -> F5 (Analyze), then Apply to DB (a) and OK. Esc twice, back to the study, and Enter on the run reopens Results. d hides the duplicates.
s (Save): Scope All N filtered structures, Format cif, keep Results table at txt, then Save. The structures and results_table.txt are written to saved_<run>/ in the directory rapmat was started from. The table should roughly match examples/expected_results_table.txt.
v (Validate): Ref. calculator UPET, Top N 20 -> F5 (Evaluate). The Validation Results header shows Kendall tau with its p-value and n, and the MAE of MatterSim against UPET over the visible structures. Expect about tau = 0.82 (p = 4.6e-9, n = 20) and an MAE of 0.028 eV/atom. examples/expected_eval.txt contains the full header and table examples.

The digits can differ with the hardware and library versions.

Concepts

Study and run

A study fixes the chemical system (e.g. Al-O) and the settings shared by all its runs: calculator, domain, external pressure, relaxation convergence criterion, etc.

A run belongs to one study and searches a formula over a range of formula units, e.g. Al2O3 x 2..4.

Using the TUI

Home

Below the menu, Home shows the database location and the detected hardware with the GPU name. The right panel lists the five most recent runs with counts per structure status. Press Right to move into it and Enter to open a run's results.

Studies

Key	Action
`n`	New study
`Enter`	Open the study
`Del`	Delete the study with all its runs and structures, after confirmation

Study detail

Key	Action
`Enter`	Results of the focused run
`r`	Resume the focused run
`n`	New run in this study
`d`	Deduplication of the focused run
`Del`	Delete the focused run, after confirmation

Results

Lists the relaxed structures of one run, sorted by energy per atom (enthalpy under pressure), lowest first.

Key	Action
`Enter`	3D view
`s`	Save structures
`o`	Options
`v`	Validate against a reference calculator
`t`	Maximum thickness
`p`	Phonons
`d`	Show or hide duplicates
`?`	Help

Esc first clears an active search, then goes back.

Validation

Computes single-point energies of the MLIP-relaxed structures with a reference calculator, typically VASP, and compares the rankings.

The structures passed are those visible in Results when v is pressed, including the thickness filter, for example.

t and d filters work as in Results.

DB Settings

The screen shows the active database and the db.toml path.

Test opens the database at the path, creating it if needed.
Save switches to the new database.
Clear Config deletes db.toml after confirmation. The default location is used from the next start.
Disk Usage shows the database size and how much of it can be reclaimed.
Compact Now releases that space, after confirmation.

VASP settings

TOML file. The keys are passed to ASE's Vasp calculator as keyword arguments:

xc = "pbe"
encut = 520
kspacing = 0.25
ismear = 0
sigma = 0.05

A directory key is ignored, rapmat assigns one per calculation.

Troubleshooting

NequIP fails on first use. The error gives the exit code and the path to nequip_install.log. Check the NequIP prerequisites. CUDA_HOME environment variable is not set in the log means the CUDA toolkit is missing.

Space-group labels look wrong, or everything is P1. Labels depend on symprec. Press o in Results or Phase Analysis and relabel with a looser (larger) or tighter (smaller) value.

Where do saved files go? Into the directory rapmat was started from, unless you change the path.

License

See LICENSE.

Metadata

Release files for rapmat 0.4.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rapmat 0.4.5
File	Size	Uploaded
rapmat-0.4.5.tar.gz	211.2 kB	Sep 28, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for rapmat 0.4.5
File	Interpreter	ABI	Platform	Reset
rapmat-0.4.5-py3-none-any.whl 165.9 kB Sep 28, 2026	Python 3	none	any	Details

Total release size: 377.1 kB

Release files / rapmat-0.4.5.tar.gz

Download URL	rapmat-0.4.5.tar.gz
Size	211.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`66ed0d82626f14c711f3a732081299462b13d42ea355b2fc2e83bd02aae7a50e`
BLAKE2b-256 checksum How to use checksums	`fb5118d837192bb358f097ff0e1d0b8010385b53a6a726cd4d3c0272dac46cd6`
Upload date	Sep 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/leqord/rapmat
Publishing commit: github.com/leqord/rapmat/tree/08926a8d7ffd2672c17575e5a8447acdbef343d2

Workflow

Publishing configuration: github.com/leqord/rapmat/blob/08926a8d7ffd2672c17575e5a8447acdbef343d2/.github/workflows/python-publish.yml
Publishing logs: github.com/leqord/rapmat/actions/runs/36453957875/attempts/1

Artifact

Subject: rapmat-0.4.5.tar.gz
SHA-256 checksum: 66ed0d82626f14c711f3a732081299462b13d42ea355b2fc2e83bd02aae7a50e Verifying attestations

Release files / rapmat-0.4.5-py3-none-any.whl

Download URL	rapmat-0.4.5-py3-none-any.whl
Size	165.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`82040d40905e3ec6d9e09f305d793b8e346f5ff03363666e956adbd7e428027d`
BLAKE2b-256 checksum How to use checksums	`cdd82bc52b716e1cd907c759e58c1ff210df6823b963c8b5e0f5cf951b541a28`
Upload date	Sep 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/leqord/rapmat
Publishing commit: github.com/leqord/rapmat/tree/08926a8d7ffd2672c17575e5a8447acdbef343d2

Workflow

Publishing configuration: github.com/leqord/rapmat/blob/08926a8d7ffd2672c17575e5a8447acdbef343d2/.github/workflows/python-publish.yml
Publishing logs: github.com/leqord/rapmat/actions/runs/36453957875/attempts/1

Artifact

Subject: rapmat-0.4.5-py3-none-any.whl
SHA-256 checksum: 82040d40905e3ec6d9e09f305d793b8e346f5ff03363666e956adbd7e428027d Verifying attestations