v0.5.4

Major Changes

• First public release after crystALL started over half a decade ago in the Spring of 2021! Please see the README and earlier release notes.
• The manuscript will be posted on arXiv soon!
• Standardized the PyPI package name to crystall-search due to a name conflict while keeping crystall in general.
• You can now constrain MPDD searches using any database metadata field via other_targets. This lets users search specifically for 2D/layered materials, pin desired crystal systems (e.g., only monoclinic or cubic prototypes), or apply arbitrary query operators. It includes query normalization so you don't send redundant composition queries, typo suggestions if you misspell a field, and provenance tracking: every filtered run automatically saves a query.yaml file and gets a short -hash suffix so different search configurations don't overwrite each other; by @lukeamyers in #12
• A tutorial for the above (tutorial/03.RefiningMPDDSearch.ipynb) has been added.
• A bugfix for filter_prototypes() re-indexed self.prototypes (setting prototype['index'] = 1, 2, ..., N) before slicing the descriptor matrix self.ks2022 causing feature vectors to get shuffled in some cases.
• Before this release, crystALL had a hard dependency on dgl and mpdd-alignn which are not needed by all users and at the same time broke native installations and CI on macOS and Windows due to upstream PyTorch/DGL wheel gaps. Now, these are optionals that install by default only on linux.

Minor Changes:

• Minor bugfix for generate_local assigning structure index from 0 unlike other generators starting from 1.
• Added the ability to have non-structure files next to input structures by filtering on _STRUCTURE_EXTENSIONS.
• Cleaned up how CrystALLSearch captured stdout by wrapping it in contextlib.redirect_stdout.
• chgnet was bumped to 0.4.2 for native support for NumPy 2.0 and no Cython 64-bit integer type mismatches on Windows.
• Updates all around to support newest pysipfenn, torch, numpy, and spglib; with relaxed version bounds on them.
• Compressed static figures in README and documentation.
• Restricted setuptools discovery via MANIFEST shrinking the wheel by preventing docs/ and tutorial/ from leaking into site-packages.
• Refactored package metadata fetching to use importlib.metadata.metadata() instead of manual parsing.
• Adjusted plot_2D and plot_3D to display Objective instead of Formation Energy in all cases.
• Added the delete_filteredout_structures: bool = True option to filter_prototypes().

New Contributors

• @lukeamyers made their first contribution in #12

Full Changelog: v0.5.0...v0.5.4

v0.5.0

Major Changes

• Unified High-Level API (CrystALLSearch): Polished the framework into more intuitive API managing the full pipeline, from prototype querying and atomic substitutions to featurization and candidate ranking
• Modular "Community" ML Calculator Adapters: Introduced plug-and-play property predictors with native support for ALIGNN via our MPDD-ALIGNN fork (multi-objective models incl. formation energy & bandgap models) and CHGNet (static evaluation and full structure relaxation)
• Systematized the Feature-Space Analysis: Integrated t-SNE embeddings with automated KMeans (silhouette-optimized) and DBSCAN clustering to separate distinct structural families and extract diverse top candidates. In earlier versions this has been done in Wolfram and R, while v0.5.0 moved everything into Python.
• Built-in 2D & 3D Visualizations: Added interactive plotting tools (plot_2D, plot_3D) for candidate cluster analysis and energy landscape sorting. The data output to custom tools is still as smooth as ever though!
• Tutorials & Pre-Built Cloud Environment: Released comprehensive hands-on Jupyter tutorials (BaSO4 walk-through and hydride discovery with embedded 3D structure models) alongside one-click GitHub Codespaces with everything pre-built.
• Packaging & CI/CD: Modernized setup with pyproject.toml, complete Sphinx documentation to be later pushed to Read The Docs, and automated multi-platform CI testing across Linux, macOS, and Windows.
• See V0.5.0 PR by @ricardonpa in #10 for discussion and design choices made

New Contributors

• @ricardonpa made their first contribution in #1

Full Changelog: v0.4.0...v0.5.0

v0.4.0 (separated from MPDD repository)

This release contains V0.4 of the crystALL script developed between 2021 and 2023 in a larger, private repository of the MPDD. Subsequent modifications will be git-tracked here.