简体中文

A NoneBot2 plugin that connects to the Materials Project API, allowing users to query crystal structures, search for materials, retrieve CIF files, and render crystal structure images via VESTA in QQ group chats.

• Material lookup: Retrieve symmetrized CIF files using a material_id (e.g., mp-162)
• Structure rendering: Render crystal structures via VESTA, either in the default view or projected along a specified crystal plane
• Material search: Automatically match one of three search modes — "only elements", "at least elements", or "chemical formula"
• Paged browsing: Search results are displayed 10 per page, with nextp / lastp for pagination
• Index reference: Reference a search result by index to fetch its CIF or rendered image
• Cooldown: Per-group cooldown timers to prevent abuse
• Admin commands: Per-group enable/disable toggle and cooldown reset

If you don't have a NoneBot2 project yet, follow the official guide to create one:

pip install nonebot2 nonebot-adapter-onebot

pip install mp-api pymatgen

Download and install the version for your OS from the official VESTA website.

Important notes

• Windows / macOS: Precompiled binaries are available. Just install and go.
• Linux: There is no official Linux binary. To run on a Linux server, use Wine to run the Windows version, together with Xvfb for a virtual display.
• VESTA is a GUI program and requires an available display environment (a Windows/macOS desktop, or Linux with Xvfb).

Place the materials_project directory inside your NoneBot2 project's plugins directory:

your_bot_project/
├── plugins/
│   └── materials_project/
│       ├── __init__.py
│       ├── config.py
│       ├── mp_api.py
│       ├── render_vesta.py
│       ├── search.py
│       ├── cooldown.py
│       └── admin.py
├── .env
└── pyproject.toml

Then make sure the plugin is loaded in pyproject.toml:

[tool.nonebot]
plugins = ["materials_project"]

Add the following to your project's .env file:

# Materials Project API Key (required)
# Apply for one at https://materialsproject.org/api
MP_API_KEY=your_api_key_here

# Path to the VESTA executable (required)
# Windows example: C:/Program Files/VESTA/VESTA.exe
# macOS example:   /Applications/VESTA/VESTA.app/Contents/MacOS/VESTA
# Linux example:   /usr/local/bin/VESTA
VESTA_EXEC=C:/Program Files/VESTA/VESTA.exe

# Image generation timeout in seconds (optional, default 30)
IMAGE_TIMEOUT=30

# Search results per page (optional, default 10)
SEARCH_PAGE_SIZE=10

These fields are automatically mapped to the Config model in config.py (NoneBot2 converts environment variable names to lowercase field names).

All commands respond only when the bot is @-mentioned (except nextp / lastp).

Automatic search mode matching:

• /mp and /mp.prev share one cooldown timer, duration 1 minutes
• /mp.search has its own timer, duration 1 minutes
• Cooldowns are tracked separately per group
• Pagination commands nextp / lastp have no cooldown

materials_project/
├── __init__.py        # Plugin entry, event handler registration, command handling
├── config.py          # Configuration model (loaded from .env)
├── mp_api.py          # Materials Project API wrapper
├── render_vesta.py    # VESTA rendering and image export
├── search.py          # Search result cache and pagination
├── cooldown.py        # Per-group cooldown management
└── admin.py           # Per-group enabled/disabled state management

The plugin invokes VESTA with the following command-line arguments:

VESTA -open structure.cif -export_img output.png -close

When a crystal plane is specified, rotation parameters are appended:

VESTA -open structure.cif -rotate_x 30 -rotate_y 45 -export_img output.png -close

• VESTA's -export_img argument only exports the image; it does not cause the program to exit. The plugin therefore actively terminates the VESTA process once the PNG is detected.

• VESTA's command line only exposes -rotate_x/y/z Euler angles and cannot directly specify the [hkl] normal direction. The plugin's plane projection uses a heuristic approximation; precise alignment would require a preset .vesta template file (not yet implemented).

• Headless Linux servers require Xvfb:

  xvfb-run -a /path/to/VESTA -open structure.cif -export_img output.png -close

  Alternatively, prepend ["xvfb-run", "-a"] to the Popen arguments in render_vesta.py.

pip install mp-api pymatgen

Issues and PRs are welcome. If you implement any of the following, contributions are especially appreciated:

• Precise [hkl] projection (via a preset .vesta template)
• Automatic Linux + Xvfb adaptation
• Support for additional rendering backends (e.g., ASE, py3Dmol)
• Filtering by space group, band gap, stability, etc.

This project is released under the MIT License.

• Materials Project — for providing an open materials database and API
• NoneBot2 — an excellent asynchronous Python bot framework
• VESTA — a powerful crystal structure visualization tool
• pymatgen — a Python library for materials science

This plugin is intended for learning and research purposes only. When using the Materials Project API, please comply with their terms of use.