Bravais.AbstractBasisType
AbstractBasis <: StaticVector{D, SVector{D,Float64}}

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

Bravais.AbstractPointType
AbstractPoint{D, T} <: StaticVector{D, T}

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

Bravais.DirectBasisType
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.

Bravais.DirectPointType
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.

Bravais.ReciprocalBasisType
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.

Bravais.ReciprocalPointType
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.

Bravais.bravaistypeFunction
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").

Bravais.cartesianizeFunction
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

Bravais.cartesianize!Function
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.

Bravais.cartesianizeMethod
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.

Bravais.centeringFunction
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
Bravais.centering_volume_fractionMethod
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.

Bravais.conventionalizeMethod
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′.

Bravais.conventionalizeMethod
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.

Bravais.conventionalizeMethod
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′.

Bravais.conventionalizeMethod
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.

Bravais.conventionalizeMethod
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)).

Bravais.crystalMethod
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.

Bravais.crystalMethod
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.

Bravais.crystalMethod
crystal(a)  -->  DirectBasis{1}

Return a one-dimensional crystal with lattice period a.

Bravais.crystalsystemMethod
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]):

DSystemConditionsFree parameters
1Dlinearnonea
2Dsquarea=b & γ=90°a
rectangularγ=90°a,b
hexagonala=b & γ=120°a
obliquenonea,b,γ
3Dcubica=b=c & α=β=γ=90°a
hexagonala=b & α=β=90° & γ=120°a,c
trigonala=b & α=β=90° & γ=120°a,c (a,α for hR)
tetragonala=b & α=β=γ=90°a,c
orthorhombicα=β=γ=90°a,b,c
monoclinicα=γ=90°a,b,c,β≥90°
triclinicnonea,b,c,α,β,γ

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).

Bravais.directbasisMethod
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).

Bravais.latticizeFunction
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.

Bravais.latticize!Function
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.

Bravais.latticizeMethod
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.

Bravais.metricmatrixMethod
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.

Bravais.primitivebasismatrixMethod
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}}.$$$

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}.$$$

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.

Bravais.primitivizeMethod
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.

Bravais.primitivizeMethod
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.

Bravais.primitivizeMethod
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.

Bravais.primitivizeMethod
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.

Bravais.primitivizeMethod
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)).

Bravais.reciprocalbasisMethod
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).

Bravais.stackMethod
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.

Bravais.transformMethod
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}$.

Bravais.transformMethod
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}}$.

Bravais.transformMethod
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}}$.

Bravais.transformMethod
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}}$.

Bravais.volumeMethod
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.

• ITA6M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016): Tables 3.1.2.1 and 3.1.2.2 (or Tables 2.1.2.1, 9.1.7.1, and 9.1.7.2 of [ITA5]).
• ITA5T. Hahn, International Tables of Crystallography, Vol. A, 5th ed. (2005).
• CDMLCracknell, Davies, Miller, & Love, Kroenecker Product Tables, Vol. 1 (1979).
• BCSBilbao Crystallographic Server, KVEC.
• AroyoAroyo et al., Acta Cryst. A70, 126 (2014): Table 2 gives $(\mathbf{P}^{-1})^{\text{T}}$.
• ITB2Hahn, International Tables of Crystallography, Vol. B, 2nd edition (2001).
• spglibSpglib documentation: Transformation to the primitive setting. Thus, Bravais.jl and Spglib.jl transform to identical primitive settings and are hence mutually compatible.