pymatgen.core.structure module

class IMolecule(species, coords, charge=0, spin_multiplicity=None, validate_proximity=False, site_properties=None)[source]

Bases: pymatgen.core.structure.SiteCollection, monty.json.MSONable

Basic immutable Molecule object without periodicity. Essentially a sequence of sites. IMolecule is made to be immutable so that they can function as keys in a dict. For a mutable molecule, use the :class:Molecule.

Molecule extends Sequence and Hashable, which means that in many cases, it can be used like any Python sequence. Iterating through a molecule is equivalent to going through the sites in sequence.

Creates a Molecule.

Parameters:
  • species – list of atomic species. Possible kinds of input include a list of dict of elements/species and occupancies, a List of elements/specie specified as actual Element/Specie, Strings (“Fe”, “Fe2+”) or atomic numbers (1,56).
  • coords (3x1 array) – list of cartesian coordinates of each species.
  • charge (float) – Charge for the molecule. Defaults to 0.
  • spin_multiplicity (int) – Spin multiplicity for molecule. Defaults to None, which means that the spin multiplicity is set to 1 if the molecule has no unpaired electrons and to 2 if there are unpaired electrons.
  • validate_proximity (bool) – Whether to check if there are sites that are less than 1 Ang apart. Defaults to False.
  • site_properties (dict) – Properties associated with the sites as a dict of sequences, e.g., {“magmom”:[5,5,5,5]}. The sequences have to be the same length as the atomic species and fractional_coords. Defaults to None for no properties.
as_dict()[source]

Json-serializable dict representation of Molecule

break_bond(ind1, ind2, tol=0.2)[source]

Returns two molecules based on breaking the bond between atoms at index ind1 and ind2.

Parameters:
  • ind1 (int) – Index of first site.
  • ind2 (int) – Index of second site.
  • tol (float) – Relative tolerance to test. Basically, the code checks if the distance between the sites is less than (1 + tol) * typical bond distances. Defaults to 0.2, i.e., 20% longer.
Returns:

Two Molecule objects representing the two clusters formed from breaking the bond.

center_of_mass

Center of mass of molecule.

charge

Charge of molecule

classmethod from_dict(d)[source]

Reconstitute a Molecule object from a dict representation created using as_dict().

Parameters:d (dict) – dict representation of Molecule.
Returns:Molecule object
classmethod from_file(filename)[source]

Reads a molecule from a file. Supported formats include xyz, gaussian input (gjf|g03|g09|com|inp), Gaussian output (.out|and pymatgen’s JSON serialized molecules. Using openbabel, many more extensions are supported but requires openbabel to be installed.

Parameters:filename (str) – The filename to read from.
Returns:Molecule
classmethod from_sites(sites, charge=0, spin_multiplicity=None, validate_proximity=False)[source]

Convenience constructor to make a Molecule from a list of sites.

Parameters:
  • sites ([Site]) – Sequence of Sites.
  • charge (int) – Charge of molecule. Defaults to 0.
  • spin_multiplicity (int) – Spin multicipity. Defaults to None, in which it is determined automatically.
  • validate_proximity (bool) – Whether to check that atoms are too close.
classmethod from_str(input_string, fmt)[source]

Reads the molecule from a string.

Parameters:
  • input_string (str) – String to parse.
  • fmt (str) – Format to output to. Defaults to JSON unless filename is provided. If fmt is specifies, it overrides whatever the filename is. Options include “xyz”, “gjf”, “g03”, “json”. If you have OpenBabel installed, any of the formats supported by OpenBabel. Non-case sensitive.
Returns:

IMolecule or Molecule.

get_boxed_structure(a, b, c, images=(1, 1, 1), random_rotation=False, min_dist=1, cls=None, offset=None, no_cross=False)[source]

Creates a Structure from a Molecule by putting the Molecule in the center of a orthorhombic box. Useful for creating Structure for calculating molecules using periodic codes.

Parameters:
  • a (float) – a-lattice parameter.
  • b (float) – b-lattice parameter.
  • c (float) – c-lattice parameter.
  • images – No. of boxed images in each direction. Defaults to (1, 1, 1), meaning single molecule with 1 lattice parameter in each direction.
  • random_rotation (bool) – Whether to apply a random rotation to each molecule. This jumbles all the molecules so that they are not exact images of each other.
  • min_dist (float) – The minimum distance that atoms should be from each other. This is only used if random_rotation is True. The randomized rotations are searched such that no two atoms are less than min_dist from each other.
  • cls – The Structure class to instantiate (defaults to pymatgen structure)
  • offset – Translation to offset molecule from center of mass coords
  • no_cross – Whether to forbid molecule coords from extending beyond boundary of box.
Returns:

Structure containing molecule in a box.

get_centered_molecule()[source]

Returns a Molecule centered at the center of mass.

Returns:Molecule centered with center of mass at origin.
get_covalent_bonds(tol=0.2)[source]

Determines the covalent bonds in a molecule.

Parameters:tol (float) – The tol to determine bonds in a structure. See CovalentBond.is_bonded.
Returns:List of bonds
get_distance(i, j)[source]

Get distance between site i and j.

Parameters:
  • i (int) – Index of first site
  • j (int) – Index of second site
Returns:

Distance between the two sites.

get_neighbors(site, r)[source]

Get all neighbors to a site within a sphere of radius r. Excludes the site itself.

Parameters:
  • site (Site) – Site at the center of the sphere.
  • r (float) – Radius of sphere.
Returns:

[(site, dist) ...] since most of the time, subsequent processing requires the distance.

get_neighbors_in_shell(origin, r, dr)[source]

Returns all sites in a shell centered on origin (coords) between radii r-dr and r+dr.

Parameters:
  • origin (3x1 array) – Cartesian coordinates of center of sphere.
  • r (float) – Inner radius of shell.
  • dr (float) – Width of shell.
Returns:

[(site, dist) ...] since most of the time, subsequent processing requires the distance.

get_sites_in_sphere(pt, r)[source]

Find all sites within a sphere from a point.

Parameters:
  • pt (3x1 array) – Cartesian coordinates of center of sphere.
  • r (float) – Radius of sphere.
Returns:

[(site, dist) ...] since most of the time, subsequent processing requires the distance.

nelectrons

Number of electrons in the molecule.

sites

Returns a tuple of sites in the Molecule.

spin_multiplicity

Spin multiplicity of molecule.

to(fmt=None, filename=None)[source]

Outputs the molecule to a file or string.

Parameters:
  • fmt (str) – Format to output to. Defaults to JSON unless filename is provided. If fmt is specifies, it overrides whatever the filename is. Options include “xyz”, “gjf”, “g03”, “json”. If you have OpenBabel installed, any of the formats supported by OpenBabel. Non-case sensitive.
  • filename (str) – If provided, output will be written to a file. If fmt is not specified, the format is determined from the filename. Defaults is None, i.e. string output.
Returns:

(str) if filename is None. None otherwise.

class IStructure(lattice, species, coords, validate_proximity=False, to_unit_cell=False, coords_are_cartesian=False, site_properties=None)[source]

Bases: pymatgen.core.structure.SiteCollection, monty.json.MSONable

Basic immutable Structure object with periodicity. Essentially a sequence of PeriodicSites having a common lattice. IStructure is made to be (somewhat) immutable so that they can function as keys in a dict. To make modifications, use the standard Structure object instead. Structure extends Sequence and Hashable, which means that in many cases, it can be used like any Python sequence. Iterating through a structure is equivalent to going through the sites in sequence.

Create a periodic structure.

Parameters:
  • lattice (Lattice/3x3 array) – The lattice, either as a pymatgen.core.lattice.Lattice or simply as any 2D array. Each row should correspond to a lattice vector. E.g., [[10,0,0], [20,10,0], [0,0,30]] specifies a lattice with lattice vectors [10,0,0], [20,10,0] and [0,0,30].
  • species ([Specie]) –

    Sequence of species on each site. Can take in flexible input, including:

    1. A sequence of element / specie specified either as string symbols, e.g. [“Li”, “Fe2+”, “P”, ...] or atomic numbers, e.g., (3, 56, ...) or actual Element or Specie objects.
    2. List of dict of elements/species and occupancies, e.g., [{“Fe” : 0.5, “Mn”:0.5}, ...]. This allows the setup of disordered structures.
  • coords (Nx3 array) – list of fractional/cartesian coordinates of each species.
  • validate_proximity (bool) – Whether to check if there are sites that are less than 0.01 Ang apart. Defaults to False.
  • coords_are_cartesian (bool) – Set to True if you are providing coordinates in cartesian coordinates. Defaults to False.
  • site_properties (dict) – Properties associated with the sites as a dict of sequences, e.g., {“magmom”:[5,5,5,5]}. The sequences have to be the same length as the atomic species and fractional_coords. Defaults to None for no properties.
as_dict(verbosity=1, fmt=None, **kwargs)[source]

Dict representation of Structure.

Parameters:
  • verbosity (int) – Verbosity level. Default of 1 includes both direct and cartesian coordinates for all sites, lattice parameters, etc. Useful for reading and for insertion into a database. Set to 0 for an extremely lightweight version that only includes sufficient information to reconstruct the object.
  • fmt (str) – Specifies a format for the dict. Defaults to None, which is the default format used in pymatgen. Other options include “abivars”.
  • **kwargs – Allow passing of other kwargs needed for certain
  • e.g., "abivars". (formats,) –
Returns:

JSON serializable dict representation.

copy(site_properties=None, sanitize=False)[source]

Convenience method to get a copy of the structure, with options to add site properties.

Parameters:
  • site_properties (dict) – Properties to add or override. The properties are specified in the same way as the constructor, i.e., as a dict of the form {property: [values]}. The properties should be in the order of the original structure if you are performing sanitization.
  • sanitize (bool) – If True, this method will return a sanitized structure. Sanitization performs a few things: (i) The sites are sorted by electronegativity, (ii) a LLL lattice reduction is carried out to obtain a relatively orthogonalized cell, (iii) all fractional coords for sites are mapped into the unit cell.
Returns:

A copy of the Structure, with optionally new site_properties and optionally sanitized.

density

Returns the density in units of g/cc

distance_matrix

Returns the distance matrix between all sites in the structure. For periodic structures, this should return the nearest image distance.

frac_coords

Fractional coordinates as a Nx3 numpy array.

classmethod from_dict(d, fmt=None)[source]

Reconstitute a Structure object from a dict representation of Structure created using as_dict().

Parameters:d (dict) – Dict representation of structure.
Returns:Structure object
classmethod from_file(filename, primitive=False, sort=False, merge_tol=0.0)[source]

Reads a structure from a file. For example, anything ending in a “cif” is assumed to be a Crystallographic Information Format file. Supported formats include CIF, POSCAR/CONTCAR, CHGCAR, LOCPOT, vasprun.xml, CSSR, Netcdf and pymatgen’s JSON serialized structures.

Parameters:
  • filename (str) – The filename to read from.
  • primitive (bool) – Whether to convert to a primitive cell Only available for cifs. Defaults to False.
  • sort (bool) – Whether to sort sites. Default to False.
  • merge_tol (float) – If this is some positive number, sites that are within merge_tol from each other will be merged. Usually 0.01 should be enough to deal with common numerical issues.
Returns:

Structure.

classmethod from_sites(sites, validate_proximity=False, to_unit_cell=False)[source]

Convenience constructor to make a Structure from a list of sites.

Parameters:
  • sites – Sequence of PeriodicSites. Sites must have the same lattice.
  • validate_proximity (bool) – Whether to check if there are sites that are less than 0.01 Ang apart. Defaults to False.
  • to_unit_cell (bool) – Whether to translate sites into the unit cell.
Returns:

(Structure) Note that missing properties are set as None.

classmethod from_spacegroup(sg, lattice, species, coords, site_properties=None, coords_are_cartesian=False, tol=1e-05)[source]

Generate a structure using a spacegroup. Note that only symmetrically distinct species and coords should be provided. All equivalent sites are generated from the spacegroup operations.

Parameters:
  • sg (str/int) – The spacegroup. If a string, it will be interpreted as one of the notations supported by pymatgen.symmetry.groups.Spacegroup. E.g., “R-3c” or “Fm-3m”. If an int, it will be interpreted as an international number.
  • lattice (Lattice/3x3 array) – The lattice, either as a pymatgen.core.lattice.Lattice or simply as any 2D array. Each row should correspond to a lattice vector. E.g., [[10,0,0], [20,10,0], [0,0,30]] specifies a lattice with lattice vectors [10,0,0], [20,10,0] and [0,0,30]. Note that no attempt is made to check that the lattice is compatible with the spacegroup specified. This may be introduced in a future version.
  • species ([Specie]) –

    Sequence of species on each site. Can take in flexible input, including:

    1. A sequence of element / specie specified either as string symbols, e.g. [“Li”, “Fe2+”, “P”, ...] or atomic numbers, e.g., (3, 56, ...) or actual Element or Specie objects.
    2. List of dict of elements/species and occupancies, e.g., [{“Fe” : 0.5, “Mn”:0.5}, ...]. This allows the setup of disordered structures.
  • coords (Nx3 array) – list of fractional/cartesian coordinates of each species.
  • coords_are_cartesian (bool) – Set to True if you are providing coordinates in cartesian coordinates. Defaults to False.
  • site_properties (dict) – Properties associated with the sites as a dict of sequences, e.g., {“magmom”:[5,5,5,5]}. The sequences have to be the same length as the atomic species and fractional_coords. Defaults to None for no properties.
  • tol (float) – A fractional tolerance to deal with numerical precision issues in determining if orbits are the same.
classmethod from_str(input_string, fmt, primitive=False, sort=False, merge_tol=0.0)[source]

Reads a structure from a string.

Parameters:
  • input_string (str) – String to parse.
  • fmt (str) – A format specification.
  • primitive (bool) – Whether to find a primitive cell. Defaults to False.
  • sort (bool) – Whether to sort the sites in accordance to the default ordering criteria, i.e., electronegativity.
  • merge_tol (float) – If this is some positive number, sites that are within merge_tol from each other will be merged. Usually 0.01 should be enough to deal with common numerical issues.
Returns:

IStructure / Structure

get_all_neighbors(r, include_index=False)[source]

Get neighbors for each atom in the unit cell, out to a distance r Returns a list of list of neighbors for each site in structure. Use this method if you are planning on looping over all sites in the crystal. If you only want neighbors for a particular site, use the method get_neighbors as it may not have to build such a large supercell However if you are looping over all sites in the crystal, this method is more efficient since it only performs one pass over a large enough supercell to contain all possible atoms out to a distance r. The return type is a [(site, dist) ...] since most of the time, subsequent processing requires the distance.

Parameters:
  • r (float) – Radius of sphere.
  • include_index (bool) – Whether to include the non-supercell site in the returned data
Returns:

A list of a list of nearest neighbors for each site, i.e., [[(site, dist, index) ...], ..] Index only supplied if include_index = True. The index is the index of the site in the original (non-supercell) structure. This is needed for ewaldmatrix by keeping track of which sites contribute to the ewald sum.

get_distance(i, j, jimage=None)[source]

Get distance between site i and j assuming periodic boundary conditions. If the index jimage of two sites atom j is not specified it selects the jimage nearest to the i atom and returns the distance and jimage indices in terms of lattice vector translations if the index jimage of atom j is specified it returns the distance between the i atom and the specified jimage atom.

Parameters:
  • i (int) – Index of first site
  • j (int) – Index of second site
  • jimage – Number of lattice translations in each lattice direction. Default is None for nearest image.
Returns:

distance

get_neighbors(site, r, include_index=False)[source]

Get all neighbors to a site within a sphere of radius r. Excludes the site itself.

Parameters:
  • site – site, which is the center of the sphere.
  • r – radius of sphere.
  • include_index – boolean that determines whether the non-supercell site index is included in the returned data
Returns:

[(site, dist) ...] since most of the time, subsequent processing requires the distance.

get_neighbors_in_shell(origin, r, dr, include_index=False)[source]

Returns all sites in a shell centered on origin (coords) between radii r-dr and r+dr.

Parameters:
  • origin (3x1 array) – Cartesian coordinates of center of sphere.
  • r (float) – Inner radius of shell.
  • dr (float) – Width of shell.
  • include_index (bool) – Whether to include the non-supercell site in the returned data
Returns:

[(site, dist, index) ...] since most of the time, subsequent processing requires the distance. Index only supplied if include_index = True. The index is the index of the site in the original (non-supercell) structure. This is needed for ewaldmatrix by keeping track of which sites contribute to the ewald sum.

get_primitive_structure(tolerance=0.25)[source]

This finds a smaller unit cell than the input. Sometimes it doesn”t find the smallest possible one, so this method is recursively called until it is unable to find a smaller cell.

NOTE: if the tolerance is greater than 1/2 the minimum inter-site distance in the primitive cell, the algorithm will reject this lattice.

Parameters:tolerance (float) – Tolerance for each coordinate of a particular site. For example, [0.1, 0, 0.1] in cartesian coordinates will be considered to be on the same coordinates as [0, 0, 0] for a tolerance of 0.25. Defaults to 0.25.
Returns:The most primitive structure found.
get_reduced_structure(reduction_algo='niggli')[source]

Get a reduced structure.

Parameters:reduction_algo (str) – The lattice reduction algorithm to use. Currently supported options are “niggli” or “LLL”.
get_sites_in_sphere(pt, r, include_index=False)[source]

Find all sites within a sphere from the point. This includes sites in other periodic images.

Algorithm:

  1. place sphere of radius r in crystal and determine minimum supercell (parallelpiped) which would contain a sphere of radius r. for this we need the projection of a_1 on a unit vector perpendicular to a_2 & a_3 (i.e. the unit vector in the direction b_1) to determine how many a_1”s it will take to contain the sphere.

    Nxmax = r * length_of_b_1 / (2 Pi)

  2. keep points falling within r.

Parameters:
  • pt (3x1 array) – cartesian coordinates of center of sphere.
  • r (float) – Radius of sphere.
  • include_index (bool) – Whether the non-supercell site index is included in the returned data
Returns:

[(site, dist) ...] since most of the time, subsequent processing requires the distance.

get_sorted_structure(key=None, reverse=False)[source]

Get a sorted copy of the structure. The parameters have the same meaning as in list.sort. By default, sites are sorted by the electronegativity of the species.

Parameters:
  • key – Specifies a function of one argument that is used to extract a comparison key from each list element: key=str.lower. The default value is None (compare the elements directly).
  • reverse (bool) – If set to True, then the list elements are sorted as if each comparison were reversed.
get_space_group_info(symprec=0.01, angle_tolerance=5.0)[source]

Convenience method to quickly get the spacegroup of a structure.

Parameters:
  • symprec (float) – Same definition as in SpacegroupAnalyzer. Defaults to 1e-2.
  • angle_tolerance (float) – Same definition as in SpacegroupAnalyzer. Defaults to 5 degrees.
Returns:

spacegroup_symbol, international_number

interpolate(end_structure, nimages=10, interpolate_lattices=False, pbc=True, autosort_tol=0)[source]

Interpolate between this structure and end_structure. Useful for construction of NEB inputs.

Parameters:
  • end_structure (Structure) – structure to interpolate between this structure and end.
  • nimages (int) – No. of interpolation images. Defaults to 10 images.
  • interpolate_lattices (bool) – Whether to interpolate the lattices. Interpolates the lengths and angles (rather than the matrix) so orientation may be affected.
  • pbc (bool) – Whether to use periodic boundary conditions to find the shortest path between endpoints.
  • autosort_tol (float) – A distance tolerance in angstrom in which to automatically sort end_structure to match to the closest points in this particular structure. This is usually what you want in a NEB calculation. 0 implies no sorting. Otherwise, a 0.5 value usually works pretty well.
Returns:

List of interpolated structures. The starting and ending structures included as the first and last structures respectively. A total of (nimages + 1) structures are returned.

lattice

Lattice of the structure.

matches(other, **kwargs)[source]

Check whether this structure is similar to another structure. Basically a convenience method to call structure matching fitting.

Parameters:
Returns:

(bool) True is the structures are similar under some affine transformation.

sites

Returns an iterator for the sites in the Structure.

to(fmt=None, filename=None, **kwargs)[source]

Outputs the structure to a file or string.

Parameters:
  • fmt (str) – Format to output to. Defaults to JSON unless filename is provided. If fmt is specifies, it overrides whatever the filename is. Options include “cif”, “poscar”, “cssr”, “json”. Non-case sensitive.
  • filename (str) – If provided, output will be written to a file. If fmt is not specified, the format is determined from the filename. Defaults is None, i.e. string output.
Returns:

(str) if filename is None. None otherwise.

volume

Returns the volume of the structure.

class Molecule(species, coords, charge=0, spin_multiplicity=None, validate_proximity=False, site_properties=None)[source]

Bases: pymatgen.core.structure.IMolecule, collections.abc.MutableSequence

Mutable Molecule. It has all the methods in IMolecule, but in addition, it allows a user to perform edits on the molecule.

Creates a MutableMolecule.

Parameters:
  • species – list of atomic species. Possible kinds of input include a list of dict of elements/species and occupancies, a List of elements/specie specified as actual Element/Specie, Strings (“Fe”, “Fe2+”) or atomic numbers (1,56).
  • coords (3x1 array) – list of cartesian coordinates of each species.
  • charge (float) – Charge for the molecule. Defaults to 0.
  • spin_multiplicity (int) – Spin multiplicity for molecule. Defaults to None, which means that the spin multiplicity is set to 1 if the molecule has no unpaired electrons and to 2 if there are unpaired electrons.
  • validate_proximity (bool) – Whether to check if there are sites that are less than 1 Ang apart. Defaults to False.
  • site_properties (dict) – Properties associated with the sites as a dict of sequences, e.g., {“magmom”:[5,5,5,5]}. The sequences have to be the same length as the atomic species and fractional_coords. Defaults to None for no properties.
add_site_property(property_name, values)[source]

Adds a property to a site.

Parameters:
  • property_name (str) – The name of the property to add.
  • values (list) – A sequence of values. Must be same length as number of sites.
append(species, coords, validate_proximity=True, properties=None)[source]

Appends a site to the molecule.

Parameters:
  • species – Species of inserted site
  • coords – Coordinates of inserted site
  • validate_proximity (bool) – Whether to check if inserted site is too close to an existing site. Defaults to True.
  • properties (dict) – A dict of properties for the Site.
Returns:

New molecule with inserted site.

apply_operation(symmop)[source]

Apply a symmetry operation to the molecule.

Parameters:symmop (SymmOp) – Symmetry operation to apply.
copy()[source]

Convenience method to get a copy of the molecule.

Returns:A copy of the Molecule.
insert(i, species, coords, validate_proximity=False, properties=None)[source]

Insert a site to the molecule.

Parameters:
  • i (int) – Index to insert site
  • species – species of inserted site
  • coords (3x1 array) – coordinates of inserted site
  • validate_proximity (bool) – Whether to check if inserted site is too close to an existing site. Defaults to True.
  • properties (dict) – Dict of properties for the Site.
Returns:

New molecule with inserted site.

perturb(distance)[source]

Performs a random perturbation of the sites in a structure to break symmetries.

Parameters:distance (float) – Distance in angstroms by which to perturb each site.
remove_sites(indices)[source]

Delete sites with at indices.

Parameters:indices – Sequence of indices of sites to delete.
remove_species(species)[source]

Remove all occurrences of a species from a molecule.

Parameters:species – Species to remove.
replace_species(species_mapping)[source]

Swap species in a molecule.

Parameters:species_mapping (dict) – dict of species to swap. Species can be elements too. E.g., {Element(“Li”): Element(“Na”)} performs a Li for Na substitution. The second species can be a sp_and_occu dict. For example, a site with 0.5 Si that is passed the mapping {Element(‘Si): {Element(‘Ge’):0.75, Element(‘C’):0.25} } will have .375 Ge and .125 C.
rotate_sites(indices=None, theta=0, axis=None, anchor=None)[source]

Rotate specific sites by some angle around vector at anchor.

Parameters:
  • indices (list) – List of site indices on which to perform the translation.
  • angle (float) – Angle in radians
  • axis (3x1 array) – Rotation axis vector.
  • anchor (3x1 array) – Point of rotation.
set_charge_and_spin(charge, spin_multiplicity=None)[source]

Set the charge and spin multiplicity.

Parameters:
  • charge (int) – Charge for the molecule. Defaults to 0.
  • spin_multiplicity (int) – Spin multiplicity for molecule. Defaults to None, which means that the spin multiplicity is set to 1 if the molecule has no unpaired electrons and to 2 if there are unpaired electrons.
substitute(index, func_grp, bond_order=1)[source]

Substitute atom at index with a functional group.

Parameters:
  • index (int) – Index of atom to substitute.
  • func_grp

    Substituent molecule. There are two options:

    1. Providing an actual molecule as the input. The first atom must be a DummySpecie X, indicating the position of nearest neighbor. The second atom must be the next nearest atom. For example, for a methyl group substitution, func_grp should be X-CH3, where X is the first site and C is the second site. What the code will do is to remove the index site, and connect the nearest neighbor to the C atom in CH3. The X-C bond indicates the directionality to connect the atoms.
    2. A string name. The molecule will be obtained from the relevant template in functional_groups.json.
  • bond_order – A specified bond order to calculate the bond length between the attached functional group and the nearest neighbor site. Defaults to 1.
translate_sites(indices=None, vector=None)[source]

Translate specific sites by some vector, keeping the sites within the unit cell.

Parameters:
  • indices (list) – List of site indices on which to perform the translation.
  • vector (3x1 array) – Translation vector for sites.
class SiteCollection[source]

Bases: collections.abc.Sequence

Basic SiteCollection. Essentially a sequence of Sites or PeriodicSites. This serves as a base class for Molecule (a collection of Site, i.e., no periodicity) and Structure (a collection of PeriodicSites, i.e., periodicity). Not meant to be instantiated directly.

DISTANCE_TOLERANCE = 0.5
atomic_numbers

List of atomic numbers.

cart_coords

Returns a np.array of the cartesian coordinates of sites in the structure.

charge

Returns the net charge of the structure based on oxidation states. If Elements are found, a charge of 0 is assumed.

composition

(Composition) Returns the composition

distance_matrix

Returns the distance matrix between all sites in the structure. For periodic structures, this is overwritten to return the nearest image distance.

formula

(str) Returns the formula.

classmethod from_file(filename)[source]

Reads in SiteCollection from a filename.

classmethod from_str(input_string, fmt)[source]

Reads in SiteCollection from a string.

get_angle(i, j, k)[source]

Returns angle specified by three sites.

Parameters:
  • i (int) – Index of first site.
  • j (int) – Index of second site.
  • k (int) – Index of third site.
Returns:

(float) Angle in degrees.

get_dihedral(i, j, k, l)[source]

Returns dihedral angle specified by four sites.

Parameters:
  • i (int) – Index of first site
  • j (int) – Index of second site
  • k (int) – Index of third site
  • l (int) – Index of fourth site
Returns:

(float) Dihedral angle in degrees.

get_distance(i, j)[source]

Returns distance between sites at index i and j.

Parameters:
  • i (int) – Index of first site
  • j (int) – Index of second site
Returns:

(float) Distance between sites at index i and index j.

group_by_types()[source]

Iterate over species grouped by type

indices_from_symbol(symbol)[source]

Returns a tuple with the sequential indices of the sites that contain an element with the given chemical symbol.

is_ordered

Checks if structure is ordered, meaning no partial occupancies in any of the sites.

is_valid(tol=0.5)[source]

True if SiteCollection does not contain atoms that are too close together. Note that the distance definition is based on type of SiteCollection. Cartesian distances are used for non-periodic Molecules, while PBC is taken into account for periodic structures.

Parameters:tol (float) – Distance tolerance. Default is 0.01A.
Returns:(bool) True if SiteCollection does not contain atoms that are too close together.
ntypesp

Number of types of atoms.

num_sites

Number of sites.

site_properties

Returns the site properties as a dict of sequences. E.g., {“magmom”: (5,-5), “charge”: (-4,4)}.

sites

Returns a tuple of sites.

species

Only works for ordered structures. Disordered structures will raise an AttributeError.

Returns:([Specie]) List of species at each site of the structure.
species_and_occu

List of species and occupancies at each site of the structure.

symbol_set

Tuple with the set of chemical symbols. Note that len(symbol_set) == len(types_of_specie)

to(fmt=None, filename=None)[source]

Generates well-known string representations of SiteCollections (e.g., molecules / structures). Should return a string type or write to a file.

types_of_specie

List of types of specie. Only works for ordered structures. Disordered structures will raise an AttributeError.

class Structure(lattice, species, coords, validate_proximity=False, to_unit_cell=False, coords_are_cartesian=False, site_properties=None)[source]

Bases: pymatgen.core.structure.IStructure, collections.abc.MutableSequence

Mutable version of structure.

Create a periodic structure.

Parameters:
  • lattice – The lattice, either as a pymatgen.core.lattice.Lattice or simply as any 2D array. Each row should correspond to a lattice vector. E.g., [[10,0,0], [20,10,0], [0,0,30]] specifies a lattice with lattice vectors [10,0,0], [20,10,0] and [0,0,30].
  • species

    List of species on each site. Can take in flexible input, including:

    1. A sequence of element / specie specified either as string symbols, e.g. [“Li”, “Fe2+”, “P”, ...] or atomic numbers, e.g., (3, 56, ...) or actual Element or Specie objects.
    2. List of dict of elements/species and occupancies, e.g., [{“Fe” : 0.5, “Mn”:0.5}, ...]. This allows the setup of disordered structures.
  • fractional_coords – list of fractional coordinates of each species.
  • validate_proximity (bool) – Whether to check if there are sites that are less than 0.01 Ang apart. Defaults to False.
  • coords_are_cartesian (bool) – Set to True if you are providing coordinates in cartesian coordinates. Defaults to False.
  • site_properties (dict) – Properties associated with the sites as a dict of sequences, e.g., {“magmom”:[5,5,5,5]}. The sequences have to be the same length as the atomic species and fractional_coords. Defaults to None for no properties.
add_oxidation_state_by_element(oxidation_states)[source]

Add oxidation states to a structure.

Parameters:oxidation_states (dict) – Dict of oxidation states. E.g., {“Li”:1, “Fe”:2, “P”:5, “O”:-2}
add_oxidation_state_by_site(oxidation_states)[source]

Add oxidation states to a structure by site.

Parameters:oxidation_states (list) – List of oxidation states. E.g., [1, 1, 1, 1, 2, 2, 2, 2, 5, 5, 5, 5, -2, -2, -2, -2]
add_site_property(property_name, values)[source]

Adds a property to all sites.

Parameters:
  • property_name (str) – The name of the property to add.
  • values – A sequence of values. Must be same length as number of sites.
append(species, coords, coords_are_cartesian=False, validate_proximity=False, properties=None)[source]

Append a site to the structure.

Parameters:
  • species – Species of inserted site
  • coords (3x1 array) – Coordinates of inserted site
  • coords_are_cartesian (bool) – Whether coordinates are cartesian. Defaults to False.
  • validate_proximity (bool) – Whether to check if inserted site is too close to an existing site. Defaults to False.
  • properties (dict) – Properties of the site.
Returns:

New structure with inserted site.

apply_operation(symmop, fractional=False)[source]

Apply a symmetry operation to the structure and return the new structure. The lattice is operated by the rotation matrix only. Coords are operated in full and then transformed to the new lattice.

Parameters:
  • symmop (SymmOp) – Symmetry operation to apply.
  • fractional (bool) – Whether the symmetry operation is applied in fractional space. Defaults to False, i.e., symmetry operation is applied in cartesian coordinates.
apply_strain(strain)[source]

Apply a strain to the lattice.

Parameters:strain (float or list) – Amount of strain to apply. Can be a float, or a sequence of 3 numbers. E.g., 0.01 means all lattice vectors are increased by 1%. This is equivalent to calling modify_lattice with a lattice with lattice parameters that are 1% larger.
insert(i, species, coords, coords_are_cartesian=False, validate_proximity=False, properties=None)[source]

Insert a site to the structure.

Parameters:
  • i (int) – Index to insert site
  • species (species-like) – Species of inserted site
  • coords (3x1 array) – Coordinates of inserted site
  • coords_are_cartesian (bool) – Whether coordinates are cartesian. Defaults to False.
  • validate_proximity (bool) – Whether to check if inserted site is too close to an existing site. Defaults to False.
  • properties (dict) – Properties associated with the site.
Returns:

New structure with inserted site.

make_supercell(scaling_matrix, to_unit_cell=True)[source]

Create a supercell.

Parameters:
  • scaling_matrix

    A scaling matrix for transforming the lattice vectors. Has to be all integers. Several options are possible:

    1. A full 3x3 scaling matrix defining the linear combination the old lattice vectors. E.g., [[2,1,0],[0,3,0],[0,0, 1]] generates a new structure with lattice vectors a’ = 2a + b, b’ = 3b, c’ = c where a, b, and c are the lattice vectors of the original structure.
    2. An sequence of three scaling factors. E.g., [2, 1, 1] specifies that the supercell should have dimensions 2a x b x c.
    3. A number, which simply scales all lattice vectors by the same factor.
  • to_unit_cell – Whether or not to fall back sites into the unit cell
merge_sites(tol=0.01, mode='sum')[source]

Merges sites (adding occupancies) within tol of each other. Removes site properties.

Parameters:
  • tol (float) – Tolerance for distance to merge sites.
  • mode (str) – Two modes supported. “delete” means duplicate sites are deleted. “sum” means the occupancies are summed for the sites. Only first letter is considered.
modify_lattice(new_lattice)[source]

Modify the lattice of the structure. Mainly used for changing the basis.

Parameters:new_lattice (Lattice) – New lattice
perturb(distance)[source]

Performs a random perturbation of the sites in a structure to break symmetries.

Parameters:distance (float) – Distance in angstroms by which to perturb each site.
remove_oxidation_states()[source]

Removes oxidation states from a structure.

remove_sites(indices)[source]

Delete sites with at indices.

Parameters:indices – Sequence of indices of sites to delete.
remove_species(species)[source]

Remove all occurrences of several species from a structure.

Parameters:species – Sequence of species to remove, e.g., [“Li”, “Na”].
replace(i, species, coords=None, coords_are_cartesian=False, properties=None)[source]

Replace a single site. Takes either a species or a dict of species and occupations.

Parameters:
  • i (int) – Index of the site in the _sites list.
  • species (species-like) – Species of replacement site
  • coords (3x1 array) – Coordinates of replacement site. If None, the current coordinates are assumed.
  • coords_are_cartesian (bool) – Whether coordinates are cartesian. Defaults to False.
  • properties (dict) – Properties associated with the site.
replace_species(species_mapping)[source]

Swap species in a structure.

Parameters:species_mapping (dict) – Dict of species to swap. Species can be elements too. e.g., {Element(“Li”): Element(“Na”)} performs a Li for Na substitution. The second species can be a sp_and_occu dict. For example, a site with 0.5 Si that is passed the mapping {Element(‘Si): {Element(‘Ge’):0.75, Element(‘C’):0.25} } will have .375 Ge and .125 C. You can also supply strings that represent elements or species and the code will try to figure out the meaning. E.g., {“C”: “C0.5Si0.5”} will replace all C with 0.5 C and 0.5 Si, i.e., a disordered site.
scale_lattice(volume)[source]

Performs a scaling of the lattice vectors so that length proportions and angles are preserved.

Parameters:volume (float) – New volume of the unit cell in A^3.
sort(key=None, reverse=False)[source]

Sort a structure in place. The parameters have the same meaning as in list.sort. By default, sites are sorted by the electronegativity of the species. The difference between this method and get_sorted_structure (which also works in IStructure) is that the latter returns a new Structure, while this just sorts the Structure in place.

Parameters:
  • key – Specifies a function of one argument that is used to extract a comparison key from each list element: key=str.lower. The default value is None (compare the elements directly).
  • reverse (bool) – If set to True, then the list elements are sorted as if each comparison were reversed.
translate_sites(indices, vector, frac_coords=True, to_unit_cell=True)[source]

Translate specific sites by some vector, keeping the sites within the unit cell.

Parameters:
  • indices – Integer or List of site indices on which to perform the translation.
  • vector – Translation vector for sites.
  • frac_coords (bool) – Whether the vector corresponds to fractional or cartesian coordinates.
  • to_unit_cell (bool) – Whether new sites are transformed to unit cell
exception StructureError[source]

Bases: Exception

Exception class for Structure. Raised when the structure has problems, e.g., atoms that are too close.