bsym 2.2.0

bsym v2.2.0

Bug fixes, correctness improvements, and performance optimisations.

---

Bug Fixes

• Mutable default argument in SymmetryGroup.__init__: all instances shared the same list, risking cross-contamination between groups.
• Stale caches after extend()/append(): unique_index_mappings and stacked_index_mappings are now invalidated when operations are added.
• Infinite loop risk in random_unique_configurations: added a max_attempts parameter (default 1000) with RuntimeError when the configuration space appears exhausted.
• Uniform sampling failure counter: rejection by the acceptance test no longer counts as a failure to find a novel configuration, preventing spurious RuntimeError for highly degenerate configurations.
• Wrong class_str in SpaceGroup: was 'SymmetryGroup' instead of 'SpaceGroup'.
• bsym.bsym called sys.exit() on import; replaced with raise ImportError(...).
• SymmetryGroup.__mul__ lost subclass type: SpaceGroup * SpaceGroup returned a plain SymmetryGroup; now preserves the left operand's type.

Performance Optimisations

• Matrix transpose for permutation inversion instead of np.linalg.inv.
• np.argmax for index_mapping and as_vector instead of Python loops.
• Set-based deduplication of symmetry operation vectors in the pymatgen interface.
• Vectorised apply_species_mapping using numpy fancy indexing.
• End-to-end: 3.9x speedup on ternary composition enumeration, 2.4x on random sampling.

Code Hygiene

• Fixed type annotations for cache fields and labels property in SymmetryGroup.
• Updated SymmetryOperation.__init__ docstring to document deprecated np.matrix acceptance.
• Removed outdated docstrings referencing numpy.matrix subclassing.
• Removed unused imports and duplicate permutation_as_config_number function.
• Simplified SymmetryOperation.__init__ type checking.
• Replaced deprecated tqdm_notebook with tqdm.auto.

CI

• Build workflow now triggers only on pull requests (main is a protected branch).

---

Breaking Changes

• permutation_as_config_number (module-level function in configuration_space) has been removed.
• Importing bsym.bsym now raises ImportError instead of calling sys.exit().

bsym 2.1.1

bsym v2.1.1

bsym 2.1.1 adds support for generating random unique structures in batches, allowing workflows where structures are generated across multiple runs without duplicates.

Highlights

Batch Generation Workflow

Generate structures in batches while ensuring no duplicates across runs:

from bsym.interface.pymatgen import random_unique_structure_substitutions

# Batch 1
structures_1 = random_unique_structure_substitutions(
    parent_structure, 'Li', {'Na': 4, 'Li': 12},
    n=10,
    seed=42,
    output_file='batch_1.json',
)

# Batch 2 - excludes all structures from batch 1
structures_2 = random_unique_structure_substitutions(
    parent_structure, 'Li', {'Na': 4, 'Li': 12},
    n=10,
    seed=43,
    exclude_file='batch_1.json',
    output_file='batch_2.json',
)

# Batch 3 - excludes structures from both previous batches
structures_3 = random_unique_structure_substitutions(
    parent_structure, 'Li', {'Na': 4, 'Li': 12},
    n=10,
    seed=44,
    exclude_file=['batch_1.json', 'batch_2.json'],
    output_file='batch_3.json',
)

Configuration files are portable JSON, so batches can be generated on different machines as long as the number of sites to substitute is the same.

---

New Features

Batch Generation Support

• exclude parameter for ConfigurationSpace.random_unique_configurations() to exclude previously generated configurations
• exclude_file and output_file parameters for random_unique_structure_substitutions() to support batch workflows
• exclude_file accepts a single path or list of paths

Configuration Serialisation

• Configuration.to_dict() and Configuration.from_dict() methods
• save_configurations() and load_configurations() utility functions for JSON file I/O

---

Documentation

• Updated random_sampling.ipynb with batch generation workflow example

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

2.0.0

bsym v2.0.0

bsym 2.0.0 is a major release that brings significant performance improvements, new composition enumeration capabilities, and a modernised codebase.

Highlights

Performance Improvements

Substantial speedups through vectorised NumPy operations and optimised data structures. Configuration enumeration is significantly faster across the board. For example, a 2×2×2 supercell of TiOF₂ (735,471 permutations) shows a 4.7× speedup.

Varying Composition Enumeration

New functionality to systematically explore multiple compositions in a single call:

from bsym.interface.pymatgen import unique_structure_substitutions_by_composition

results = unique_structure_substitutions_by_composition(
    structure, 
    'X',                    # Sites to substitute
    ['Li', 'Na'],          # Species to substitute
    bounds={'Li': (1, 3)}  # Optional composition constraints
)

# results[(2, 2)] gives all unique structures with 2 Li and 2 Na
# results[(3, 1)] gives all unique structures with 3 Li and 1 Na

This includes species exchange symmetry optimisation that reduces expensive symmetry analyses.

Documentation Overhaul

Complete restructuring with separate sections for theory, practical usage, and API reference.

---

Breaking Changes

Python Version Requirement

Minimum Python version is now 3.10. Python 3.9 and earlier are no longer supported.

Removed ColourOperation Class

The ColourOperation class has been removed from the main codebase. This functionality has been preserved in the feature/colour-operations branch for potential future development. If you need this functionality, please contact the maintainers or check out the feature branch.

---

New Features

Composition Enumeration

• unique_configurations_by_composition method enables systematic exploration of composition ranges
• Species exchange symmetry optimisation analyses only canonical compositions and generates equivalent compositions through relabeling
• Progress tracking with nested progress bars and verbose output options
• Occupancy constraints via bounds parameter to filter composition ranges

Supporting Utilities

• generate_partitions - Integer partitioning for composition generation
• compute_mapping_vectors - Species permutation mapping
• satisfies_bounds - Occupancy constraint validation

pymatgen Interface

• unique_structure_substitutions_by_composition - High-level interface for varying composition enumeration with crystal structures

---

Improvements

Performance Optimisations

• Implemented batched symmetry operations using cached stacked_index_mappings and unique_index_mappings properties
• Replaced individual loops with vectorised NumPy operations
• Optimised Configuration storage using np.int8 arrays for optimal speed/memory balance
• Consistent byte-level representations throughout the codebase

Type Safety

• Comprehensive type hints throughout the codebase
• Added mypy static type checking to CI pipeline
• Better IDE support and code completion

Development Infrastructure

• Migrated CI to GitHub Actions with Python 3.10-3.14 support
• CI now uses pytest as test runner (unittest test suite maintained)
• Pip caching and parallelised coverage reporting
• Modernised pyproject.toml-based configuration

---

Documentation

Complete Restructure

• Getting Started: Introduction, installation, and quickstart guide
• Theory and Core Concepts: Mathematical foundations and algorithms
  • Configuration spaces and symmetry operations
  • Unique configuration enumeration
  • Composition enumeration algorithms
• User Guide: Practical examples as executable Jupyter notebooks
  • Basic substitutions
  • Fixed composition substitutions
  • Varying composition enumeration
  • Multi-level disorder enumeration
• API Reference: Auto-generated class and method documentation

Format Updates

• Converted narrative documentation from reStructuredText to Markdown for better readability
• Added comprehensive theory documents explaining mathematical foundations
• Practical tutorials with real pymatgen Structure examples
• Expanded README with improved installation, testing, and usage instructions

---

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 .

Development Installation

git clone https://github.com/bjmorgan/bsym.git
cd bsym
pip install -e ".[dev]"

---

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

---

Note: If you're upgrading from v1.x, please review the breaking changes section above, particularly the Python version requirement and removal of ColourOperation.

1.2.0

Update to fix compatibility with pymatgen >= v2022.0

1.1.0

Fixed 2nd bug in setup.py

JOSS accepted version

Archival version "as accepted" to JOSS: openjournals/joss-reviews#370

Changes for issues raised in review:

• A bug, where submodules were not installing correctly using pip, has been fixed.
• The full configuration degeneracy is now preserved over a series of site substitutions.
• Examples using the pymatgen interface to auto-generate SymmetryGroup and ConfigurationSpace objects have been added to the example Jupyter notebook.

1.0 beta 6

(hopefully) fixed PyPI installation via pip.

1.0.b2

2nd beta release.

• x3 speed-up for enumerating symmetry-inequivalent structures.
• cleaned up docs and examples (typos etc.).
• Indexed on PyPI.
  Installation can now use pip install bsym.

First public beta of v 1.0

1.0.b1

Version bump to 1.0.b1