Base classes

While you may never have to deal with these classes directly, here’s the documentation anyway:

Lattice

class crystals.Lattice(lattice_vectors: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], _SupportsArray[dtype], Sequence[_SupportsArray[dtype]], Sequence[Sequence[_SupportsArray[dtype]]], Sequence[Sequence[Sequence[_SupportsArray[dtype]]]], Sequence[Sequence[Sequence[Sequence[_SupportsArray[dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]], **kwargs)

Container class for lattice information and manipulations.

Instances can also be create from the standard ‘three lengths and angles’ parameters via Lattice.from_parameters:

Parameters

lattice_vectors (iterable of ~numpy.ndarray, shape (3,)) – Lattice vectors.

bounded_reflections(bound: float, min_bound: float = 0) Iterator[Tuple[int, int, int]]

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

Parameters
  • bound (float) – Maximal scattering vector norm [\(A^{-1}\)].

  • min_bound (float, optional) – Minimal scattering vector norm [\(A^{-1}\)].

    New in version 1.2.0.

Yields

reflection (3-tuple of ints) – Miller indices of a bounded reflection.

:raises ValueError : if bound is smaller than min_bound.:

Examples

>>> cryst = Crystal.from_database('C')
>>> refls = cryst.bounded_reflections(1.5) # 1.5 inverse Angstroms
>>> list(refls)
[(0, 0, -1), (0, 0, 0), (0, 0, 1)]
static frac_mesh(*xi, indexing: str = 'xy') Tuple[ndarray, ndarray, ndarray]

Coordinate arrays for fractional coordinates.

Parameters
  • x1, x2, x3 (~numpy.ndarray, shape (N,)) – 1d coordinate vectors. If only x1 is provided, it is assumed that x1 = x2 = x3. Otherwise, three coordinate vectors are expected.

  • indexing (str, {‘ij’, ‘xy’}) – Cartesian (‘xy’, default) or matrix (‘ij’) indexing of output.

Returns

out1, out2, out3 (~numpy.ndarray) – Fractional coordinate arrays.

:raises ValueError : if number of input vectors is neither 1 nor 3.:

See also

numpy.meshgrid

Coordinate arrays from coordinate vectors

Lattice.mesh

Real-space coordinate arrays from fractional coordinate vectors

classmethod from_parameters(a: float, b: float, c: float, alpha: float, beta: float, gamma: float)

Create a Lattice instance from three lengths and angles.

Parameters
  • a, b, c (floats) – Lattice vectors lengths [Å]

  • alpha, beta, gamma (floats) – Angles between lattice vectors [deg]

:raises ValueError : if lattice parameters are invalid.:

mesh(*xi: ndarray, indexing: str = 'xy') Tuple[ndarray, ndarray, ndarray]

Cartesian coordinate arrays from fractional coordinate vectors.

Parameters
  • x1, x2, x3 (~numpy.ndarray, shape (N,)) – 1d coordinate vectors in fractional coordinates. If only x1 is provided, it is assumed that x1 = x2 = x3. Otherwise, three coordinate vectors are expected.

  • indexing (str, {‘ij’, ‘xy’}) – Cartesian (‘xy’, default) or matrix (‘ij’) indexing of output.

Returns

out1, out2, out3 (~numpy.ndarray) – Real-space (cartesian) coordinate arrays.

:raises ValueError : if number of input vectors is neither 1 nor 3.:

See also

numpy.meshgrid

Coordinate arrays from coordinate vectors

Lattice.frac_mesh

Coordinate arrays for fractional coordinates

miller_indices(scattering_vector: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], _SupportsArray[dtype], Sequence[_SupportsArray[dtype]], Sequence[Sequence[_SupportsArray[dtype]]], Sequence[Sequence[Sequence[_SupportsArray[dtype]]]], Sequence[Sequence[Sequence[Sequence[_SupportsArray[dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]]) ndarray

Miller indices from scattering vector components.

Changed in version 1.3: Can now operate on tables of vectors, where every vector is a row.

Parameters

scattering_vector (array_like, shape (3,) or (N, 3)) – Scattering vector in \(A^{-1}\).

Returns

reflection (~numpy.ndarray, shape (3,) or (N, 3)) – Miller indices.

scattering_vector(reflection: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], _SupportsArray[dtype], Sequence[_SupportsArray[dtype]], Sequence[Sequence[_SupportsArray[dtype]]], Sequence[Sequence[Sequence[_SupportsArray[dtype]]]], Sequence[Sequence[Sequence[Sequence[_SupportsArray[dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]]) ndarray

Scattering vector from Miller indices.

Changed in version 1.3: Can now operate on tables of reflections, where every reflection is a row.

Parameters

reflection (array_like, shape (3,) or (N, 3)) – Miller indices.

Returns

G (ndarray, shape (3,) or (N, 3)) – Scattering vector in \(A^{-1}\).

property lattice_parameters: Tuple[float, float, float, float, float, float]

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

property lattice_system: LatticeSystem

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

property lattice_vectors: Tuple[ndarray, ndarray, ndarray]

Iterable of lattice vectors

property periodicity: Tuple[float, float, float]

Crystal periodicity in x, y and z direction from the lattice constants. This is effectively a bounding cube for the unit cell, which is itself a unit cell.

Returns

x, y, z (float) – Periodicity in Angstroms along the x, y, and z direction, respectively.

property reciprocal: Lattice

Reciprocal lattice

property reciprocal_vectors: Tuple[ndarray, ndarray, ndarray]

Reciprocal lattice vectors, defined as:

\[b_i = 2 \pi \frac{a_j \times a_k}{v}\]

For \(v\) the unit cell volume.

property volume: float

Lattice cell volume Angtroms cubed

AtomicStructure

class crystals.AtomicStructure(atoms: Optional[Iterable[Atom]] = None, substructures: Optional[Iterable[AtomicStructure]] = None, **kwargs)

Base class for atomic structures. These structures can be made out of Atom objects, or other AtomicStructures subclasses.

The AtomicStructures class provides an abstraction over structure with and without substructure. Subclasses can be iterated over as an iterable of atoms. Order of iteration is not guaranteed.

Hierarchical containership of AtomicStructures is implemented, as well as containership of Atom instances.

Parameters
  • atoms (iterable, optional) – Atoms not attached to a substructure.

  • substructures (iterable, optional) – Atomic substructures. For example, different atom chains could form a secondary structure in a protein.

itersorted(*, key: Optional[Callable[[Atom], Any]] = None, reverse: bool = False) Iterator[Atom]

Yields Atom in sorted order. By default, atoms are sorted by element.

Parameters
  • key (callable or None, optional) – Function of one argument that is used to extract a comparison key for an Atom instance.

  • reverse (bool, optional) – If True, elements are yielded in reverse order.

Yields

atm (Atom)

satisfying(predicate: Callable[[Atom], bool]) AtomicStructure

Builds a new AtomicStructure from atoms satisfying a predicate.

This method is similar to the built-in filter, except that the properties of AtomicStructures are conserved.

Parameters

predicate (callable) – Function that takes a single atom, and returns boolean.

Returns

out (AtomicStructure)

transform(*operators: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], _SupportsArray[dtype], Sequence[_SupportsArray[dtype]], Sequence[Sequence[_SupportsArray[dtype]]], Sequence[Sequence[Sequence[_SupportsArray[dtype]]]], Sequence[Sequence[Sequence[Sequence[_SupportsArray[dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]]) AtomicStructure

Return a transformed AtomicStructure based on symmetry operators.

Parameters

operators (iterable of array_like) – Symmetry operators, either 3x3 or 4x4.

Returns

transformed (AtomicStructure) – New structure.

property chemical_composition: Dict[str, float]

Chemical composition of this structure as an ordered dictionary. Keys are elemental symbols. Elements are in descending order of prevalence.

Example

>>> c = Crystal.from_cod(1508819)
>>> c.chemical_composition 
OrderedDict([('H',  0.441),
             ('C',  0.349),
             ('N',  0.093),
             ('O',  0.093),
             ('Cl', 0.023)
             ])
property chemical_formula: str

Empirical chemical formula for this structure based on the chemical symbols. The string is returned in Hill notation: symbols are alphabetically ordered except for carbon (C) and hydrogen (H), which are put first.

Example

>>> c = Crystal.from_cod(1508819)
>>> c.chemical_formula
'C15 H19 Cl N4 O4'