shry package

shry package#

Submodules#

shry.cif_io module#

CIF I/O using PyCifRW instead of pymatgen.io.cif Supports magnetic CIF files for future development.

shry.cif_io.parse_cif_string_to_structure(cif_text, primitive=False, sort=False, merge_tol=0.001, keep_oxidation_states=False)#

Parse a CIF string using PyCifRW and convert to pymatgen Structure.

Parameters:

  • cif_text (str) – CIF contents as a string

  • primitive (bool) – Whether to convert to primitive cell

  • sort (bool) – Whether to sort sites

  • merge_tol (float) – Tolerance for merging sites

  • keep_oxidation_states (bool) – Whether to keep oxidation states when present

Returns:

pymatgen.Structure object

Return type:

Structure

shry.cif_io.parse_cif_to_structure(cif_path, primitive=False, sort=False, merge_tol=0.001, keep_oxidation_states=False)#

Parse a CIF file using PyCifRW and convert to pymatgen Structure.

Parameters:

  • cif_path (str) – Path to CIF file

  • primitive (bool) – Whether to convert to primitive cell

  • sort (bool) – Whether to sort sites

  • merge_tol (float) – Tolerance for merging sites

  • keep_oxidation_states (bool) – Whether to keep oxidation states when present

Returns:

pymatgen.Structure object

Return type:

Structure

shry.const module#

Shared constants

shry.core module#

Core operations, pattern generation, etc.

exception shry.core.NeedSupercellError#

Bases: Exception

Just so that this error will raise a distinguishable exception

class shry.core.Substitutor(structure, symprec=0.01, angle_tolerance=5.0, atol=1e-05, groupby=None, shuffle=False, seed=1770947752, no_dmat=False, t_kind='sum', cache=None, n_jobs=1)#

Bases: object

Enumerate symmetrically unique ordered structures from a disordered structure.

Since the PatternMaker instances are saved, it is advantageous to reuse the same Substitutor for symmetrically similar structures.

This includes different subsitute concentrations from the same basic structure, among others.

Variables:

disorder_groups (dict) – Mapping of grouping key (orbit identifier) to tuples of disordered PeriodicSite objects that are substituted together.

Parameters:

  • structure (pymatgen.core.Structure or shry.LabeledStructure) – Input structure. Both plain pymatgen Structure and SHRY LabeledStructure instances are supported.

  • symprec (float) – Symmetry precision.

  • angle_tolerance (float) – Angle tolerance for symmetry search.

  • atol (float) – Absolute tolerance used in internal floating-point comparisons.

  • groupby (function) –

    Function to group disordered sites. Defaults to lambda x: x.properties[“_atom_site_label”], with the x loops over all PeriodicSites within the Structure.

    The proper function depends on what you want; do you want all sites of a certain species or crystallographic orbit to be subsituted together?

    Fallback to crystallographic orbit when failed.

  • shuffle (bool) – If True, randomize branch traversal order during pattern search.

  • seed (int) – Random seed used when shuffle=True.

  • no_dmat (bool) – Whether or not to use distance matrix as permutation invariant (faster, default=True)

  • t_kind (str) – Invariant mode used by PatternMaker (e.g. sum, plsum, det).

  • cache (bool or None) – By default(=None), cache patterns when involving either multiple orbits or multiple species, but otherwise don’t. Caching allows “reuse” of previously generated patterns, at the cost of memory. Set to False if memory is limited, but note that pattern generation will be much slower.

  • n_jobs (int) – Number of worker processes for pattern search. 1 (default) disables process-based parallel search and is the safest option for script usage on spawn-based platforms. -1 uses all available CPU cores.

ase_atoms_writers(symprec=None)#

Generate ASE Atoms objects for all unique patterns.

Parameters:

symprec (float | None) – Unused. Kept for API compatibility.

Yields:

ase.Atoms – ASE representation of each ordered configuration.

cifwriters(symprec=None)#

Generate CIF writers (or magCIF string writers in MSG mode).

Parameters:

symprec (float | None) – Optional symmetry precision used when building symmetry-reduced CIF blocks.

Yields:

CifWriter | _StringWriter – Writer object for each configuration.

count()#

Return the number of symmetry-inequivalent substitution patterns.

Returns:

Number of unique patterns after symmetry reduction.

Return type:

int

disorder_groups#
ewalds(symprec=None)#

Generate Ewald energies for all unique patterns.

Parameters:

symprec (float | None) – Optional symmetry precision forwarded to CIF generation.

Yields:

float – Ewald total energy for each configuration.

property groupby#

Grouping function used to partition disorder sites into substitution orbits.

Returns:

Function that maps each PeriodicSite to a grouping key.

Return type:

Callable

letters()#

Generate letter-encoded substitution patterns.

Yields:

str – Compact letter string representing one substitution pattern.

make_patterns()#

Generate raw substitution patterns for all disordered sites.

Returns:

Pairs of (aut, pattern) where aut is the automorphism index array and pattern is the orbit-wise substitution index pattern.

Return type:

Iterator[tuple[np.ndarray, list[np.ndarray]]]

static ordinalize(array, atol=1e-05)#

Ordinalize array elements to the specified absolute tolerance.

Parameters:

  • array (np.array) – The array to be ordinalized.

  • atol (float) – Absolute tolerance. Defaults to 1e-5.

Returns:

The ordinalized array.

Return type:

np.array

property pattern_makers#

Access cached PatternMaker instances.

Returns:

Mapping from PatternMaker label to PatternMaker instance.

Return type:

dict

quantities(q, symprec=None)#

Generate selected quantities for each symmetry-inequivalent configuration.

Parameters:

  • q (list[str]) – Keys to include in each yielded packet. Valid keys are "cifwriter", "weight", "letter", "ewald", and "structure".

  • symprec (float | None) – Optional symmetry precision used for CIF/Ewald generation in helper methods.

Yields:

dict – Dictionary containing requested quantities for one configuration.

property structure#

Input structure currently held by this Substitutor.

Returns:

Internal working copy of the input structure.

Return type:

pymatgen.core.Structure

structure_writers(symprec=None)#

Generate ordered pymatgen structures for all unique patterns.

Parameters:

symprec (float | None) – Unused. Kept for API compatibility with other writer generators.

Yields:

pymatgen.core.Structure – Ordered structure for each configuration.

total_count()#

Return the total number of combinatorial substitutions (without symmetry reduction).

Returns:

Total number of possible substitutions.

Return type:

int

weights()#

Generate symmetry weights for all unique patterns.

Yields:

int – Weight of one pattern (group-size divided by automorphism size).

exception shry.core.TooBigError#

Bases: Exception

When the number of substitution is too large

shry.main module#

Main task abstraction

class shry.main.LabeledStructure(lattice, species, coords, charge=None, validate_proximity=False, to_unit_cell=False, coords_are_cartesian=False, site_properties=None, labels=None, properties=None)#

Bases: Structure

Structure subclass that preserves CIF label and magnetic-moment metadata.

In addition to standard pymatgen.Structure behavior, this class stores per-site CIF-derived properties such as _atom_site_label and magnetic moment mappings. These properties are kept consistent across common structure operations (copy, supercell expansion, species replacement), so downstream SHRY substitution logic can track site identity robustly.

Parameters:

  • lattice (ArrayLike | Lattice)

  • species (Sequence[CompositionLike])

  • coords (Sequence[ArrayLike] | ArrayLike)

  • charge (float | None)

  • validate_proximity (bool)

  • to_unit_cell (bool)

  • coords_are_cartesian (bool)

  • site_properties (dict | None)

  • labels (Sequence[str | None] | None)

  • properties (dict | None)

copy(*args, **kwargs)#

Return a deep copy preserving the LabeledStructure type.

pymatgen’s Structure.copy() returns a Structure instance; SHRY relies on LabeledStructure methods (e.g. replace_species) to keep CIF labels and magnetic moments consistent after modifications.

Returns:

Copied instance with duplicated site and structure

properties.

Return type:

LabeledStructure

classmethod from_file(filename, primitive=False, sort=False, merge_tol=0.0, symmetrize=False)#

Create a LabeledStructure from CIF/magCIF and attach labels.

Parameters:

  • filename (str) – Path to .cif or .mcif file.

  • primitive (bool) – Whether to return a primitive structure.

  • sort (bool) – Whether to sort sites during parsing.

  • merge_tol (float) – Site merge tolerance used by parser.

  • symmetrize (bool) – If True, match labels using spglib symmetry operations instead of CIF symmetry operators.

Returns:

Parsed structure populated with

_atom_site_label and related properties.

Return type:

LabeledStructure

Raises:

ValueError – If file extension is not CIF/magCIF.

read_label(cif_filename, symprec=0.01, angle_tolerance=5.0, symmetrize=False)#

Read CIF/magCIF labels and map them onto current structure sites.

Adds _atom_site_label and associated magnetic/occupancy properties to each site. For magCIF input, magnetic moments are transformed according to magnetic symmetry operations when required.

Parameters:

  • cif_filename (str) – Source CIF file.

  • symprec (float) – Symmetry precision used when symmetrize=True.

  • angle_tolerance (float) – Angle tolerance for symmetry operations.

  • symmetrize (bool) – If True, use spglib-derived symmetry operations for label matching.

Raises:

RuntimeError – If any structure site cannot be matched to CIF-defined positions/labels.

replace_species(species_mapping)#

Replace species/labels while preserving CIF and magnetic metadata.

Parameters:

species_mapping (dict[str, str]) – Mapping from source label/element to target species expression. Keys are first matched against _atom_site_label entries; if not found, element-symbol matches are attempted.

Raises:

RuntimeError – If no sites match at least one source key in specification.

shry.patches module#

Runtime patches for pymatgen classes.

shry.script module#

Command line interface.

Module contents#

Contents