Using SHRY as a Python module
See ${SHRY_INSTALLDIR}/examples
for examples.
Basic function
(See example1.py
for this section).
Substitutor
is the main interface for using
functions implemented in SHRY.
It uses Pymatgen’s Structure
as the
structure representation.
from pymatgen.core import Structure
from shry import Substitutor
...
structure = Structure.from_file(file_name)
substitutor = Substitutor(structure)
We recommend enumerating the unique structures
using Substitutor.count()
before generating them.
It is an implementation of Polya enumeration,
which is almost instant for most cases.
The structures (either as CIF or Structure
), weights,
configuration letters, etc. can then be obtained from
Substitutor.quantities(string_tuple)
.
The string_tuple
may contain any of these keywords:
cifwriter
. Pymatgen’sCifWriter
instances.structure
. Pymatgen’sStructure
instances. Use this for writing CIF files.weight
. How many configurationsletter
. Configuration letter (‘aaa’, ‘bab’, etc.) corresponding to the substitution.ewald
. Ewald energy for the given structure.
Substitutor.quantities(string_tuple)
is a generator
of a dictionary with the previous keywords as keys.
For example, if you want to get the CIFs and weights, do
for i, packet in enumerate(substitutor.quantities(("cifwriter", "weight"))):
cifwriter = packet["cifwriter"]
weight = packet["weight"]
filename=f"cif_i{i}w{weight}.cif"
cifwriter.write_file(filename=os.path.join(output_dir, filename))
There are also individual generators for each of the quantities:
cifwriters()
structure_writers()
weights()
letters()
ewalds()
however these will invoke one full run for every call, so if more than one quantities is required, it will be slower.
Enumlib equivalent
See example2.py
for comparison with equivalent
enumlib
functions through Pymatgen’s EnumlibAdaptor
.
Advanced use
LabeledStructure
LabeledStructure
is a modified Pymatgen’s Structure
,
but it tracks the CIF’s _atom_site_label
.
This is useful if you want to group sites
together regardless of supercell use,
which can sometimes split the sites.
It also implements replace_species
for substituting sites
with a slightly more convenient syntax (see example3.py
).
Saving substitutor instance
Substitutor
can automatically “remap” pattern
generated in other structure if the structures are
symmetrically similar.
This can save a lot of time if you are dealing with
multiple concentrations or a set of symmetrically similar sytems.
See example4a.py
for how to enable caching and pickle
the Substitutor
instance, and example4b.py
for the later reloading.