cryptex-descriptors 0.1.2
Cryptex: A novel, extensible crystal descriptor engine for materials machine learning
License: MIT
Requires Python: >=3.8

📦 Cryptex
A Novel, Extensible Crystal Descriptor Engine for Materials Machine Learning
Cryptex is a modern, research‑grade Python library for generating structural, chemical, graph‑based, symmetry‑aware, and information‑theoretic descriptors from CIF crystal structures.
It includes many descriptors that do not exist in any prior package, making it ideal for:

materials machine learning

structure–property prediction

crystal classification

symmetry analysis

dataset generation

feature engineering for research

Cryptex is inspired by tools like RDKit, Mordred, DScribe, and Matminer, but focuses exclusively on crystal structures and introduces novel descriptors unavailable anywhere else.

🚀 Features
✔ 30+ descriptors, including:
Geometry descriptors

Symmetry descriptors

Graph‑based descriptors

Chemical descriptors

Voronoi‑based descriptors

SOAP‑like simplified descriptors

Information‑theoretic descriptors

Novel descriptors not found in any existing library

✔ Novel descriptors unique to Cryptex
Examples include:

Packing Efficiency

Lattice Anisotropy

Bond Angle Variance

Electronegativity Spread

Topological Density

Motif Entropy

Voronoi Anisotropy

Voronoi Volume Entropy

Radial Power Spectrum (SOAP‑like)

Coordination Shell Roughness

Element Embedding Distance

These descriptors are original, interpretable, and ML‑ready.

✔ Batch CIF → CSV dataset generator
Generate full ML datasets from folders of CIF files:

Code
cryptex my_cifs/ --csv > dataset.csv
✔ Simple CLI
Code
cryptex file.cif --csv
cryptex file.cif --json
✔ Extensible architecture
Add your own descriptors with a simple Python class.

📥 Installation
Once published to PyPI:

Code
pip install cryptex
Or install from source:

Code
uv pip install -e .
🧪 Usage
Single CIF → JSON
bash
cryptex example.cif --json
Single CIF → CSV
bash
cryptex example.cif --csv
Folder of CIFs → dataset CSV
bash
cryptex data/ --csv > dataset.csv
🧠 Example (Python API)
python
from cif import Crystal, calc_all

cr = Crystal.from_cif("example.cif")
features = calc_all(cr)

for name, value in features.items():
    print(name, value)
🧩 Architecture
Cryptex uses a clean, extensible descriptor system:

Code
src/cif/
    ├── descriptors/
    │     ├── packing.py
    │     ├── anisotropy.py
    │     ├── motif_entropy.py
    │     ├── voronoi_anisotropy.py
    │     ├── ...
    ├── registry.py
    ├── crystal.py
    └── cli.py
To add a new descriptor, simply create a file:

python
from .base import Descriptor

class MyDescriptor(Descriptor):
    name = "my_descriptor"
    category = "custom"
    ml_type = "continuous"

    def __call__(self, crystal):
        return 42
Cryptex automatically discovers it.

📊 Descriptor Categories
Category	Examples
Geometry	packing_efficiency, lattice_anisotropy, rdf_entropy
Graph	bond_angle_variance, topological_density, shell_roughness
Chemistry	electronegativity_spread, element_fraction_entropy, mass_variance
Symmetry	wyckoff_diversity
Voronoi	voronoi_anisotropy, voronoi_volume_entropy
SOAP‑like	radial_power_spectrum
Information‑theoretic	motif_entropy
📚 Dependencies
Cryptex builds on powerful scientific libraries:

pymatgen

spglib

numpy

networkx

🛠 Development
Clone the repository:

Code
git clone https://github.com/hassanabrar2026-dot/cryptex
cd cryptex
uv pip install -e .
Run tests (optional):

Code
pytest
🤝 Contributing
Contributions are welcome!
You can add descriptors, improve documentation, or submit issues.

📄 License
MIT License — free for academic and commercial use.

🌟 Citation
If you use Cryptex in research, please cite the GitHub repository:

Code
@software{cryptex2025,
  author = {Abrar, Hassan},
  title = {Cryptex: A Novel Crystal Descriptor Engine},
  url = {https://github.com/hassanabrar2026-dot/cryptex},
  year = {2025}
}