AbstractBasis <: StaticVector{D, SVector{D,Float64}}

Abstract supertype of a D-dimensional basis in D-dimensional space.

AbstractPoint{D, T} <: StaticVector{D, T}

Abstract supertype of a D-dimensional point with elements of type T.

DirectBasis{D} <: AbstractBasis{D}

A wrapper type over D distinct D-dimensional vectors (given as a SVector{D, SVector{D,Float64}}), defining a lattice basis in direct space.

DirectPoint{D} <: AbstractPoint{D}

A wrapper type over an SVector{D, Float64}, defining a single point in D-dimensional direct space.

The coordinates of a DirectPoint are generally assumed specified relative to an associated DirectBasis. To convert to Cartesian coordinates, see cartesianize.

ReciprocalBasis{D} <: AbstractBasis{D}

A wrapper type over D distinct D-dimensional vectors (given as a SVector{D, SVector{D,Float64}}), defining a lattice basis in reciprocal space.

ReciprocalPoint{D} <: AbstractPoint{D}

A wrapper type over an SVector{D, Float64}, defining a single point in D-dimensional reciprocal space.

The coordinates of a ReciprocalPoint are generally assumed specified relative to an associated ReciprocalBasis. To convert to Cartesian coordinates, see cartesianize.

bravaistype(sgnum::Integer, D::Integer=3; normalize::Bool=false)  -->  String

Return the Bravais type of sgnum in dimension D as a string (as the concatenation of the single-character crystal abbreviation and the centering type).

Keyword arguments

• normalize: If the centering type associated with sgnum is 'A', we can choose (depending on the keyword argument normalize, defaulting to false) to "normalize" to the centering type 'C', since the difference between 'A' and 'C' centering only amounts to a basis change. With normalize=true we then have only the canonical 14 Bravais type, i.e. unique(bravaistype.(1:230, 3), normalize=true) returns only 14 distinct types, rather than 15.

  This only affects space groups 38-41 (normalizing their conventional Bravais types from "oA" to "oC").

cartesianize

Transform an object with coordinates in an lattice basis to an object with coordinates in a Cartesian basis.

Depending on the object, the basis may be inferrable directly from the object; if not, it must be supplied explicitly. @doc

cartesianize!

In-place transform an object with coordinates in an lattice basis to an object with coordinates in a Cartesian basis.

Depending on the object, the basis may be inferrable directly from the object; if not, it must be supplied explicitly.

cartesianize(v::AbstractVector{<:Real}, basis)

Transform a vector v with coordinates referred to a lattice basis to a vector with coordinates referred to the Cartesian basis implied by the columns (or vectors) of basis.

centering(sgnum::Integer, D::Integer=3)  -->  Char

Return the conventional centering type cntr of the space group with number sgnum and dimension D.

The centering type is equal to the first letter of the Hermann-Mauguin notation's label, i.e., centering(sgnum, D) == first(Crystalline.iuc(sgnum, D)). Equivalently, the centering type is the second and last letter of the Bravais type (bravaistype), i.e., centering(sgnum, D) == bravaistype(sgnum, D).

Possible values of cntr, depending on dimensionality D, are (see ITA Sec. 9.1.4):

• D = 1:
  • cntr = 'p': no centering (primitive)
• D = 2:
  • cntr = 'p': no centring (primitive)
  • cntr = 'c': face centered
• D = 3:
  • cntr = 'P': no centring (primitive)
  • cntr = 'I': body centred (innenzentriert)
  • cntr = 'F': all-face centred
  • cntr = 'A' or 'C': one-face centred, (b,c) or (a,b)
  • cntr = 'R': hexagonal cell rhombohedrally centred

centering_volume_fraction(cntr, Dᵛ, Pᵛ) --> Int

Return the (integer-) ratio between the volumes of the conventional and primitive unit cells for a space or subperiodic group with centering cntr, embedding dimension D, and periodicity dimension P.

conventionalize(Rs′::DirectBasis, cntr_or_sgnum::Union{Char, <:Integer}) --> Rs::typeof(Rs′)

Return the conventional direct basis Rs corresponding to the input primitive direct basis Rs′.

conventionalize(r′::DirectPoint, cntr_or_sgnum::Union{Char, <:Integer}) --> r::typeof(r′)

Return the direct point r with coordinates in a conventional basis, corresponding to the input point r′ with coordinates in a primitive basis.

conventionalize(Gs′::ReciprocalBasis, cntr_or_sgnum::Union{Char, <:Integer}) --> Gs::typeof(Gs′)

Return the conventional reciprocal basis Gs corresponding to the input primitive reciprocal basis Gs′.

conventionalize(k′::ReciprocalPoint, cntr_or_sgnum::Union{Char, <:Integer}) --> k::typeof(k′)

Return the reciprocal point k with coordinates in a conventional basis, corresponding to the input point k′ with coordinates in a primitive basis.

conventionalize(V′::Union{AbstractBasis, AbstractPoint}, 
                cntr_or_sgnum::Union{Char, <:Integer})    -->  V::typeof(V′)

Return the conventional basis or point V associated with the input primitive AbstractBasis or AbstractPoint V′.

The assumed centering type is specified by cntr_or_sgnum, given either as a centering character (::Char) or inferred from a space group number (::Integer) and the dimensionality of V′ (see also centering(::Integer, ::Integer)).

crystal(a, b, c, α, β, γ)  -->  DirectBasis{3}

Calculate basis vectors $\mathbf{R}_1$, $\mathbf{R}_2$, $\mathbf{R}_3$ in a 3D Cartesian basis for a right-handed coordinate system with specified basis vector lengths a, b, c (associated with $\mathbf{R}_1$, $\mathbf{R}_2$, & $\mathbf{R}_3$, respectively) and specified interaxial angles α $= ∠(\mathbf{R}_2,\mathbf{R}_3)$, β $= ∠(\mathbf{R}_3,\mathbf{R}_1)$, γ $= ∠(\mathbf{R}_1,\mathbf{R}_2)$, with $∠$ denoting the angle between two vectors.

For definiteness, the $\mathbf{R}_1$ basis vector is oriented along the $x$-axis of the Cartesian coordinate system, and the $\mathbf{R}_2$ axis is placed in the $xy$-plane.

crystal(a, b, γ)  -->  DirectBasis{2}

Calculate basis vectors $\mathbf{R}_1$, $\mathbf{R}_2$ in a 2D Cartesian basis for a right-handed coordinate system with specified basis vector lengths a, b (associated with $\mathbf{R}_1$ & $\mathbf{R}_2$, respectively) and specified interaxial angle γ $= ∠(\mathbf{R}_1,\mathbf{R}_2)$.

For definiteness, the $\mathbf{R}_1$ basis vector is oriented along the $x$-axis of the Cartesian coordinate system.

crystal(a)  -->  DirectBasis{1}

Return a one-dimensional crystal with lattice period a.

crystalsystem(Rs::DirectBasis{D})  -->  String

Determine the crystal system of a point lattice Rs, assuming the conventional setting choice defined in the International Tables of Crystallography ^[ITA6].

There are 4 crystal systems in 2D and 7 in 3D (see Section 2.1.2(iii) of ^[ITA5]):

The Rs must specify a set of conventional basis vectors, i.e., not generally primitive. For primitive basis vectors, the crystal system can be further reduced into 5 Bravais types in 2D and 14 in 3D (see bravaistype).

directbasis(sgnum, D=3;    abclims, αβγlims)
directbasis(sgnum, Val(D); abclims, αβγlims) --> DirectBasis{D}

Return a random (conventional) DirectBasis for a crystal compatible with the space group number sgnum and dimensionality D. Free parameters in the lattice vectors are chosen randomly, with limits optionally supplied in abclims (lengths) and αβγlims (angles). By convention, the length of the first lattice vector (a) is set to unity, such that the second and third (b and c) lattice vectors' lengths are relative to the first.

Limits on the relative uniform distribution of lengths b and c can be specified as 2-tuple kwarg abclims; similarly, limits on the angles α, β, γ can be set via αβγlims (only affects oblique, monoclinic, & triclinic lattices).

latticize

Transform an object with coordinates in a Cartesian basis to an object with coordinates in a lattice basis.

Depending on the object, the basis may be inferrable directly from the object; if not, it must be supplied explicitly.

latticize!

In-place transform object with coordinates in a Cartesian basis to an object with coordinates in a lattice basis.

Depending on the object, the basis may be inferrable directly from the object; if not, it must be supplied explicitly.

latticize(v::AbstractVector{<:Real}, basis)

Transform a vector v with coordinates referred to the Cartesian basis to a vector with coordinates referred to the lattice basis implied by the columns (or vectors) of basis.

metricmatrix(Vs::AbstractBasis)

Return the (real, symmetric) metric matrix of a basis Vs, i.e., the matrix with elements $G_{ij} =$ dot(Vs[i], Vs[j]), as defined in the International Tables of Crystallography, Volume A, Section 5.2.2.3.

Equivalently, this is the Gram matrix of Vs, and so can also be expressed as Vm' * Vm with Vm denoting the columnwise concatenation of the basis vectors in Vs.

See also volume.

primitivebasismatrix(cntr::Char, ::Val{D}=Val(3)) --> SMatrix{D,D,Float64}
primitivebasismatrix(cntr::Char, ::Val{D}, ::Val{P}) --> SMatrix{D,D,Float64}

Return the transformation matrix $\mathbf{P}$ that transforms a conventional unit cell with centering cntr to the corresponding primitive unit cell (in dimension D and periodicity P) in CDML setting.

If P is not provided, it default to D (as e.g., applicable to Crystalline.jl's spacegroup). If D and P differ, a subperiodic group setting is assumed (as e.g., applicable to Crystalline.jl's subperiodicgroup).

Transformations in direct and reciprocal space

Bases

The returned transformation matrix $\mathbf{P}$ transforms a direct-space conventional basis $(\mathbf{a}\ \mathbf{b}\ \mathbf{c})$ to the direct-space primitive basis

\[ (\mathbf{a}'\ \mathbf{b}'\ \mathbf{c}') = (\mathbf{a}\ \mathbf{b}\ \mathbf{c})\mathbf{P}.\]

Analogously, $\mathbf{P}$ transforms a reciprocal-space conventional basis $(\mathbf{a}^*\ \mathbf{b}^*\ \mathbf{c}^*)$ to

\[(\mathbf{a}^{*\prime}\ \mathbf{b}^{*\prime}\ \mathbf{c}^{*\prime}) = (\mathbf{a}^*\ \mathbf{b}^*\ \mathbf{c}^*)(\mathbf{P}^{-1})^{\text{T}}.\]

see also transform(::DirectBasis, ::AbstractMatrix{<:Real}) and transform(::ReciprocalBasis, ::AbstractMatrix{<:Real})).

Coordinates

The coordinates of a point in either direct or reciprocal space, each referred to a basis, also transform under $\mathbf{P}$. Concretely, direct- and reciprocal-space conventional points $\mathbf{r} = (r_1, r_2, r_3)^{\text{T}}$ and $\mathbf{k} = (k_1, k_2, k_3)^{\text{T}}$, respectively, transform to a primitive setting under $\mathbf{P}$ according to:

\[\mathbf{r}' = \mathbf{P}^{-1}\mathbf{r},\\ \mathbf{k}' = \mathbf{P}^{\text{T}}\mathbf{k}.\]

See also transform(::DirectPoint, ::AbstractMatrix{<:Real}) and transform(::ReciprocalPoint, ::AbstractMatrix{<:Real})).

Setting conventions

The setting choice for the primitive cell implied by the returned $\mathbf{P}$ follows the widely adopted Cracknell-Davies-Miller-Love (CDML) convention.^[CDML] This convention is explicated e.g. in Table 2 of ^[Aroyo] (or, alternatively, can be inferred from Tables 1.5.4.1 and 1.5.4.2 of ^[ITB2]) and is followed e.g. on the Bilbao Crystallographic Server^[BCS], in the CDML reference work on space group irreps^[CDML], and in the C library spglib.^[spglib]

Note that this setting choice is not what is frequently referred to as the "ITA primitive setting", from which it differs for hP, hR, and oA Bravais types.

The setting choice is usually referred to as the CDML primitive setting, or, less frequently and more ambiguously, as the crystallographic primitive setting.

primitivize(Rs::DirectBasis, cntr_or_sgnum::Union{Char, <:Integer}) --> Rs′::typeof(Rs)

Return the primitive direct basis Rs′ corresponding to the input conventional direct basis Rs.

primitivize(r::DirectPoint, cntr_or_sgnum::Union{Char, <:Integer}) --> r′::typeof(r)

Return the direct point r′ with coordinates in a primitive basis, corresponding to the input point r with coordinates in a conventional basis.

primitivize(Gs::ReciprocalBasis, cntr_or_sgnum::Union{Char, <:Integer}) --> Gs′::typeof(Gs)

Return the primitive reciprocal basis Gs′ corresponding to the input conventional reciprocal basis Gs.

primitivize(k::ReciprocalPoint, cntr_or_sgnum::Union{Char, <:Integer}) --> k′::typeof(k)

Return the reciprocal point k′ with coordinates in a primitive basis, corresponding to the input point k with coordinates in a conventional basis.

primitivize(V::Union{AbstractBasis, AbstractPoint}, 
            cntr_or_sgnum::Union{Char, <:Integer})   -->  V′::typeof(V)

Return the primitive basis or point V′ associated with the input conventional AbstractBasis or AbstractPoint V.

The assumed centering type is specified by cntr_or_sgnum, given either as a centering character (::Char) or inferred from a space group number (::Integer) and the dimensionality of V (see also centering(::Integer, ::Integer)).

reciprocalbasis(Rs)  -->  ::ReciprocalBasis{D}

Return the reciprocal basis of a direct basis Rs in D dimensions, provided as a StaticVector of AbstractVectors (e.g., a DirectBasis{D}) or a D-dimensional NTuple of AbstractVectors, or a (or, type-unstably, as any iterable of AbstractVectors).

stack(Vs::AbstractBasis)

Return a matrix [Vs[1] Vs[2] .. Vs[D]] from Vs::AbstractBasis{D}, i.e., the matrix whose columns are the basis vectors of Vs.

transform(Rs::DirectBasis, P::AbstractMatrix{<:Real})

Transform a direct basis Rs $= (\mathbf{a}\ \mathbf{b}\ \mathbf{c})$ under the transformation matrix P $= \mathbf{P}$, returning Rs′ $= (\mathbf{a}'\ \mathbf{b}'\ \mathbf{c}') = (\mathbf{a}\ \mathbf{b}\ \mathbf{c}) \mathbf{P}$.

transform(r::DirectPoint, P::AbstractMatrix{<:Real})  -->  r′::typeof(r)

Transform a point in direct space r $= (r_1, r_2, r_3)^{\text{T}}$ under the transformation matrix P $= \mathbf{P}$, returning r′ $= (r_1', r_2', r_3')^{\text{T}} = \mathbf{P}^{-1}(r_1', r_2', r_3')^{\text{T}}$.

transform(Gs::ReciprocalBasis, P::AbstractMatrix{<:Real})

Transform a reciprocal basis Gs $= (\mathbf{a}^* \mathbf{b}^* \mathbf{c}^*)$ under the transformation matrix P $= \mathbf{P}$, returning Gs′ $= (\mathbf{a}^{*\prime}\ \mathbf{b}^{*\prime}\ \mathbf{c}^{*\prime}) = (\mathbf{a}^*\ \mathbf{b}^*\ \mathbf{c}^*)(\mathbf{P}^{-1})^{\text{T}}$.

transform(k::ReciprocalPoint, P::AbstractMatrix{<:Real})  -->  k′::typeof(k)

Transform a point in reciprocal space k $= (k_1, k_2, k_3)^{\text{T}}$ under the transformation matrix P $= \mathbf{P}$, returning k′ $= (k_1', k_2', k_3')^{\text{T}} = \mathbf{P}^{\text{T}}(k_1', k_2', k_3')^{\text{T}}$.

volume(Vs::AbstractBasis)

Return the volume $V$ of the unit cell associated with the basis Vs::AbstractBasis{D}.

The volume is computed as $V = \sqrt{\mathrm{det}\mathbf{G}}$ with with $\mathbf{G}$ denoting the metric matrix of Vs (cf. the International Tables of Crystallography, Volume A, Section 5.2.2.3).

See also metricmatrix.