crystal_torture.pymatgen_doping

Simple functions for manipulating and doping a pymatgen structure.

crystal_torture.pymatgen_doping.count_sites(structure: Structure, species: set[str] | None = None, labels: set[str] | None = None) → int

Count sites in structure by species and/or labels.

Given structure object and either specie string or label string, it counts and returns the number of sites with that species or label (or both) in the structure.

Parameters:

• structure – Pymatgen structure object.

• species – Site species to count.

• labels – Site labels to count.

Returns:

Number of sites occupied by species or label (or both) in structure.

Raises:

ValueError – If neither species nor labels are provided.

crystal_torture.pymatgen_doping.dope_structure(structure: Structure, conc: float, species_to_rem: str, species_to_insert: list[str], label_to_remove: str | None = None) → Structure

Dope a pymatgen structure object to a particular concentration.

Removes conc * no(species_to_remove) from structure and inserts species to insert in their place. Does so at random (excepting when label_to_remove is passed).

Parameters:

• structure – Pymatgen structure object.

• conc – Fractional percentage of sites to remove.

• species_to_rem – The species to remove from structure.

• species_to_insert – A list of species to equally distribute over sites that are removed.

• label_to_remove – Label of sites to select for removal.

Returns:

The doped structure.

Raises:

ValueError – If species_to_rem is not in structure.

crystal_torture.pymatgen_doping.dope_structure_by_no(structure: Structure, no_dopants: int, species_to_rem: str, species_to_insert: list[str], label_to_remove: str | None = None) → Structure

Dope a pymatgen structure object by swapping a specific number of sites.

Removes no_dopants of species_to_remove from structure and inserts species to insert in their place. Does so at random (excepting when label_to_remove is passed).

Parameters:

• structure – Pymatgen structure object.

• no_dopants – Number of each type of dopant to insert.

• species_to_rem – The species to remove from structure.

• species_to_insert – A list of species to equally distribute over sites that are removed.

• label_to_remove – Label of sites to select for removal.

Returns:

The doped structure.

Raises:

ValueError – If species_to_rem is not in structure.

crystal_torture.pymatgen_doping.index_sites(structure: Structure, species: set[str] | None = None, labels: set[str] | None = None) → list[int]

Return site indices occupied by specie or label (or both).

Parameters:

• structure – Pymatgen structure object.

• species – Site species to find.

• labels – Site labels to find.

Returns:

List with site indices occupied by species or label (or both) in structure.

Raises:

ValueError – If neither species nor labels are provided.

crystal_torture.pymatgen_doping.set_site_labels(structure: Structure, labels: list[str]) → None

Set site labels using the built-in label property.

Parameters:

• structure – Pymatgen structure object.

• labels – List of labels to assign to sites.

Raises:

ValueError – If number of labels doesn’t match number of sites.

crystal_torture.pymatgen_doping.sort_structure(structure: Structure, order: list[str]) → Structure

Sort structure species so their indices sit side by side in given order.

Given a pymatgen structure object sort the species so that their indices sit side by side in the structure, in given order - allows for POSCAR file to be written in a readable way after doping.

Parameters:

• structure – Pymatgen structure object.

• order – List of species str in order to sort.

Returns:

Ordered pymatgen Structure object.

Raises:

ValueError – If order elements don’t match structure elements.