bsym.configuration_space

class bsym.configuration_space.ConfigurationSpace(objects: list, symmetry_group: SymmetryGroup | None = None)[source]

Bases: object

enumerate_configurations(generator, verbose=False)[source]

Find all symmetry inequivalent configurations within the set produced by generator.

Parameters:

generator (generator) – Generator object, that yields the configurations to search through.
(opt (verbose) – default=False): Print verbose output.

Returns:

A list of Configuration objects, for each symmetry: inequivalent configuration.

Return type:

unique_configurations (list)

random_unique_configurations(site_distribution: dict[int, int], n: int, sampling: str = 'degeneracy_weighted', seed: int | None = None, exclude: list[Configuration] | None = None, max_attempts: int = 1000) → list[Configuration][source]

Generate n random symmetry-inequivalent configurations.

Parameters:

site_distribution – Dictionary mapping species labels to counts.
n – Number of unique configurations to generate.
sampling – Sampling method. Either ‘degeneracy_weighted’ (default) or ‘uniform’. ‘degeneracy_weighted’ samples configurations with probability proportional to their degeneracy. ‘uniform’ samples uniformly over equivalence classes.
seed – Random seed for reproducibility.
exclude – List of configurations to exclude. Any configuration equivalent to one in this list will not be returned.
max_attempts – Maximum number of consecutive failed attempts before raising RuntimeError. Default is 1000.

Returns:

List of n unique Configuration objects with count attributes set.

Raises:

ValueError – If sampling is not ‘degeneracy_weighted’ or ‘uniform’.
RuntimeError – If the configuration space appears exhausted.

unique_colourings(colours, verbose=False)[source]

Find the symmetry inequivalent colourings for a given number of ‘colours’.

Parameters:

colours (list) – A list of each object that may be arranged zero or more times in this system.
(opt (verbose) – default=False): Print verbose output.

Returns:

A list of Configuration objects, for each symmetry: inequivalent colouring.

Return type:

unique_colours (list)

unique_configurations(site_distribution, verbose=False, show_progress=False)[source]

Find the symmetry inequivalent configurations for a given population of objects.

Parameters:

site_distribution (dict) –
A dictionary that defines the number of each object to be arranged in this system.

e.g. for a system with four sites, with two occupied (denoted 1) and two unoccupied (denoted 0):
```
{ 1: 2, 0: 2 }
```
(opt (show_progress) – default=False): Print verbose output.
(opt – default=False): Show a progress bar. Setting to True gives a simple progress bar. Setting to “notebook” gives a Jupyter notebook compatible progress bar.

Returns:

A list of Configuration objects, for each symmetry: inequivalent configuration.

Return type:

unique_configurations (list)

unique_configurations_by_composition(n_species: int, bounds: dict[int, tuple[int | None, int | None]] | None = None, verbose: bool = False, show_progress: bool | str = False) → dict[tuple[int, ...], list[Configuration]][source]

Find symmetry-inequivalent configurations for all possible compositions.

Enumerates integer partitions of the number of sites into n_species parts. For each partition, the canonical permutation undergoes full symmetry analysis; non-canonical permutations are obtained by relabelling species.

Parameters:

n_species – Number of distinct species.
bounds – Optional occupancy bounds per species index. Keys are species indices, values are (min, max) tuples. None in either position means unbounded.
verbose – Print verbose output.
show_progress – Show a progress bar. True for a terminal bar, "notebook" for Jupyter.

Returns:

A dictionary mapping composition tuples to lists of Configuration objects. Keys are tuples like (2, 1, 1) where each element gives the count of the corresponding species.

bsym.configuration_space.apply_species_mapping(config, mapping_vector)[source]

Apply species permutation to a Configuration.

Creates a new Configuration where each species index is remapped according to the mapping vector. This is used to generate configurations for non-canonical compositions by relabeling species from canonical composition results.

Parameters:

config (Configuration) – Configuration object with species indices.
mapping_vector (list[int]) – 0-indexed list where mapping_vector[i] gives the new species index for current species i. e.g., [1, 0] swaps species 0 and 1.

Returns:

New Configuration with relabeled species. The count: (degeneracy) is preserved from the original configuration.

Return type:

Configuration

Example

>>> config = Configuration([0, 0, 1])
>>> config.count = 2
>>> mapping = [1, 0]  # Swap species 0 and 1
>>> result = apply_species_mapping(config, mapping)
>>> list(result)
[1, 1, 0]
>>> result.count
2

bsym.configuration_space.colourings_generator(colours, dim)[source]