LatticeGeometry

abstract type AbstractCrystalGeometer end

A generic family of structures/functors that will control the access to metrics and distances based on basis vectors.

abstract type AbstractIndexingScheme

A generic type for indexing the elements of a lattice – that is, the UnitCells and the atoms within them.

AbstractionError <: Exception

A pretty generic catch all for abtract typing on the fly.

AtomOrdered <: AbstractIndexingScheme

In this type of AbstractIndexingScheme one iterates over the all the atom species in a UnitCells before proceeding.

The index ordering function is given by

\[\mathtt{index}(\mathtt{atom}, \mathtt{cell}) = \mathtt{atom} + (\mathtt{cell} - 1) * N_{\mathrm{atoms}}\]

CellOrdered <: AbstractIndexingScheme

In this type of AbstractIndexingScheme one iterates over the same atom species throughout all UnitCells before proceeding.

The index ordering function is given by

\[\mathtt{index}(\mathtt{atom}, \mathtt{cell}) = \mathtt{cell} + (\mathtt{atom} - 1) * N_{\mathrm{cells}}\]

• Note: this is the DefaultIndexing scheme.

DefaultCrystalGeometer{D, T}

The go-to AbstractCrystalGeometer one can use for systems of spatial dimension D and with basis vectors of with eltype T <: AbstractFloat.

** Note The metric will be stored in a secondary default type of MT = Float64 for higher precision calculations, particularly of angles between vectors. If, for some crazy reason, one wants to store the basis vectors as a type T with more precision than Float64, then MT will be be promoted to T.

LatticeIndexer(; Natoms, Ncells)

This struct is almost a functor which is used to index atom and UnitCells in the LatticeStructure. Its two fields are the atoms_per_cell (Natoms) and the number of cells (Ncells) in the LatticeStructure.

LatticeIndices(; atom, cell)

This is essentially a NamedTuple that encloses two Ints which denote the atom_index (atom) and the cell_index (cell).

LatticeIndices(::LatticeIndexer, idx::Number, ::AtomOrdered)

Create a LatticeIndices struct from the index idx in the AtomOrdered scheme.

julia> indexer = LatticeIndexer(; Natoms = 2, Ncells = 5)
LatticeIndexer(2, 5)

julia> indices = LatticeIndices(indexer, 3, AtomOrdered())
LatticeIndices(1, 2)

julia> atom(indices)
1

julia> cell(indices)
2

LatticeIndices(::LatticeIndexer, idx::Number, ::CellOrdered)

Create a LatticeIndices struct from the index idx in the CellOrdered scheme.

julia> indexer = LatticeIndexer(; Natoms = 2, Ncells = 5)
LatticeIndexer(2, 5)

julia> indices = LatticeIndices(indexer, 3, CellOrdered())
LatticeIndices(1, 3)

julia> atom(indices)
1

julia> cell(indices)
3

LatticeIndices(::LatticeIndexer, idx::Number)

Default implementation for LatticeIndices.

julia> indexer = LatticeIndexer(; Natoms = 2, Ncells = 5)
LatticeIndexer(2, 5)

julia> LatticeIndices(indexer, 3) == LatticeIndices(indexer, 3, DefaultIndexing())
true

UnitCell{Natoms, Dimension, Type} <: AbstractUnitCell

Generic UnitCell structure with Natoms in a given spatial Dimension. Type signifies the numerical type used to store the positions. We use the standard convention of writing the positions in the cell coordinates, where each component of the positions must lie on [0,1].

UnitCell([atom_names], atomic_positions)

Constructor for the UnitCell. The atomic_positions must be supplied as a StaticArrays.SVector of StaticArrays.SVectors to optimize memory. The atom_names are optional, though if they are supplied then length(atom_names) == length(atomic_positions). If they are not supplied, default atom_names will be used.

julia> using StaticArrays

julia> positions = @SVector [ SVector(0.0, 0.0, 0.0), SVector(0.5, 0.5, 0.5) ];

julia> labels = SVector( "Fe", "As" );

julia> UnitCell(labels, positions)

  `UnitCell` containing 2 atoms in 3 spatial dimensions.

    Fe at [0.0, 0.0, 0.0]
    As at [0.5, 0.5, 0.5]

julia> UnitCell(positions; warn_on = false)

  `UnitCell` containing 2 atoms in 3 spatial dimensions.

    Atom_1 at [0.0, 0.0, 0.0]
    Atom_2 at [0.5, 0.5, 0.5]

_positions_within_bounds(positions; [interval = [0, 1]])

Internal function to check that each position coordinate is on the supplied interval.

angle_between(Pvec, Qvec, ::AbstractCrystalGeometer, ::AbstractVectorBasis)

Compute the angle between Pvec and Qvec, both measured in a given AbstractVectorBasis using a metric from the AbstractCrystalGeometer. This function relies on the scalar dot product and the vector norm.

basis_change(::AbstractCrystalGeometer, ::AbstractBasisTransformation)

Return the transformation matrix from the AbstractCrystalGeometer for the appropriate AbstractBasisTransformation.

basis_vectors(::AbstractCrystalGeometer)

Return the lattice basis vectors (in the CrystalBasis).

cell_volume(::AbstractCrystalGeometer)

Return the unit-cell volume for a given set of basis_vectors. This is just the determinant of the basis_change(::AbstractCrystalGeometer, ReducedToCrystal()).

change_coordinates(Pvec, ::AbstractCrystalGeometer, ::AbstractBasisTransformation)

Convert the Pvec vector into a different set of coordinates using the given AbstractCrystalGeometer and AbstractBasisTransformation. For example, to go from reduced coordinates to the physical crystal coordinates, use

change_coordinates(Pvec, geo, ReducedToCrystal())  # geo <: AbstractCrystalGeometer

Mathematically, the coordinate change in the example above amounts to

\[\vec{P} = \vec{a}_i P_i = C \cdot \boldsymbol{P},\]

where $\boldsymbol{P}$ is the vector of reduced coordinates and $C = [\vec{a}_1 | \vec{a}_2 | \dots]$ is the matrix of lattice vectors.

cosine_angle_between(Pvec, Qvec, ::AbstractCrystalGeometer, ::AbstractVectorBasis)

Compute the cosine of the angle between Pvec and Qvec, both measured in a given AbstractVectorBasis using a metric from the AbstractCrystalGeometer. This function relies on the scalar dot product and the vector norm.

dimension(::AbstractCrystalGeometer)

Return the spatial dimension of the AbstractCrystalGeometer.

index(::LatticeIndexer, ::LatticeIndices, ::AtomOrdered)

Return the flattened index associated with the given LatticeIndices in the AtomOrdered scheme.

julia> indexer = LatticeIndexer(; Natoms = 2, Ncells = 5)
LatticeIndexer(2, 5)

julia> index(indexer, LatticeIndices(; atom = 1, cell = 1), AtomOrdered())
1

julia> index(indexer, LatticeIndices(; atom = 2, cell = 4), AtomOrdered())
8

index(::LatticeIndexer, ::LatticeIndices, ::CellOrdered)

Return the flattened index associated with the given LatticeIndices in the CellOrdered scheme.

julia> indexer = LatticeIndexer(; Natoms = 2, Ncells = 5)
LatticeIndexer(2, 5)

julia> index(indexer, LatticeIndices(; atom = 1, cell = 1), CellOrdered())
1

julia> index(indexer, LatticeIndices(; atom = 2, cell = 4), CellOrdered())
9

index(::LatticeIndexer, ::LatticeIndices [, ::AbstractIndexingScheme = DefaultIndexing()])

Default implementation of the indexing scheme for LatticeStructures.

julia> indexer = LatticeIndexer(; Natoms = 2, Ncells = 5)
LatticeIndexer(2, 5)

julia> index(indexer, LatticeIndices(; atom = 1, cell = 2)) == index(indexer, LatticeIndices(; atom = 1, cell = 2), DefaultIndexing())
true

metric(::AbstractCrystalGeometer, ::CrystalBasis)

In the CrystalBasis, the metric is the identity, LinearAlgebra.I.

metric(::AbstractCrystalGeometer, ::ReducedBasis)

In the ReducedBasis, the metric is used to compute physical crystal angles between vectors measured in the ReducedBasis. For example, if $\boldsymbol{P}$ and $\boldsymbol{Q}$ denote points within the crystal in the ReducedBasis, which are the points $\vec{P}$ and $\vec{Q}$ in the CrystalBasis, then the scalar product between them is

\[\vec{P} \cdot \vec{Q} = g_{ij}P_i Q_j,\]

where $g_{ij}$ is the metric tensor. Quantitatively, it follows as $g_{ij} = C_{ki}C_{kj}$ where $C_{ij} = a_{j,i}$ is the matrix of basis vectors $\{\vec{a}_i}\}$. Thus, the components of the metric tensor are

\[g_{ij} = a_{i,k}a_{j,k} = \vec{a}_i \cdot \vec{a}_j.\]

LinearAlgebra.dot(Pvec, Qvec, ::AbstractCrystalGeometer, ::AbstractVectorBasis)

Compute the scalar dot product between two vectors Pvec and Qvec, both measured in a particular AbstractVectorBasis. Use the AbstractCrystalGeometer to determine the metric tensor, $g_{ij}$, such that

\[\vec{P} \cdot \vec{Q} = g_{ij}P_i Q_j.\]

LinearAlgebra.norm(Pvec, ::AbstractCrystalGeometer, ::AbstractVectorBasis)

Compute the vector norm of Pvec, measured in the given AbstractVectorBasis, using the metric tensor. This [norm] is simply the square-root of the dot product of Pvec with itself.