cryptex-descriptors 0.1.0

Cryptex: A novel, extensible crystal descriptor engine for materials machine learning

📦 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} }