class crystals.Crystal(unitcell, lattice_vectors, source=None, **kwargs)

The Crystal class is a set-like container that represent crystalline structures. In addition to constructing the Crystal object yourself, other constructors are also available (and preferred):

  • Crystal.from_cif(): create an instance from a CIF file;

  • Crystal.from_pdb(): create an instance from a Protein Data Bank entry;

  • Crystal.from_database(): create an instance from the internal database of CIF files;

  • Crystal.from_cod(): create an instance from a Crystallography Open Database entry;

  • Crystal.from_mp(): create an instance from the Materials Project database;

  • Crystal.from_pwscf(): create an instance from the output of the PWSCF program;

  • Crystal.from_ase(): create an instance from an ase.Atoms instance;

  • Crystal.from_poscar(): create an instance from VASP POSCAR files.

  • unitcell (iterable of Atom or AtomicStructure) – Unit cell atoms or substructures. It is assumed that the atoms are in fractional coordinates.

  • lattice_vectors (iterable of array_like) – Lattice vectors. If lattice_vectors is provided as a 3x3 array, it is assumed that each lattice vector is a row.

  • source (str or None, optional) – Provenance, e.g. filename. Only used for bookkeeping.

__init__(unitcell, lattice_vectors, source=None, **kwargs)



Create a new structure made from the combination of two structures.

__array__(*args, **kwargs)

Returns an array in which each row represents an Atom instance.


An AtomicStructure is False if empty, and True otherwise


Check containership of Atom instances or AtomicStructure substructures recursively.

__delattr__(name, /)

Implement delattr(self, name).


Default dir() implementation.


Return self==value.

__format__(format_spec, /)

Default object formatter.

__ge__(value, /)

Return self>=value.

__getattribute__(name, /)

Return getattr(self, name).

__gt__(value, /)

Return self>value.


Return hash(self).

__init__(unitcell, lattice_vectors[, source])


This method is called when a class is subclassed.


Yields Atom instances from the structure and substructures recursively.

__le__(value, /)

Return self<=value.


Number of Atom instances present in the structure and substructures

__lt__(value, /)

Return self<value.

__ne__(value, /)

Return self!=value.



Helper for pickle.

__reduce_ex__(protocol, /)

Helper for pickle.


Verbose string representation of this instance.

__setattr__(name, value, /)

Implement setattr(self, name, value).


Size of object in memory, in bytes.


String representation of this instance.


Abstract classes can override this to customize issubclass().

_from_spglib_cell(lattice_vectors, ...)

Build a Crystal object from the return value of many SPGLIB routines.


Returns an array in spglib's cell format.


Generate a string representation of this Crystal.


Calculates the asymmetric cell that generates the crystal unit cell.

bounded_reflections(bound[, min_bound])

Generates reflections (hkl) with norm(G) <= bound

frac_mesh(*xi[, indexing])

Coordinate arrays for fractional coordinates.

from_ase(atoms, **kwargs)

Returns a Crystal object created from an ASE Atoms object.

from_cif(path, **kwargs)

Returns a Crystal object created from a CIF 1.0, 1.1 or 2.0 file.

from_cod(num[, revision, download_dir, ...])

Returns a Crystal object built from the Crystallography Open Database.

from_database(name, **kwargs)

Returns a Crystal object create from the internal CIF database.

from_mp(query[, api_key, download_dir, ...])

Returns a Crystal object built from the Materials Project.

from_parameters(a, b, c, alpha, beta, gamma)

Create a Lattice instance from three lengths and angles.

from_pdb(ID[, download_dir, overwrite])

Returns a Crystal object created from a Protein DataBank entry.

from_poscar(path, **kwargs)

Returns a Crystal object created from a VASP's POSCAR file.

from_pwscf(path, **kwargs)

Returns a Crystal object created from an output file of PWSCF.


Returns a Crystal object with an idealized unit cell.


Return a crystal structure, indexed by another lattice/crystal structure.

itersorted(*[, key, reverse])

Yields Atom in sorted order.

mesh(*xi[, indexing])

Cartesian coordinate arrays from fractional coordinate vectors.


Miller indices from scattering vector components.


Returns a Crystal object in the primitive unit cell.


Get the symmetry operations that the reciprocal unit cell respects.


Builds a new AtomicStructure from atoms satisfying a predicate.


Scattering vector from Miller indices.

supercell(n1, n2, n3)

Create a supercell from this crystal, i.e. an atomic structure where the crystal unit cell is duplicated along lattice vectors.

symmetry([symprec, angle_tolerance])

Returns a dictionary containing space-group information.


Get the symmetry operations that the crystal unit cell respects.


Convert a into an ase.Atoms object.


Convert this Crystal instance to a CIF file.

to_poscar(filename, **kwargs)

Convert this Crystal instance to a POSCAR file.


Convert this Crystal instance to a XYZ file.


Return a transformed AtomicStructure based on symmetry operators.




Centering type of this crystals.


Chemical composition of this structure as an ordered dictionary.


Empirical chemical formula for this structure based on the chemical symbols.


Hall number (between 1 and 531).


Hall symbol.


Hermann-Mauguin symbol.


International Tables of Crystallography space-group full symbol.


International Tables of Crystallography space-group number (between 1 and 230).


International Tables of Crystallography space-group short symbol.


Lattice parameters as three lengths [Å] and three angles [degrees].


One of the seven lattice system, returned in the form of the LatticeSystem enumeration.


Iterable of lattice vectors


Crystal periodicity in x, y and z direction from the lattice constants.


International Tables of Crystallography point-group.


Reciprocal lattice


Reciprocal lattice vectors, defined as:


Generator of atoms forming the crystal unit cell.


Lattice cell volume Angtroms cubed