Instructions to use c-bone/CrystaLLM-pi_mp_20_base with libraries, inference providers, notebooks, and local apps. Follow these links to get started.

Libraries

How to use c-bone/CrystaLLM-pi_mp_20_base with Transformers:

# Use a pipeline as a high-level helper
from transformers import pipeline

pipe = pipeline("text-generation", model="c-bone/CrystaLLM-pi_mp_20_base")

# Load model directly
from transformers import AutoTokenizer, AutoModelForCausalLM

tokenizer = AutoTokenizer.from_pretrained("c-bone/CrystaLLM-pi_mp_20_base")
model = AutoModelForCausalLM.from_pretrained("c-bone/CrystaLLM-pi_mp_20_base")

Notebooks
Google Colab
Kaggle
Local Apps

vLLM

How to use c-bone/CrystaLLM-pi_mp_20_base with vLLM:

Install from pip and serve model

# Install vLLM from pip:
pip install vllm
# Start the vLLM server:
vllm serve "c-bone/CrystaLLM-pi_mp_20_base"
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:8000/v1/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "c-bone/CrystaLLM-pi_mp_20_base",
		"prompt": "Once upon a time,",
		"max_tokens": 512,
		"temperature": 0.5
	}'

Use Docker

docker model run hf.co/c-bone/CrystaLLM-pi_mp_20_base

SGLang

How to use c-bone/CrystaLLM-pi_mp_20_base with SGLang:

Install from pip and serve model

# Install SGLang from pip:
pip install sglang
# Start the SGLang server:
python3 -m sglang.launch_server \
    --model-path "c-bone/CrystaLLM-pi_mp_20_base" \
    --host 0.0.0.0 \
    --port 30000
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:30000/v1/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "c-bone/CrystaLLM-pi_mp_20_base",
		"prompt": "Once upon a time,",
		"max_tokens": 512,
		"temperature": 0.5
	}'

Use Docker images

docker run --gpus all \
    --shm-size 32g \
    -p 30000:30000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=<secret>" \
    --ipc=host \
    lmsysorg/sglang:latest \
    python3 -m sglang.launch_server \
        --model-path "c-bone/CrystaLLM-pi_mp_20_base" \
        --host 0.0.0.0 \
        --port 30000
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:30000/v1/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "c-bone/CrystaLLM-pi_mp_20_base",
		"prompt": "Once upon a time,",
		"max_tokens": 512,
		"temperature": 0.5
	}'

Docker Model Runner
How to use c-bone/CrystaLLM-pi_mp_20_base with Docker Model Runner:
```
docker model run hf.co/c-bone/CrystaLLM-pi_mp_20_base
```

CrystaLLM-pi_mp_20_base / README.md

c-bone

Create README.md

fa84530 verified about 1 month ago

preview code

raw

history blame contribute delete

4.6 kB

	---
	language:
	- en
	license: mit
	library_name: transformers
	tags:
	- materials-science
	- crystallography
	- generative-ai
	- inverse-design
	- chemistry
	- unconditional
	datasets:
	- c-bone/mp_20
	pipeline_tag: text-generation
	---

	# Model Card for mp_20_base

	## Model Details

	### Model Description

	mp_20_base is an unconditional generative model designed for the generation of valid inorganic crystal structures. It serves as a foundational pre-trained model for the `CrystaLLM-pi` framework, specifically optimized for smaller unit cells. Based on a GPT-2 decoder-only architecture, it is trained on a corpus of Crystallographic Information Files (CIFs) to learn the syntax, symmetry, and chemical rules governing crystalline matter.

	This model does not accept property conditioning vectors. It generates structures based on text prompts (e.g., chemical composition or space group) or unconditionally (ab-initio generation).

	- Developed by: Bone et al. (University College London)
	- Model type: Autoregressive Transformer (GPT-2)
	- Language(s): CIF (Crystallographic Information File) syntax
	- License: MIT

	### Model Sources

	- Repository: [GitHub: CrystaLLM-pi](https://github.com/C-Bone-UCL/CrystaLLM-pi)
	- Paper: [Discovery and recovery of crystalline materials with property-conditioned transformers (arXiv:2511.21299)](https://arxiv.org/abs/2511.21299)
	- Dataset: [HuggingFace: c-bone/mp_20](https://huggingface.co/datasets/c-bone/mp_20)

	## Uses

	### Direct Use

	The model is intended for:
	1. Unconditional Generation: Exploring the general chemical space of stable crystals with 20 atoms or fewer in the unit cell.
	2. Composition/Space Group Completion: Generating valid structures given a partial prompt (e.g., a chemical formula).
	3. Fine-tuning base: Serving as the pre-trained initialization for property-conditional models.

	### Out-of-Scope Use

	- Property Conditioning: This model cannot be steered by properties like band gap or density. Use the specific fine-tuned variants for those tasks.
	- Large Unit Cells: The model is strictly trained on and intended for unit cells containing 20 atoms or fewer.

	## Bias, Risks, and Limitations

	- Training Distribution: The model reflects the biases present in the Materials Project dataset. It is biased toward theoretical, DFT-relaxed inorganic compounds rather than experimentally synthesized disordered structures.
	- Size Constraint Bias: Because it is trained exclusively on the `mp_20` subset, the model has a strong prior for generating small, highly symmetric unit cells (≤ 20 atoms) and will struggle to extrapolate to larger, more complex systems.
	- Validity: While it learns CIF syntax robustly, it may still generate physically invalid structures (e.g., overlapping atoms) or chemically unstable compositions.

	## Training Details

	### Training Data

	The model was pre-trained on the mp_20 dataset (`c-bone/mp_20`), a curated subset of the Materials Project database restricted to crystal structures containing 20 atoms or fewer per unit cell.

	- Source: Materials Project (via `c-bone/mp_20`)
	- Preprocessing: CIFs are filtered for size (≤ 20 atoms), deduplicated, augmented (with symmetry operations and fractional coordinate shifts), and tokenized.

	### Training Procedure

	- Architecture: GPT-2 Small (~25.9M parameters).
	- Objective: Causal Language Modeling (Next-token prediction).
	- Loss Function: Cross-entropy with specific weighting for fixed syntax tokens to accelerate learning of the CIF format.

	## Evaluation

	### Metrics

	The model is evaluated based on:
	1. Validity: The rate at which generated sequences can be parsed as valid CIF files.
	2. Structural Consistency: Adherence to space group symmetry and reasonable bond lengths.

	### Results

	The base model achieves high validity rates for small unit cells and effectively learns to generate chemically plausible structures, serving as a robust foundation for downstream tasks requiring rigid size constraints.

	## Citation

	```bibtex
	@misc{bone2025discoveryrecoverycrystallinematerials,
	title={Discovery and recovery of crystalline materials with property-conditioned transformers},
	author={Cyprien Bone and Matthew Walker and Kuangdai Leng and Luis M. Antunes and Ricardo Grau-Crespo and Amil Aligayev and Javier Dominguez and Keith T. Butler},
	year={2025},
	eprint={2511.21299},
	archivePrefix={arXiv},
	primaryClass={cond-mat.mtrl-sci},
	url={[https://arxiv.org/abs/2511.21299](https://arxiv.org/abs/2511.21299)},
	}