SciVerseGym User ManualSciVerseGym 用户说明书

1. Overview1. 项目概览

SciVerseGym is a Gymnasium-style environment for materials discovery. Agents do not emit raw CIF files. They submit structured crystal-edit actions. The environment applies the edit to the current ASE Atoms, evaluates the new structure with the configured MLFF or custom calculator, computes reward, and returns a standard transition.

SciVerseGym 是一个 Gymnasium 风格的材料发现环境。智能体不需要直接输出 CIF 文件，而是提交 结构化晶体编辑 action。环境会把 action 应用到当前 ASE Atoms，再用配置好的 MLFF 或自定义 calculator 评估新结构，计算 reward，并返回标准 transition。

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

2. Install2. 安装

Install the repository in editable mode with development tools:

以 editable 模式安装仓库和开发工具：

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

Install built-in MLFF adapters and their optional dependencies:

安装内置 MLFF 适配器和可选依赖：

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

3. Jupyter From Zero3. Jupyter 从 0 开始

Cell 1: imports and pathsCell 1：导入和路径

from pathlib import Path
import gymnasium as gym
import numpy as np

import sciverse_gym
from sciverse_gym.benchmarks.bo_baselines.simple_bo import (
    candidate_actions,
    choose_action,
    featurize,
)

DATA_PATH = Path("data/alex-mp-20")
print("parquet files:", [p.name for p in DATA_PATH.glob("*.parquet")])

Cell 2: create an MLFF-backed environmentCell 2：创建 MLFF 环境

env = gym.make(
    "CrystalDiscovery-v0",
    data_path=str(DATA_PATH),
    mlff_model="sevennet",
    mlff_relax=False,
    max_steps=5,
    max_dataset_rows=20,
)

obs, info = env.reset(seed=0, options={"index": 0})
print(env.render())
print(info)

Cell 3: submit one action and read the new stateCell 3：提交 action 并读取新 state

action = {"action_type": 0, "site": 0, "element": 28}  # 28 = Ni
old_formula = obs["structure"].get_chemical_formula()

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

print("old formula:", old_formula)
print("submitted action:", action)
print("new formula:", info["formula"])
print("new energy:", float(obs["energy"]))
print("reward:", reward)
print("backend:", info["backend"])
print("step:", obs["step"], "budget_left:", obs["budget_left"])

4. Environment API4. 环境接口

env = gym.make("CrystalDiscovery-v0", ...)

Phonon-related mlff_kwargs example声子相关 mlff_kwargs 示例

env = gym.make(
    "CrystalDiscovery-v0",
    data_path="data/alex-mp-20",
    mlff_model="sevennet",
    mlff_compute_phonons=True,
    mlff_kwargs={
        "phonon_supercell": (2, 2, 2),
        "phonon_displacement": 0.01,
        "phonon_mesh": (8, 8, 8),
        "phonon_stability_tolerance": -0.1,
    },
    max_steps=1,
)

5. Actions5. Action 结构

Actions are dictionaries. Missing fields use conservative defaults, but explicit fields are recommended.

action 是 dictionary。缺失字段有保守默认值，但推荐显式写清字段。

• element is an atomic number clipped to 1..94.element 是原子序数，内部裁剪到 1..94。
• lattice_delta is clipped to [-0.15, 0.15] per component.lattice_delta 每个分量裁剪到 [-0.15, 0.15]。
• atom_delta is clipped to [-0.25, 0.25] per component.atom_delta 每个分量裁剪到 [-0.25, 0.25]。

6. Atomic Number Table6. 原子序数表

The table is generated from one shared data source, so both languages show the same atomic numbers and symbols.

下表由同一份数据生成，因此中英文显示相同的原子序数和元素符号。

7. State and Info7. State 与 Info

8. MLFF8. MLFF 配置

Supported built-in backends are sevennet, mattersim, and orb. Examples use sevennet.

内置后端包括 sevennet、mattersim 和 orb。示例使用 sevennet。

from ase.build import bulk
from sciverse_gym.calculators import mlff_energy

atoms = bulk("Si", "diamond", a=5.43)
energy_per_atom = mlff_energy(atoms, model="sevennet", per_atom=True)
print(energy_per_atom)

9. Reward9. Reward 机制

The default reward combines stability, element abundance, and composition novelty.

默认 reward 由稳定性、元素丰度和组成新颖性三部分构成。

reward = 0.80 * stability + 0.10 * abundance_proxy + 0.10 * novelty

Example:
energy_above_hull = 0.05 eV/atom
mean_Z = 30
new formula in this episode

stability = 1 / (1 + 0.05 / 0.1) = 0.6667
abundance_proxy = 1 / (1 + 30 / 60) = 0.6667
novelty = 0.25
reward = 0.80*0.6667 + 0.10*0.6667 + 0.10*0.25 = 0.6250

10. BO and RL10. BO 和 RL

Run the built-in BO baseline运行内置 BO baseline

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

Minimal BO training loop最小 BO 训练循环

bo_env = gym.make(
    "CrystalDiscovery-v0",
    data_path=str(DATA_PATH),
    mlff_model="sevennet",
    mlff_relax=False,
    max_steps=5,
    max_dataset_rows=20,
)
obs, info = bo_env.reset(seed=1, options={"index": 0})
rng = np.random.default_rng(1)
x_train, y_train = [], []

for _ in range(5):
    actions = candidate_actions(obs)
    action = choose_action(obs, actions, x_train, y_train, rng, exploration=1.5)
    old_obs = obs
    obs, reward, terminated, truncated, info = bo_env.step(action)
    x_train.append(featurize(old_obs, action))
    y_train.append(float(reward))
    if terminated or truncated:
        break

Minimal RL/action-value loop最小 RL/action-value 循环

def action_key(action):
    return tuple(sorted((k, tuple(v) if isinstance(v, list) else v) for k, v in action.items()))

q_values = {}
alpha = 0.3
rng = np.random.default_rng(2)
obs, info = env.reset(seed=2, options={"index": 0})

while True:
    actions = candidate_actions(obs)
    action = dict(actions[int(rng.integers(len(actions)))])
    obs, reward, terminated, truncated, info = env.step(action)
    key = action_key(action)
    q_values[key] = q_values.get(key, 0.0) + alpha * (float(reward) - q_values.get(key, 0.0))
    if terminated or truncated:
        break

11. Formation Energy, Convex Hull, and Phonons11. 形成能、Convex Hull 和声子

E_form_per_atom = (E_total - sum_i n_i * mu_i) / N

Convex hull requires same-force-field hull reference entries. Without them, energy_above_hull=None.

Convex hull 需要同力场 hull reference entries。没有这些 reference 时，energy_above_hull=None。

from sciverse_gym.calculators import build_alex_mp20_physical_calculator

calculator = build_alex_mp20_physical_calculator(
    data_path="data/alex-mp-20",
    model="sevennet",
    reference_cache_path="data/alex-mp-20/sevennet_reference_hull.json",
    max_reference_entries=None,
    relax=True,
    relax_cell=False,
    relax_references=False,
    compute_phonons=False,
)

env = gym.make(
    "CrystalDiscovery-v0",
    data_path="data/alex-mp-20",
    calculator=calculator,
)

Phonons can be enabled directly through the MLFF path or through the reference-backed calculator. They are expensive because displaced supercells require force evaluations.

声子可以直接通过 MLFF 路径开启，也可以在带 reference 的 calculator 中开启。声子很慢，因为多个有限位移超胞都要计算 forces。

env = gym.make(
    "CrystalDiscovery-v0",
    data_path="data/alex-mp-20",
    mlff_model="sevennet",
    mlff_compute_phonons=True,
    mlff_kwargs={
        "phonon_supercell": (2, 2, 2),
        "phonon_mesh": (8, 8, 8),
        "phonon_displacement": 0.01,
        "phonon_stability_tolerance": -0.1,
    },
    max_steps=1,
)

12. Dataset12. 数据集

The default data directory is data/alex-mp-20. The dataset should return StructureRecord objects with atoms, material_id, and metadata.

默认数据目录是 data/alex-mp-20。数据集应返回包含 atoms、material_id、metadata 的 StructureRecord。

env = gym.make(
    "CrystalDiscovery-v0",
    dataset=my_dataset,
    mlff_model="sevennet",
    mlff_relax=False,
)

13. API Reference13. API 速查

14. Crystal Playground14. 晶体可视化界面

The file docs/crystal-playground.html is a standalone browser interface for exploring SVGym-style crystal generation and edit actions without installing Python packages or starting a server. It is intended as a visual entry point before running the Gymnasium environment in code.

docs/crystal-playground.html 是一个可以直接在浏览器打开的本地晶体可视化界面，用来体验 SVGym 风格的晶体生成和编辑动作。它不需要安装 Python 包，也不需要启动服务器，适合在正式写 Gymnasium 代码前先理解结构、action 和 observation 的关系。

Open it from zero从零打开

1. Open the repository folder on your computer.在电脑上打开本项目文件夹。
2. Go to docs/ and double-click crystal-playground.html.进入 docs/ 目录，双击 crystal-playground.html。
3. Use the language button in the top-right area of the page to switch between English and Chinese.使用页面右上角的语言按钮在英文和中文之间切换。
4. No network, backend service, or build step is required.不需要网络、后端服务或构建步骤。

Generate a preset crystal生成预设晶体

In Structure preset, choose a template such as rocksalt, BCC, FCC, diamond, perovskite, fluorite, rutile, or spinel. The three chemistry-channel selectors define which elements are placed on the A, B, and C/anion sites for these presets.

在 结构预设 中选择 rocksalt、BCC、FCC、diamond、perovskite、fluorite、rutile、 spinel 等模板。三个化学通道选择器用于决定预设结构中 A、B、C/阴离子位点放入哪些元素。

Upload a CIF file上传 CIF 文件

Click Upload CIF and choose a local .cif file. The playground reads fractional atom coordinates, detects element symbols from _atom_site_type_symbol or labels, expands common symmetry-operation loops into the full unit cell, and then applies the current supercell size.

点击 上传 CIF 并选择本地 .cif 文件。界面会读取原子分数坐标，从 _atom_site_type_symbol 或 label 中识别元素，读取常见对称操作并展开为完整晶胞， 然后再按照当前超胞尺寸复制。

Use the action buttons使用 action 按钮

Read the display阅读界面信息

• Drag the main crystal view to rotate the structure manually.拖动主晶体视图可以手动旋转结构。
• Click an atom to focus the local zoom view on its neighborhood.点击某个原子，右侧局部放大图会聚焦它的邻域。
• The top chips show formula, toy energy, and reward for quick feedback.顶部标签显示化学式、玩具能量和 reward，用于快速反馈。
• The element legend confirms whether CIF elements were detected as separate species.元素图例可以确认 CIF 中的元素是否被识别成不同种类。
• The observation panel shows a JSON-like state snapshot similar to what an environment returns.Observation 面板展示类似环境返回值的 JSON 状态快照。

Export and limitations导出与限制

Use Export JSON to save the current visual observation. The playground is a teaching and exploration interface: its energy and reward values are lightweight toy scores, not MLFF calculations. For real optimization, use the Python environment and MLFF backends described in earlier sections.

使用 导出 JSON 可以保存当前可视化 observation。该界面是教学和探索工具，其中能量与 reward 是轻量玩具分数，不是 MLFF 真实计算。真正的优化任务请使用前面章节介绍的 Python 环境和 MLFF 后端。

15. Troubleshooting15. 常见问题

• If energy_above_hull is None, build a same-force-field reference calculator.如果 energy_above_hull 是 None，需要构建同力场 reference calculator。
• If formation_energy_per_atom is None, an elemental reference is missing.如果 formation_energy_per_atom 是 None，说明缺少元素 reference。
• If raw random actions select unsupported elements, use controlled candidate actions instead of env.action_space.sample().如果裸随机 action 抽到 MLFF 不支持的元素，请使用受控候选 action，不要直接用 env.action_space.sample()。
• If PyG optional extensions warn about ABI mismatch, the fallback graph path may still allow environment loops to run.如果 PyG 可选扩展出现 ABI warning，fallback graph 路径通常仍可让环境循环运行。

16. Citation16. 引用方式

If you use SVGym (SciVerseGym), please cite:

如果你使用 SVGym (SciVerseGym)，请引用：

@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},
}