# Chemeleon-DNG: Chemeleon for De Novo Generation
While [Chemeleon](https://github.com/hspark1212/chemeleon) GitHub repository focuses on text-guided crystal structure generation, this repository provides a framework for **De Novo Generation (DNG)** and **Crystal Structure Prediction (CSP)** tasks.
- **CSP (Crystal Structure Prediction)**: Predicts stable crystal structures from given atom types
- **DNG (De Novo Generation)**: Generates new crystal structures from scratch
## Installation
### Prerequisites
- Python 3.11+
- PyTorch >= 2.1.0
- CUDA (optional, for GPU acceleration)
### Install via pip
```bash
pip install chemeleon-dng
```
### Install from Source
If you don't have uv installed:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Then install the package:
```bash
git clone https://github.com/hspark1212/chemeleon-dng.git
cd chemeleon-dng
uv sync
```
## Quick Start
### Crystal Structure Prediction (CSP)
Generate crystal structures for given chemical formulas:
```python
from chemeleon_dng.sample import sample
sample(
task="csp",
formulas=["NaCl", "LiMnO2"],
num_samples=10,
output_dir="results",
device="cpu"
)
```
> [!TIP]
> Invoke `help(sample)` to explore all available parameters and usage examples.
### Command-Line Interface
After installing via pip, you can use the `chemeleon-dng` command directly:
```bash
chemeleon-dng --task=csp --formulas="NaCl,LiMnO2" --num_samples=10 --output_dir="results" --device=cpu
```
This command generates 10 crystal structures for the given formulas using the CSP task and saves the CIF files of the generated structures in the `results/` directory using CPU.
### De Novo Generation (DNG)
Generate novel crystal structures without predefined compositions:
```python
from chemeleon_dng.sample import sample
sample(
task="dng",
num_samples=200,
batch_size=100,
output_dir="results",
device="cuda"
)
```
For the command line interface:
```bash
chemeleon-dng --task=dng --num_samples=200 --batch_size=100 --output_dir="results" --device=cuda
```
This command generates 200 random crystal structures using the DNG task with two batches of 100 each, and saves the generated structures in the `results/` directory using GPU.
## Pretrained Models
When you run the sample script, it will automatically download the pretrained models from the [figshare](https://figshare.com/articles/dataset/Chemeleon-dng/29196176?file=54966305) repository and save them in the `ckpts/` directory (if not already present). The pretrained models were trained on `mp-20` and `alex_mp_20` datasets.
The framework includes pretrained checkpoints located in the `ckpts/` directory:
- `chemeleon_csp_alex_mp_20_v0.0.2.ckpt`
- `chemeleon_dng_alex_mp_20_v0.0.2.ckpt`
- `chemeleon_csp_mp_20_v0.0.2.ckpt`
- `chemeleon_dng_mp_20_v0.0.2.ckpt`
## Benchmarks
For benchmarking purposes, we provide 10,000 sampled structures for the `DNG` task trained on [`mp-20`](benchmarks/chemeleon_dng_mp_20_v0.0.2.json.gz) and [`alex_mp_20`](benchmarks/chemeleon_dng_alex_mp_20_v0.0.2.json.gz) datasets in the `benchmarks/` directory. The sampled structures are saved in CIF format and compressed JSON format.
## Citation
If you find our work helpful, please cite the following publication:
**"Exploration of crystal chemical space using text-guided generative artificial intelligence"** *Nature Communications* (2025)
DOI: [10.1038/s41467-025-59636-y](https://doi.org/10.1038/s41467-025-59636-y)
```bibtex
@article{park2025exploration,
title={Exploration of crystal chemical space using text-guided generative artificial intelligence},
author={Park, Hyunsoo and Onwuli, Anthony and Walsh, Aron},
journal={Nature Communications},
volume={16},
number={1},
pages={1--14},
year={2025},
publisher={Nature Publishing Group}
}
```
## License
This project is licensed under the MIT License, developed by [Hyunsoo Park](https://hspark1212.github.io) as part of the [Materials Design Group](https://github.com/wmd-group) at Imperial College London.
See the [LICENSE file](https://github.com/hspark1212/chemeleon/blob/main/LICENSE) for more details.
Raw data
{
"_id": null,
"home_page": null,
"name": "chemeleon-dng",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Hyunsoo Park <hspark1212@gmail.com>",
"keywords": "crystal structure, materials science, generative AI, diffusion models, crystal structure prediction, de novo generation",
"author": null,
"author_email": "Hyunsoo Park <hspark1212@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b3/2f/7c9138985f860f6cc5ccef8030ac7382b6057361a66d3f5a0e0acd6552e4/chemeleon_dng-0.1.2.tar.gz",
"platform": null,
"description": "# Chemeleon-DNG: Chemeleon for De Novo Generation\n\nWhile [Chemeleon](https://github.com/hspark1212/chemeleon) GitHub repository focuses on text-guided crystal structure generation, this repository provides a framework for **De Novo Generation (DNG)** and **Crystal Structure Prediction (CSP)** tasks.\n\n- **CSP (Crystal Structure Prediction)**: Predicts stable crystal structures from given atom types\n- **DNG (De Novo Generation)**: Generates new crystal structures from scratch\n\n## Installation\n\n### Prerequisites\n\n- Python 3.11+\n- PyTorch >= 2.1.0\n- CUDA (optional, for GPU acceleration)\n\n### Install via pip\n\n```bash\npip install chemeleon-dng\n```\n\n### Install from Source\n\nIf you don't have uv installed:\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\nThen install the package:\n\n```bash\ngit clone https://github.com/hspark1212/chemeleon-dng.git\ncd chemeleon-dng\nuv sync\n```\n\n## Quick Start\n\n### Crystal Structure Prediction (CSP)\n\nGenerate crystal structures for given chemical formulas:\n\n```python\nfrom chemeleon_dng.sample import sample\n\nsample(\n task=\"csp\",\n formulas=[\"NaCl\", \"LiMnO2\"],\n num_samples=10,\n output_dir=\"results\",\n device=\"cpu\"\n)\n```\n\n> [!TIP]\n> Invoke `help(sample)` to explore all available parameters and usage examples.\n\n### Command-Line Interface\n\nAfter installing via pip, you can use the `chemeleon-dng` command directly:\n\n```bash\nchemeleon-dng --task=csp --formulas=\"NaCl,LiMnO2\" --num_samples=10 --output_dir=\"results\" --device=cpu\n```\n\nThis command generates 10 crystal structures for the given formulas using the CSP task and saves the CIF files of the generated structures in the `results/` directory using CPU.\n\n### De Novo Generation (DNG)\n\nGenerate novel crystal structures without predefined compositions:\n\n```python\nfrom chemeleon_dng.sample import sample\n\nsample(\n task=\"dng\",\n num_samples=200,\n batch_size=100,\n output_dir=\"results\",\n device=\"cuda\"\n)\n```\n\nFor the command line interface:\n\n```bash\nchemeleon-dng --task=dng --num_samples=200 --batch_size=100 --output_dir=\"results\" --device=cuda\n```\n\nThis command generates 200 random crystal structures using the DNG task with two batches of 100 each, and saves the generated structures in the `results/` directory using GPU.\n\n## Pretrained Models\n\nWhen you run the sample script, it will automatically download the pretrained models from the [figshare](https://figshare.com/articles/dataset/Chemeleon-dng/29196176?file=54966305) repository and save them in the `ckpts/` directory (if not already present). The pretrained models were trained on `mp-20` and `alex_mp_20` datasets.\n\nThe framework includes pretrained checkpoints located in the `ckpts/` directory:\n\n- `chemeleon_csp_alex_mp_20_v0.0.2.ckpt`\n- `chemeleon_dng_alex_mp_20_v0.0.2.ckpt`\n- `chemeleon_csp_mp_20_v0.0.2.ckpt`\n- `chemeleon_dng_mp_20_v0.0.2.ckpt`\n\n## Benchmarks\n\nFor benchmarking purposes, we provide 10,000 sampled structures for the `DNG` task trained on [`mp-20`](benchmarks/chemeleon_dng_mp_20_v0.0.2.json.gz) and [`alex_mp_20`](benchmarks/chemeleon_dng_alex_mp_20_v0.0.2.json.gz) datasets in the `benchmarks/` directory. The sampled structures are saved in CIF format and compressed JSON format.\n\n## Citation\n\nIf you find our work helpful, please cite the following publication:\n\n**\"Exploration of crystal chemical space using text-guided generative artificial intelligence\"** *Nature Communications* (2025) \nDOI: [10.1038/s41467-025-59636-y](https://doi.org/10.1038/s41467-025-59636-y)\n\n```bibtex\n@article{park2025exploration,\n title={Exploration of crystal chemical space using text-guided generative artificial intelligence},\n author={Park, Hyunsoo and Onwuli, Anthony and Walsh, Aron},\n journal={Nature Communications},\n volume={16},\n number={1},\n pages={1--14},\n year={2025},\n publisher={Nature Publishing Group}\n}\n```\n\n## License\n\nThis project is licensed under the MIT License, developed by [Hyunsoo Park](https://hspark1212.github.io) as part of the [Materials Design Group](https://github.com/wmd-group) at Imperial College London. \nSee the [LICENSE file](https://github.com/hspark1212/chemeleon/blob/main/LICENSE) for more details.\n",
"bugtrack_url": null,
"license": null,
"summary": "Chemeleon framework for De Novo Generation (DNG) and Crystal Structure Prediction (CSP) tasks",
"version": "0.1.2",
"project_urls": {
"Documentation": "https://github.com/hspark1212/chemeleon-dng#readme",
"Homepage": "https://github.com/hspark1212/chemeleon-dng",
"Issues": "https://github.com/hspark1212/chemeleon-dng/issues",
"Repository": "https://github.com/hspark1212/chemeleon-dng"
},
"split_keywords": [
"crystal structure",
" materials science",
" generative ai",
" diffusion models",
" crystal structure prediction",
" de novo generation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "34b0314b88df28813c9c3819b972890a1b6d98fecedf768f62fe9146f205ab36",
"md5": "92e96de562ec72cdaf0238c48844a8ab",
"sha256": "3673daf4e50d38e277925460dd8c809185bd15f4ad7b5ac4374fd6064fbe40be"
},
"downloads": -1,
"filename": "chemeleon_dng-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "92e96de562ec72cdaf0238c48844a8ab",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 30220,
"upload_time": "2025-10-28T08:30:27",
"upload_time_iso_8601": "2025-10-28T08:30:27.565136Z",
"url": "https://files.pythonhosted.org/packages/34/b0/314b88df28813c9c3819b972890a1b6d98fecedf768f62fe9146f205ab36/chemeleon_dng-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b32f7c9138985f860f6cc5ccef8030ac7382b6057361a66d3f5a0e0acd6552e4",
"md5": "0f26cf981c3984495fc36bf6469f36a8",
"sha256": "275c6ada5fd20ab3990797a33596c8f6e44303806a6e4651ed793bc5ab772e7e"
},
"downloads": -1,
"filename": "chemeleon_dng-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "0f26cf981c3984495fc36bf6469f36a8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 27539,
"upload_time": "2025-10-28T08:30:28",
"upload_time_iso_8601": "2025-10-28T08:30:28.870708Z",
"url": "https://files.pythonhosted.org/packages/b3/2f/7c9138985f860f6cc5ccef8030ac7382b6057361a66d3f5a0e0acd6552e4/chemeleon_dng-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-28 08:30:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hspark1212",
"github_project": "chemeleon-dng#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "chemeleon-dng"
}
JSON
