bsym 2.1.0

bsym 2.1.0

bsym 2.1.0 adds the ability to generate random samples of symmetry-inequivalent configurations, useful when full enumeration is computationally prohibitive.

Highlights

Random Configuration Sampling

Generate N random symmetry-inequivalent configurations without enumerating the complete set:

from bsym.interface.pymatgen import random_unique_structure_substitutions

# Generate 20 random unique structures from a large configuration space
random_structures = random_unique_structure_substitutions(
    parent_structure,
    'Li',
    {'Na': 8, 'Li': 8},
    n=20,
    seed=42  # For reproducibility
)

This is particularly useful when:

• Full enumeration would take too long or use too much memory
• You only need a representative subset (e.g., for machine learning training data)
• You want to explore a large configuration space without exhaustive enumeration

Two Sampling Modes

• degeneracy_weighted (default): High-degeneracy configurations are more likely to be sampled, reflecting their statistical weight
• uniform: Each equivalence class has equal probability, useful for building diverse training sets

---

New Features

Core API

• ConfigurationSpace.random_unique_configurations() - generate N random unique configurations with optional seed for reproducibility

pymatgen Interface

• random_unique_structure_substitutions() - high-level interface for random structure generation from pymatgen structures

---

Documentation

• New user guide: random_sampling.ipynb covering basic usage, sampling modes, reproducibility, and practical examples

---

Installation

From PyPI

pip install bsym

Requires Python 3.10 or later.

From Source

git clone https://github.com/bjmorgan/bsym.git
cd bsym
pip install .

---

Links

• Documentation: https://bsym.readthedocs.io
• PyPI: https://pypi.org/project/bsym/
• Source Code: https://github.com/bjmorgan/bsym
• Issue Tracker: https://github.com/bjmorgan/bsym/issues

---

Full Changelog

See CHANGELOG.md for complete details.

---

Citation

If you use bsym in your research, please cite:

Morgan, Benjamin J. (2017). bsym: A basic symmetry module. Journal of Open Source Software, 2(12), 387. https://doi.org/10.21105/joss.00370