ElementSorter

Sort chemical elements by custom labels (e.g. R/M/X roles in intermetallics), by Mendeleev number, or alphabetically. Custom labels come from a dict or from an Excel file with Binary, Ternary, and Quaternary sheets. New in cifkit 1.2.1 (migrated from bobleesj.utils). See the OLED tutorial for elemental-data context.

Reference

class cifkit.sorters.element_sorter.ElementSorter(label_mapping: dict = None, excel_path: str = None)

Bases: object

Sort chemical elements by custom labels, Mendeleev numbers, or alphabetically.

Parameters:

• label_mapping (dict, optional) – The custom label mapping for sorting elements.

• excel_path (str, optional) – The path to Excel file with custom labels. It overrides label_mapping if provided.

Examples

>>> element_sorter = ElementSorter(excel_path="labels.xlsx")
>>> element_sorter.sort(["Fe", "Si"], method="custom")
('Fe', 'Si')
>>> custom_labels = {
...     2: {"A": ["Fe", "Co"], "B": ["Si", "Ga"]},
...     3: {"R": ["Sc", "Y"], "M": ["Fe", "Co"],
            "X": ["Si", "Ga"]},
...     4: {"A": ["Sc", "Y"], "B": ["Fe", "Co"],
            "C": ["Si", "Ga"], "D": ["Gd", "Tb", "Dy"]},
... }
>>> element_sorter = ElementSorter(label_mapping=custom_labels)
>>> element_sorter.sort(["Sc", "Fe", "Si"], method="custom")
('Sc', 'Fe', 'Si')
>>> element_sorter.sort(["O", "Fe"], method="mendeleev")
('O', 'Fe')

sort(elements: list[str], method=None, descending: bool = True) → tuple

Sort a list of elements.

Parameters:

• elements (list of str) – Element symbols to sort (e.g., [‘Fe’, ‘O’]).

• method (str or None, optional) – ‘custom’: custom label-based sorting. ‘mendeleev’: by Mendeleev numbers. None/other: alphabetical (default).

• descending (bool, default=True) – Sort descending.

Returns:

Sorted element symbols.

Return type:

tuple

Raises:

ValueError – If method is unsupported or custom sorting fails.

Examples

>>> elements.sort(["O", "Fe"], descending=False)
('Fe', 'O')
>>> elements.sort(['O', 'Fe'], method="mendeleev")
('O', 'Fe')
>>> elements.sort(["Fe", "O"], method="custom")
('Fe', 'O')