Base classes¶
While you may never have to deal with these classes directly, here’s the documentation anyway:
Lattice¶
- class crystals.Lattice(lattice_vectors: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[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 thatx1 = 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 thatx1 = 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: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[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: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[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_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: Iterable[Atom] | None = None, substructures: Iterable[AtomicStructure] | None = None, **kwargs)¶
Base class for atomic structures. These structures can be made out of
Atom
objects, or otherAtomicStructures
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 ofAtom
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: Callable[[Atom], Any] | None = 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: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[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'