# Crystalyse v1.0
**Intelligent Scientific AI Agent for Inorganic Materials Design**
[](https://badge.fury.io/py/crystalyse)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
> **Version 1.0.0**
> Research tool combining composition validation (SMACT), structure prediction (Chemeleon), energy calculations (MACE), and materials analysis (PyMatGen)
## What's New in v1.0
Version 1.0 includes significant architectural changes focused on computational traceability and simplified setup:
### Key Features
**Provenance System**
- Every numerical value traces to actual calculations
- Render gate prevents unprovenanced values from being displayed
- Full audit trail of all operations
- No fabricated or hallucinated numbers
**Automated Setup**
- Chemeleon checkpoints auto-download on first use (~600 MB)
- Materials Project phase diagrams auto-download (~170 MB, 271,617 entries)
- Files cached in `~/.cache/crystalyse/`
- Environment variables are optional
**PyMatGen Integration**
- Energy above hull calculations using 271,617 Materials Project entries
- Phase diagram construction
- Decomposition product analysis
- Stability assessment (stable/metastable/unstable)
**Adaptive Clarification System**
- Learns user expertise level over time
- Adjusts question complexity accordingly
- Fewer interruptions for experienced users
- More guidance for new users
**Analysis Modes**
- **Creative Mode**: Fast exploration (~50s) with Chemeleon + MACE
- **Rigorous Mode**: Full validation (2-5min) with SMACT + Chemeleon + MACE + analysis
- **Adaptive Mode**: Automatic mode selection based on query complexity
**Simplified Architecture**
- Modular tool implementations
- Python packaging for MCP servers
- Cleaner separation of concerns
## Quick Start
### Installation
```bash
# Install from PyPI (includes all dependencies and MCP servers)
pip install crystalyse
# Optional: visualization tools
pip install crystalyse[visualization]
# Set your OpenAI API key
export OPENAI_MDG_API_KEY="sk-your-key-here"
# Verify installation
crystalyse --help
```
### First Run
On first run, CrystaLyse will automatically download:
- Chemeleon model checkpoints (~600 MB, one-time)
- Materials Project phase diagrams (~170 MB, one-time)
These are cached in `~/.cache/crystalyse/` and never downloaded again.
### Basic Usage
```bash
# Creative mode (fast exploration)
crystalyse analyse "Find stable perovskite materials for solar cells" --mode creative
# Rigorous mode (complete validation)
crystalyse analyse "Analyze LiCoO2 for battery applications" --mode rigorous
# Interactive session with memory
crystalyse chat -u researcher -s battery_project
# Resume previous session
crystalyse resume battery_project -u researcher
```
## Scientific Capabilities
### Materials Discovery Pipeline
1. **Composition Validation** (SMACT)
- Chemical plausibility screening
- Charge balancing
- Electronegative balance
- Quick filtering of impossible compositions
2. **Structure Prediction** (Chemeleon)
- AI-powered crystal structure generation
- Multiple polymorph candidates
- Confidence scores for each structure
- Text-guided generation
3. **Energy Calculations** (MACE)
- Formation energy evaluation
- Structure relaxation
- Uncertainty quantification
- GPU-accelerated calculations
4. **Stability Analysis** (PyMatGen)
- Energy above hull calculations
- Phase diagram construction
- Decomposition products
- Competing phases analysis
5. **Visualization** (Optional)
- 3D crystal structures
- XRD patterns
- Radial distribution functions
- Coordination environment analysis
### Research Applications
**Energy Materials**
- Battery cathodes and anodes (Li-ion, Na-ion, solid-state)
- Solid electrolytes and fast ion conductors
- Photovoltaic semiconductors and perovskites
- Thermoelectric materials
**Electronic Materials**
- Ferroelectric and multiferroic materials
- Magnetic materials and spintronics
- Semiconductor devices
- Quantum materials
**Structural Materials**
- High-temperature ceramics
- Hard coatings and superhard materials
- Transparent conductors
## Performance
| Operation | Creative Mode | Rigorous Mode |
|-----------|---------------|---------------|
| Simple query (single material) | ~50 seconds | 2-3 minutes |
| Complex analysis (multiple candidates) | 1-2 minutes | 3-5 minutes |
| Batch screening (10+ materials) | 5-10 minutes | 15-30 minutes |
## Advanced Usage
### Interactive Sessions
```bash
# Start research session
crystalyse chat -u researcher -s solar_cells -m creative
# In-session commands
/mode rigorous # Switch to rigorous mode
/mode creative # Switch to creative mode
/help # Show commands
/exit # Exit session
```
### Custom Data Paths
```bash
# Use custom checkpoint directory
export CHEMELEON_CHECKPOINT_DIR=/path/to/checkpoints
crystalyse analyse "BaTiO3"
# Use custom phase diagram data
export CRYSTALYSE_PPD_PATH=/path/to/ppd.pkl.gz
crystalyse analyse "LiCoO2"
```
### Programmatic API
```python
from crystalyse.agents import EnhancedCrystaLyseAgent
from crystalyse.config import CrystaLyseConfig
# Initialize agent
config = CrystaLyseConfig()
agent = EnhancedCrystaLyseAgent(config=config, mode="rigorous")
# Run analysis
result = agent.query(
"Analyze CsSnI3 perovskite for photovoltaic applications",
user_id="researcher"
)
print(result.response)
```
## Computational Honesty
Crystalyse implements a provenance system to track the origin of all computed values:
- **Traceability**: Every numerical value traces to actual tool calculations
- **Render Gate**: Blocks unprovenanced values from being displayed
- **Audit Trail**: Full JSONL logs of all operations
- **Uncertainty**: Predictions include confidence scores when available
If Crystalyse reports a formation energy, it was calculated by MACE. If it reports an energy above hull, it came from PyMatGen with Materials Project data. The LLM interprets results but doesn't fabricate numbers.
## Migration from crystalyse-ai
If you're upgrading from the old `crystalyse-ai` package:
### Breaking Changes
1. **Package name**: `pip install crystalyse` (not `crystalyse-ai`)
2. **Import name**: `from crystalyse import ...` (not `from crystalyse_ai import ...`)
3. **MCP servers**: Now bundled automatically (no separate installation)
4. **Auto-download**: Checkpoints and data files download automatically
5. **Environment variables**: Custom checkpoint/data paths are now optional
### Migration Steps
```bash
# Uninstall old version
pip uninstall crystalyse-ai
# Install new version
pip install crystalyse
# Update imports in your code
# OLD: from crystalyse_ai.agents import ...
# NEW: from crystalyse.agents import ...
# Remove manual checkpoint/data management
# Everything auto-downloads now
```
### What Stays the Same
- CLI interface (mostly compatible)
- Core workflow concepts
- Analysis modes (creative/rigorous/adaptive)
- Session management
## System Requirements
- **Python**: 3.11 or higher
- **Memory**: 8GB minimum, 16GB recommended
- **Disk**: 2GB for checkpoints and cache
- **GPU**: Optional, accelerates MACE calculations
- **Network**: Required for first-time setup (auto-downloads)
## Documentation
- [Installation Guide](https://github.com/ryannduma/CrystaLyse.AI/blob/master/docs/installation.md)
- [User Guide](https://github.com/ryannduma/CrystaLyse.AI/blob/master/docs/user-guide.md)
- [API Documentation](https://github.com/ryannduma/CrystaLyse.AI/blob/master/docs/api.md)
- [Provenance System](https://github.com/ryannduma/CrystaLyse.AI/blob/master/docs/provenance.md)
- [CLAUDE.md](https://github.com/ryannduma/CrystaLyse.AI/blob/master/CLAUDE.md) - Developer guide
## Acknowledgments
Crystalyse builds on open-source tools from the materials science community:
- **SMACT** - Semiconducting Materials by Analogy and Chemical Theory
- **Chemeleon** - AI-powered crystal structure prediction
- **MACE** - Machine learning ACE force fields
- **PyMatGen** - Python Materials Genomics
- **Pymatviz** - Materials visualization toolkit
- **OpenAI Agents SDK** - Agent orchestration framework
## Citation
If you use CrystaLyse in your research, please cite the underlying tools:
```bibtex
@article{davies2019smact,
title={SMACT: Semiconducting Materials by Analogy and Chemical Theory},
author={Davies, Daniel W and Butler, Keith T and Jackson, Adam J and others},
journal={Journal of Open Source Software},
volume={4},
number={38},
pages={1361},
year={2019}
}
@article{park2025chemeleon,
title={Exploration of crystal chemical space using text-guided generative artificial intelligence},
author={Park, Hyun Seo and others},
journal={Nature Communications},
year={2025}
}
@article{batatia2022mace,
title={MACE: Higher Order Equivariant Message Passing Neural Networks for Fast and Accurate Force Fields},
author={Batatia, Ilyes and others},
journal={NeurIPS},
year={2022}
}
```
## License
MIT License - see [LICENSE](LICENSE) for details.
## Support
- **Issues**: [GitHub Issues](https://github.com/ryannduma/CrystaLyse.AI/issues)
- **Discussions**: [GitHub Discussions](https://github.com/ryannduma/CrystaLyse.AI/discussions)
- **Email**: ryannduma@gmail.com
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for version history.
---
**Made with computational honesty by [Ryan Nduma](https://github.com/ryannduma)**
Raw data
{
"_id": null,
"home_page": null,
"name": "crystalyse",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Ryan Nduma <ryannduma@gmail.com>",
"keywords": "materials-design, crystal-structure-prediction, formation-energy, computational-materials-science, ai-agents, chemistry, inorganic-materials, autonomous-agents, openai-agents, mcp-servers, provenance, computational-honesty",
"author": null,
"author_email": "Ryan Nduma <ryannduma@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b4/a0/960cd0987959c748be112ed4cd0572b839a3a37b8cdaa59254a262463b2d/crystalyse-1.0.1.tar.gz",
"platform": null,
"description": "# Crystalyse v1.0\n\n**Intelligent Scientific AI Agent for Inorganic Materials Design**\n\n[](https://badge.fury.io/py/crystalyse)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\n> **Version 1.0.0**\n> Research tool combining composition validation (SMACT), structure prediction (Chemeleon), energy calculations (MACE), and materials analysis (PyMatGen)\n\n## What's New in v1.0\n\nVersion 1.0 includes significant architectural changes focused on computational traceability and simplified setup:\n\n### Key Features\n\n**Provenance System**\n- Every numerical value traces to actual calculations\n- Render gate prevents unprovenanced values from being displayed\n- Full audit trail of all operations\n- No fabricated or hallucinated numbers\n\n**Automated Setup**\n- Chemeleon checkpoints auto-download on first use (~600 MB)\n- Materials Project phase diagrams auto-download (~170 MB, 271,617 entries)\n- Files cached in `~/.cache/crystalyse/`\n- Environment variables are optional\n\n**PyMatGen Integration**\n- Energy above hull calculations using 271,617 Materials Project entries\n- Phase diagram construction\n- Decomposition product analysis\n- Stability assessment (stable/metastable/unstable)\n\n**Adaptive Clarification System**\n- Learns user expertise level over time\n- Adjusts question complexity accordingly\n- Fewer interruptions for experienced users\n- More guidance for new users\n\n**Analysis Modes**\n- **Creative Mode**: Fast exploration (~50s) with Chemeleon + MACE\n- **Rigorous Mode**: Full validation (2-5min) with SMACT + Chemeleon + MACE + analysis\n- **Adaptive Mode**: Automatic mode selection based on query complexity\n\n**Simplified Architecture**\n- Modular tool implementations\n- Python packaging for MCP servers\n- Cleaner separation of concerns\n\n## Quick Start\n\n### Installation\n\n```bash\n# Install from PyPI (includes all dependencies and MCP servers)\npip install crystalyse\n\n# Optional: visualization tools\npip install crystalyse[visualization]\n\n# Set your OpenAI API key\nexport OPENAI_MDG_API_KEY=\"sk-your-key-here\"\n\n# Verify installation\ncrystalyse --help\n```\n\n### First Run\n\nOn first run, CrystaLyse will automatically download:\n- Chemeleon model checkpoints (~600 MB, one-time)\n- Materials Project phase diagrams (~170 MB, one-time)\n\nThese are cached in `~/.cache/crystalyse/` and never downloaded again.\n\n### Basic Usage\n\n```bash\n# Creative mode (fast exploration)\ncrystalyse analyse \"Find stable perovskite materials for solar cells\" --mode creative\n\n# Rigorous mode (complete validation)\ncrystalyse analyse \"Analyze LiCoO2 for battery applications\" --mode rigorous\n\n# Interactive session with memory\ncrystalyse chat -u researcher -s battery_project\n\n# Resume previous session\ncrystalyse resume battery_project -u researcher\n```\n\n## Scientific Capabilities\n\n### Materials Discovery Pipeline\n\n1. **Composition Validation** (SMACT)\n - Chemical plausibility screening\n - Charge balancing\n - Electronegative balance\n - Quick filtering of impossible compositions\n\n2. **Structure Prediction** (Chemeleon)\n - AI-powered crystal structure generation\n - Multiple polymorph candidates\n - Confidence scores for each structure\n - Text-guided generation\n\n3. **Energy Calculations** (MACE)\n - Formation energy evaluation\n - Structure relaxation\n - Uncertainty quantification\n - GPU-accelerated calculations\n\n4. **Stability Analysis** (PyMatGen)\n - Energy above hull calculations\n - Phase diagram construction\n - Decomposition products\n - Competing phases analysis\n\n5. **Visualization** (Optional)\n - 3D crystal structures\n - XRD patterns\n - Radial distribution functions\n - Coordination environment analysis\n\n### Research Applications\n\n**Energy Materials**\n- Battery cathodes and anodes (Li-ion, Na-ion, solid-state)\n- Solid electrolytes and fast ion conductors\n- Photovoltaic semiconductors and perovskites\n- Thermoelectric materials\n\n**Electronic Materials**\n- Ferroelectric and multiferroic materials\n- Magnetic materials and spintronics\n- Semiconductor devices\n- Quantum materials\n\n**Structural Materials**\n- High-temperature ceramics\n- Hard coatings and superhard materials\n- Transparent conductors\n\n## Performance\n\n| Operation | Creative Mode | Rigorous Mode |\n|-----------|---------------|---------------|\n| Simple query (single material) | ~50 seconds | 2-3 minutes |\n| Complex analysis (multiple candidates) | 1-2 minutes | 3-5 minutes |\n| Batch screening (10+ materials) | 5-10 minutes | 15-30 minutes |\n\n## Advanced Usage\n\n### Interactive Sessions\n\n```bash\n# Start research session\ncrystalyse chat -u researcher -s solar_cells -m creative\n\n# In-session commands\n/mode rigorous # Switch to rigorous mode\n/mode creative # Switch to creative mode\n/help # Show commands\n/exit # Exit session\n```\n\n### Custom Data Paths\n\n```bash\n# Use custom checkpoint directory\nexport CHEMELEON_CHECKPOINT_DIR=/path/to/checkpoints\ncrystalyse analyse \"BaTiO3\"\n\n# Use custom phase diagram data\nexport CRYSTALYSE_PPD_PATH=/path/to/ppd.pkl.gz\ncrystalyse analyse \"LiCoO2\"\n```\n\n### Programmatic API\n\n```python\nfrom crystalyse.agents import EnhancedCrystaLyseAgent\nfrom crystalyse.config import CrystaLyseConfig\n\n# Initialize agent\nconfig = CrystaLyseConfig()\nagent = EnhancedCrystaLyseAgent(config=config, mode=\"rigorous\")\n\n# Run analysis\nresult = agent.query(\n \"Analyze CsSnI3 perovskite for photovoltaic applications\",\n user_id=\"researcher\"\n)\n\nprint(result.response)\n```\n\n## Computational Honesty\n\nCrystalyse implements a provenance system to track the origin of all computed values:\n\n- **Traceability**: Every numerical value traces to actual tool calculations\n- **Render Gate**: Blocks unprovenanced values from being displayed\n- **Audit Trail**: Full JSONL logs of all operations\n- **Uncertainty**: Predictions include confidence scores when available\n\nIf Crystalyse reports a formation energy, it was calculated by MACE. If it reports an energy above hull, it came from PyMatGen with Materials Project data. The LLM interprets results but doesn't fabricate numbers.\n\n## Migration from crystalyse-ai\n\nIf you're upgrading from the old `crystalyse-ai` package:\n\n### Breaking Changes\n\n1. **Package name**: `pip install crystalyse` (not `crystalyse-ai`)\n2. **Import name**: `from crystalyse import ...` (not `from crystalyse_ai import ...`)\n3. **MCP servers**: Now bundled automatically (no separate installation)\n4. **Auto-download**: Checkpoints and data files download automatically\n5. **Environment variables**: Custom checkpoint/data paths are now optional\n\n### Migration Steps\n\n```bash\n# Uninstall old version\npip uninstall crystalyse-ai\n\n# Install new version\npip install crystalyse\n\n# Update imports in your code\n# OLD: from crystalyse_ai.agents import ...\n# NEW: from crystalyse.agents import ...\n\n# Remove manual checkpoint/data management\n# Everything auto-downloads now\n```\n\n### What Stays the Same\n\n- CLI interface (mostly compatible)\n- Core workflow concepts\n- Analysis modes (creative/rigorous/adaptive)\n- Session management\n\n## System Requirements\n\n- **Python**: 3.11 or higher\n- **Memory**: 8GB minimum, 16GB recommended\n- **Disk**: 2GB for checkpoints and cache\n- **GPU**: Optional, accelerates MACE calculations\n- **Network**: Required for first-time setup (auto-downloads)\n\n## Documentation\n\n- [Installation Guide](https://github.com/ryannduma/CrystaLyse.AI/blob/master/docs/installation.md)\n- [User Guide](https://github.com/ryannduma/CrystaLyse.AI/blob/master/docs/user-guide.md)\n- [API Documentation](https://github.com/ryannduma/CrystaLyse.AI/blob/master/docs/api.md)\n- [Provenance System](https://github.com/ryannduma/CrystaLyse.AI/blob/master/docs/provenance.md)\n- [CLAUDE.md](https://github.com/ryannduma/CrystaLyse.AI/blob/master/CLAUDE.md) - Developer guide\n\n## Acknowledgments\n\nCrystalyse builds on open-source tools from the materials science community:\n\n- **SMACT** - Semiconducting Materials by Analogy and Chemical Theory\n- **Chemeleon** - AI-powered crystal structure prediction\n- **MACE** - Machine learning ACE force fields\n- **PyMatGen** - Python Materials Genomics\n- **Pymatviz** - Materials visualization toolkit\n- **OpenAI Agents SDK** - Agent orchestration framework\n\n## Citation\n\nIf you use CrystaLyse in your research, please cite the underlying tools:\n\n```bibtex\n@article{davies2019smact,\n title={SMACT: Semiconducting Materials by Analogy and Chemical Theory},\n author={Davies, Daniel W and Butler, Keith T and Jackson, Adam J and others},\n journal={Journal of Open Source Software},\n volume={4},\n number={38},\n pages={1361},\n year={2019}\n}\n\n@article{park2025chemeleon,\n title={Exploration of crystal chemical space using text-guided generative artificial intelligence},\n author={Park, Hyun Seo and others},\n journal={Nature Communications},\n year={2025}\n}\n\n@article{batatia2022mace,\n title={MACE: Higher Order Equivariant Message Passing Neural Networks for Fast and Accurate Force Fields},\n author={Batatia, Ilyes and others},\n journal={NeurIPS},\n year={2022}\n}\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/ryannduma/CrystaLyse.AI/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/ryannduma/CrystaLyse.AI/discussions)\n- **Email**: ryannduma@gmail.com\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history.\n\n---\n\n**Made with computational honesty by [Ryan Nduma](https://github.com/ryannduma)**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Crystalyse v1.0 - Intelligent Scientific AI Agent for Inorganic Materials Design",
"version": "1.0.1",
"project_urls": {
"Changelog": "https://github.com/ryannduma/CrystaLyse.AI/blob/master/CHANGELOG.md",
"Documentation": "https://github.com/ryannduma/CrystaLyse.AI/tree/master/docs",
"Homepage": "https://github.com/ryannduma/CrystaLyse.AI",
"Issues": "https://github.com/ryannduma/CrystaLyse.AI/issues",
"Repository": "https://github.com/ryannduma/CrystaLyse.AI.git"
},
"split_keywords": [
"materials-design",
" crystal-structure-prediction",
" formation-energy",
" computational-materials-science",
" ai-agents",
" chemistry",
" inorganic-materials",
" autonomous-agents",
" openai-agents",
" mcp-servers",
" provenance",
" computational-honesty"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6db4089b05310af1d38e3a1c3221dd2ac2acaf2cd491b0269a3832bbc0cabb3d",
"md5": "711751258a76e3080b82a22d760daccf",
"sha256": "17a740158c7e602df402c485c4926ed31e01f3bb487270b7b03f989227a8b4d5"
},
"downloads": -1,
"filename": "crystalyse-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "711751258a76e3080b82a22d760daccf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 242954,
"upload_time": "2025-11-01T21:36:18",
"upload_time_iso_8601": "2025-11-01T21:36:18.507466Z",
"url": "https://files.pythonhosted.org/packages/6d/b4/089b05310af1d38e3a1c3221dd2ac2acaf2cd491b0269a3832bbc0cabb3d/crystalyse-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b4a0960cd0987959c748be112ed4cd0572b839a3a37b8cdaa59254a262463b2d",
"md5": "fd4b8a77945cd5bbcdfdaed58913de4a",
"sha256": "29cbc70928136d987ce734a81e1c0f2a5c8e8b1f9b2c72cfb4805b51142d8023"
},
"downloads": -1,
"filename": "crystalyse-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "fd4b8a77945cd5bbcdfdaed58913de4a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 211295,
"upload_time": "2025-11-01T21:36:20",
"upload_time_iso_8601": "2025-11-01T21:36:20.701404Z",
"url": "https://files.pythonhosted.org/packages/b4/a0/960cd0987959c748be112ed4cd0572b839a3a37b8cdaa59254a262463b2d/crystalyse-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-01 21:36:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ryannduma",
"github_project": "CrystaLyse.AI",
"github_not_found": true,
"lcname": "crystalyse"
}
JSON
