SciVerseGym (SVGym) is a Gymnasium-style environment for crystal-structure discovery. Agents submit structured crystal-edit actions, and the environment returns the standard Gymnasium step tuple:

obs, reward, terminated, truncated, info = env.step(action)

Highlights

Install

python -m pip install -e ".[dev,mlff]"

Quick Start

import gymnasium as gym
import sciverse_gym  # registers CrystalDiscovery-v0

env = gym.make(
    "CrystalDiscovery-v0",
    data_path="data/alex-mp-20",
    mlff_model="sevennet",
    mlff_relax=False,
    max_steps=5,
    max_dataset_rows=20,
)

obs, info = env.reset(seed=0, options={"index": 0})
action = {"action_type": 0, "site": 0, "element": 28}
obs, reward, terminated, truncated, info = env.step(action)
print(info["formula"], float(obs["energy"]), reward)

Commands

python -m pytest
python -m sciverse_gym.benchmarks.bo_baselines.simple_bo --steps 5 --mlff-model sevennet
python -m sciverse_gym.benchmarks.rl_baselines.random_rollout --steps 5 --mlff-model sevennet

Documentation

Open docs/manual.html in a browser for the full manual. It covers installation, all gym.make(...) parameters, action schemas, atomic numbers, BO/RL examples, reward calculation, formation energy, convex hull, phonons, datasets, and troubleshooting.

Crystal Playground

Open docs/crystal-playground.html directly in a browser to try the bilingual English/Chinese SVGym Crystal Playground. It runs locally with no server or extra dependencies. Use the controls to generate many crystal presets, upload a CIF file with symmetry expansion into the full unit cell, adjust the lattice, add displacement or vacancies, run SVGym-style edit steps, inspect the local zoom view, relax the structure, and export the current observation as JSON.

Citation

If you use SVGym (SciVerseGym), please cite:

@misc{cao2026svgymsciversegymenvironmentreinforcement,
      title={SVGym (SciVerseGym): An Environment for Reinforcement Learning and Bayesian Optimization in Crystal Discovery},
      author={Bin Cao},
      year={2026},
      eprint={2606.22425},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2606.22425},
}