From a3f2d79524741752c61d356884c69c6b9445bfec Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Fri, 18 Oct 2024 14:52:28 +0000 Subject: [PATCH] build based on 3491851 --- previews/PR49/.documenter-siteinfo.json | 2 +- previews/PR49/api/index.html | 100 ++++++++++++------------ previews/PR49/bandreps/index.html | 4 +- previews/PR49/bravais/index.html | 20 ++--- previews/PR49/groups/index.html | 2 +- previews/PR49/index.html | 2 +- previews/PR49/internal-api/index.html | 30 +++---- previews/PR49/irreps/index.html | 2 +- previews/PR49/lattices/index.html | 10 +-- previews/PR49/operations/index.html | 2 +- previews/PR49/search_index.js | 2 +- 11 files changed, 88 insertions(+), 88 deletions(-) diff --git a/previews/PR49/.documenter-siteinfo.json b/previews/PR49/.documenter-siteinfo.json index 88f7cc6b..c578c936 100644 --- a/previews/PR49/.documenter-siteinfo.json +++ b/previews/PR49/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-10-18T14:39:06","documenter_version":"1.7.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-10-18T14:52:14","documenter_version":"1.7.0"}} \ No newline at end of file diff --git a/previews/PR49/api/index.html b/previews/PR49/api/index.html index 3956708a..83dac719 100644 --- a/previews/PR49/api/index.html +++ b/previews/PR49/api/index.html @@ -1,5 +1,5 @@ -API · Crystalline.jl

Public API

Exported types

Crystalline.BandRep — Type
struct BandRep <: AbstractVector{Int64}

  • wyckpos::String

  • sitesym::String

  • label::String

  • dim::Int64

  • spinful::Bool

  • irvec::Vector{Int64}

  • irlabs::Vector{String}

source
Crystalline.BandRepSet — Type
struct BandRepSet <: AbstractVector{BandRep}

  • sgnum::Int64

  • bandreps::Vector{BandRep}

  • kvs::Vector{<:KVec}

  • klabs::Vector{String}

  • irlabs::Vector{String}

  • spinful::Bool

  • timereversal::Bool

source
Crystalline.CharacterTable — Type
struct CharacterTable{D} <: Crystalline.AbstractCharacterTable

  • ops::Array{SymOperation{D}, 1} where D

  • irlabs::Vector{String}

  • table::Matrix{ComplexF64}

  • tag::String

source
Crystalline.Collection — Type
Collection{T} <: AbstractVector{T}

A wrapper around a Vector{T}, that allows custom printing and dispatch rules of custom T (e.g., AbstractIrrep & NewBandRep).

In Crystalline, it is assumed that all elements of the wrapped vector are associated with the same space or point group. Accordingly, if T implements dim or num, either must return the same value for each element of the Collection (and is equal to dim(::Collection) and num(::Collection)).

source
Crystalline.CompositeBandRep — Type

CompositeBandRep{D} <: AbstractSymmetryVector{D}

A type representing a linear rational-coefficient combination of NewBandRep{D}s.

Although the coefficients may be rational numbers in general, their superposition must correspond to integer-valued irrep multiplicities and band occupation numbers; in particular, if they do not, conversion to a SymmetryVector will error.

See also CompositeBandRep_from_indices for construction from a vector included indices into brs.

Fields

  • coefs::Vector{Rational{Int}}: a coefficient vector associated with each band representation in brs; the coefficient of the ith band representation brs[i] is coefs[i].
  • brs::Collection{NewBandRep{D}}: the band representations referenced by coefs.

Example

Fragile symmetry vector

As a first example, we build a CompositeBandRep representing a fragilely topological configuration (i.e., featuring negative integer coefficients):

julia> brs = calc_bandreps(2);
+API · Crystalline.jl
Public API
Exported types
Crystalline.BandRep — Type
struct BandRep <: AbstractVector{Int64}
  • wyckpos::String
  • sitesym::String
  • label::String
  • dim::Int64
  • spinful::Bool
  • irvec::Vector{Int64}
  • irlabs::Vector{String}
source
Crystalline.BandRepSet — Type
struct BandRepSet <: AbstractVector{BandRep}
  • sgnum::Int64
  • bandreps::Vector{BandRep}
  • kvs::Vector{<:KVec}
  • klabs::Vector{String}
  • irlabs::Vector{String}
  • spinful::Bool
  • timereversal::Bool
source
Crystalline.CharacterTable — Type
struct CharacterTable{D} <: Crystalline.AbstractCharacterTable
  • ops::Array{SymOperation{D}, 1} where D
  • irlabs::Vector{String}
  • table::Matrix{ComplexF64}
  • tag::String
source
Crystalline.Collection — Type
Collection{T} <: AbstractVector{T}
A wrapper around a Vector{T}, that allows custom printing and dispatch rules of custom T (e.g., AbstractIrrep & NewBandRep).
In Crystalline, it is assumed that all elements of the wrapped vector are associated with the same space or point group. Accordingly, if T implements dim or  num, either must return the same value for each element of the Collection (and is equal to dim(::Collection) and num(::Collection)).
source
Crystalline.CompositeBandRep — Type
CompositeBandRep{D} <: AbstractSymmetryVector{D}
A type representing a linear rational-coefficient combination of NewBandRep{D}s. 
Although the coefficients may be rational numbers in general, their superposition must correspond to integer-valued irrep multiplicities and band occupation numbers; in particular, if they do not, conversion to a SymmetryVector will error.
See also CompositeBandRep_from_indices for construction from a vector included indices into brs.
Fields
  • coefs::Vector{Rational{Int}}: a coefficient vector associated with each band representation in brs; the coefficient of the ith band representation brs[i] is coefs[i].
  • brs::Collection{NewBandRep{D}}: the band representations referenced by coefs.
Example
Fragile symmetry vector
As a first example, we build a CompositeBandRep representing a fragilely topological configuration (i.e., featuring negative integer coefficients):
julia> brs = calc_bandreps(2);
 
 julia> coefs = [0, 0, 1, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, -1];
 
@@ -16,21 +16,21 @@
 
 julia> SymmetryVector(cbr)
 16-irrep SymmetryVector{3}:
- [Z₁⁺, Y₁⁻, U₁⁻, X₁⁻, T₁⁻, Γ₁⁻, V₁⁻, R₁⁻] (1 band)
source
Crystalline.KVec — Method
KVec{D}(str::AbstractString) --> KVec{D}
+ [Z₁⁺, Y₁⁻, U₁⁻, X₁⁻, T₁⁻, Γ₁⁻, V₁⁻, R₁⁻] (1 band)
source
Crystalline.KVec — Method
KVec{D}(str::AbstractString) --> KVec{D}
 KVec(str::AbstractString)    --> KVec
 KVec(::AbstractVector, ::AbstractMatrix) --> KVec
Return a KVec by parsing the string representations str, supplied in one of the following formats:
"($1,$2,$3)"
 "[$1,$2,$3]"
 "$1,$2,$3"
where the coordinates $1,$2, and $3 are strings that may contain fractions, decimal numbers, and "free" parameters {'α','β','γ'} (or, alternatively and equivalently, {'u','v','w'} or {'x','y','z'}).
Fractions such as 1/2 and decimal numbers can be parsed: but use of any other special operator besides / will produce undefined behavior (e.g. do not use *).
Example
julia> KVec("0.25,α,0")
-[1/4, α, 0]
source
Crystalline.LGIrrep — Type
struct LGIrrep{D} <: Crystalline.AbstractIrrep{D}
  • cdml::String
  • g::LittleGroup
  • matrices::Vector{Matrix{ComplexF64}}
  • translations::Vector{Vector{Float64}}
  • reality::Reality
  • iscorep::Bool
source
Crystalline.LittleGroup — Type
struct LittleGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}
  • num::Int64
  • kv::KVec
  • klab::String
  • operations::Array{SymOperation{D}, 1} where D
source
Crystalline.MSpaceGroup — Type
struct MSpaceGroup{D} <: Crystalline.AbstractGroup{D, MSymOperation{D}}
  • num::Tuple{Int64, Int64}
  • operations::Array{MSymOperation{D}, 1} where D
source
Crystalline.ModulatedFourierLattice — Type
ModulatedFourierLattice{D} <: AbstractFourierLattice{D}
A D-dimensional concrete Fourier (plane wave) lattice, derived from  a UnityFourierLattice{D} by scaling and modulating its orbit coefficients  by complex numbers; in general, the coefficients do not have unit norm.
source
Crystalline.MultTable — Method
MultTable(ops::AbstractVector, modτ=true)
Compute the multiplication (or Cayley) table of ops, an iterable of SymOperations.
A MultTable is returned, which contains symmetry operations resulting from composition  of row and col operators; the table of indices give the symmetry operators relative to the ordering of ops.
Keyword arguments
  • modτ (default: true): whether composition of operations is taken modulo lattice
vectors (true) or not (false).
source
Crystalline.PGIrrep — Type
struct PGIrrep{D} <: Crystalline.AbstractIrrep{D}
  • cdml::String
  • g::PointGroup
  • matrices::Vector{Matrix{ComplexF64}}
  • reality::Reality
  • iscorep::Bool
source
Crystalline.PointGroup — Type
struct PointGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}
  • num::Int64
  • label::String
  • operations::Array{SymOperation{D}, 1} where D
source
Crystalline.LGIrrep — Type
struct LGIrrep{D} <: Crystalline.AbstractIrrep{D}
  • cdml::String
  • g::LittleGroup
  • matrices::Vector{Matrix{ComplexF64}}
  • translations::Vector{Vector{Float64}}
  • reality::Reality
  • iscorep::Bool
source
Crystalline.LittleGroup — Type
struct LittleGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}
  • num::Int64
  • kv::KVec
  • klab::String
  • operations::Array{SymOperation{D}, 1} where D
source
Crystalline.MSpaceGroup — Type
struct MSpaceGroup{D} <: Crystalline.AbstractGroup{D, MSymOperation{D}}
  • num::Tuple{Int64, Int64}
  • operations::Array{MSymOperation{D}, 1} where D
source
Crystalline.ModulatedFourierLattice — Type
ModulatedFourierLattice{D} <: AbstractFourierLattice{D}
A D-dimensional concrete Fourier (plane wave) lattice, derived from  a UnityFourierLattice{D} by scaling and modulating its orbit coefficients  by complex numbers; in general, the coefficients do not have unit norm.
source
Crystalline.MultTable — Method
MultTable(ops::AbstractVector, modτ=true)
Compute the multiplication (or Cayley) table of ops, an iterable of SymOperations.
A MultTable is returned, which contains symmetry operations resulting from composition  of row and col operators; the table of indices give the symmetry operators relative to the ordering of ops.
Keyword arguments
  • modτ (default: true): whether composition of operations is taken modulo lattice
vectors (true) or not (false).
source
Crystalline.PGIrrep — Type
struct PGIrrep{D} <: Crystalline.AbstractIrrep{D}
  • cdml::String
  • g::PointGroup
  • matrices::Vector{Matrix{ComplexF64}}
  • reality::Reality
  • iscorep::Bool
source
Crystalline.PointGroup — Type
struct PointGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}
  • num::Int64
  • label::String
  • operations::Array{SymOperation{D}, 1} where D
source
Crystalline.RVec — Method
RVec{D}(str::AbstractString) --> RVec{D}
 RVec(str::AbstractString)    --> RVec
 RVec(::AbstractVector, ::AbstractMatrix) --> RVec
Return a RVec by parsing the string representations str, supplied in one of the following formats:
"($1,$2,$3)"
 "[$1,$2,$3]"
 "$1,$2,$3"
where the coordinates $1,$2, and $3 are strings that may contain fractions, decimal numbers, and "free" parameters {'α','β','γ'} (or, alternatively and equivalently, {'u','v','w'} or {'x','y','z'}).
Fractions such as 1/2 and decimal numbers can be parsed: but use of any other special operator besides / will produce undefined behavior (e.g. do not use *).
Example
julia> RVec("0.25,α,0")
-[1/4, α, 0]
source
Crystalline.SiteGroup — Type
struct SiteGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}
  • num::Int64
  • wp::WyckoffPosition
  • operations::Array{SymOperation{D}, 1} where D
  • cosets::Array{SymOperation{D}, 1} where D
source
Crystalline.SiteIrrep — Type
struct SiteIrrep{D} <: Crystalline.AbstractIrrep{D}
  • cdml::String
  • g::SiteGroup
  • matrices::Vector{Matrix{ComplexF64}}
  • reality::Reality
  • iscorep::Bool
  • pglabel::String
source
Crystalline.SpaceGroup — Type
struct SpaceGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}
  • num::Int64
  • operations::Array{SymOperation{D}, 1} where D
source
Crystalline.SubperiodicGroup — Type
struct SubperiodicGroup{D, P} <: Crystalline.AbstractGroup{D, SymOperation{D}}
  • num::Int64
  • operations::Array{SymOperation{D}, 1} where D
A subperiodic group of embedding dimension D and periodicity dimension P. 
Fields: 
  • operations: the SymOperations of the finite factor group $G/T$, where $G$ is the
subperiodic group and $T$ is the translation group of the associated lattice.
  • num: the canonical number of the group, following the International Tables for
Crystallography, Volume E.
source
Crystalline.SymOperation — Type
struct SymOperation{D} <: Crystalline.AbstractOperation{D}
  • rotation::Crystalline.SquareStaticMatrices.SqSMatrix{D, Float64} where D
  • translation::StaticArraysCore.SVector{D, Float64} where D
source
Crystalline.SymmetryVector — Method
SymmetryVector(n::AbstractSymmetryVector) -> SymmetryVector
Return a SymmetryVector realization of n. If n is already a SymmetryVector, return n directly; usually, the returned value will directly reference information in n (i.e., will not be a copy).
source
Exported methods
Base.inv — Method
inv(op::SymOperation{D}) --> SymOperation{D}
Compute the inverse {W|w}⁻¹ ≡ {W⁻¹|-W⁻¹w} of an operator op ≡ {W|w}.
source
Crystalline.SiteGroup — Type
struct SiteGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}
  • num::Int64
  • wp::WyckoffPosition
  • operations::Array{SymOperation{D}, 1} where D
  • cosets::Array{SymOperation{D}, 1} where D
source
Crystalline.SiteIrrep — Type
struct SiteIrrep{D} <: Crystalline.AbstractIrrep{D}
  • cdml::String
  • g::SiteGroup
  • matrices::Vector{Matrix{ComplexF64}}
  • reality::Reality
  • iscorep::Bool
  • pglabel::String
source
Crystalline.SpaceGroup — Type
struct SpaceGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}
  • num::Int64
  • operations::Array{SymOperation{D}, 1} where D
source
Crystalline.SubperiodicGroup — Type
struct SubperiodicGroup{D, P} <: Crystalline.AbstractGroup{D, SymOperation{D}}
  • num::Int64
  • operations::Array{SymOperation{D}, 1} where D
A subperiodic group of embedding dimension D and periodicity dimension P. 
Fields: 
  • operations: the SymOperations of the finite factor group $G/T$, where $G$ is the
subperiodic group and $T$ is the translation group of the associated lattice.
  • num: the canonical number of the group, following the International Tables for
Crystallography, Volume E.
source
Crystalline.SymOperation — Type
struct SymOperation{D} <: Crystalline.AbstractOperation{D}
  • rotation::Crystalline.SquareStaticMatrices.SqSMatrix{D, Float64} where D
  • translation::StaticArraysCore.SVector{D, Float64} where D
source
Crystalline.SymmetryVector — Method
SymmetryVector(n::AbstractSymmetryVector) -> SymmetryVector
Return a SymmetryVector realization of n. If n is already a SymmetryVector, return n directly; usually, the returned value will directly reference information in n (i.e., will not be a copy).
source
Exported methods
Base.inv — Method
inv(op::SymOperation{D}) --> SymOperation{D}
Compute the inverse {W|w}⁻¹ ≡ {W⁻¹|-W⁻¹w} of an operator op ≡ {W|w}.
source
Base.isapprox — Method
isapprox(v1::T, v2::T, 
          [cntr::Union{Char, Nothing, AbstractMatrix{<:Real}}, modw::Bool];
-         kwargs...) --> Bool
Compute approximate equality of two vector quantities v1 and v2 of type, T = Union{<:AbstractVec, <:AbstractPoint}. 
If modw = true, equivalence is considered modulo lattice vectors. If v1 and v2 are in the conventional setting of a non-primitive lattice, the centering type cntr (see Bravais.centering) should be given to ensure that the relevant (primitive) lattice vectors are used in the comparison.
Optional arguments
  • cntr: if not provided, the comparison will not account for equivalence by primitive lattice vectors (equivalent to setting cntr=nothing), only equivalence by lattice vectors in the basis of v1 and v2. cntr may also be provided as a D×D AbstractMatrix to give the relevant transformation matrix directly.
  • modw: whether vectors that differ by multiples of a lattice vector are considered equivalent.
  • kwargs...: optional keyword arguments (e.g., atol and rtol) to be forwarded to Base.isapprox.
source
Base.position — Method
position(x::Union{AbstractGroup, AbstractIrrep})
If a position is associated with x, return it; if no position is associated, return nothing.
Applicable cases include LittleGroup (return the associated k-vector) and SiteGroup (returns the associated Wyckoff position), as well as their associated irrep types (LGIrrep and SiteIrrep).
source
Bravais.cartesianize — Method
cartesianize(op::SymOperation{D}, Rs::DirectBasis{D}) --> SymOperation{D}
Converts opˡ from a lattice basis to a Cartesian basis, by computing the transformed operators opᶜ = 𝐑*opˡ*𝐑⁻¹ via the Cartesian basis matrix 𝐑 (whose columns are the DirectBasis vectors Rs[i]). 
Note 1
The matrix 𝐑 maps vectors coefficients in a lattice basis 𝐯ˡ to coefficients in a Cartesian basis 𝐯ᶜ as 𝐯ˡ = 𝐑⁻¹𝐯ᶜ and vice versa as 𝐯ᶜ = 𝐑𝐯ˡ. Since a general transformation P  transforms an "original" vectors with coefficients 𝐯 to new coefficients 𝐯′ via 𝐯′ = P⁻¹𝐯 and since we here here consider the lattice basis as the "original" basis we have P = 𝐑⁻¹.  As such, the transformation of the operator op transforms as opᶜ = P⁻¹*opˡ*P, i.e. opᶜ = transform(opˡ,P) = transform(opˡ,𝐑⁻¹).
Note 2
The display (e.g. Seitz and xyzt notation) of SymOperations e.g. in the REPL implicitly assumes integer coefficients for its point-group matrix: as a consequence, displaying  SymOperations in a Cartesian basis may produce undefined behavior. The matrix representation remains valid, however.
source
Bravais.centering — Method
centering(g::AbstractGroup) --> Char
Return the conventional centering type of a group. 
For groups without lattice structure (e.g., point groups), return nothing.
source
Bravais.conventionalize — Method
conventionalize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat′)
Given flat referred to a primitive basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated conventional basis. 
See also the complementary method primitivize(::AbstractFourierLattice, ::Char) for additional details.
source
Bravais.conventionalize — Method
conventionalize(v′::AbstractVec, cntr::Char)  -->  v::typeof(v′)
Transforms a primitive coordinate vector v′ back to a standard conventional basis (specified by the centering type cntr), returning the conventional coordinate vector v.
See also primitivize and transform.
source
Bravais.conventionalize — Method
conventionalize(op′::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)
Return a symmetry operation op $= \{W|w\}$ in a conventional setting, transformed from an input symmetry operation op′ $≡ \{W'|w'\}$ in a primitive setting.
See primitivize(::SymOperation, ::Char, ::Bool) for description of the centering argument cntr and optional argument modw.
source
Bravais.primitivize — Method
primitivize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat)
Given flat referred to a conventional basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated primitive basis. 
Specifically, if flat refers to a direct conventional basis Rs $≡ (\mathbf{a} \mathbf{b} \mathbf{c})$ [with coordinate vectors $\mathbf{r} ≡ (r_1, r_2, r_3)^{\mathrm{T}}$] then flat′ refers to a direct primitive basis Rs′ $≡ (\mathbf{a}' \mathbf{b}' \mathbf{c}') ≡ (\mathbf{a} \mathbf{b} \mathbf{c})\mathbf{P}$ [with coordinate vectors  $\mathbf{r}' ≡ (r_1', r_2', r_3')^{\mathrm{T}} = \mathbf{P}^{-1}\mathbf{r}$], where $\mathbf{P}$ denotes the basis-change matrix obtained from primitivebasismatrix(...).
To compute the associated primitive basis vectors, see primitivize(::DirectBasis, ::Char) [specifically, Rs′ = primitivize(Rs, cntr)].
Examples
A centered ('c') lattice from plane group 5 in 2D, plotted in its  conventional and primitive basis (requires using PyPlot):
julia> sgnum = 5; D = 2; cntr = centering(sgnum, D)  # 'c' (body-centered)
+         kwargs...) --> Bool
Compute approximate equality of two vector quantities v1 and v2 of type, T = Union{<:AbstractVec, <:AbstractPoint}. 
If modw = true, equivalence is considered modulo lattice vectors. If v1 and v2 are in the conventional setting of a non-primitive lattice, the centering type cntr (see Bravais.centering) should be given to ensure that the relevant (primitive) lattice vectors are used in the comparison.
Optional arguments
  • cntr: if not provided, the comparison will not account for equivalence by primitive lattice vectors (equivalent to setting cntr=nothing), only equivalence by lattice vectors in the basis of v1 and v2. cntr may also be provided as a D×D AbstractMatrix to give the relevant transformation matrix directly.
  • modw: whether vectors that differ by multiples of a lattice vector are considered equivalent.
  • kwargs...: optional keyword arguments (e.g., atol and rtol) to be forwarded to Base.isapprox.
source
Base.position — Method
position(x::Union{AbstractGroup, AbstractIrrep})
If a position is associated with x, return it; if no position is associated, return nothing.
Applicable cases include LittleGroup (return the associated k-vector) and SiteGroup (returns the associated Wyckoff position), as well as their associated irrep types (LGIrrep and SiteIrrep).
source
Bravais.cartesianize — Method
cartesianize(op::SymOperation{D}, Rs::DirectBasis{D}) --> SymOperation{D}
Converts opˡ from a lattice basis to a Cartesian basis, by computing the transformed operators opᶜ = 𝐑*opˡ*𝐑⁻¹ via the Cartesian basis matrix 𝐑 (whose columns are the DirectBasis vectors Rs[i]). 
Note 1
The matrix 𝐑 maps vectors coefficients in a lattice basis 𝐯ˡ to coefficients in a Cartesian basis 𝐯ᶜ as 𝐯ˡ = 𝐑⁻¹𝐯ᶜ and vice versa as 𝐯ᶜ = 𝐑𝐯ˡ. Since a general transformation P  transforms an "original" vectors with coefficients 𝐯 to new coefficients 𝐯′ via 𝐯′ = P⁻¹𝐯 and since we here here consider the lattice basis as the "original" basis we have P = 𝐑⁻¹.  As such, the transformation of the operator op transforms as opᶜ = P⁻¹*opˡ*P, i.e. opᶜ = transform(opˡ,P) = transform(opˡ,𝐑⁻¹).
Note 2
The display (e.g. Seitz and xyzt notation) of SymOperations e.g. in the REPL implicitly assumes integer coefficients for its point-group matrix: as a consequence, displaying  SymOperations in a Cartesian basis may produce undefined behavior. The matrix representation remains valid, however.
source
Bravais.centering — Method
centering(g::AbstractGroup) --> Char
Return the conventional centering type of a group. 
For groups without lattice structure (e.g., point groups), return nothing.
source
Bravais.conventionalize — Method
conventionalize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat′)
Given flat referred to a primitive basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated conventional basis. 
See also the complementary method primitivize(::AbstractFourierLattice, ::Char) for additional details.
source
Bravais.conventionalize — Method
conventionalize(v′::AbstractVec, cntr::Char)  -->  v::typeof(v′)
Transforms a primitive coordinate vector v′ back to a standard conventional basis (specified by the centering type cntr), returning the conventional coordinate vector v.
See also primitivize and transform.
source
Bravais.conventionalize — Method
conventionalize(op′::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)
Return a symmetry operation op $= \{W|w\}$ in a conventional setting, transformed from an input symmetry operation op′ $≡ \{W'|w'\}$ in a primitive setting.
See primitivize(::SymOperation, ::Char, ::Bool) for description of the centering argument cntr and optional argument modw.
source
Bravais.primitivize — Method
primitivize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat)
Given flat referred to a conventional basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated primitive basis. 
Specifically, if flat refers to a direct conventional basis Rs $≡ (\mathbf{a} \mathbf{b} \mathbf{c})$ [with coordinate vectors $\mathbf{r} ≡ (r_1, r_2, r_3)^{\mathrm{T}}$] then flat′ refers to a direct primitive basis Rs′ $≡ (\mathbf{a}' \mathbf{b}' \mathbf{c}') ≡ (\mathbf{a} \mathbf{b} \mathbf{c})\mathbf{P}$ [with coordinate vectors  $\mathbf{r}' ≡ (r_1', r_2', r_3')^{\mathrm{T}} = \mathbf{P}^{-1}\mathbf{r}$], where $\mathbf{P}$ denotes the basis-change matrix obtained from primitivebasismatrix(...).
To compute the associated primitive basis vectors, see primitivize(::DirectBasis, ::Char) [specifically, Rs′ = primitivize(Rs, cntr)].
Examples
A centered ('c') lattice from plane group 5 in 2D, plotted in its  conventional and primitive basis (requires using PyPlot):
julia> sgnum = 5; D = 2; cntr = centering(sgnum, D)  # 'c' (body-centered)
 
 julia> Rs   = directbasis(sgnum, Val(D))     # conventional basis (rectangular)
 julia> flat = levelsetlattice(sgnum, Val(D)) # Fourier lattice in basis of Rs
@@ -41,19 +41,19 @@
 julia> flat′ = primitivize(flat, cntr)  # Fourier lattice in basis of Rs′
 
 julia> using PyPlot
-julia> plot(flat′, Rs′)
source
Bravais.primitivize — Method
primitivize(v::AbstractVec, cntr::Char)  -->  v′::typeof(v)
Transforms a conventional coordinate vector v to a standard primitive basis (specified by the centering type cntr), returning the primitive coordinate vector v′.
Note that a basis change matrix $\mathbf{P}$ (as returned e.g. by Bravais.primitivebasismatrix) transforms direct coordinate vectors (RVec) as $\mathbf{r}' = \mathbf{P}^{-1}\mathbf{r}$ but transforms reciprocal coordinates (KVec) as $\mathbf{k}' = \mathbf{P}^{\text{T}}\mathbf{k}$ [ITA6]. Recall also the distinction between transforming a basis and the coordinates of a vector.
source
Bravais.primitivize — Method
primitivize(op::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)
Return a symmetry operation op′ $≡ \{W'|w'\}$ in a primitive setting, transformed from an input symmetry operation op $= \{W|w\}$ in a conventional setting. The operations $\{W'|w'\}$ and $\{W|w\}$ are related by a transformation $\{P|p\}$ via (cf. Section 1.5.2.3 of [ITA6]):
\[\{W'|w'\} = \{P|p\}⁻¹\{W|w\}\{P|p\}.\]
where $P$ and $p$ are the basis change matrix and origin shifts, respectively. The relevant transformation $\{P|p\}$ is inferred from the centering type, as provided by cntr (see also Bravais.centering).
By default, translation parts of op′, i.e. $w'$ are reduced modulo 1 (modw = true); to disable this, set modw = false.
source
Bravais.transform — Method
transform(v::AbstractVec, P::AbstractMatrix)  -->  v′::typeof(v)
Return a transformed coordinate vector v′ from an original coordinate vector v using a basis change matrix P.
Note that a basis change matrix $\mathbf{P}$ transforms direct coordinate vectors (RVec) as $\mathbf{r}' = \mathbf{P}^{-1}\mathbf{r}$ but transforms reciprocal coordinates (KVec) as $\mathbf{k}' = \mathbf{P}^{\mathrm{T}}\mathbf{k}$ [ITA6]
source
Bravais.transform — Method
transform(op::SymOperation, P::AbstractMatrix{<:Real}, 
+julia> plot(flat′, Rs′)
source
Bravais.primitivize — Method
primitivize(v::AbstractVec, cntr::Char)  -->  v′::typeof(v)
Transforms a conventional coordinate vector v to a standard primitive basis (specified by the centering type cntr), returning the primitive coordinate vector v′.
Note that a basis change matrix $\mathbf{P}$ (as returned e.g. by Bravais.primitivebasismatrix) transforms direct coordinate vectors (RVec) as $\mathbf{r}' = \mathbf{P}^{-1}\mathbf{r}$ but transforms reciprocal coordinates (KVec) as $\mathbf{k}' = \mathbf{P}^{\text{T}}\mathbf{k}$ [ITA6]. Recall also the distinction between transforming a basis and the coordinates of a vector.
source
Bravais.primitivize — Method
primitivize(op::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)
Return a symmetry operation op′ $≡ \{W'|w'\}$ in a primitive setting, transformed from an input symmetry operation op $= \{W|w\}$ in a conventional setting. The operations $\{W'|w'\}$ and $\{W|w\}$ are related by a transformation $\{P|p\}$ via (cf. Section 1.5.2.3 of [ITA6]):
\[\{W'|w'\} = \{P|p\}⁻¹\{W|w\}\{P|p\}.\]
where $P$ and $p$ are the basis change matrix and origin shifts, respectively. The relevant transformation $\{P|p\}$ is inferred from the centering type, as provided by cntr (see also Bravais.centering).
By default, translation parts of op′, i.e. $w'$ are reduced modulo 1 (modw = true); to disable this, set modw = false.
source
Bravais.transform — Method
transform(v::AbstractVec, P::AbstractMatrix)  -->  v′::typeof(v)
Return a transformed coordinate vector v′ from an original coordinate vector v using a basis change matrix P.
Note that a basis change matrix $\mathbf{P}$ transforms direct coordinate vectors (RVec) as $\mathbf{r}' = \mathbf{P}^{-1}\mathbf{r}$ but transforms reciprocal coordinates (KVec) as $\mathbf{k}' = \mathbf{P}^{\mathrm{T}}\mathbf{k}$ [ITA6]
source
Bravais.transform — Method
transform(op::SymOperation, P::AbstractMatrix{<:Real}, 
           p::Union{AbstractVector{<:Real}, Nothing}=nothing,
           modw::Bool=true)                           --> SymOperation
Transforms a op $= \{\mathbf{W}|\mathbf{w}\}$ by a rotation matrix P and a translation vector p (can be nothing for zero-translations), producing a new symmetry operation  op′ $= \{\mathbf{W}'|\mathbf{w}'\}$ (cf. Section 1.5.2.3 of [ITA6])
\[\{\mathbf{W}'|\mathbf{w}'\} = \{\mathbf{P}|\mathbf{p}\}^{-1}\{\mathbf{W}|\mathbf{w}\}
 \{\mathbf{P}|\mathbf{p}\}\]
with
\[\mathbf{W}' = \mathbf{P}^{-1}\mathbf{W}\mathbf{P}
 \text{ and }
-\mathbf{w}' = \mathbf{P}^{-1}(\mathbf{w}+\mathbf{W}\mathbf{p}-\mathbf{p})\]
By default, the translation part of op′, i.e. $\mathbf{w}'$, is reduced to the range $[0,1)$, i.e. computed modulo 1. This can be disabled by setting modw = false (default, modw = true).
See also Bravais.primitivize(::SymOperation, ::Char, ::Bool) and Bravais.conventionalize(::SymOperation, ::Char, ::Bool).
source
Crystalline.:⊕ — Method
⊕(ir1::T, ir2::T, ir3::T...) where T<:AbstractIrrep --> T
Compute the representation obtained from direct sum of the irreps ir1, ir2, ir3, etc. The resulting representation is reducible and has dimension irdim(ir1) + irdim(ir2) + irdim(ir3) + ….
The groups of the provided irreps must be identical. If T isa LGIrrep, the irrep translation factors must also be identical (due to an implementation detail of the LGIrrep type).
Also provided via Base.:+.
source
Crystalline.bandreps — Function
bandreps(sgnum::Integer, D::Integer=3; 
-         allpaths::Bool=false, spinful::Bool=false, timereversal::Bool=true)
Returns the elementary band representations (EBRs) as a BandRepSet for space group sgnum and dimension D.
Keyword arguments
  • allpaths: include a minimal sufficient set (false, default) or all (true)              k-vectors. 
  • spinful: single- (false, default) or double-valued (true) irreps, as appropriate for            spinless and spinful particles, respectively. Only available for D=3.
  • timereversal: assume presence (true, default) or absence (false) of time-reversal                 symmetry.
References
3D EBRs are obtained from the Bilbao Crystallographic Server's  BANDREP program; please reference the original research papers noted there if used in published work.
source
Crystalline.basisdim — Method
basisdim(brs::BandRepSet) --> Int
Return the dimension of the (linearly independent parts) of a band representation set. This is $d^{\text{bs}} = d^{\text{ai}}$ in the notation of Po, Watanabe, & Vishwanath, Nature Commun. 8, 50 (2017), or  equivalently, the rank of stack(brs) over the ring of integers. This is the number of linearly independent basis vectors that span the expansions of a band structure viewed as symmetry data.
source
Crystalline.:⊕ — Method
⊕(ir1::T, ir2::T, ir3::T...) where T<:AbstractIrrep --> T
Compute the representation obtained from direct sum of the irreps ir1, ir2, ir3, etc. The resulting representation is reducible and has dimension irdim(ir1) + irdim(ir2) + irdim(ir3) + ….
The groups of the provided irreps must be identical. If T isa LGIrrep, the irrep translation factors must also be identical (due to an implementation detail of the LGIrrep type).
Also provided via Base.:+.
source
Crystalline.bandreps — Function
bandreps(sgnum::Integer, D::Integer=3; 
+         allpaths::Bool=false, spinful::Bool=false, timereversal::Bool=true)
Returns the elementary band representations (EBRs) as a BandRepSet for space group sgnum and dimension D.
Keyword arguments
  • allpaths: include a minimal sufficient set (false, default) or all (true)              k-vectors. 
  • spinful: single- (false, default) or double-valued (true) irreps, as appropriate for            spinless and spinful particles, respectively. Only available for D=3.
  • timereversal: assume presence (true, default) or absence (false) of time-reversal                 symmetry.
References
3D EBRs are obtained from the Bilbao Crystallographic Server's  BANDREP program; please reference the original research papers noted there if used in published work.
source
Crystalline.basisdim — Method
basisdim(brs::BandRepSet) --> Int
Return the dimension of the (linearly independent parts) of a band representation set. This is $d^{\text{bs}} = d^{\text{ai}}$ in the notation of Po, Watanabe, & Vishwanath, Nature Commun. 8, 50 (2017), or  equivalently, the rank of stack(brs) over the ring of integers. This is the number of linearly independent basis vectors that span the expansions of a band structure viewed as symmetry data.
source
Crystalline.calc_bandreps — Method
calc_bandreps(sgnum::Integer, Dᵛ::Val{D}=Val(3);
               timereversal::Bool=true,
-              allpaths::Bool=false)
Compute the band representations of space group sgnum in dimension D, returning a BandRepSet.
Keyword arguments
  • timereversal (default, true): whether the irreps used to induce the band representations are assumed to be time-reversal invariant (i.e., are coreps, see  realify).
  • allpaths (default, false): whether the band representations are projected to all distinct k-points returned by lgirreps (allpaths = false), including high-symmetry k-lines and -plane, or only to the maximal k-points (allpaths = true), i.e., just to high-symmetry points.
Notes
All band representations associated with maximal Wyckoff positions are returned,  irregardless of whether they are elementary (i.e., no regard is made to whether the band representation is "composite"). As such, the returned band representations generally are a superset of the set of elementary band representations (and so contain all elementary band representations).
Implementation
The implementation is based on Cano, Bradlyn, Wang, Elcoro, et al., Phys. Rev. B 97, 035139 (2018), Sections II.C-D.
source
Crystalline.calc_reality — Method
calc_reality(lgir::LGIrrep, 
+              allpaths::Bool=false)
Compute the band representations of space group sgnum in dimension D, returning a BandRepSet.
Keyword arguments
  • timereversal (default, true): whether the irreps used to induce the band representations are assumed to be time-reversal invariant (i.e., are coreps, see  realify).
  • allpaths (default, false): whether the band representations are projected to all distinct k-points returned by lgirreps (allpaths = false), including high-symmetry k-lines and -plane, or only to the maximal k-points (allpaths = true), i.e., just to high-symmetry points.
Notes
All band representations associated with maximal Wyckoff positions are returned,  irregardless of whether they are elementary (i.e., no regard is made to whether the band representation is "composite"). As such, the returned band representations generally are a superset of the set of elementary band representations (and so contain all elementary band representations).
Implementation
The implementation is based on Cano, Bradlyn, Wang, Elcoro, et al., Phys. Rev. B 97, 035139 (2018), Sections II.C-D.
source
Crystalline.calc_reality — Method
calc_reality(lgir::LGIrrep, 
              sgops::AbstractVector{SymOperation{D}},
-             αβγ::Union{Vector{<:Real},Nothing}=nothing) --> ::(Enum Reality)
Compute and return the reality of a lgir::LGIrrep using the Herring criterion.
The computed value is one of three integers in ${1,-1,0}$. In practice, this value is returned via a member of the Enum Reality, which has instances REAL = 1, PSEUDOREAL = -1, and COMPLEX = 0.
Optional arguments
As a sanity check, a value of αβγ can be provided to check for invariance along a symmetry symmetry line/plane/general point in k-space. The reality must be invariant to this choice.
Note
The provided space group operations sgops must be the set reduced by primitive translation vectors; i.e. using spacegroup(...) directly is not allowable in general (since the irreps we reference only include these "reduced" operations). This reduced set of operations can be obtained e.g. from the Γ point irreps of ISOTROPY's dataset, or alternatively, from reduce_ops(spacegroup(...), true).
Implementation
The Herring criterion evaluates the following sum
$[∑ χ({β|b}²)]/[g_0/M(k)]$
over symmetry operations ${β|b}$ that take $k → -k$. Here $g_0$ is the order of the point group of the space group and $M(k)$ is the order of star($k$) [both in a primitive basis].
See e.g. Cornwell, p. 150-152 & 187-188 (which we mainly followed), Inui Eq. (13.48),  Dresselhaus, p. 618, or Herring's original paper.
source
Crystalline.characters — Method
characters(irs::AbstractVector{<:AbstractIrrep}, αβγ=nothing)
Compute the character table associated with vector of AbstractIrreps irs, returning a CharacterTable.
Optional arguments
Optionally, an αβγ::AbstractVector{<:Real} variable can be passed to evaluate the irrep (and associated characters) with concrete free parameters (e.g., for LGIrreps, a concrete k-vector sampled from a "line-irrep"). Defaults to nothing, indicating it being either  irrelevant (e.g., for PGIrreps) or all free parameters implicitly set to zero.
source
Crystalline.classcharacters — Method
classcharacters(irs::AbstractVector{<:AbstractIrrep}, αβγ=nothing)
Compute the character table associated with the conjugacy classes of a vector of AbstractIrreps irs, returning a ClassCharacterTable.
Since characters depend only on the conjugacy class (this is not true for ray, or projective, irreps), the class-specific characters often more succintly communicate the same information as the characters for each operation (as returned by characters).
See also: classes.
Optional arguments
Optionally, an αβγ::AbstractVector{<:Real} variable can be passed to evaluate the irrep (and associated characters) with concrete free parameters (e.g., for LGIrreps, a concrete k-vector sampled from a "line-irrep"). Defaults to nothing, indicating it being either  irrelevant (e.g., for PGIrreps) or all free parameters implicitly set to zero.
source
Crystalline.classes — Method
classes(ops::AbstractVector{SymOperation{D}}, [cntr::Union{Char, Nothing}])
-                                                -->  Vector{Vector{SymOperation{D}}}
Return the conjugacy classes of a group $G$ defined by symmetry operations ops.
Definitions
Two elements $a$ and $b$ in $G$ are considered conjugate if there exists a $g ∈ G$ such that $gag^{-1} = b$. This defines an equivalence relation $\sim$, i.e., we say that $a \sim b$ if $a$ and $b$ are conjugate. The conjugacy classes of $G$ are the distinct equivalence classes that can be identified under this equivalence relation, i.e. the grouping of $G$ into subsets that are equivalent under conjugacy.
Extended help
If ops describe operations in a crystal system that is not primitive (i.e., if its centering type is not p or P) but is presented in a conventional setting, the centering symbol cntr must be given. If ops is not in a centered crystal system, or if ops is already reduced to a primitive setting, cntr should be given as nothing (default behavior) or, alternatively, as P or p (depending on dimensionality).
A single-argument calls to classes with SpaceGroup or LittleGroup types will assume that ops is provided in a conventional setting, i.e., will forward the method call to classes(ops, centering(ops, dim(ops))). To avoid this behavior (if ops was already reduced to a primitive setting prior to calling classes), cntr should be provided explicitly as nothing.
source
Crystalline.classification — Method
classification(brs_or_F::Union{BandRepSet, Smith}) --> String
Return the symmetry indicator group $X^{\text{BS}}$ of an EBR basis F_or_brs, provided as a BandRepSet or Smith decomposition.
Technically, the calculation answers the question "what direct product of  $\mathbb{Z}_n$ groups is the the quotient group $X^{\text{BS}} = \{\text{BS}\}/\{\text{AI}\}$ isomorphic to?" (see Po, Watanabe, & Vishwanath, Nature Commun. 8, 50 (2017) for more information).
source
Crystalline.compose — Method
compose(op::SymOperation, kv::KVec[, checkabc::Bool=true])  -->  KVec
Return the composition op $= \{\mathbf{W}|\mathbf{w}\}$ and a reciprocal-space vector kv $= \mathbf{k}$.
The operation is assumed to be specified the direct lattice basis, and kv in the reciprocal lattice basis. If both were specified in the Cartesian basis, op would act directly via its rotation part. However, because of the different bases, it now acts as:
\[    \mathbf{k}' = (\mathbf{W}^{\text{T}})^{-1}\mathbf{k}.\]
Note the transposition and inverse of $\mathbf{W}$, arising as a result of the implicit real-space basis of $\{\mathbf{W}|\mathbf{w}\}$ versus the reciprocal-space basis of $\mathbf{k}$. Note also that the composition of $\{\mathbf{W}|\mathbf{w}\}$ with $\mathbf{k}$ is invariant under $\mathbf{w}$, i.e., translations do not act in reciprocal space.
Extended help
If checkabc = false, the free part of KVec is not transformed (can be improve  performance in situations when kabc is zero, and several transformations are requested).
source
Crystalline.compose — Method
compose(op::SymOperation, rv::RVec)  -->  RVec
Return the composition of op $= \{\mathbf{W}|\mathbf{w}\}$ and a real-space vector rv $= \mathbf{r}$.
The operation is taken to act directly, returning
\[    \mathbf{r}' = \{\mathbf{W}|\mathbf{w}\}\mathbf{r} = \mathbf{W}\mathbf{r} + \mathbf{w}.\]
The corresponding inverse action $\{\mathbf{W}|\mathbf{w}\}^{-1}\mathbf{r} =  \mathbf{W}^{-1}\mathbf{r} - \mathbf{W}^{-1}\mathbf{w}$ can be obtained via  compose(inv(op), rv).
source
Crystalline.compose — Method
compose(op1::T, op2::T, modτ::Bool=true) where T<:SymOperation
Compose two symmetry operations op1 $= \{W₁|w₁\}$ and op2 $= \{W₂|w₂\}$ using the composition rule (in Seitz notation)
$\{W₁|w₁\}\{W₂|w₂\} = \{W₁W₂|w₁+W₁w₂\}$
By default, the translation part of the $\{W₁W₂|w₁+W₁w₂\}$ is reduced to the range $[0,1[$, i.e. computed modulo 1. This can be toggled off (or on) by the Boolean flag modτ (enabled, i.e. true, by default). Returns another SymOperation.
The multiplication operator * is overloaded for SymOperations to call compose, in the manner op1 * op2 = compose(op1, op2, modτ=true).
source
Crystalline.conjugacy_relations — Method
conjugacy_relations(gr::GroupRelationGraph, sgnumᴳ, sgnumᴴ) --> Vector{<:ConjugacyTransform}
Given a graph gr representing a sub- or supergroup relation, return the possible transformations that make up the conjugacy classes between the groups sgnumᴳ and sgnumᴴ.
The returned transforms bring G into the setting of H via transform(G, P, p), where P and p denote one of the possible conjugacy transforms in the returned vector.  Note that the transforms need not preserve volume: accordingly, some operations may be redundant after transformation (use reduce_ops or unique! to remove these).
source
Crystalline.cosets — Method
cosets(g::SiteGroup) -> Array{SymOperation{D}, 1} where D
-
Return the left coset representatives of a SiteGroup g (in its parent space group).
The cosets generate the orbit of the Wyckoff position position(g) (see also orbit(::SiteGroup)) and furnish a left-coset decomposition of the underlying space group, jointly with the operations in g itself.
See also cosets(::AbstractVector, ::AbstractVector). This method is equivalent (but may return different representatives in general) to cosets(spacegroup(sgnum), g).
source
Crystalline.cosets — Method
cosets(G, H)
For a subgroup H $=H$ of G = $G$, find a set of (left) coset representatives  $\{g_i\}$ of $H$ in $G$, such that (see e.g., Inui et al., Section 2.7)
\[    G = \bigcup_i g_i H.\]
The identity operation $1$ is always included in $\{g_i\}$.
Example
julia> G = pointgroup("6mm");
+             αβγ::Union{Vector{<:Real},Nothing}=nothing) --> ::(Enum Reality)
Compute and return the reality of a lgir::LGIrrep using the Herring criterion.
The computed value is one of three integers in ${1,-1,0}$. In practice, this value is returned via a member of the Enum Reality, which has instances REAL = 1, PSEUDOREAL = -1, and COMPLEX = 0.
Optional arguments
As a sanity check, a value of αβγ can be provided to check for invariance along a symmetry symmetry line/plane/general point in k-space. The reality must be invariant to this choice.
Note
The provided space group operations sgops must be the set reduced by primitive translation vectors; i.e. using spacegroup(...) directly is not allowable in general (since the irreps we reference only include these "reduced" operations). This reduced set of operations can be obtained e.g. from the Γ point irreps of ISOTROPY's dataset, or alternatively, from reduce_ops(spacegroup(...), true).
Implementation
The Herring criterion evaluates the following sum
$[∑ χ({β|b}²)]/[g_0/M(k)]$
over symmetry operations ${β|b}$ that take $k → -k$. Here $g_0$ is the order of the point group of the space group and $M(k)$ is the order of star($k$) [both in a primitive basis].
See e.g. Cornwell, p. 150-152 & 187-188 (which we mainly followed), Inui Eq. (13.48),  Dresselhaus, p. 618, or Herring's original paper.
source
Crystalline.characters — Method
characters(irs::AbstractVector{<:AbstractIrrep}, αβγ=nothing)
Compute the character table associated with vector of AbstractIrreps irs, returning a CharacterTable.
Optional arguments
Optionally, an αβγ::AbstractVector{<:Real} variable can be passed to evaluate the irrep (and associated characters) with concrete free parameters (e.g., for LGIrreps, a concrete k-vector sampled from a "line-irrep"). Defaults to nothing, indicating it being either  irrelevant (e.g., for PGIrreps) or all free parameters implicitly set to zero.
source
Crystalline.classcharacters — Method
classcharacters(irs::AbstractVector{<:AbstractIrrep}, αβγ=nothing)
Compute the character table associated with the conjugacy classes of a vector of AbstractIrreps irs, returning a ClassCharacterTable.
Since characters depend only on the conjugacy class (this is not true for ray, or projective, irreps), the class-specific characters often more succintly communicate the same information as the characters for each operation (as returned by characters).
See also: classes.
Optional arguments
Optionally, an αβγ::AbstractVector{<:Real} variable can be passed to evaluate the irrep (and associated characters) with concrete free parameters (e.g., for LGIrreps, a concrete k-vector sampled from a "line-irrep"). Defaults to nothing, indicating it being either  irrelevant (e.g., for PGIrreps) or all free parameters implicitly set to zero.
source
Crystalline.classes — Method
classes(ops::AbstractVector{SymOperation{D}}, [cntr::Union{Char, Nothing}])
+                                                -->  Vector{Vector{SymOperation{D}}}
Return the conjugacy classes of a group $G$ defined by symmetry operations ops.
Definitions
Two elements $a$ and $b$ in $G$ are considered conjugate if there exists a $g ∈ G$ such that $gag^{-1} = b$. This defines an equivalence relation $\sim$, i.e., we say that $a \sim b$ if $a$ and $b$ are conjugate. The conjugacy classes of $G$ are the distinct equivalence classes that can be identified under this equivalence relation, i.e. the grouping of $G$ into subsets that are equivalent under conjugacy.
Extended help
If ops describe operations in a crystal system that is not primitive (i.e., if its centering type is not p or P) but is presented in a conventional setting, the centering symbol cntr must be given. If ops is not in a centered crystal system, or if ops is already reduced to a primitive setting, cntr should be given as nothing (default behavior) or, alternatively, as P or p (depending on dimensionality).
A single-argument calls to classes with SpaceGroup or LittleGroup types will assume that ops is provided in a conventional setting, i.e., will forward the method call to classes(ops, centering(ops, dim(ops))). To avoid this behavior (if ops was already reduced to a primitive setting prior to calling classes), cntr should be provided explicitly as nothing.
source
Crystalline.classification — Method
classification(brs_or_F::Union{BandRepSet, Smith}) --> String
Return the symmetry indicator group $X^{\text{BS}}$ of an EBR basis F_or_brs, provided as a BandRepSet or Smith decomposition.
Technically, the calculation answers the question "what direct product of  $\mathbb{Z}_n$ groups is the the quotient group $X^{\text{BS}} = \{\text{BS}\}/\{\text{AI}\}$ isomorphic to?" (see Po, Watanabe, & Vishwanath, Nature Commun. 8, 50 (2017) for more information).
source
Crystalline.compose — Method
compose(op::SymOperation, kv::KVec[, checkabc::Bool=true])  -->  KVec
Return the composition op $= \{\mathbf{W}|\mathbf{w}\}$ and a reciprocal-space vector kv $= \mathbf{k}$.
The operation is assumed to be specified the direct lattice basis, and kv in the reciprocal lattice basis. If both were specified in the Cartesian basis, op would act directly via its rotation part. However, because of the different bases, it now acts as:
\[    \mathbf{k}' = (\mathbf{W}^{\text{T}})^{-1}\mathbf{k}.\]
Note the transposition and inverse of $\mathbf{W}$, arising as a result of the implicit real-space basis of $\{\mathbf{W}|\mathbf{w}\}$ versus the reciprocal-space basis of $\mathbf{k}$. Note also that the composition of $\{\mathbf{W}|\mathbf{w}\}$ with $\mathbf{k}$ is invariant under $\mathbf{w}$, i.e., translations do not act in reciprocal space.
Extended help
If checkabc = false, the free part of KVec is not transformed (can be improve  performance in situations when kabc is zero, and several transformations are requested).
source
Crystalline.compose — Method
compose(op::SymOperation, rv::RVec)  -->  RVec
Return the composition of op $= \{\mathbf{W}|\mathbf{w}\}$ and a real-space vector rv $= \mathbf{r}$.
The operation is taken to act directly, returning
\[    \mathbf{r}' = \{\mathbf{W}|\mathbf{w}\}\mathbf{r} = \mathbf{W}\mathbf{r} + \mathbf{w}.\]
The corresponding inverse action $\{\mathbf{W}|\mathbf{w}\}^{-1}\mathbf{r} =  \mathbf{W}^{-1}\mathbf{r} - \mathbf{W}^{-1}\mathbf{w}$ can be obtained via  compose(inv(op), rv).
source
Crystalline.compose — Method
compose(op1::T, op2::T, modτ::Bool=true) where T<:SymOperation
Compose two symmetry operations op1 $= \{W₁|w₁\}$ and op2 $= \{W₂|w₂\}$ using the composition rule (in Seitz notation)
$\{W₁|w₁\}\{W₂|w₂\} = \{W₁W₂|w₁+W₁w₂\}$
By default, the translation part of the $\{W₁W₂|w₁+W₁w₂\}$ is reduced to the range $[0,1[$, i.e. computed modulo 1. This can be toggled off (or on) by the Boolean flag modτ (enabled, i.e. true, by default). Returns another SymOperation.
The multiplication operator * is overloaded for SymOperations to call compose, in the manner op1 * op2 = compose(op1, op2, modτ=true).
source
Crystalline.conjugacy_relations — Method
conjugacy_relations(gr::GroupRelationGraph, sgnumᴳ, sgnumᴴ) --> Vector{<:ConjugacyTransform}
Given a graph gr representing a sub- or supergroup relation, return the possible transformations that make up the conjugacy classes between the groups sgnumᴳ and sgnumᴴ.
The returned transforms bring G into the setting of H via transform(G, P, p), where P and p denote one of the possible conjugacy transforms in the returned vector.  Note that the transforms need not preserve volume: accordingly, some operations may be redundant after transformation (use reduce_ops or unique! to remove these).
source
Crystalline.cosets — Method
cosets(g::SiteGroup) -> Array{SymOperation{D}, 1} where D
+
Return the left coset representatives of a SiteGroup g (in its parent space group).
The cosets generate the orbit of the Wyckoff position position(g) (see also orbit(::SiteGroup)) and furnish a left-coset decomposition of the underlying space group, jointly with the operations in g itself.
See also cosets(::AbstractVector, ::AbstractVector). This method is equivalent (but may return different representatives in general) to cosets(spacegroup(sgnum), g).
source
Crystalline.cosets — Method
cosets(G, H)
For a subgroup H $=H$ of G = $G$, find a set of (left) coset representatives  $\{g_i\}$ of $H$ in $G$, such that (see e.g., Inui et al., Section 2.7)
\[    G = \bigcup_i g_i H.\]
The identity operation $1$ is always included in $\{g_i\}$.
Example
julia> G = pointgroup("6mm");
 
 julia> H = pointgroup("3");
 
@@ -67,7 +67,7 @@
  [1, 3₀₀₁⁺, 3₀₀₁⁻]
  [2₀₀₁, 6₀₀₁⁻, 6₀₀₁⁺]
  [m₁₁₀, m₁₀₀, m₀₁₀]
- [m₋₁₁₀, m₁₂₀, m₂₁₀]
source
Crystalline.dim — Method
dim(BR::BandRep) --> Int
Return the number of bands included in the provided BandRep.
source
Crystalline.dim — Method
dim(g::AbstractGroup) -> Int
Return the dimensionality of the coordinate space of the group g. This is a statically known number, either equaling 1, 2, or 3.
source
Crystalline.dim — Method
dim(BR::BandRep) --> Int
Return the number of bands included in the provided BandRep.
source
Crystalline.dim — Method
dim(g::AbstractGroup) -> Int
Return the dimensionality of the coordinate space of the group g. This is a statically known number, either equaling 1, 2, or 3.
source
Crystalline.find_isomorphic_parent_pointgroup — Method
find_isomorphic_parent_pointgroup(g::AbstractVector{SymOperation{D}}) 
                                                 --> PointGroup{D}, Vector{Int}, Bool
Given a group g (or a collection of operators, defining a group), identifies a "parent" point group that is isomorphic to g.
Three variables are returned:
  • pg: the identified "parent" point group, with operators sorted to match the sorting of g's operators.
  • Iᵖ²ᵍ: a permutation vector which transforms the standard sorting of point group operations (as returned by pointgroup(::String)) to the operator sorting of g.
  • equal: a boolean, identifying whether the point group parts of g operations are identical (true) or merely isomorphic to the point group operations in g. In practice, this indicates whether pg and g are in the same setting or not.
Implementation
The identification is made partly on the basis of comparison of operators (this is is sufficient for the equal = true case) and partly on the basis of comparison of  multiplication tables (equal = false case); the latter can be combinatorially slow if the sorting of operators is unlucky (i.e., if permutation between sortings in g and pg differ by many pairwise permutations).
Beyond mere isomorphisms of multiplication tables, the search also guarantees that all rotation orders are shared between pg and g; similarly, the rotation senses (e.g., 4⁺ & 4⁻ have opposite rotation senses or directions) are shared. This disambiguates point groups  that are intrinsically isomorphic to eachother, e.g. "m" and "-1", but which still differ in their spatial interpretation.
Properties
The following properties hold for g, pg, and Iᵖ²ᵍ:
pg, Iᵖ²ᵍ, equal = find_isomorphic_parent_pointgroup(g)
 @assert MultTable(pg) == MultTable(pointgroup(g))
 pg′ = pointgroup(label(pg), dim(pg)) # "standard" sorting
@@ -75,7 +75,7 @@
 wp    = wyckoffs(sgnum, Val(3))[end] # 4a Wyckoff position
 sg    = spacegroup(sgnum, Val(3))
 siteg = sitegroup(sg, wp)
-pg, Iᵖ²ᵍ, equal = find_isomorphic_parent_pointgroup(siteg)
source
Crystalline.find_representation — Function
find_representation(symvals::AbstractVector{Number}, 
                     lgirs::AbstractVector{<:AbstractIrrep},
                     αβγ::Union{AbstractVector{<:Real},Nothing}=nothing,
                     assert_return_T::Type{<:Union{Integer, AbstractFloat}}=Int),
@@ -84,7 +84,7 @@
                     verbose::Bool=false)
 
                     --> Vector{assert_return_T}
From a vector (or vector of vectors) of symmetry eigenvalues symvals sampled along all the operations of a group gᵢ, whose irreps are contained in irs (evaluated with optional free  parameters αβγ), return the multiplicities of each irrep.
Optionally, the multiciplities' element type can be specified via the assert_return_T argument (performing checked conversion; returns nothing if representation in  assert_return_T is impossible). This can be useful if one suspects a particular band to  transform like a fraction of an irrep (i.e., the specified symmetry data is incomplete).
If no valid set of multiplicities exist (i.e., is solvable, and has real-valued and assert_return_T representible type), the sentinel value nothing is returned. Optional debugging information can in this case be shown by setting verbose=true.
Extended help
Effectively, this applies the projection operator P⁽ʲ⁾ of each irrep's character set χ⁽ʲ⁾(gᵢ) (j = 1, ... , Nⁱʳʳ) to the symmetry data sᵢ ≡ symvals:
P⁽ʲ⁾  ≡ (dⱼ/|g|) ∑ᵢ χ⁽ʲ⁾(gᵢ)*gᵢ         [characters χ⁽ʲ⁾(gᵢ), irrep dimension dⱼ]
-P⁽ʲ⁾s = (dⱼ/|g|) ∑ᵢ χ⁽ʲ⁾(gᵢ)*sᵢ = nⱼ,   [number of bands that transform like jth irrep]
returning the irrep multiplicities mⱼ ≡ nⱼ/dⱼ.
source
Crystalline.findmaximal — Method
findmaximal(sitegs::AbstractVector{<:SiteGroup})
Given an AbstractVector{<:SiteGroup} over the distinct Wyckoff positions of a space group, return those SiteGroups that are associated with a maximal Wyckoff positions.
Results are returned as a view into the input vector (i.e. as an  AbstractVector{<:SiteGroup}). The associated Wyckoff positions can be retrieved via position.
Definition
A Wyckoff position is maximal if its site symmetry group has higher order than the site symmetry groups of any "nearby" Wyckoff positions (i.e. Wyckoff positions that can be  connected, i.e. made equivalent, through parameter variation to the considered Wyckoff position).
Example
julia> sgnum = 5;
+P⁽ʲ⁾s = (dⱼ/|g|) ∑ᵢ χ⁽ʲ⁾(gᵢ)*sᵢ = nⱼ,   [number of bands that transform like jth irrep]
returning the irrep multiplicities mⱼ ≡ nⱼ/dⱼ.
source
Crystalline.findmaximal — Method
findmaximal(sitegs::AbstractVector{<:SiteGroup})
Given an AbstractVector{<:SiteGroup} over the distinct Wyckoff positions of a space group, return those SiteGroups that are associated with a maximal Wyckoff positions.
Results are returned as a view into the input vector (i.e. as an  AbstractVector{<:SiteGroup}). The associated Wyckoff positions can be retrieved via position.
Definition
A Wyckoff position is maximal if its site symmetry group has higher order than the site symmetry groups of any "nearby" Wyckoff positions (i.e. Wyckoff positions that can be  connected, i.e. made equivalent, through parameter variation to the considered Wyckoff position).
Example
julia> sgnum = 5;
 
 julia> D = 2;
 
@@ -98,13 +98,13 @@
 julia> only(findmaximal(sitegs))
 SiteGroup{2} ⋕5 (c1m1) at 2a = [0, β] with 2 operations:
  1
- m₁₀
source
Crystalline.generate — Method
generate(
     gens::AbstractArray{SymOperation{D}, 1};
     cntr,
     modτ,
     Nmax
 ) -> Crystalline.GenericGroup
-
Return the group generated from a finite set of generators gens.
Keyword arguments
  • cntr (default, nothing): check equivalence of operations modulo primitive lattice vectors (see also isapprox(::SymOperation, ::SymOperation, cntr::Union{Nothing, Char});  only nonequivalent operations are included in the returned group.
  • modτ (default, true): the group composition operation can either be taken modulo lattice vectors (true) or not (false, useful e.g. for site symmetry groups). In this case, the provided generators will also be taken modulo integer lattice translations.
  • Nmax (default, 256): the maximum size of the generated group. This is essentially a cutoff set to ensure halting of execution in case the provided set of generators do not define a finite group (especially relevant if modτ=false). If more operations than Nmax are generated, the method throws an overflow error.
source
Crystalline.generators — Method
generators(num::Integer, T::Type{AbstractGroup{D}}[, optargs])
+
Return the group generated from a finite set of generators gens.
Keyword arguments
  • cntr (default, nothing): check equivalence of operations modulo primitive lattice vectors (see also isapprox(::SymOperation, ::SymOperation, cntr::Union{Nothing, Char});  only nonequivalent operations are included in the returned group.
  • modτ (default, true): the group composition operation can either be taken modulo lattice vectors (true) or not (false, useful e.g. for site symmetry groups). In this case, the provided generators will also be taken modulo integer lattice translations.
  • Nmax (default, 256): the maximum size of the generated group. This is essentially a cutoff set to ensure halting of execution in case the provided set of generators do not define a finite group (especially relevant if modτ=false). If more operations than Nmax are generated, the method throws an overflow error.
source
Crystalline.generators — Method
generators(num::Integer, T::Type{AbstractGroup{D}}[, optargs])
 generators(pgiuc::String, T::PointGroup{D}})              -->  Vector{SymOperation{D}}
Return the generators of the group type T which may be a SpaceGroup{D} or a  PointGroup{D} parameterized by its dimensionality D. Depending on T, the group is determined by inputting as the first argument:
  • SpaceGroup{D}: the space group number num::Integer.
  • PointGroup{D}: the point group IUC label pgiuc::String (see also [pointgroup(::String)) or the canonical point group number num::Integer, which can optionally be supplemented by an integer-valued setting choice setting::Integer (see also pointgroup(::Integer, ::Integer, ::Integer)]).
  • SubperiodicGroup{D}: the subperiodic group number num::Integer.
Setting choices match those in spacegroup, pointgroup, and subperiodicgroup.
Iterated composition of the returned symmetry operations will generate all operations of the associated space or point group (see generate). As an example, generate(generators(num,SpaceGroup{D}))andspacegroup(num, D)` return identical operations (with different sorting typically); and similarly so for point and subperiodic groups.
Example
Generators of space group 200:
julia> generators(200, SpaceGroup{3})
 4-element Vector{SymOperation{3}}:
  2₀₀₁
@@ -116,46 +116,46 @@
  -1
Generators of the Frieze group 𝓅2mg:
julia> generators(7, SubperiodicGroup{2, 1})
 2-element Vector{SymOperation{2}}:
  2
- {m₁₀|½,0}
Citing
Please cite the original data sources if used in published work:
Extended help
Note that the returned generators are not guaranteed to be the smallest possible set of generators; i.e., there may exist other generators with fewer elements (an example is space group 168 (P6), for which the returned generators are [2₀₀₁, 3₀₀₁⁺] even though the group could be generated by just [6₀₀₁⁺]). The returned generators, additionally, are not guaranteed to be minimal, i.e., they may include proper subsets that generate the group themselves (e.g., in space group 75 (P4), the returned generators are [2₀₀₁, 4₀₀₁⁺] although the subset [4₀₀₁⁺] is sufficient to generate the group). The motivation for this is to expose as similar generators as possible for similar crystal systems (see e.g. Section 8.3.5 of the International Tables of Crystallography, Vol. A, Ed. 5 (ITA) for further background).
Note also that, contrary to conventions in ITA, the identity operation is excluded among the returned generators (except in space group 1) since it composes trivially and adds no additional context.
source
Crystalline.generators — Method
generators(num::Integer, ::Type{SubperiodicGroup{D,P}})  -->  ::Vector{SymOperation{D}}
Return a canonical set of generators for the subperiodic group num of embedding dimension D and periodicity dimension P. See also subperiodicgroup.
See also generators(::Integer, ::Type{SpaceGroup}) and information therein.
Example
julia> generators(7, SubperiodicGroup{2, 1})
+ {m₁₀|½,0}
Citing
Please cite the original data sources if used in published work:
Extended help
Note that the returned generators are not guaranteed to be the smallest possible set of generators; i.e., there may exist other generators with fewer elements (an example is space group 168 (P6), for which the returned generators are [2₀₀₁, 3₀₀₁⁺] even though the group could be generated by just [6₀₀₁⁺]). The returned generators, additionally, are not guaranteed to be minimal, i.e., they may include proper subsets that generate the group themselves (e.g., in space group 75 (P4), the returned generators are [2₀₀₁, 4₀₀₁⁺] although the subset [4₀₀₁⁺] is sufficient to generate the group). The motivation for this is to expose as similar generators as possible for similar crystal systems (see e.g. Section 8.3.5 of the International Tables of Crystallography, Vol. A, Ed. 5 (ITA) for further background).
Note also that, contrary to conventions in ITA, the identity operation is excluded among the returned generators (except in space group 1) since it composes trivially and adds no additional context.
source
Crystalline.generators — Method
generators(num::Integer, ::Type{SubperiodicGroup{D,P}})  -->  ::Vector{SymOperation{D}}
Return a canonical set of generators for the subperiodic group num of embedding dimension D and periodicity dimension P. See also subperiodicgroup.
See also generators(::Integer, ::Type{SpaceGroup}) and information therein.
Example
julia> generators(7, SubperiodicGroup{2, 1})
 2-element Vector{SymOperation{2}}:
  2
- {m₁₀|½,0}
Data sources
The generators returned by this function were originally retrieved from the Bilbao Crystallographic Database, SUBPERIODIC GENPOS.
source
Crystalline.irreps — Method
irreps(n::AbstractSymmetryVector{D}) -> AbstractVector{<:Collection{<:AbstractIrrep{D}}}
Return the irreps referenced by n. 
The returned value is an AbstractVector of Collection{<:AbstractIrrep}s, with irreps for distinct groups, usually associated with specific k-manifolds, belonging to the same Collection.
See also multiplicities(::AbstractSymmetryVector).
source
Crystalline.is_abelian — Method
is_abelian(ops::AbstractVector{SymOperation}, [cntr::Union{Char, Nothing}])  -->  Bool
Return the whether the group composed of the elements ops is Abelian.
A group $G$ is Abelian if all its elements commute mutually, i.e., if $g = hgh^{-1}$ for all $g,h ∈ G$.
See discussion of the setting argument cntr in classes.
source
Crystalline.irreps — Method
irreps(n::AbstractSymmetryVector{D}) -> AbstractVector{<:Collection{<:AbstractIrrep{D}}}
Return the irreps referenced by n. 
The returned value is an AbstractVector of Collection{<:AbstractIrrep}s, with irreps for distinct groups, usually associated with specific k-manifolds, belonging to the same Collection.
See also multiplicities(::AbstractSymmetryVector).
source
Crystalline.is_abelian — Method
is_abelian(ops::AbstractVector{SymOperation}, [cntr::Union{Char, Nothing}])  -->  Bool
Return the whether the group composed of the elements ops is Abelian.
A group $G$ is Abelian if all its elements commute mutually, i.e., if $g = hgh^{-1}$ for all $g,h ∈ G$.
See discussion of the setting argument cntr in classes.
source
Crystalline.isnormal — Method
isnormal(opsᴳ::AbstractVector{<:SymOperation},
          opsᴴ::AbstractVector{<:SymOperation};
-         verbose::Bool=false)                    --> Bool
Determine whether the operations in group $H$ are normal in the group $G$ (each with  operations opsᴳ and opsᴴ), in the sense that 
\[ghg⁻¹ ∈ H, ∀ g∈G, ∀ h∈H\]
Returns a Boolean answer (true if normal, false if not).
Note
This compares space groups rather than space group types, i.e. the comparison assumes a matching setting choice between $H$ and $G$. To compare space group types with different conventional settings, they must first be transformed to a shared setting.
source
Crystalline.israyrep — Function
israyrep(lgir::LGIrrep, αβγ=nothing) -> (::Bool, ::Matrix)
Computes whether a given little group irrep ir is a ray representation  by computing the coefficients αᵢⱼ in DᵢDⱼ=αᵢⱼDₖ; if any αᵢⱼ differ  from unity, we consider the little group irrep a ray representation (as opposed to the simpler "vector" representations where DᵢDⱼ=Dₖ). The function returns a boolean (true => ray representation) and the coefficient matrix αᵢⱼ.
source
Crystalline.issubgroup — Method
issubgroup(opsᴳ::T, opsᴴ::T′) where T⁽′⁾<:AbstractVector{SymOperation} --> Bool
Determine whether the operations in group $H$ are a subgroup of the group $G$ (each with  operations opsᴳ and opsᴴ, respectively), i.e. whether $H<G$. Specifically, this requires that $G$ and $H$ are both groups and that for every $h∈H$ there exists an element $g∈G$ such that $h=g$.
Returns a Boolean answer (true if normal, false if not).
Note
This compares space groups rather than space group types, i.e. the comparison assumes a matching setting choice between $H$ and $G$. To compare space group types with different conventional settings, they must first be transformed to a shared setting.
source
Crystalline.issymmorph — Function
issymmorph(sgnum::Integer, D::Integer=3) --> Bool
Return whether the space group with number sgnum and dimensionality D is symmorphic  (true) or nonsymmorphic (false).
Equivalent to issymmorph(spacegroup(sgnum, D)) but uses memoization for performance.
source
Crystalline.issymmorph — Method
issymmorph(sg::Union{SpaceGroup, LittleGroup}) --> Bool
Return whether a given space group sg is symmorphic (true) or nonsymmorphic (false).
source
Crystalline.issymmorph — Method
issymmorph(op::SymOperation, cntr::Char) --> Bool
Return whether a given symmetry operation op is symmorphic (true) or nonsymmorphic (false). 
The operation is assumed provided in conventional basis with centering type cntr:  checking symmorphism is then equivalent to checking whether the operation's translation part is zero or a lattice vector in the associated primitive basis.
source
Crystalline.iuc — Function
iuc(sgnum::Integer, D::Integer=3) --> String
Return the IUC (International Union of Crystallography) notation for space group number sgnum in dimension D (1, 2, or 3), as used in the International Tables of Crystallography.
The notation is sometimes also known as the Hermann-Mauguin notation.
source
Crystalline.levelsetlattice — Method
levelsetlattice(sgnum::Integer, D::Integer=2, idxmax::NTuple=ntuple(i->2,D))
+         verbose::Bool=false)                    --> Bool
Determine whether the operations in group $H$ are normal in the group $G$ (each with  operations opsᴳ and opsᴴ), in the sense that 
\[ghg⁻¹ ∈ H, ∀ g∈G, ∀ h∈H\]
Returns a Boolean answer (true if normal, false if not).
Note
This compares space groups rather than space group types, i.e. the comparison assumes a matching setting choice between $H$ and $G$. To compare space group types with different conventional settings, they must first be transformed to a shared setting.
source
Crystalline.israyrep — Function
israyrep(lgir::LGIrrep, αβγ=nothing) -> (::Bool, ::Matrix)
Computes whether a given little group irrep ir is a ray representation  by computing the coefficients αᵢⱼ in DᵢDⱼ=αᵢⱼDₖ; if any αᵢⱼ differ  from unity, we consider the little group irrep a ray representation (as opposed to the simpler "vector" representations where DᵢDⱼ=Dₖ). The function returns a boolean (true => ray representation) and the coefficient matrix αᵢⱼ.
source
Crystalline.issubgroup — Method
issubgroup(opsᴳ::T, opsᴴ::T′) where T⁽′⁾<:AbstractVector{SymOperation} --> Bool
Determine whether the operations in group $H$ are a subgroup of the group $G$ (each with  operations opsᴳ and opsᴴ, respectively), i.e. whether $H<G$. Specifically, this requires that $G$ and $H$ are both groups and that for every $h∈H$ there exists an element $g∈G$ such that $h=g$.
Returns a Boolean answer (true if normal, false if not).
Note
This compares space groups rather than space group types, i.e. the comparison assumes a matching setting choice between $H$ and $G$. To compare space group types with different conventional settings, they must first be transformed to a shared setting.
source
Crystalline.issymmorph — Function
issymmorph(sgnum::Integer, D::Integer=3) --> Bool
Return whether the space group with number sgnum and dimensionality D is symmorphic  (true) or nonsymmorphic (false).
Equivalent to issymmorph(spacegroup(sgnum, D)) but uses memoization for performance.
source
Crystalline.issymmorph — Method
issymmorph(sg::Union{SpaceGroup, LittleGroup}) --> Bool
Return whether a given space group sg is symmorphic (true) or nonsymmorphic (false).
source
Crystalline.issymmorph — Method
issymmorph(op::SymOperation, cntr::Char) --> Bool
Return whether a given symmetry operation op is symmorphic (true) or nonsymmorphic (false). 
The operation is assumed provided in conventional basis with centering type cntr:  checking symmorphism is then equivalent to checking whether the operation's translation part is zero or a lattice vector in the associated primitive basis.
source
Crystalline.iuc — Function
iuc(sgnum::Integer, D::Integer=3) --> String
Return the IUC (International Union of Crystallography) notation for space group number sgnum in dimension D (1, 2, or 3), as used in the International Tables of Crystallography.
The notation is sometimes also known as the Hermann-Mauguin notation.
source
Crystalline.levelsetlattice — Method
levelsetlattice(sgnum::Integer, D::Integer=2, idxmax::NTuple=ntuple(i->2,D))
     --> UnityFourierLattice{D}
Compute a "neutral"/uninitialized Fourier lattice basis, a UnityFourierLattice, consistent with the symmetries of the space group sgnum in dimension D.  The resulting lattice flat is expanded in a Fourier basis split into symmetry-derived orbits, with intra-orbit coefficients constrained by the symmetries of the space-group. The inter-orbit coefficients are, however, free and unconstrained.
The Fourier resolution along each reciprocal lattice vector is controlled by idxmax: e.g., if D = 2 and idxmax = (2, 3), the resulting Fourier lattice may contain  reciprocal lattice vectors (k₁, k₂) with k₁∈[0,±1,±2] and k₂∈[0,±1,±2,±3], referred  to a 𝐆-basis.
This "neutral" lattice can, and usually should, be subsequently modulated by modulate (which modulates the inter-orbit coefficients, which may eliminate "synthetic symmetries" that can exist in the "neutral" configuration, due to all  inter-orbit coefficients being set to unity).
Examples
Compute a UnityFourierLattice, modulate it with random inter-orbit coefficients  via modulate, and finally plot it (via PyPlot.jl):
julia> uflat = levelsetlattice(16, Val(2))
 julia> flat  = modulate(uflat)
 julia> Rs    = directbasis(16, Val(2)) 
 julia> using PyPlot
-julia> plot(flat, Rs)
source
Crystalline.lgirreps — Method
lgirreps(sgnum::Integer, D::Union{Val{Int}, Integer}=Val(3))
-                                        -> Dict{String, Collection{LGIrrep{D}}}
For given space group number sgnum and dimension D, return the associated little group (or "small") irreps (LGIrrep{D}s) at high-symmetry k-points, lines, and planes. 
Returns a Dict with little group k-point labels as keys and vectors of LGIrrep{D}s as values.
Notes
  • The returned irreps are complex in general. Real irreps (as needed in time-reversal invariant settings) can subsequently be obtained with the realify method.
  • Returned irreps are spinless.
  • The irrep labelling follows CDML conventions.
  • Irreps along lines or planes may depend on free parameters αβγ that parametrize the k point. To evaluate the irreps at a particular value of αβγ and return the associated matrices, use (lgir::LGIrrep)(αβγ). If αβγ is an empty tuple in this call, the matrices associated with lgir will be evaluated assuming αβγ = [0,0,...].
References
The underlying data is sourced from the ISOTROPY ISO-IR dataset. Please cite the original reference material associated with ISO-IR:
  1. Stokes, Hatch, & Campbell,  ISO-IR, ISOTROPY Software Suite.
  2. Stokes, Campbell, & Cordes, Acta Cryst. A. 69, 388-395 (2013).
The ISO-IR dataset is occasionally missing some k-points that lie outside the basic domain but still resides in the representation domain (i.e. k-points with postscripted 'A', 'B', etc. labels, such as 'ZA'). In such cases, the missing irreps may instead have been manually sourced from the Bilbao Crystallographic Database.
source
Crystalline.lgirreps — Method
lgirreps(sgnum::Integer, D::Union{Val{Int}, Integer}=Val(3))
+                                        -> Dict{String, Collection{LGIrrep{D}}}
For given space group number sgnum and dimension D, return the associated little group (or "small") irreps (LGIrrep{D}s) at high-symmetry k-points, lines, and planes. 
Returns a Dict with little group k-point labels as keys and vectors of LGIrrep{D}s as values.
Notes
  • The returned irreps are complex in general. Real irreps (as needed in time-reversal invariant settings) can subsequently be obtained with the realify method.
  • Returned irreps are spinless.
  • The irrep labelling follows CDML conventions.
  • Irreps along lines or planes may depend on free parameters αβγ that parametrize the k point. To evaluate the irreps at a particular value of αβγ and return the associated matrices, use (lgir::LGIrrep)(αβγ). If αβγ is an empty tuple in this call, the matrices associated with lgir will be evaluated assuming αβγ = [0,0,...].
References
The underlying data is sourced from the ISOTROPY ISO-IR dataset. Please cite the original reference material associated with ISO-IR:
  1. Stokes, Hatch, & Campbell,  ISO-IR, ISOTROPY Software Suite.
  2. Stokes, Campbell, & Cordes, Acta Cryst. A. 69, 388-395 (2013).
The ISO-IR dataset is occasionally missing some k-points that lie outside the basic domain but still resides in the representation domain (i.e. k-points with postscripted 'A', 'B', etc. labels, such as 'ZA'). In such cases, the missing irreps may instead have been manually sourced from the Bilbao Crystallographic Database.
source
Crystalline.littlegroup — Function
littlegroup(sg::SpaceGroup, kv::KVec) -> LittleGroup
 littlegroup(
     sg::SpaceGroup,
     kv::KVec,
     klab::String
 ) -> LittleGroup
-
Return the little group associated with space group sg at the k-vector kv.
Optionally, an associated k-vector label klab can be provided; if not provided, the empty string is used as label.
source
Crystalline.littlegroups — Method
littlegroups(sgnum::Integer, D::Union{Val{Int}, Integer}=Val(3)) 
-                                                    -> Dict{String, LittleGroup{D}}
For given space group number sgnum and dimension D, return the associated little groups (LittleGroups{D}s) at high-symmetry k-points, lines, and planes (see also lgirreps).
Returns a Dict with little group k-point labels as keys and vectors of LittleGroup{D}s as values.
Notes
A conventional crystallographic setting is assumed (as in spacegroup).
Unlike spacegroup, "centering"-copies of symmetry operations are not included in the returned LittleGroups; as an example, space group 110 (body-centered, with centering symbol 'I') has a centering translation [1/2,1/2,1/2] in the conventional setting: the symmetry operations returned by spacegroup thus includes e.g. both {1|0} and  {1|½,½,½} while the symmetry operations returned by littlegroups only include {1|0} (and so on).
Currently, only D = 3 is supported.
References
The underlying data is sourced from the ISOTROPY dataset: see also lgirreps.
source
Crystalline.matrix — Method
matrix(op::AbstractOperation{D}) --> SMatrix{D, D+1, Float64}
Return the D×D+1 matrix representation of op.
source
Crystalline.maximal_subgroups — Method
maximal_subgroups(num::Integer, AG::Type{<:AbstractGroup}=SpaceGrop{3}; kind)
Returns the graph structure of the maximal subgroups as a GroupRelationGraph for a group of type AG and number num.
Visualization
The resulting group structure can be plotted using Makie.jl (e.g., GLMakie.jl) using plot(::GroupRelationGraph):
julia> using Crystalline
+
Return the little group associated with space group sg at the k-vector kv.
Optionally, an associated k-vector label klab can be provided; if not provided, the empty string is used as label.
source
Crystalline.littlegroups — Method
littlegroups(sgnum::Integer, D::Union{Val{Int}, Integer}=Val(3)) 
+                                                    -> Dict{String, LittleGroup{D}}
For given space group number sgnum and dimension D, return the associated little groups (LittleGroups{D}s) at high-symmetry k-points, lines, and planes (see also lgirreps).
Returns a Dict with little group k-point labels as keys and vectors of LittleGroup{D}s as values.
Notes
A conventional crystallographic setting is assumed (as in spacegroup).
Unlike spacegroup, "centering"-copies of symmetry operations are not included in the returned LittleGroups; as an example, space group 110 (body-centered, with centering symbol 'I') has a centering translation [1/2,1/2,1/2] in the conventional setting: the symmetry operations returned by spacegroup thus includes e.g. both {1|0} and  {1|½,½,½} while the symmetry operations returned by littlegroups only include {1|0} (and so on).
Currently, only D = 3 is supported.
References
The underlying data is sourced from the ISOTROPY dataset: see also lgirreps.
source
Crystalline.matrix — Method
matrix(op::AbstractOperation{D}) --> SMatrix{D, D+1, Float64}
Return the D×D+1 matrix representation of op.
source
Crystalline.maximal_subgroups — Method
maximal_subgroups(num::Integer, AG::Type{<:AbstractGroup}=SpaceGrop{3}; kind)
Returns the graph structure of the maximal subgroups as a GroupRelationGraph for a group of type AG and number num.
Visualization
The resulting group structure can be plotted using Makie.jl (e.g., GLMakie.jl) using plot(::GroupRelationGraph):
julia> using Crystalline
 julia> gr = maximal_subgroups(112, SpaceGroup{3})
 julia> using GraphMakie, GLMakie
-julia> plot(gr)
Keyword arguments
  • kind (default, Crystalline.TRANSLATIONENGLEICHE): to return klassengleiche relations, set kind = Crystalline.KLASSENGLEICHE). For klassengleiche relationships, only a selection of reasonably low-index relationships are returned.
Data sources
The group relationships returned by this function were retrieved from the Bilbao Crystallographic Server's MAXSUB program. Please cite the original reference work associated with MAXSUB:
source
Crystalline.minimal_supergroups — Method
minimal_supergroups(num::Integer, AG::Type{<:AbstractGroup}=SpaceGrop{3}; kind)
Returns the graph structure of the minimal supergroups as a GroupRelationGraph for a group of type AG and number num.
Visualization
The resulting group structure can be plotted using Makie.jl (e.g., GLMakie.jl) using plot(::GroupRelationGraph):
julia> using Crystalline
+julia> plot(gr)
Keyword arguments
  • kind (default, Crystalline.TRANSLATIONENGLEICHE): to return klassengleiche relations, set kind = Crystalline.KLASSENGLEICHE). For klassengleiche relationships, only a selection of reasonably low-index relationships are returned.
Data sources
The group relationships returned by this function were retrieved from the Bilbao Crystallographic Server's MAXSUB program. Please cite the original reference work associated with MAXSUB:
source
Crystalline.minimal_supergroups — Method
minimal_supergroups(num::Integer, AG::Type{<:AbstractGroup}=SpaceGrop{3}; kind)
Returns the graph structure of the minimal supergroups as a GroupRelationGraph for a group of type AG and number num.
Visualization
The resulting group structure can be plotted using Makie.jl (e.g., GLMakie.jl) using plot(::GroupRelationGraph):
julia> using Crystalline
 julia> gr = minimal_supergroups(112, SpaceGroup{3})
 julia> using GraphMakie, GLMakie
-julia> plot(gr)
Keyword arguments
  • kind (default, Crystalline.TRANSLATIONENGLEICHE): to return klassengleiche relations, set kind = Crystalline.KLASSENGLEICHE). For klassengleiche relationships, only a selection of reasonably low-index relationships are returned.
Data sources
The group relationships returned by this function were retrieved from the Bilbao Crystallographic Server's MAXSUB program. Please cite the original reference work associated with MAXSUB:
source
Crystalline.modulate — Method
modulate(flat::UnityFourierLattice{D},
+julia> plot(gr)
Keyword arguments
  • kind (default, Crystalline.TRANSLATIONENGLEICHE): to return klassengleiche relations, set kind = Crystalline.KLASSENGLEICHE). For klassengleiche relationships, only a selection of reasonably low-index relationships are returned.
Data sources
The group relationships returned by this function were retrieved from the Bilbao Crystallographic Server's MAXSUB program. Please cite the original reference work associated with MAXSUB:
source
Crystalline.modulate — Method
modulate(flat::UnityFourierLattice{D},
 modulation::AbstractVector{ComplexF64}=rand(ComplexF64, length(getcoefs(flat))),
 expon::Union{Nothing, Real}=nothing, Gs::Union{ReciprocalBasis{D}, Nothing}=nothing)
-                        --> ModulatedFourierLattice{D}
Derive a concrete, modulated Fourier lattice from a UnityFourierLattice flat (containing the interrelations between orbit coefficients), by  multiplying the "normalized" orbit coefficients by a modulation, a complex modulating vector (in general, should be complex; otherwise restores unintended symmetry to the lattice). Distinct modulation vectors produce distinct  realizations of the same lattice described by the original flat. By default, a random complex vector is used.
An exponent expon can be provided, which introduces a penalty term to short- wavelength features (i.e. high-|G| orbits) by dividing the orbit coefficients by |G|^expon; producing a "simpler" and "smoother" lattice boundary when expon > 0 (reverse for expon < 0). This basically amounts to a  continuous "simplifying" operation on the lattice (it is not necessarily a  smoothing operation; it simply suppresses "high-frequency" components). If expon = nothing, no rescaling is performed. If Gs is provided as nothing, the orbit norm is computed in the reciprocal lattice basis (and, so, may not strictly speaking be a norm if the lattice basis is not cartesian); to account for the basis explicitly, Gs must be provided as a ReciprocalBasis, see also normscale.
source
Crystalline.mspacegroup — Method
mspacegroup(BNS₁, BNS₂)
-mspacegroup(OG₃)        --> MSpaceGroup{3}
Return the magnetic space group with BNS numbers (BNS₁, BNS₂) or the sequential OG number OG₃ (from 1 to 1651).
Data sources
The data underlying this function was retrieved from ISOTROPY's compilation of Daniel  Litvin's magnetic space group tables (http://www.bk.psu.edu/faculty/litvin/Download.html).
source
Crystalline.mulliken — Method
mulliken(pgir::PGIrrep{D}) -> String
-
Return the Mulliken label of a point group irrep pgir.
Notes
This functionality is a simple mapping between the tabulated CDML point group irrep labels and associated Mulliken labels [1], using the listings from the Bilbao Crystallographic Database [2].
Ignoring subscript, the rough rules associated with assignment of Mulliken labels are:
  1. Irrep dimensionality: 
    • 1D irreps: if a real irrep, assign A or B (B if antisymmetric under a principal  rotation); if a complex irrep, assigned label ¹E or ²E.
    • 2D irreps: assign label E.
    • 3D irreps: assign label T.
  2. u and g subscripts: if the group contains inversion, indicate whether irrep is symmetric (g ~ gerade) or antisymmetric (u ~ ungerade) under inversion.
  3. Prime superscripts: if the group contains a mirror m aligned with a principal  rotation axis, but does not contain inversion, indicate whether irrep is symmetric (′)  or antisymmetric (′′) under this mirror.
  4. Numeral subscripts: the rules for assignment of numeral subscripts are too complicated in general - and indeed, we are unaware of a general coherent rule – to describe here.
References
source
Crystalline.nontrivial_factors — Method
nontrivial_factors(F::Smith) -> Any
-
Return the nontrivial (i.e., ≠ {0,1}) elementary factors of an EBR basis, provided as a BandRepSet or Smith decomposition.
source
Crystalline.normscale! — Method
normscale!(flat::ModulatedFourierLattice, expon::Real,
-           Gs::Union{ReciprocalBasis, Nothing} = nothing) --> ModulatedFourierLattice
In-place equivalent of normscale: mutates flat.
source
Crystalline.normscale — Method
normscale(flat::ModulatedFourierLattice, expon::Real, 
-          Gs::Union{ReciprocalBasis, Nothing} = nothing)  --> ModulatedFourierLattice
Applies inverse-orbit norm rescaling of expansion coefficients with a norm exponent expon. If Gs is nothing, the orbit norm is computed in the lattice basis (and, so, is not strictly a norm); by providing Gs as ReciprocalBasis, the norm is evaluated correctly in cartesian setting. See further discussion in modulate.
An in-place equivalent is provided in normscale!.
source
Crystalline.num — Method
num(g::AbstractGroup) -> Int
Return the conventional number assigned to the group g.
source
Crystalline.occupation — Method
occupation(n::AbstractSymmetryVector) -> Int
Return the occupation of (i.e., number of bands contained within) n.
source
Crystalline.operations — Method
operations(g::AbstractGroup) -> Vector{<:AbstractOperation}
Return an Vector containing the operations of the group g.
source
Crystalline.orbit — Method
orbit(g::SiteGroup)  -->  Vector{WyckoffPosition}
Compute the orbit of the Wyckoff position associated with the site symmetry group g.
Extended help
The orbit of a Wyckoff position $\mathbf{r}$ in a space group $G$ is defined as the set of inequivalent points in the unit cell that can be obtained by applying the elements of $G$ to $\mathbf{r}$. Equivalently, every element of the orbit of $\mathbf{r}$ can be written as the composition of a coset representative of the Wyckoff position's site group in $G$ with $\mathbf{r}$.
source
Crystalline.orbit — Method
orbit(g::AbstractVector{<:SymOperation}, kv::KVec, cntr::Char)  -->  Vector{KVec{D}}
+                        --> ModulatedFourierLattice{D}
Derive a concrete, modulated Fourier lattice from a UnityFourierLattice flat (containing the interrelations between orbit coefficients), by  multiplying the "normalized" orbit coefficients by a modulation, a complex modulating vector (in general, should be complex; otherwise restores unintended symmetry to the lattice). Distinct modulation vectors produce distinct  realizations of the same lattice described by the original flat. By default, a random complex vector is used.
An exponent expon can be provided, which introduces a penalty term to short- wavelength features (i.e. high-|G| orbits) by dividing the orbit coefficients by |G|^expon; producing a "simpler" and "smoother" lattice boundary when expon > 0 (reverse for expon < 0). This basically amounts to a  continuous "simplifying" operation on the lattice (it is not necessarily a  smoothing operation; it simply suppresses "high-frequency" components). If expon = nothing, no rescaling is performed. If Gs is provided as nothing, the orbit norm is computed in the reciprocal lattice basis (and, so, may not strictly speaking be a norm if the lattice basis is not cartesian); to account for the basis explicitly, Gs must be provided as a ReciprocalBasis, see also normscale.
source
Crystalline.mspacegroup — Method
mspacegroup(BNS₁, BNS₂)
+mspacegroup(OG₃)        --> MSpaceGroup{3}
Return the magnetic space group with BNS numbers (BNS₁, BNS₂) or the sequential OG number OG₃ (from 1 to 1651).
Data sources
The data underlying this function was retrieved from ISOTROPY's compilation of Daniel  Litvin's magnetic space group tables (http://www.bk.psu.edu/faculty/litvin/Download.html).
source
Crystalline.mulliken — Method
mulliken(pgir::PGIrrep{D}) -> String
+
Return the Mulliken label of a point group irrep pgir.
Notes
This functionality is a simple mapping between the tabulated CDML point group irrep labels and associated Mulliken labels [1], using the listings from the Bilbao Crystallographic Database [2].
Ignoring subscript, the rough rules associated with assignment of Mulliken labels are:
  1. Irrep dimensionality: 
    • 1D irreps: if a real irrep, assign A or B (B if antisymmetric under a principal  rotation); if a complex irrep, assigned label ¹E or ²E.
    • 2D irreps: assign label E.
    • 3D irreps: assign label T.
  2. u and g subscripts: if the group contains inversion, indicate whether irrep is symmetric (g ~ gerade) or antisymmetric (u ~ ungerade) under inversion.
  3. Prime superscripts: if the group contains a mirror m aligned with a principal  rotation axis, but does not contain inversion, indicate whether irrep is symmetric (′)  or antisymmetric (′′) under this mirror.
  4. Numeral subscripts: the rules for assignment of numeral subscripts are too complicated in general - and indeed, we are unaware of a general coherent rule – to describe here.
References
source
Crystalline.nontrivial_factors — Method
nontrivial_factors(F::Smith) -> Any
+
Return the nontrivial (i.e., ≠ {0,1}) elementary factors of an EBR basis, provided as a BandRepSet or Smith decomposition.
source
Crystalline.normscale! — Method
normscale!(flat::ModulatedFourierLattice, expon::Real,
+           Gs::Union{ReciprocalBasis, Nothing} = nothing) --> ModulatedFourierLattice
In-place equivalent of normscale: mutates flat.
source
Crystalline.normscale — Method
normscale(flat::ModulatedFourierLattice, expon::Real, 
+          Gs::Union{ReciprocalBasis, Nothing} = nothing)  --> ModulatedFourierLattice
Applies inverse-orbit norm rescaling of expansion coefficients with a norm exponent expon. If Gs is nothing, the orbit norm is computed in the lattice basis (and, so, is not strictly a norm); by providing Gs as ReciprocalBasis, the norm is evaluated correctly in cartesian setting. See further discussion in modulate.
An in-place equivalent is provided in normscale!.
source
Crystalline.num — Method
num(g::AbstractGroup) -> Int
Return the conventional number assigned to the group g.
source
Crystalline.occupation — Method
occupation(n::AbstractSymmetryVector) -> Int
Return the occupation of (i.e., number of bands contained within) n.
source
Crystalline.operations — Method
operations(g::AbstractGroup) -> Vector{<:AbstractOperation}
Return an Vector containing the operations of the group g.
source
Crystalline.orbit — Method
orbit(g::SiteGroup)  -->  Vector{WyckoffPosition}
Compute the orbit of the Wyckoff position associated with the site symmetry group g.
Extended help
The orbit of a Wyckoff position $\mathbf{r}$ in a space group $G$ is defined as the set of inequivalent points in the unit cell that can be obtained by applying the elements of $G$ to $\mathbf{r}$. Equivalently, every element of the orbit of $\mathbf{r}$ can be written as the composition of a coset representative of the Wyckoff position's site group in $G$ with $\mathbf{r}$.
source
Crystalline.orbit — Method
orbit(g::AbstractVector{<:SymOperation}, kv::KVec, cntr::Char)  -->  Vector{KVec{D}}
 orbit(lg::LittleGroup)
-orbit(lgir::LGIrrep)
Return the orbit of of the reciprocal-space vector kv under the action of the group g, also known as the star of k.
The orbit of kv in g is the set of inequivalent k-points obtained by composition of all the symmetry operations of g with kv. Two reciprocal vectors $\mathbf{k}$ and $\mathbf{k}'$ are equivalent if they differ by a primitive reciprocal lattice vector.
If kv and g are specified in a conventional basis but refer to a non-primitive lattice, the centering type cntr must be provided to ensure that only equivalence by primitive (not conventional) reciprocal lattice vectors are considered. If the centering type of the group g can be inferred from g (e.g., if g is a SpaceGroup), orbit will assume a conventional setting and use the inferred centering type; otherwise, if cntr is neither explicitly set nor inferrable, a primitive setting is assumed.
source
Crystalline.pgirreps — Function
pgirreps(iuclab::String, ::Val{D}=Val(3); mullikken::Bool=false) where D ∈ (1,2,3)
-pgirreps(iuclab::String, D; mullikken::Bool=false)
Return the (crystallographic) point group irreps of the IUC label iuclab of dimension D as a Vector{PGIrrep{D}}.
See Crystalline.PG_IUC2NUM[D] for possible IUC labels in dimension D.
Notation
The irrep labelling follows the conventions of CDML [1] [which occasionally differ from those in e.g. Bradley and Cracknell, The Mathematical Theory of Symmetry in Solids  (1972)].
To use Mulliken ("spectroscopist") irrep labels instead, set the keyword argument mulliken = true (default, false). See also mulliken.
Data sources
The data is sourced from the Bilbao Crystallographic Server [2]. If you are using this  functionality in an explicit fashion, please cite the original reference [3].
References
source
Crystalline.pointgroup — Method
pointgroup(ops:AbstractVector{SymOperation{D}})
-pointgroup(sg::AbstractGroup)
Computes the point group associated with a space group sg (characterized by a set of operators ops, which, jointly with lattice translations generate  the space group), obtained by "taking away" any translational parts and  then reducing to the resulting unique rotational operations. (technically, in the language of Bradley & Cracknell, this is the so-called isogonal point group of sg; see Sec. 1.5).
Returns a Vector of SymOperations.
source
Crystalline.pointgroup — Method
pointgroup(iuclab::String, ::Union{Val{D}, Integer}=Val(3))  -->  PointGroup{D}
Return the symmetry operations associated with the point group identified with label iuclab in dimension D as a PointGroup{D}.
source
Crystalline.pointgroup — Method
pointgroup(pgnum::Integer, ::Union{Val{D}, Integer}=Val(3), setting::Integer=1)
-                                                                  -->  PointGroup{D}
Return the symmetry operations associated with the point group identfied with canonical number pgnum in dimension D as a PointGroup{D}. The connection between a point group's numbering and its IUC label is enumerated in Crystalline.PG_NUM2IUC[D] and Crystalline.IUC2NUM[D].
Certain point groups feature in multiple setting variants: e.g., IUC labels 321 and 312 both correspond to pgnum = 18 and correspond to the same group structure expressed in two different settings. The setting argument allows choosing between these setting variations.
source
Crystalline.realify! — Method
realify!(lgirsd::AbstractDict{<:AbstractIrrep, <:AbstractVector{<:AbstractIrrep}})
Apply realify to each value of lgirsd in-place, returning the mutated lgirsd.
source
Crystalline.realify — Method
realify(lgirsd::AbstractDict{<:AbstractIrrep, <:AbstractVector{<:AbstractIrrep}}) 
-                    --> Dict{<:AbstractIrrep, <:AbstractVector{<:AbstractIrrep}}
Apply realify to each value of lgirsd, returning a new Dict of realified irreps.
source
Crystalline.realify — Method
realify(lgirs::AbstractVector{<:LGIrrep}; verbose::Bool=false)
-                                                    --> AbstractVector{<:LGIrrep}
From lgirs, a vector of LGIrreps, determine the associated (gray) co-representations, i.e. the "real", or "physical" irreps that are relevant in scenarios with time-reversal symmetry.
For LGIrrep that are REAL, or that characterize a k-point 𝐤 which is not equivalent to -𝐤 (i.e. its star does not include both 𝐤 and -𝐤; equivalently, the little group includes time-reversal symmetry), the associated co-representations are just the  original irreps themselves.  For PSEUDOREAL and COMPLEX LGIrreps where ±𝐤 are equivalent, the associated co-representations are built from pairs of irreps that "stick" together. This method computes this pairing and sets the LGIrrep field iscorep to true, to indicate that the resulting "paired irrep" (i.e. the co-representation) should be doubled with  itself (PSEUDOREAL reality) or its complex conjugate (COMPLEX reality).
Background
For background, see p. 650-652 (and p. 622-626 for point groups) in Bradley & Cracknell's book. Their discussion is for magnetic groups (the "realified" irreps are, in fact, simply co-representations of the "gray" magnetic groups).  Cornwell's book also explicates this at some length as does Inui et al. (p. 296-299).
Keyword arguments
  • verbose::Bool: if set to true, prints details about mapping from small irrep to small
corep for each LGIrrep (default: false).
source
Crystalline.realify — Method
realify(pgirs::AbstractVector{T}) where T<:AbstractIrrep --> Vector{T}
Return physically real irreps (coreps) from a set of conventional irreps (as produced by e.g. pgirreps). Fallback method for point-group-like AbstractIrreps.
Example
julia> pgirs = pgirreps("4", Val(3));
+orbit(lgir::LGIrrep)
Return the orbit of of the reciprocal-space vector kv under the action of the group g, also known as the star of k.
The orbit of kv in g is the set of inequivalent k-points obtained by composition of all the symmetry operations of g with kv. Two reciprocal vectors $\mathbf{k}$ and $\mathbf{k}'$ are equivalent if they differ by a primitive reciprocal lattice vector.
If kv and g are specified in a conventional basis but refer to a non-primitive lattice, the centering type cntr must be provided to ensure that only equivalence by primitive (not conventional) reciprocal lattice vectors are considered. If the centering type of the group g can be inferred from g (e.g., if g is a SpaceGroup), orbit will assume a conventional setting and use the inferred centering type; otherwise, if cntr is neither explicitly set nor inferrable, a primitive setting is assumed.
source
Crystalline.pgirreps — Function
pgirreps(iuclab::String, ::Val{D}=Val(3); mullikken::Bool=false) where D ∈ (1,2,3)
+pgirreps(iuclab::String, D; mullikken::Bool=false)
Return the (crystallographic) point group irreps of the IUC label iuclab of dimension D as a Vector{PGIrrep{D}}.
See Crystalline.PG_IUC2NUM[D] for possible IUC labels in dimension D.
Notation
The irrep labelling follows the conventions of CDML [1] [which occasionally differ from those in e.g. Bradley and Cracknell, The Mathematical Theory of Symmetry in Solids  (1972)].
To use Mulliken ("spectroscopist") irrep labels instead, set the keyword argument mulliken = true (default, false). See also mulliken.
Data sources
The data is sourced from the Bilbao Crystallographic Server [2]. If you are using this  functionality in an explicit fashion, please cite the original reference [3].
References
source
Crystalline.pointgroup — Method
pointgroup(ops:AbstractVector{SymOperation{D}})
+pointgroup(sg::AbstractGroup)
Computes the point group associated with a space group sg (characterized by a set of operators ops, which, jointly with lattice translations generate  the space group), obtained by "taking away" any translational parts and  then reducing to the resulting unique rotational operations. (technically, in the language of Bradley & Cracknell, this is the so-called isogonal point group of sg; see Sec. 1.5).
Returns a Vector of SymOperations.
source
Crystalline.pointgroup — Method
pointgroup(iuclab::String, ::Union{Val{D}, Integer}=Val(3))  -->  PointGroup{D}
Return the symmetry operations associated with the point group identified with label iuclab in dimension D as a PointGroup{D}.
source
Crystalline.pointgroup — Method
pointgroup(pgnum::Integer, ::Union{Val{D}, Integer}=Val(3), setting::Integer=1)
+                                                                  -->  PointGroup{D}
Return the symmetry operations associated with the point group identfied with canonical number pgnum in dimension D as a PointGroup{D}. The connection between a point group's numbering and its IUC label is enumerated in Crystalline.PG_NUM2IUC[D] and Crystalline.IUC2NUM[D].
Certain point groups feature in multiple setting variants: e.g., IUC labels 321 and 312 both correspond to pgnum = 18 and correspond to the same group structure expressed in two different settings. The setting argument allows choosing between these setting variations.
source
Crystalline.realify! — Method
realify!(lgirsd::AbstractDict{<:AbstractIrrep, <:AbstractVector{<:AbstractIrrep}})
Apply realify to each value of lgirsd in-place, returning the mutated lgirsd.
source
Crystalline.realify — Method
realify(lgirsd::AbstractDict{<:AbstractIrrep, <:AbstractVector{<:AbstractIrrep}}) 
+                    --> Dict{<:AbstractIrrep, <:AbstractVector{<:AbstractIrrep}}
Apply realify to each value of lgirsd, returning a new Dict of realified irreps.
source
Crystalline.realify — Method
realify(lgirs::AbstractVector{<:LGIrrep}; verbose::Bool=false)
+                                                    --> AbstractVector{<:LGIrrep}
From lgirs, a vector of LGIrreps, determine the associated (gray) co-representations, i.e. the "real", or "physical" irreps that are relevant in scenarios with time-reversal symmetry.
For LGIrrep that are REAL, or that characterize a k-point 𝐤 which is not equivalent to -𝐤 (i.e. its star does not include both 𝐤 and -𝐤; equivalently, the little group includes time-reversal symmetry), the associated co-representations are just the  original irreps themselves.  For PSEUDOREAL and COMPLEX LGIrreps where ±𝐤 are equivalent, the associated co-representations are built from pairs of irreps that "stick" together. This method computes this pairing and sets the LGIrrep field iscorep to true, to indicate that the resulting "paired irrep" (i.e. the co-representation) should be doubled with  itself (PSEUDOREAL reality) or its complex conjugate (COMPLEX reality).
Background
For background, see p. 650-652 (and p. 622-626 for point groups) in Bradley & Cracknell's book. Their discussion is for magnetic groups (the "realified" irreps are, in fact, simply co-representations of the "gray" magnetic groups).  Cornwell's book also explicates this at some length as does Inui et al. (p. 296-299).
Keyword arguments
  • verbose::Bool: if set to true, prints details about mapping from small irrep to small
corep for each LGIrrep (default: false).
source
Crystalline.realify — Method
realify(pgirs::AbstractVector{T}) where T<:AbstractIrrep --> Vector{T}
Return physically real irreps (coreps) from a set of conventional irreps (as produced by e.g. pgirreps). Fallback method for point-group-like AbstractIrreps.
Example
julia> pgirs = pgirreps("4", Val(3));
 julia> characters(pgirs)
 CharacterTable{3}: ⋕9 (4)
 ───────┬────────────────────
@@ -176,10 +176,10 @@
   2₀₀₁ │  1   1    -2
  4₀₀₁⁺ │  1  -1     0
  4₀₀₁⁻ │  1  -1     0
-───────┴──────────────
source
Crystalline.reduce_ops — Method
reduce_ops(ops::AbstractVector{SymOperation{D}},
+───────┴──────────────
source
Crystalline.reduce_ops — Method
reduce_ops(ops::AbstractVector{SymOperation{D}},
            cntr::Char,
            conv_or_prim::Bool=true,
-           modw::Bool=true) --> Vector{SymOperation{D}}
Reduce the operations ops, removing operations that are identical in the primitive basis associated with the centering cntr. 
If conv_or_prim = false, the reduced operations are returned in the primitive basis associated with cntr; otherwise, in the conventional. If modw = true, the comparison in the primitive basis is done modulo unit primitive lattice vectors; otherwise not. A final argument of type ::Val{P} can be specified to indicate a subperiodic group of periodicity dimension P, different from the spatial embedding dimension D.
source
Crystalline.rotation — Method
rotation(op::AbstractOperation{D}) --> SMatrix{D, D, Float64}
Return the D×Drotation part ofop`.
source
Crystalline.seitz — Method
seitz(op::SymOperation) --> String
Computes the correponding Seitz notation for a symmetry operation in triplet/xyzt form.
Implementation based on ITA5 Table 11.2.1.1, with 3D point group parts inferred from the trace and determinant of the matrix $\mathb{W}$ in the triplet $\{\mathbf{W}|\mathbf{w}\}$.
detW/trW-3-2-10123
123461
-1-1-6-4-3m
with the elements of the table giving the type of symmetry operation in in Hermann-Mauguin notation. The rotation axis and the rotation sense are computed following the rules in ITA6 Sec. 1.2.2.4(1)(b-c). See also .
Note that the orientation of the axis (i.e. its sign) does not necessarily match the orientation picked in Tables 1.4.2.1-5 of ITA6; it is a matter of (arbitrary) convention, and the conventions have not been explicated in ITA.
2D operations are treated by the same procedure, by elevation in a third dimension; 1D operations by a simple inspection of sign.
source
Crystalline.sitegroup — Method
sitegroup(
+           modw::Bool=true) --> Vector{SymOperation{D}}
Reduce the operations ops, removing operations that are identical in the primitive basis associated with the centering cntr. 
If conv_or_prim = false, the reduced operations are returned in the primitive basis associated with cntr; otherwise, in the conventional. If modw = true, the comparison in the primitive basis is done modulo unit primitive lattice vectors; otherwise not. A final argument of type ::Val{P} can be specified to indicate a subperiodic group of periodicity dimension P, different from the spatial embedding dimension D.
source
Crystalline.rotation — Method
rotation(op::AbstractOperation{D}) --> SMatrix{D, D, Float64}
Return the D×Drotation part ofop`.
source
Crystalline.seitz — Method
seitz(op::SymOperation) --> String
Computes the correponding Seitz notation for a symmetry operation in triplet/xyzt form.
Implementation based on ITA5 Table 11.2.1.1, with 3D point group parts inferred from the trace and determinant of the matrix $\mathb{W}$ in the triplet $\{\mathbf{W}|\mathbf{w}\}$.
detW/trW-3-2-10123
123461
-1-1-6-4-3m
with the elements of the table giving the type of symmetry operation in in Hermann-Mauguin notation. The rotation axis and the rotation sense are computed following the rules in ITA6 Sec. 1.2.2.4(1)(b-c). See also .
Note that the orientation of the axis (i.e. its sign) does not necessarily match the orientation picked in Tables 1.4.2.1-5 of ITA6; it is a matter of (arbitrary) convention, and the conventions have not been explicated in ITA.
2D operations are treated by the same procedure, by elevation in a third dimension; 1D operations by a simple inspection of sign.
source
Crystalline.sitegroup — Method
sitegroup(
     sg::SpaceGroup{D},
     wp::WyckoffPosition{D}
 ) -> SiteGroup
@@ -207,8 +207,8 @@
 ──────────┴──────────────────────────────
The original space group can be reconstructed from a left-coset decomposition, using the operations and cosets contained in a SiteGroup:
julia> ops = [opʰ*opᵍ for opʰ in cosets(g) for opᵍ in g];
 
 julia> Set(sg) == Set(ops)
-true
Terminology
Mathematically, the site symmetry group is a stabilizer group for a Wyckoff position, in the same sense that the little group of k is a stabilizer group for a k-point.
See also sitegroups for calculation of all site symmetry groups of a given space group.
source
Crystalline.sitegroups — Method
sitegroups(sg::SpaceGroup{D}) -> Any
-
Return all site symmetry groups associated with a space group, specified either as  sg :: SpaceGroup{D} or by its conventional number sgnum and dimension D.
See also sitegroup for calculation of the site symmetry group of a specific Wyckoff position.
source
Crystalline.siteirreps — Method
siteirreps(sitegroup::SiteGroup; mulliken::Bool=false]) --> Vector{PGIrrep}
Return the site symmetry irreps associated with the provided SiteGroup, obtained from a search over isomorphic point groups. The SiteIrreps are in general a permutation of the irreps of the associated isomorphic point group.
By default, the labels of the site symmetry irreps are given in the CDML notation; to use the Mulliken notation, set the keyword argument mulliken to true (default, false).
Example
julia> sgnum = 16;
+true
Terminology
Mathematically, the site symmetry group is a stabilizer group for a Wyckoff position, in the same sense that the little group of k is a stabilizer group for a k-point.
See also sitegroups for calculation of all site symmetry groups of a given space group.
source
Crystalline.sitegroups — Method
sitegroups(sg::SpaceGroup{D}) -> Any
+
Return all site symmetry groups associated with a space group, specified either as  sg :: SpaceGroup{D} or by its conventional number sgnum and dimension D.
See also sitegroup for calculation of the site symmetry group of a specific Wyckoff position.
source
Crystalline.siteirreps — Method
siteirreps(sitegroup::SiteGroup; mulliken::Bool=false]) --> Vector{PGIrrep}
Return the site symmetry irreps associated with the provided SiteGroup, obtained from a search over isomorphic point groups. The SiteIrreps are in general a permutation of the irreps of the associated isomorphic point group.
By default, the labels of the site symmetry irreps are given in the CDML notation; to use the Mulliken notation, set the keyword argument mulliken to true (default, false).
Example
julia> sgnum = 16;
 
 julia> sg = spacegroup(sgnum, 2);
 
@@ -252,20 +252,20 @@
     │
     ├─ {3⁻|0,1}: ───────────────────── (-x+y,-x+1)
     │     exp(0.6667iπ)
-    └─────────────────────────────────────────────
source
Crystalline.spacegroup — Method
spacegroup(sgnum::Integer, ::Val{D}=Val(3))
-spacegroup(sgnum::Integer, D::Integer)          --> SpaceGroup{D}
Return the space group symmetry operations for a given space group number sgnum and  dimensionality D as a SpaceGroup{D}. The returned symmetry operations are specified relative to the conventional basis vectors, i.e. are not necessarily primitive (see centering). If desired, operations for the primitive unit cell can subsequently be generated using  primitivize or Crystalline.reduce_ops.
The default choices for the conventional basis vectors follow the conventions of the Bilbao Crystallographic Server (or, equivalently, the International Tables of Crystallography),  which are:
  • Unique axis b (cell choice 1) for monoclinic space groups.
  • Obverse triple hexagonal unit cell for rhombohedral space groups.
  • Origin choice 2: inversion centers are placed at (0,0,0). (relevant for certain centrosymmetric space groups with two possible choices; e.g., in the orthorhombic, tetragonal or cubic crystal systems).
See also directbasis.
Data sources
The symmetry operations returned by this function were originally retrieved from the Bilbao Crystallographic Server, SPACEGROUP GENPOS. The associated citation is: (Aroyo et al., Z. Kristallogr. Cryst. Mater. 221, 15 (2006).).
source
Crystalline.subduction_count — Method
subduction_count(Dᴳᵢ, Dᴴⱼ[, αβγᴴⱼ]) --> Int
For two groups $G$ and $H$, where $H$ is a subgroup of $G$, i.e. $H<G$, with associated irreducible representations Dᴳᵢ = $D^G_i(g)$ and Dᴴⱼ = $D^H_j(g)$ over operations $g∈G$ and $h∈H<G$, compute the compatibility relation between the two irreps from the subduction reduction formula (or "magic" formula/Schur orthogonality relation), returning how many times $n^{GH}_{ij}$ the subduced representation $D^G_i↓H$ contains  the irrep $D^H_j$; in other words, this gives the compatibility between the two irreps.
Optionally, a vector αβγᴴⱼ may be provided, to evaluate the characters/irreps  of Dᴳᵢ at a concrete value of $(α,β,γ)$. This is e.g. meaningful for LGIrreps at non-special k-vectors. Defaults to nothing.
The result is computed using the reduction formula [see e.g. Eq. (15) of arXiv:1706.09272v2]:
$n^{GH}_{ij} = |H|^{-1} \sum_h \chi^G_i(h)\chi^H_j(h)^*$
Example
Consider the two compatible k-vectors Γ (a point) and Σ (a line) in space group 207:
lgirsd  = lgirreps(207, Val(3));
+    └─────────────────────────────────────────────
source
Crystalline.spacegroup — Method
spacegroup(sgnum::Integer, ::Val{D}=Val(3))
+spacegroup(sgnum::Integer, D::Integer)          --> SpaceGroup{D}
Return the space group symmetry operations for a given space group number sgnum and  dimensionality D as a SpaceGroup{D}. The returned symmetry operations are specified relative to the conventional basis vectors, i.e. are not necessarily primitive (see centering). If desired, operations for the primitive unit cell can subsequently be generated using  primitivize or Crystalline.reduce_ops.
The default choices for the conventional basis vectors follow the conventions of the Bilbao Crystallographic Server (or, equivalently, the International Tables of Crystallography),  which are:
  • Unique axis b (cell choice 1) for monoclinic space groups.
  • Obverse triple hexagonal unit cell for rhombohedral space groups.
  • Origin choice 2: inversion centers are placed at (0,0,0). (relevant for certain centrosymmetric space groups with two possible choices; e.g., in the orthorhombic, tetragonal or cubic crystal systems).
See also directbasis.
Data sources
The symmetry operations returned by this function were originally retrieved from the Bilbao Crystallographic Server, SPACEGROUP GENPOS. The associated citation is: (Aroyo et al., Z. Kristallogr. Cryst. Mater. 221, 15 (2006).).
source
Crystalline.subduction_count — Method
subduction_count(Dᴳᵢ, Dᴴⱼ[, αβγᴴⱼ]) --> Int
For two groups $G$ and $H$, where $H$ is a subgroup of $G$, i.e. $H<G$, with associated irreducible representations Dᴳᵢ = $D^G_i(g)$ and Dᴴⱼ = $D^H_j(g)$ over operations $g∈G$ and $h∈H<G$, compute the compatibility relation between the two irreps from the subduction reduction formula (or "magic" formula/Schur orthogonality relation), returning how many times $n^{GH}_{ij}$ the subduced representation $D^G_i↓H$ contains  the irrep $D^H_j$; in other words, this gives the compatibility between the two irreps.
Optionally, a vector αβγᴴⱼ may be provided, to evaluate the characters/irreps  of Dᴳᵢ at a concrete value of $(α,β,γ)$. This is e.g. meaningful for LGIrreps at non-special k-vectors. Defaults to nothing.
The result is computed using the reduction formula [see e.g. Eq. (15) of arXiv:1706.09272v2]:
$n^{GH}_{ij} = |H|^{-1} \sum_h \chi^G_i(h)\chi^H_j(h)^*$
Example
Consider the two compatible k-vectors Γ (a point) and Σ (a line) in space group 207:
lgirsd  = lgirreps(207, Val(3));
 Γ_lgirs = lgirsd["Γ"]; # at Γ ≡ [0.0, 0.0, 0.0]
 Σ_lgirs = lgirsd["Σ"]; # at Σ ≡ [α, α, 0.0]
We can test their compatibility via:
[[subduction_count(Γi, Σj) for Γi in Γ_lgirs] for Σj in Σ_lgirs]
 > # Γ₁ Γ₂ Γ₃ Γ₄ Γ₅
 >  [ 1, 0, 1, 1, 2] # Σ₁
->  [ 0, 1, 1, 2, 1] # Σ₂
With following enterpretatation for compatibility relations between irreps at Γ and Σ:
Compatibility relationDegeneracies
Γ₁ → Σ₁1 → 1
Γ₂ → Σ₂1 → 1
Γ₃ → Σ₁ + Σ₂2 → 1 + 1
Γ₄ → Σ₁ + 2Σ₂3 → 1 + 2
Γ₅ → 2Σ₁ + Σ₂3 → 2 + 1
where, in this case, all the small irreps are one-dimensional.
source
Crystalline.subperiodicgroup — Method
subperiodicgroup(num::Integer, ::Val{D}=Val(3), ::Val{P}=Val(2))
+>  [ 0, 1, 1, 2, 1] # Σ₂
With following enterpretatation for compatibility relations between irreps at Γ and Σ:
Compatibility relationDegeneracies
Γ₁ → Σ₁1 → 1
Γ₂ → Σ₂1 → 1
Γ₃ → Σ₁ + Σ₂2 → 1 + 1
Γ₄ → Σ₁ + 2Σ₂3 → 1 + 2
Γ₅ → 2Σ₁ + Σ₂3 → 2 + 1
where, in this case, all the small irreps are one-dimensional.
source
Crystalline.subperiodicgroup — Method
subperiodicgroup(num::Integer, ::Val{D}=Val(3), ::Val{P}=Val(2))
 subperiodicgroup(num::Integer, D::Integer, P::Integer)
                                                         --> ::SubperiodicGroup{D,P}
Return the operations of the subperiodic group num of embedding dimension D and periodicity dimension P as a SubperiodicGroup{D,P}.
The setting choices are those of the International Tables for Crystallography, Volume E.
Allowed combinations of D and P and their associated group names are:
  • D = 3, P = 2: Layer groups (num = 1, …, 80).
  • D = 3, P = 1: Rod groups (num = 1, …, 75).
  • D = 2, P = 1: Frieze groups (num = 1, …, 7).
Example
julia> subperiodicgroup(7, Val(2), Val(1))
 SubperiodicGroup{2, 1} ⋕7 (𝓅2mg) with 4 operations:
  1
  2
  {m₁₀|½,0}
- {m₀₁|½,0}
Data sources
The symmetry operations returned by this function were originally retrieved from the Bilbao Crystallographic Database, SUBPERIODIC GENPOS.
source
Crystalline.surface_basis — Method
surface_basis(Rs, n; cartesian=true)
Compute a basis for the surface-cell obtained from terminating a 3D lattice Rs over a surface surface specified by its normal vector n (or Miller indices if cartesian=false).
Output
The function returns a tuple (rs³ᴰ, rs′²ᴰ, P), whose elements are described below:
  • rs³ᴰ: a DirectBasis{3}, whose first two basis vectors lie in the plane of the surface, and whose third vector is (positively) aligned with the surface normal. All basis vectors correspond to points in the original direct lattice.
  • rs′²ᴰ: a DirectBasis{2}, whose basis vectors are given in the local coordinate system of the surface unit cell; effectively, this is $(x,y)$-components of rs³ᴰ after a rotation that takes n to $\hat{\mathbf{z}}$. The first basis vector is aligned with the $\hat{\mathbf{x}}$-direction of the local coordinate system.
  • P: a rotation matrix that takes rs³ᴰ to the local n-to-$\hat{\mathbf{z}}$ rotated coordinate system of rs′²ᴰ. In particular, defining rs′³ᴰ = transform.(DirectPoint.(rs³ᴰ), Ref(P)), the following  holds: 	- rs′³ᴰ[i] ≈ [rs′²ᴰ[i]..., 0] for i ∈ 1:2, 	- rs′³ᴰ[3] is (positively) aligned with [0,0,1]. To transform the other way, i.e., from surface-local to lattice-global coordinates, simply use P⁻¹ = transpose(P) instead.
The returned basis is right-handed.
Keyword arguments
  • cartesian :: Bool = true: whether the surface normal n is specified in Cartesian coordinates (true) or in the basis of the reciprocal lattice vectors (false), i.e., corresponding to the Cartesian vector n[1]*Gs[1] + n[2]*Gs[2] + n[3]*Gs with Gs denoting the Cartesian representation of the reciprocal lattice vectors, i.e., Gs = reciprocalbasis(Rs). The latter case (false) is a specification of the surface in terms of its Miller indices: the coordinates of n can then equivalently be interpreted as the inverse of the surface's intercept with each of the axes spanned by Rs.
Example
julia> sgnum = 195; # P23, a cubic lattice
+ {m₀₁|½,0}
Data sources
The symmetry operations returned by this function were originally retrieved from the Bilbao Crystallographic Database, SUBPERIODIC GENPOS.
source
Crystalline.surface_basis — Method
surface_basis(Rs, n; cartesian=true)
Compute a basis for the surface-cell obtained from terminating a 3D lattice Rs over a surface surface specified by its normal vector n (or Miller indices if cartesian=false).
Output
The function returns a tuple (rs³ᴰ, rs′²ᴰ, P), whose elements are described below:
  • rs³ᴰ: a DirectBasis{3}, whose first two basis vectors lie in the plane of the surface, and whose third vector is (positively) aligned with the surface normal. All basis vectors correspond to points in the original direct lattice.
  • rs′²ᴰ: a DirectBasis{2}, whose basis vectors are given in the local coordinate system of the surface unit cell; effectively, this is $(x,y)$-components of rs³ᴰ after a rotation that takes n to $\hat{\mathbf{z}}$. The first basis vector is aligned with the $\hat{\mathbf{x}}$-direction of the local coordinate system.
  • P: a rotation matrix that takes rs³ᴰ to the local n-to-$\hat{\mathbf{z}}$ rotated coordinate system of rs′²ᴰ. In particular, defining rs′³ᴰ = transform.(DirectPoint.(rs³ᴰ), Ref(P)), the following  holds: 	- rs′³ᴰ[i] ≈ [rs′²ᴰ[i]..., 0] for i ∈ 1:2, 	- rs′³ᴰ[3] is (positively) aligned with [0,0,1]. To transform the other way, i.e., from surface-local to lattice-global coordinates, simply use P⁻¹ = transpose(P) instead.
The returned basis is right-handed.
Keyword arguments
  • cartesian :: Bool = true: whether the surface normal n is specified in Cartesian coordinates (true) or in the basis of the reciprocal lattice vectors (false), i.e., corresponding to the Cartesian vector n[1]*Gs[1] + n[2]*Gs[2] + n[3]*Gs with Gs denoting the Cartesian representation of the reciprocal lattice vectors, i.e., Gs = reciprocalbasis(Rs). The latter case (false) is a specification of the surface in terms of its Miller indices: the coordinates of n can then equivalently be interpreted as the inverse of the surface's intercept with each of the axes spanned by Rs.
Example
julia> sgnum = 195; # P23, a cubic lattice
 
 julia> Rs = directbasis(sgnum, 3)
 DirectBasis{3} (cubic):
@@ -292,14 +292,14 @@
 DirectBasis{3} (hexagonal):
  [1.414213562373095, -1.1102230246251563e-16, 0.0]
  [-0.7071067811865476, 1.2247448713915885, 0.0]
- [0.0, -1.1102230246251563e-16, 1.7320508075688772]
Warning
This function will likely be moved from Crystalline to Bravais.jl at some point in the future.
source
Crystalline.translation — Method
translation(op::AbstractOperation{D}) --> SVector{D, Float64}
Return the D-dimensional translation part of op.
source
Crystalline.wyckoffs — Method
wyckoffs(sgnum::Integer) -> Vector{WyckoffPosition{3}}
+ [0.0, -1.1102230246251563e-16, 1.7320508075688772]
Warning
This function will likely be moved from Crystalline to Bravais.jl at some point in the future.
source
Crystalline.translation — Method
translation(op::AbstractOperation{D}) --> SVector{D, Float64}
Return the D-dimensional translation part of op.
source
Crystalline.wyckoffs — Method
wyckoffs(sgnum::Integer) -> Vector{WyckoffPosition{3}}
 wyckoffs(sgnum::Integer, ::Val{D}) -> Any
 
Return the Wyckoff positions of space group sgnum in dimension D as a  Vector{WyckoffPosition{D}.
The positions are given in the conventional basis setting, following the conventions of the Bilbao Crystallographic Server (from which the underlying data is sourced [1]).
Example
julia> wps = wyckoffs(16, 2)
 4-element Vector{WyckoffPosition{2}}:
  6d: [α, β]
  3c: [1/2, 0]
  2b: [1/3, 2/3]
- 1a: [0, 0]
References
source
Exported macros
Crystalline.@S_str — Macro
@S_str -> SymOperation
Construct a SymOperation from a triplet form given as a string.
Example
julia> S"-y,x"
+ 1a: [0, 0]
References
source
Exported macros
Crystalline.@S_str — Macro
@S_str -> SymOperation
Construct a SymOperation from a triplet form given as a string.
Example
julia> S"-y,x"
 4⁺ ──────────────────────────────── (-y,x)
  ┌ 0 -1 ╷ 0 ┐
- └ 1  0 ╵ 0 ┘
source
Exported constants
Crystalline.ENANTIOMORPHIC_PAIRS — Constant
ENANTIOMORPHIC_PAIRS :: NTuple{11, Pair{Int,Int}}
Return the space group numbers of the 11 enantiomorphic space group pairs in 3D.
The space group types associated with each such pair (sgnum, sgnum') are related by a mirror transformation: i.e. there exists a transformation  $\mathbb{P} = \{\mathbf{P}|\mathbf{p}\}$ between the two groups $G = \{g\}$ and $G' = \{g'\}$ such that $G' = \mathbb{P}^{-1}G\mathbb{P}$ where $\mathbf{P}$ is improper (i.e. $\mathrm{det}\mathbf{P} < 0$).
We define distinct space group types as those that cannot be related by a proper transformation (i.e. with $\mathrm{det}\mathbf{P} > 0$). With that view, there are 230 space group types. If the condition is relaxed to allow improper rotations, there are  $230-11 = 219$ distinct affine space group types. See e.g. ITA5 Section 8.2.2.
The enantiomorphic space group types are also chiral space group types in 3D. There are no enantiomorphic pairs in lower dimensions; in 3D all enantiomorphic pairs involve screw symmetries, whose direction is inverted between pairs (i.e. have opposite handedness).
source
Crystalline.MAX_MSGNUM — Constant
MAX_MSGNUM :: Tuple{Int,Int,Int}
Analogous to MAX_SUBGNUM, but for the number of magnetic space groups.
source
Crystalline.MAX_MSUBGNUM — Constant
MAX_MSUBGNUM :: Tuple{Int,Int,Int}
Analogous to MAX_SUBGNUM, but for the number of magnetic subperiodic groups.
source
Crystalline.MAX_SGNUM — Constant
MAX_SGNUM :: Tuple{Int,Int,Int}
Return the number of distinct space group types across dimensions 1, 2, and 3 (indexable by dimensionality).
source
Crystalline.MAX_SUBGNUM — Constant
MAX_SUBGNUM :: ImmutableDict
An immutable dictionary with values v::Int and keys k::Tuple{Int,Int}, where v is the number of distinct subperiodic group types for a given key k = (D,P) describing a subperiodic group of dimensionality D and periodicity P:
  • layer groups: (D,P) = (3,2)
  • rod groups: (D,P) = (3,1)
  • frieze groups: (D,P) = (2,1)
source

+ └ 1  0 ╵ 0 ┘
source

Exported constants

Crystalline.ENANTIOMORPHIC_PAIRS — Constant
ENANTIOMORPHIC_PAIRS :: NTuple{11, Pair{Int,Int}}

Return the space group numbers of the 11 enantiomorphic space group pairs in 3D.

The space group types associated with each such pair (sgnum, sgnum') are related by a mirror transformation: i.e. there exists a transformation $\mathbb{P} = \{\mathbf{P}|\mathbf{p}\}$ between the two groups $G = \{g\}$ and $G' = \{g'\}$ such that $G' = \mathbb{P}^{-1}G\mathbb{P}$ where $\mathbf{P}$ is improper (i.e. $\mathrm{det}\mathbf{P} < 0$).

We define distinct space group types as those that cannot be related by a proper transformation (i.e. with $\mathrm{det}\mathbf{P} > 0$). With that view, there are 230 space group types. If the condition is relaxed to allow improper rotations, there are $230-11 = 219$ distinct affine space group types. See e.g. ITA5 Section 8.2.2.

The enantiomorphic space group types are also chiral space group types in 3D. There are no enantiomorphic pairs in lower dimensions; in 3D all enantiomorphic pairs involve screw symmetries, whose direction is inverted between pairs (i.e. have opposite handedness).

source
Crystalline.MAX_MSGNUM — Constant
MAX_MSGNUM :: Tuple{Int,Int,Int}

Analogous to MAX_SUBGNUM, but for the number of magnetic space groups.

source
Crystalline.MAX_MSUBGNUM — Constant
MAX_MSUBGNUM :: Tuple{Int,Int,Int}

Analogous to MAX_SUBGNUM, but for the number of magnetic subperiodic groups.

source
Crystalline.MAX_SGNUM — Constant
MAX_SGNUM :: Tuple{Int,Int,Int}

Return the number of distinct space group types across dimensions 1, 2, and 3 (indexable by dimensionality).

source
Crystalline.MAX_SUBGNUM — Constant
MAX_SUBGNUM :: ImmutableDict

An immutable dictionary with values v::Int and keys k::Tuple{Int,Int}, where v is the number of distinct subperiodic group types for a given key k = (D,P) describing a subperiodic group of dimensionality D and periodicity P:

  • layer groups: (D,P) = (3,2)
  • rod groups: (D,P) = (3,1)
  • frieze groups: (D,P) = (2,1)
source
diff --git a/previews/PR49/bandreps/index.html b/previews/PR49/bandreps/index.html index 2700325b..bf0582a2 100644 --- a/previews/PR49/bandreps/index.html +++ b/previews/PR49/bandreps/index.html @@ -25,5 +25,5 @@ ──────┴──────────────────────────────────────────────── KVecs: Γ, X, L, W

which returns a BandRepSet, which itself is an AbstractVector of BandReps. This allows us to index into brs easily:

brs[1] # obtain the EBR induced by Wyckoff position 8a with irrep A
2-band BandRep (A↑G at 8a):
  [Γ₁+Γ₂, X₁+X₂, L₁L₂, W₁W₂]

By default, bandreps returns the spinless EBRs with time-reversal symmetry. This behavior can be controlled with the keyword arguments spinful (default, false) and timereversal (default, true). By default, only minimal paths are included in the sampling of k-vectors; additional paths can be obtained by setting the keyword argument allpaths = true (default, false).

The distinct topological classes identifiable from symmetry can can be calculated via classification, which uses the Smith normal form's principle factors:

classification(brs)
"Z₁"

Which demonstrates that the symmetry indicator group of spinless particles with time-reversal symmetry in space group 219 is trivial.

Topology and associated bases

The SymmetryBases.jl package provides tools to analyze topology of symmetry vectors and compute associated Hilbert bases.

API

Crystalline.bandreps — Function
bandreps(sgnum::Integer, D::Integer=3; 
-         allpaths::Bool=false, spinful::Bool=false, timereversal::Bool=true)

Returns the elementary band representations (EBRs) as a BandRepSet for space group sgnum and dimension D.

Keyword arguments

  • allpaths: include a minimal sufficient set (false, default) or all (true) k-vectors.
  • spinful: single- (false, default) or double-valued (true) irreps, as appropriate for spinless and spinful particles, respectively. Only available for D=3.
  • timereversal: assume presence (true, default) or absence (false) of time-reversal symmetry.

References

3D EBRs are obtained from the Bilbao Crystallographic Server's BANDREP program; please reference the original research papers noted there if used in published work.

source
Crystalline.classification — Function
classification(brs_or_F::Union{BandRepSet, Smith}) --> String

Return the symmetry indicator group $X^{\text{BS}}$ of an EBR basis F_or_brs, provided as a BandRepSet or Smith decomposition.

Technically, the calculation answers the question "what direct product of $\mathbb{Z}_n$ groups is the the quotient group $X^{\text{BS}} = \{\text{BS}\}/\{\text{AI}\}$ isomorphic to?" (see Po, Watanabe, & Vishwanath, Nature Commun. 8, 50 (2017) for more information).

source
Crystalline.nontrivial_factors — Function
nontrivial_factors(F::Smith) -> Any
-

Return the nontrivial (i.e., ≠ {0,1}) elementary factors of an EBR basis, provided as a BandRepSet or Smith decomposition.

source
Crystalline.basisdim — Function
basisdim(brs::BandRepSet) --> Int

Return the dimension of the (linearly independent parts) of a band representation set. This is $d^{\text{bs}} = d^{\text{ai}}$ in the notation of Po, Watanabe, & Vishwanath, Nature Commun. 8, 50 (2017), or equivalently, the rank of stack(brs) over the ring of integers. This is the number of linearly independent basis vectors that span the expansions of a band structure viewed as symmetry data.

source
+ allpaths::Bool=false, spinful::Bool=false, timereversal::Bool=true)

Returns the elementary band representations (EBRs) as a BandRepSet for space group sgnum and dimension D.

Keyword arguments

References

3D EBRs are obtained from the Bilbao Crystallographic Server's BANDREP program; please reference the original research papers noted there if used in published work.

source
Crystalline.classification — Function
classification(brs_or_F::Union{BandRepSet, Smith}) --> String

Return the symmetry indicator group $X^{\text{BS}}$ of an EBR basis F_or_brs, provided as a BandRepSet or Smith decomposition.

Technically, the calculation answers the question "what direct product of $\mathbb{Z}_n$ groups is the the quotient group $X^{\text{BS}} = \{\text{BS}\}/\{\text{AI}\}$ isomorphic to?" (see Po, Watanabe, & Vishwanath, Nature Commun. 8, 50 (2017) for more information).

source
Crystalline.nontrivial_factors — Function
nontrivial_factors(F::Smith) -> Any
+

Return the nontrivial (i.e., ≠ {0,1}) elementary factors of an EBR basis, provided as a BandRepSet or Smith decomposition.

source
Crystalline.basisdim — Function
basisdim(brs::BandRepSet) --> Int

Return the dimension of the (linearly independent parts) of a band representation set. This is $d^{\text{bs}} = d^{\text{ai}}$ in the notation of Po, Watanabe, & Vishwanath, Nature Commun. 8, 50 (2017), or equivalently, the rank of stack(brs) over the ring of integers. This is the number of linearly independent basis vectors that span the expansions of a band structure viewed as symmetry data.

source
diff --git a/previews/PR49/bravais/index.html b/previews/PR49/bravais/index.html index cfa810e2..0a4ced37 100644 --- a/previews/PR49/bravais/index.html +++ b/previews/PR49/bravais/index.html @@ -1,16 +1,16 @@ -Bravais types & bases · Crystalline.jl

Bravais.jl

Bravais types, basis systems, and transformations between conventional and primitive settings.

API

Types

Bravais.AbstractBasis — Type
AbstractBasis <: StaticVector{D, SVector{D, T}}

Abstract supertype of a D-dimensional basis in D-dimensional space with coordinate values of type T.

source
Bravais.DirectBasis — Type
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.

source
Bravais.ReciprocalBasis — Type
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.

source
Bravais.AbstractPoint — Type
AbstractPoint{D, T} <: StaticVector{D, T}

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

source
Bravais.DirectPoint — Type
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.

source
Bravais.ReciprocalPoint — Type
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.

source

Crystal systems & Bravais types

Bravais.crystalsystem — Function
crystalsystem(Rs::DirectBasis{D})  -->  String
-crystalsystem(Gs::ReciprocalBasis{D})  -->  String

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

If a ReciprocalBasis Gs is provided for the associated reciprocal point lattice, the crystal system is determined by first transforming to the direct lattice.

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

source
Bravais.bravaistype — Function
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").

source
Bravais.centering — Function
centering(g::AbstractGroup) --> Char

Return the conventional centering type of a group.

For groups without lattice structure (e.g., point groups), return nothing.

source
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
source

Basis construction

Bravais.crystal — Function
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.

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

source
crystal(a)  -->  DirectBasis{1}

Return a one-dimensional crystal with lattice period a.

source
Bravais.directbasis — Function
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).

source
Bravais.reciprocalbasis — Function
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).

source
Bravais.nigglibasis — Function
nigglibasis(Rs; rtol=1e-5, max_iterations=200)

Given a set of primitive basis vectors Rs, return a basis Rs′ for the corresponding Niggli-reduced unit cell, as well as a transformation matrix P, such that Rs′ = transform(Rs, P) (see transform).

Definition

A Niggli-reduced basis $(\mathbf{a}, \mathbf{b}, \mathbf{c})$ represents a unique choice of basis for any given lattice (or, more precisely, a unique choice of the basis vector lengths $|\mathbf{a}|, |\mathbf{b}|, |\mathbf{c}|$, and mutual angles between $\mathbf{a}, \mathbf{b}, \mathbf{c}$). This uniqueness is one of the main motivations for computing the Niggli reduction procedure, as it enables easy comparison of lattices. Additionally, the associated Niggli-reduced basis vectors $(\mathbf{a}, \mathbf{b}, \mathbf{c})$, fulfil several conditions [3]:

  1. "Main" conditions:
    • The basis vectors are sorted by increasing length: $|\mathbf{a}| ≤ |\mathbf{b}| ≤ |\mathbf{c}|$.
    • The angles between basis vectors are either all acute or all non-acute.
  2. "Special" conditions:
    • Several special conditions, applied in "special" cases, such as $|\mathbf{a}| = |\mathbf{b}|$ or \mathbf{b}\cdot\mathbf{c} = \tfrac{1}{2}|\mathbf{b}|^2. See Ref. [3] for details.

Equivalently, the Niggli-reduced basis fulfils the following geometric conditions (Section 9.3.1 of Ref. [3]):

  • The basis vectors are sorted by increasing length.
  • The basis vectors have least possible total length, i.e., ``|\mathbf{a}| + |\mathbf{b}|
    • |\mathbf{c}|`` is minimum. I.e., the associated Niggli cell is a Buerger cell.
  • The associated Buerger cell has maximum deviation among all other Buerger cells, i.e., the basis vector angles $α, β, γ$ maximize $|90° - α| + |90° - β| + |90° - γ|$.

Keyword arguments

  • rtol :: Real: relative tolerance used in the Grosse-Kunstleve approach for floating point comparisons (default: 1e-5).
  • max_iterations :: Int: maximum number of iterations in which to cycle the Krivy-Gruber steps (default: 200).

Implementation

Implementation follows the algorithm originally described by Krivy & Gruber [1], with the stability modificiations proposed by Grosse-Kunstleve et al. [2] (without which the algorithm proposed in [1] simply does not work on floating point hardware).

[1] I. Krivy & B. Gruber. A unified algorithm for determinign the reduced (Niggli) cell, Acta Crystallogr. A 32, 297 (1976). [2] R.W. Grosse-Kunstleve, N.K. Sauter, & P.D. Adams, Numerically stable algorithms for the computation of reduced unit cells, Acta Crystallogr. A 60, 1 (2004) [3] Sections 9.2 & 9.3, International Tables of Crystallography, Volume A, 5th ed. (2005).

source

Transformations

Bravais.primitivebasismatrix — Function
primitivebasismatrix(cntr::Char, ::Val{D}=Val(3)) --> SMatrix{D,D,Float64}
+Bravais types & bases · Crystalline.jl
Bravais.jl
Bravais types, basis systems, and transformations between conventional and primitive settings.
API
Types
Bravais.AbstractBasis — Type
AbstractBasis <: StaticVector{D, SVector{D, T}}
Abstract supertype of a D-dimensional basis in D-dimensional space with coordinate values of type T.
source
Bravais.DirectBasis — Type
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.
source
Bravais.ReciprocalBasis — Type
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.
source
Bravais.AbstractPoint — Type
AbstractPoint{D, T} <: StaticVector{D, T}
Abstract supertype of a D-dimensional point with elements of type T.
source
Bravais.DirectPoint — Type
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.
source
Bravais.ReciprocalPoint — Type
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.
source
Crystal systems & Bravais types
Bravais.crystalsystem — Function
crystalsystem(Rs::DirectBasis{D})  -->  String
+crystalsystem(Gs::ReciprocalBasis{D})  -->  String
Determine the crystal system of a point lattice with DirectBasis Rs, assuming the conventional setting choice defined in the International Tables of Crystallography [ITA6].
If a ReciprocalBasis Gs is provided for the associated reciprocal point lattice, the crystal system is determined by first transforming to the direct lattice.
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).
source
Bravais.bravaistype — Function
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").
source
Bravais.centering — Function
centering(g::AbstractGroup) --> Char
Return the conventional centering type of a group. 
For groups without lattice structure (e.g., point groups), return nothing.
source
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
source
Basis construction
Bravais.crystal — Function
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.
source
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.
source
crystal(a)  -->  DirectBasis{1}
Return a one-dimensional crystal with lattice period a.
source
Bravais.directbasis — Function
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).
source
Bravais.reciprocalbasis — Function
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).
source
Bravais.nigglibasis — Function
nigglibasis(Rs; rtol=1e-5, max_iterations=200)
Given a set of primitive basis vectors Rs, return a basis Rs′ for the corresponding Niggli-reduced unit cell, as well as a transformation matrix P, such that Rs′ = transform(Rs, P) (see transform).
Definition
A Niggli-reduced basis $(\mathbf{a}, \mathbf{b}, \mathbf{c})$ represents a unique choice of basis for any given lattice (or, more precisely, a unique choice of the basis vector lengths $|\mathbf{a}|, |\mathbf{b}|, |\mathbf{c}|$, and mutual angles between  $\mathbf{a}, \mathbf{b}, \mathbf{c}$). This uniqueness is one of the main motivations for computing the Niggli reduction procedure, as it enables easy comparison of lattices. Additionally, the associated Niggli-reduced basis vectors $(\mathbf{a}, \mathbf{b}, \mathbf{c})$, fulfil several conditions [3]:
  1. "Main" conditions:
    • The basis vectors are sorted by increasing length: $|\mathbf{a}| ≤ |\mathbf{b}| ≤ |\mathbf{c}|$.
    • The angles between basis vectors are either all acute or all non-acute.
  2. "Special" conditions:
    • Several special conditions, applied in "special" cases, such as $|\mathbf{a}| = |\mathbf{b}|$ or  \mathbf{b}\cdot\mathbf{c} = \tfrac{1}{2}|\mathbf{b}|^2. See Ref. [3] for details.
Equivalently, the Niggli-reduced basis fulfils the following geometric conditions (Section 9.3.1 of Ref. [3]):
  • The basis vectors are sorted by increasing length.
  • The basis vectors have least possible total length, i.e., ``|\mathbf{a}| + |\mathbf{b}|
    • |\mathbf{c}|`` is minimum. I.e., the associated Niggli cell is a Buerger cell.
  • The associated Buerger cell has maximum deviation among all other Buerger cells, i.e., the basis vector angles $α, β, γ$ maximize $|90° - α| + |90° - β| + |90° - γ|$.
Keyword arguments
  • rtol :: Real: relative tolerance used in the Grosse-Kunstleve approach for floating point comparisons (default: 1e-5).
  • max_iterations :: Int: maximum number of iterations in which to cycle the Krivy-Gruber steps (default: 200).
Implementation
Implementation follows the algorithm originally described by Krivy & Gruber [1], with the stability modificiations proposed by Grosse-Kunstleve et al. [2] (without which the  algorithm proposed in [1] simply does not work on floating point hardware).
[1] I. Krivy & B. Gruber. A unified algorithm for determinign the reduced (Niggli) cell,     Acta Crystallogr. A 32, 297 (1976). [2] R.W. Grosse-Kunstleve, N.K. Sauter, & P.D. Adams, Numerically stable algorithms for the     computation of reduced unit cells,     Acta Crystallogr. A 60, 1 (2004) [3] Sections 9.2 & 9.3, International Tables of Crystallography, Volume A, 5th ed. (2005).
source
Transformations
Bravais.primitivebasismatrix — Function
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.
source
Bravais.transform — Function
transform(v::AbstractVec, P::AbstractMatrix)  -->  v′::typeof(v)
Return a transformed coordinate vector v′ from an original coordinate vector v using a basis change matrix P.
Note that a basis change matrix $\mathbf{P}$ transforms direct coordinate vectors (RVec) as $\mathbf{r}' = \mathbf{P}^{-1}\mathbf{r}$ but transforms reciprocal coordinates (KVec) as $\mathbf{k}' = \mathbf{P}^{\mathrm{T}}\mathbf{k}$ [ITA6]
source
transform(op::SymOperation, P::AbstractMatrix{<:Real}, 
+\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.
source
Bravais.transform — Function
transform(v::AbstractVec, P::AbstractMatrix)  -->  v′::typeof(v)
Return a transformed coordinate vector v′ from an original coordinate vector v using a basis change matrix P.
Note that a basis change matrix $\mathbf{P}$ transforms direct coordinate vectors (RVec) as $\mathbf{r}' = \mathbf{P}^{-1}\mathbf{r}$ but transforms reciprocal coordinates (KVec) as $\mathbf{k}' = \mathbf{P}^{\mathrm{T}}\mathbf{k}$ [ITA6]
source
transform(op::SymOperation, P::AbstractMatrix{<:Real}, 
           p::Union{AbstractVector{<:Real}, Nothing}=nothing,
           modw::Bool=true)                           --> SymOperation
Transforms a op $= \{\mathbf{W}|\mathbf{w}\}$ by a rotation matrix P and a translation vector p (can be nothing for zero-translations), producing a new symmetry operation  op′ $= \{\mathbf{W}'|\mathbf{w}'\}$ (cf. Section 1.5.2.3 of [ITA6])
\[\{\mathbf{W}'|\mathbf{w}'\} = \{\mathbf{P}|\mathbf{p}\}^{-1}\{\mathbf{W}|\mathbf{w}\}
 \{\mathbf{P}|\mathbf{p}\}\]
with
\[\mathbf{W}' = \mathbf{P}^{-1}\mathbf{W}\mathbf{P}
 \text{ and }
-\mathbf{w}' = \mathbf{P}^{-1}(\mathbf{w}+\mathbf{W}\mathbf{p}-\mathbf{p})\]
By default, the translation part of op′, i.e. $\mathbf{w}'$, is reduced to the range $[0,1)$, i.e. computed modulo 1. This can be disabled by setting modw = false (default, modw = true).
See also Bravais.primitivize(::SymOperation, ::Char, ::Bool) and Bravais.conventionalize(::SymOperation, ::Char, ::Bool).
source
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}$.
source
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}}$.
source
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}}$.
source
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}}$.
source
Bravais.primitivize — Function
primitivize(v::AbstractVec, cntr::Char)  -->  v′::typeof(v)
Transforms a conventional coordinate vector v to a standard primitive basis (specified by the centering type cntr), returning the primitive coordinate vector v′.
Note that a basis change matrix $\mathbf{P}$ (as returned e.g. by Bravais.primitivebasismatrix) transforms direct coordinate vectors (RVec) as $\mathbf{r}' = \mathbf{P}^{-1}\mathbf{r}$ but transforms reciprocal coordinates (KVec) as $\mathbf{k}' = \mathbf{P}^{\text{T}}\mathbf{k}$ [ITA6]. Recall also the distinction between transforming a basis and the coordinates of a vector.
source
primitivize(op::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)
Return a symmetry operation op′ $≡ \{W'|w'\}$ in a primitive setting, transformed from an input symmetry operation op $= \{W|w\}$ in a conventional setting. The operations $\{W'|w'\}$ and $\{W|w\}$ are related by a transformation $\{P|p\}$ via (cf. Section 1.5.2.3 of [ITA6]):
\[\{W'|w'\} = \{P|p\}⁻¹\{W|w\}\{P|p\}.\]
where $P$ and $p$ are the basis change matrix and origin shifts, respectively. The relevant transformation $\{P|p\}$ is inferred from the centering type, as provided by cntr (see also Bravais.centering).
By default, translation parts of op′, i.e. $w'$ are reduced modulo 1 (modw = true); to disable this, set modw = false.
source
primitivize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat)
Given flat referred to a conventional basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated primitive basis. 
Specifically, if flat refers to a direct conventional basis Rs $≡ (\mathbf{a} \mathbf{b} \mathbf{c})$ [with coordinate vectors $\mathbf{r} ≡ (r_1, r_2, r_3)^{\mathrm{T}}$] then flat′ refers to a direct primitive basis Rs′ $≡ (\mathbf{a}' \mathbf{b}' \mathbf{c}') ≡ (\mathbf{a} \mathbf{b} \mathbf{c})\mathbf{P}$ [with coordinate vectors  $\mathbf{r}' ≡ (r_1', r_2', r_3')^{\mathrm{T}} = \mathbf{P}^{-1}\mathbf{r}$], where $\mathbf{P}$ denotes the basis-change matrix obtained from primitivebasismatrix(...).
To compute the associated primitive basis vectors, see primitivize(::DirectBasis, ::Char) [specifically, Rs′ = primitivize(Rs, cntr)].
Examples
A centered ('c') lattice from plane group 5 in 2D, plotted in its  conventional and primitive basis (requires using PyPlot):
julia> sgnum = 5; D = 2; cntr = centering(sgnum, D)  # 'c' (body-centered)
+\mathbf{w}' = \mathbf{P}^{-1}(\mathbf{w}+\mathbf{W}\mathbf{p}-\mathbf{p})\]
By default, the translation part of op′, i.e. $\mathbf{w}'$, is reduced to the range $[0,1)$, i.e. computed modulo 1. This can be disabled by setting modw = false (default, modw = true).
See also Bravais.primitivize(::SymOperation, ::Char, ::Bool) and Bravais.conventionalize(::SymOperation, ::Char, ::Bool).
source
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}$.
source
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}}$.
source
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}}$.
source
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}}$.
source
Bravais.primitivize — Function
primitivize(v::AbstractVec, cntr::Char)  -->  v′::typeof(v)
Transforms a conventional coordinate vector v to a standard primitive basis (specified by the centering type cntr), returning the primitive coordinate vector v′.
Note that a basis change matrix $\mathbf{P}$ (as returned e.g. by Bravais.primitivebasismatrix) transforms direct coordinate vectors (RVec) as $\mathbf{r}' = \mathbf{P}^{-1}\mathbf{r}$ but transforms reciprocal coordinates (KVec) as $\mathbf{k}' = \mathbf{P}^{\text{T}}\mathbf{k}$ [ITA6]. Recall also the distinction between transforming a basis and the coordinates of a vector.
source
primitivize(op::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)
Return a symmetry operation op′ $≡ \{W'|w'\}$ in a primitive setting, transformed from an input symmetry operation op $= \{W|w\}$ in a conventional setting. The operations $\{W'|w'\}$ and $\{W|w\}$ are related by a transformation $\{P|p\}$ via (cf. Section 1.5.2.3 of [ITA6]):
\[\{W'|w'\} = \{P|p\}⁻¹\{W|w\}\{P|p\}.\]
where $P$ and $p$ are the basis change matrix and origin shifts, respectively. The relevant transformation $\{P|p\}$ is inferred from the centering type, as provided by cntr (see also Bravais.centering).
By default, translation parts of op′, i.e. $w'$ are reduced modulo 1 (modw = true); to disable this, set modw = false.
source
primitivize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat)
Given flat referred to a conventional basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated primitive basis. 
Specifically, if flat refers to a direct conventional basis Rs $≡ (\mathbf{a} \mathbf{b} \mathbf{c})$ [with coordinate vectors $\mathbf{r} ≡ (r_1, r_2, r_3)^{\mathrm{T}}$] then flat′ refers to a direct primitive basis Rs′ $≡ (\mathbf{a}' \mathbf{b}' \mathbf{c}') ≡ (\mathbf{a} \mathbf{b} \mathbf{c})\mathbf{P}$ [with coordinate vectors  $\mathbf{r}' ≡ (r_1', r_2', r_3')^{\mathrm{T}} = \mathbf{P}^{-1}\mathbf{r}$], where $\mathbf{P}$ denotes the basis-change matrix obtained from primitivebasismatrix(...).
To compute the associated primitive basis vectors, see primitivize(::DirectBasis, ::Char) [specifically, Rs′ = primitivize(Rs, cntr)].
Examples
A centered ('c') lattice from plane group 5 in 2D, plotted in its  conventional and primitive basis (requires using PyPlot):
julia> sgnum = 5; D = 2; cntr = centering(sgnum, D)  # 'c' (body-centered)
 
 julia> Rs   = directbasis(sgnum, Val(D))     # conventional basis (rectangular)
 julia> flat = levelsetlattice(sgnum, Val(D)) # Fourier lattice in basis of Rs
@@ -21,14 +21,14 @@
 julia> flat′ = primitivize(flat, cntr)  # Fourier lattice in basis of Rs′
 
 julia> using PyPlot
-julia> plot(flat′, Rs′)
source
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)).
source
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.
source
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.
source
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. 
source
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. 
source
Bravais.conventionalize — Function
conventionalize(v′::AbstractVec, cntr::Char)  -->  v::typeof(v′)
Transforms a primitive coordinate vector v′ back to a standard conventional basis (specified by the centering type cntr), returning the conventional coordinate vector v.
See also primitivize and transform.
source
conventionalize(op′::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)
Return a symmetry operation op $= \{W|w\}$ in a conventional setting, transformed from an input symmetry operation op′ $≡ \{W'|w'\}$ in a primitive setting.
See primitivize(::SymOperation, ::Char, ::Bool) for description of the centering argument cntr and optional argument modw.
source
conventionalize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat′)
Given flat referred to a primitive basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated conventional basis. 
See also the complementary method primitivize(::AbstractFourierLattice, ::Char) for additional details.
source
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)).
source
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′.
source
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′.
source
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.
source
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. 
source
Bravais.cartesianize — Function
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 
source
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.
source
Bravais.latticize — Function
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.
source
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.
source
Miscellaneous
Bravais.volume — Function
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.
source
Bravais.metricmatrix — Function
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.
source
Crystalline.jl extensions of Bravais.jl functions
SymOperation
Bravais.transform — Function
transform(op::SymOperation, P::AbstractMatrix{<:Real}, 
+julia> plot(flat′, Rs′)
source
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)).
source
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.
source
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.
source
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. 
source
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. 
source
Bravais.conventionalize — Function
conventionalize(v′::AbstractVec, cntr::Char)  -->  v::typeof(v′)
Transforms a primitive coordinate vector v′ back to a standard conventional basis (specified by the centering type cntr), returning the conventional coordinate vector v.
See also primitivize and transform.
source
conventionalize(op′::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)
Return a symmetry operation op $= \{W|w\}$ in a conventional setting, transformed from an input symmetry operation op′ $≡ \{W'|w'\}$ in a primitive setting.
See primitivize(::SymOperation, ::Char, ::Bool) for description of the centering argument cntr and optional argument modw.
source
conventionalize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat′)
Given flat referred to a primitive basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated conventional basis. 
See also the complementary method primitivize(::AbstractFourierLattice, ::Char) for additional details.
source
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)).
source
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′.
source
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′.
source
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.
source
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. 
source
Bravais.cartesianize — Function
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 
source
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.
source
Bravais.latticize — Function
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.
source
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.
source
Miscellaneous
Bravais.volume — Function
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.
source
Bravais.metricmatrix — Function
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.
source
Crystalline.jl extensions of Bravais.jl functions
SymOperation
Bravais.transform — Function
transform(op::SymOperation, P::AbstractMatrix{<:Real}, 
           p::Union{AbstractVector{<:Real}, Nothing}=nothing,
           modw::Bool=true)                           --> SymOperation
Transforms a op $= \{\mathbf{W}|\mathbf{w}\}$ by a rotation matrix P and a translation vector p (can be nothing for zero-translations), producing a new symmetry operation  op′ $= \{\mathbf{W}'|\mathbf{w}'\}$ (cf. Section 1.5.2.3 of [ITA6])
\[\{\mathbf{W}'|\mathbf{w}'\} = \{\mathbf{P}|\mathbf{p}\}^{-1}\{\mathbf{W}|\mathbf{w}\}
 \{\mathbf{P}|\mathbf{p}\}\]
with
\[\mathbf{W}' = \mathbf{P}^{-1}\mathbf{W}\mathbf{P}
 \text{ and }
-\mathbf{w}' = \mathbf{P}^{-1}(\mathbf{w}+\mathbf{W}\mathbf{p}-\mathbf{p})\]
By default, the translation part of op′, i.e. $\mathbf{w}'$, is reduced to the range $[0,1)$, i.e. computed modulo 1. This can be disabled by setting modw = false (default, modw = true).
See also Bravais.primitivize(::SymOperation, ::Char, ::Bool) and Bravais.conventionalize(::SymOperation, ::Char, ::Bool).
source
Bravais.primitivize — Method
primitivize(op::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)
Return a symmetry operation op′ $≡ \{W'|w'\}$ in a primitive setting, transformed from an input symmetry operation op $= \{W|w\}$ in a conventional setting. The operations $\{W'|w'\}$ and $\{W|w\}$ are related by a transformation $\{P|p\}$ via (cf. Section 1.5.2.3 of [ITA6]):
\[\{W'|w'\} = \{P|p\}⁻¹\{W|w\}\{P|p\}.\]
where $P$ and $p$ are the basis change matrix and origin shifts, respectively. The relevant transformation $\{P|p\}$ is inferred from the centering type, as provided by cntr (see also Bravais.centering).
By default, translation parts of op′, i.e. $w'$ are reduced modulo 1 (modw = true); to disable this, set modw = false.
source
Bravais.conventionalize — Method
conventionalize(op′::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)
Return a symmetry operation op $= \{W|w\}$ in a conventional setting, transformed from an input symmetry operation op′ $≡ \{W'|w'\}$ in a primitive setting.
See primitivize(::SymOperation, ::Char, ::Bool) for description of the centering argument cntr and optional argument modw.
source
AbstractVec
Bravais.transform — Method
transform(v::AbstractVec, P::AbstractMatrix)  -->  v′::typeof(v)
Return a transformed coordinate vector v′ from an original coordinate vector v using a basis change matrix P.
Note that a basis change matrix $\mathbf{P}$ transforms direct coordinate vectors (RVec) as $\mathbf{r}' = \mathbf{P}^{-1}\mathbf{r}$ but transforms reciprocal coordinates (KVec) as $\mathbf{k}' = \mathbf{P}^{\mathrm{T}}\mathbf{k}$ [ITA6]
source
Bravais.primitivize — Method
primitivize(v::AbstractVec, cntr::Char)  -->  v′::typeof(v)
Transforms a conventional coordinate vector v to a standard primitive basis (specified by the centering type cntr), returning the primitive coordinate vector v′.
Note that a basis change matrix $\mathbf{P}$ (as returned e.g. by Bravais.primitivebasismatrix) transforms direct coordinate vectors (RVec) as $\mathbf{r}' = \mathbf{P}^{-1}\mathbf{r}$ but transforms reciprocal coordinates (KVec) as $\mathbf{k}' = \mathbf{P}^{\text{T}}\mathbf{k}$ [ITA6]. Recall also the distinction between transforming a basis and the coordinates of a vector.
source
Bravais.conventionalize — Method
conventionalize(v′::AbstractVec, cntr::Char)  -->  v::typeof(v′)
Transforms a primitive coordinate vector v′ back to a standard conventional basis (specified by the centering type cntr), returning the conventional coordinate vector v.
See also primitivize and transform.
source
AbstractFourierLattice
Bravais.primitivize — Method
primitivize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat)
Given flat referred to a conventional basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated primitive basis. 
Specifically, if flat refers to a direct conventional basis Rs $≡ (\mathbf{a} \mathbf{b} \mathbf{c})$ [with coordinate vectors $\mathbf{r} ≡ (r_1, r_2, r_3)^{\mathrm{T}}$] then flat′ refers to a direct primitive basis Rs′ $≡ (\mathbf{a}' \mathbf{b}' \mathbf{c}') ≡ (\mathbf{a} \mathbf{b} \mathbf{c})\mathbf{P}$ [with coordinate vectors  $\mathbf{r}' ≡ (r_1', r_2', r_3')^{\mathrm{T}} = \mathbf{P}^{-1}\mathbf{r}$], where $\mathbf{P}$ denotes the basis-change matrix obtained from primitivebasismatrix(...).
To compute the associated primitive basis vectors, see primitivize(::DirectBasis, ::Char) [specifically, Rs′ = primitivize(Rs, cntr)].
Examples
A centered ('c') lattice from plane group 5 in 2D, plotted in its  conventional and primitive basis (requires using PyPlot):
julia> sgnum = 5; D = 2; cntr = centering(sgnum, D)  # 'c' (body-centered)
+\mathbf{w}' = \mathbf{P}^{-1}(\mathbf{w}+\mathbf{W}\mathbf{p}-\mathbf{p})\]
By default, the translation part of op′, i.e. $\mathbf{w}'$, is reduced to the range $[0,1)$, i.e. computed modulo 1. This can be disabled by setting modw = false (default, modw = true).
See also Bravais.primitivize(::SymOperation, ::Char, ::Bool) and Bravais.conventionalize(::SymOperation, ::Char, ::Bool).
source
Bravais.primitivize — Method
primitivize(op::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)
Return a symmetry operation op′ $≡ \{W'|w'\}$ in a primitive setting, transformed from an input symmetry operation op $= \{W|w\}$ in a conventional setting. The operations $\{W'|w'\}$ and $\{W|w\}$ are related by a transformation $\{P|p\}$ via (cf. Section 1.5.2.3 of [ITA6]):
\[\{W'|w'\} = \{P|p\}⁻¹\{W|w\}\{P|p\}.\]
where $P$ and $p$ are the basis change matrix and origin shifts, respectively. The relevant transformation $\{P|p\}$ is inferred from the centering type, as provided by cntr (see also Bravais.centering).
By default, translation parts of op′, i.e. $w'$ are reduced modulo 1 (modw = true); to disable this, set modw = false.
source
Bravais.conventionalize — Method
conventionalize(op′::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)
Return a symmetry operation op $= \{W|w\}$ in a conventional setting, transformed from an input symmetry operation op′ $≡ \{W'|w'\}$ in a primitive setting.
See primitivize(::SymOperation, ::Char, ::Bool) for description of the centering argument cntr and optional argument modw.
source
AbstractVec
Bravais.transform — Method
transform(v::AbstractVec, P::AbstractMatrix)  -->  v′::typeof(v)
Return a transformed coordinate vector v′ from an original coordinate vector v using a basis change matrix P.
Note that a basis change matrix $\mathbf{P}$ transforms direct coordinate vectors (RVec) as $\mathbf{r}' = \mathbf{P}^{-1}\mathbf{r}$ but transforms reciprocal coordinates (KVec) as $\mathbf{k}' = \mathbf{P}^{\mathrm{T}}\mathbf{k}$ [ITA6]
source
Bravais.primitivize — Method
primitivize(v::AbstractVec, cntr::Char)  -->  v′::typeof(v)
Transforms a conventional coordinate vector v to a standard primitive basis (specified by the centering type cntr), returning the primitive coordinate vector v′.
Note that a basis change matrix $\mathbf{P}$ (as returned e.g. by Bravais.primitivebasismatrix) transforms direct coordinate vectors (RVec) as $\mathbf{r}' = \mathbf{P}^{-1}\mathbf{r}$ but transforms reciprocal coordinates (KVec) as $\mathbf{k}' = \mathbf{P}^{\text{T}}\mathbf{k}$ [ITA6]. Recall also the distinction between transforming a basis and the coordinates of a vector.
source
Bravais.conventionalize — Method
conventionalize(v′::AbstractVec, cntr::Char)  -->  v::typeof(v′)
Transforms a primitive coordinate vector v′ back to a standard conventional basis (specified by the centering type cntr), returning the conventional coordinate vector v.
See also primitivize and transform.
source
AbstractFourierLattice
Bravais.primitivize — Method
primitivize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat)
Given flat referred to a conventional basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated primitive basis. 
Specifically, if flat refers to a direct conventional basis Rs $≡ (\mathbf{a} \mathbf{b} \mathbf{c})$ [with coordinate vectors $\mathbf{r} ≡ (r_1, r_2, r_3)^{\mathrm{T}}$] then flat′ refers to a direct primitive basis Rs′ $≡ (\mathbf{a}' \mathbf{b}' \mathbf{c}') ≡ (\mathbf{a} \mathbf{b} \mathbf{c})\mathbf{P}$ [with coordinate vectors  $\mathbf{r}' ≡ (r_1', r_2', r_3')^{\mathrm{T}} = \mathbf{P}^{-1}\mathbf{r}$], where $\mathbf{P}$ denotes the basis-change matrix obtained from primitivebasismatrix(...).
To compute the associated primitive basis vectors, see primitivize(::DirectBasis, ::Char) [specifically, Rs′ = primitivize(Rs, cntr)].
Examples
A centered ('c') lattice from plane group 5 in 2D, plotted in its  conventional and primitive basis (requires using PyPlot):
julia> sgnum = 5; D = 2; cntr = centering(sgnum, D)  # 'c' (body-centered)
 
 julia> Rs   = directbasis(sgnum, Val(D))     # conventional basis (rectangular)
 julia> flat = levelsetlattice(sgnum, Val(D)) # Fourier lattice in basis of Rs
@@ -39,4 +39,4 @@
 julia> flat′ = primitivize(flat, cntr)  # Fourier lattice in basis of Rs′
 
 julia> using PyPlot
-julia> plot(flat′, Rs′)
source
Bravais.conventionalize — Method
conventionalize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat′)
Given flat referred to a primitive basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated conventional basis. 
See also the complementary method primitivize(::AbstractFourierLattice, ::Char) for additional details.
source
  • 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.
  • ITA6M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th edition (2016):      Secs. 1.5.1.2 and 1.5.2.1.
  • ITA6M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016).
  • ITA6M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th edition (2016):      Secs. 1.5.1.2 and 1.5.2.1.
  • ITA6M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016).
  • ITA6M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016).
  • ITA6M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016).
  • ITA6M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th edition (2016):      Secs. 1.5.1.2 and 1.5.2.1.
  • ITA6M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th edition (2016):      Secs. 1.5.1.2 and 1.5.2.1.

+julia> plot(flat′, Rs′)
source
Bravais.conventionalize — Method
conventionalize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat′)

Given flat referred to a primitive basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated conventional basis.

See also the complementary method primitivize(::AbstractFourierLattice, ::Char) for additional details.

source
  • 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.
  • ITA6M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th edition (2016): Secs. 1.5.1.2 and 1.5.2.1.
  • ITA6M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016).
  • ITA6M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th edition (2016): Secs. 1.5.1.2 and 1.5.2.1.
  • ITA6M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016).
  • ITA6M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016).
  • ITA6M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016).
  • ITA6M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th edition (2016): Secs. 1.5.1.2 and 1.5.2.1.
  • ITA6M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th edition (2016): Secs. 1.5.1.2 and 1.5.2.1.
diff --git a/previews/PR49/groups/index.html b/previews/PR49/groups/index.html index 30c57cd2..b4d9e41f 100644 --- a/previews/PR49/groups/index.html +++ b/previews/PR49/groups/index.html @@ -26,4 +26,4 @@ 2₀₀₁ 2₀₁₀ 1 - 2₁₀₀

Magnetic space groups

Magnetic space groups are accessible via mspacegroup.

+ 2₁₀₀

Magnetic space groups

Magnetic space groups are accessible via mspacegroup.

diff --git a/previews/PR49/index.html b/previews/PR49/index.html index 539be88a..8f34ee86 100644 --- a/previews/PR49/index.html +++ b/previews/PR49/index.html @@ -1,2 +1,2 @@ -Home · Crystalline.jl +Home · Crystalline.jl diff --git a/previews/PR49/internal-api/index.html b/previews/PR49/internal-api/index.html index 3c75d279..5ce53e97 100644 --- a/previews/PR49/internal-api/index.html +++ b/previews/PR49/internal-api/index.html @@ -1,6 +1,6 @@ Internal API · Crystalline.jl

Internal API

This page lists unexported functionality from Crystalline, that may be of interest to developers.

Unexported, internal functionality

Crystalline.AbstractFourierLattice — Method
(flat::AbstractFourierLattice)(xyz) --> Float64
-(flat::AbstractFourierLattice)(xyzs...) --> Float64

Evaluate an AbstractFourierLattice at the point xyz and return its real part, i.e.

\[ \mathop{\mathrm{Re}}\sum_i c_i \exp(2\pi i\mathbf{G}_i\cdot\mathbf{r})\]

with $\mathrm{G}_i$ denoting reciprocal lattice vectors in the allowed orbits of flat, with $c_i$ denoting the associated coefficients (and $\mathbf{r} \equiv$ xyz).

xyz may be any iterable object with dimension matching flat consisting of real numbers (e.g., a Tuple, Vector, or SVector). Alternatively, the coordinates can be supplied individually (i.e., as flat(x, y, z)).

source
Crystalline.AbstractGroup — Type
abstract type AbstractGroup{D, O} <: AbstractArray{O, 1}

The abstract supertype of all group structures, with assumed group elements of type O and embedding dimension D.

Minimum interface includes definitions of: - num(::AbstractGroup), returning an integer or tuple of integers. - operations(::AbstractGroup), returning a set of operations. or, alternatively, fields with names num and operations, behaving accordingly.

source
Crystalline.AbstractIrrep — Type
AbstractIrrep{D}

Abstract supertype for irreps of dimensionality D: must have fields cdml, matrices, g (underlying group), reality (and possibly translations). May overload a function irreps that returns the associated irrep matrices; if not, will simply be matrices.

source
Crystalline.GenericGroup — Type
struct GenericGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}
  • operations::Array{SymOperation{D}, 1} where D
source
Crystalline.UnityFourierLattice — Type
UnityFourierLattice{D} <: AbstractFourierLattice{D}

A general D-dimensional Fourier (plane wave) lattice specified by orbits of reciprocal lattice vectors (orbits) and coefficient interrelations (orbitcoefs)). The norm of all elements in orbitcoefs is unity. orbits (and associated coefficients) are sorted in order of increasing norm (low to high).

source
Base.parse — Method
parse(::Type{SymmetryVector{D}}, 
+(flat::AbstractFourierLattice)(xyzs...) --> Float64

Evaluate an AbstractFourierLattice at the point xyz and return its real part, i.e.

\[ \mathop{\mathrm{Re}}\sum_i c_i \exp(2\pi i\mathbf{G}_i\cdot\mathbf{r})\]

with $\mathrm{G}_i$ denoting reciprocal lattice vectors in the allowed orbits of flat, with $c_i$ denoting the associated coefficients (and $\mathbf{r} \equiv$ xyz).

xyz may be any iterable object with dimension matching flat consisting of real numbers (e.g., a Tuple, Vector, or SVector). Alternatively, the coordinates can be supplied individually (i.e., as flat(x, y, z)).

source
Crystalline.AbstractGroup — Type
abstract type AbstractGroup{D, O} <: AbstractArray{O, 1}

The abstract supertype of all group structures, with assumed group elements of type O and embedding dimension D.

Minimum interface includes definitions of: - num(::AbstractGroup), returning an integer or tuple of integers. - operations(::AbstractGroup), returning a set of operations. or, alternatively, fields with names num and operations, behaving accordingly.

source
Crystalline.AbstractIrrep — Type
AbstractIrrep{D}

Abstract supertype for irreps of dimensionality D: must have fields cdml, matrices, g (underlying group), reality (and possibly translations). May overload a function irreps that returns the associated irrep matrices; if not, will simply be matrices.

source
Crystalline.GenericGroup — Type
struct GenericGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}
  • operations::Array{SymOperation{D}, 1} where D
source
Crystalline.UnityFourierLattice — Type
UnityFourierLattice{D} <: AbstractFourierLattice{D}

A general D-dimensional Fourier (plane wave) lattice specified by orbits of reciprocal lattice vectors (orbits) and coefficient interrelations (orbitcoefs)). The norm of all elements in orbitcoefs is unity. orbits (and associated coefficients) are sorted in order of increasing norm (low to high).

source
Base.parse — Method
parse(::Type{SymmetryVector{D}}, 
       s::AbstractString,
       lgirsv::Vector{Collection{LGIrrep{D}}})  ->  SymmetryVector{D}

Parse a string s to a SymmetryVector over the irreps provided in lgirsv. The irrep labels of lgirsv and s must use the same convention.

Example

julia> brs = calc_bandreps(220);
 
@@ -10,7 +10,7 @@
 
 julia> parse(SymmetryVector, s, lgirsv)
 15-irrep SymmetryVector{3}:
- [2P₃, 4N₁, H₁H₂+H₄H₅, Γ₁+Γ₂+Γ₄+Γ₅, 2PA₃] (8 bands)
source
Crystalline.:⊚ — Method
(⊚)(op1::T, op2::T) where T<:SymOperation -->  Vector{Float64}

Compose two symmetry operations op1 $= \{W₁|w₁\}$ and op2 $= \{W₂|w₂\}$ and return the quotient of $w₁+W₁w₂$ and 1. This functionality complements op1*op2, which yields the translation modulo 1; accordingly, translation(op1*op2) + op1⊚op2 yields the translation component of the composition op1 and op2 without taking it modulo 1, i.e. including any "trivial" lattice translation.

Note that ⊚ can be auto-completed in Julia via \circledcirc+[tab]

source
Crystalline.CompositeBandRep_from_indices — Method
CompositeBandRep_from_indices(idxs::Vector{Int}, brs::Collection{<:NewBandRep})

Return a CompositeBandRep whose symmetry content is equal to the sum the band representations of brs over idxs. In terms of irrep multiplicity, this is equivalent to sum(brs[idxs]) in the sense that CompositeBandRep(idxs, brs) is equal to sum(brs[idxs]) for each irrep multiplicity.

The difference, and primary motivation for using CompositeBandRep, is that CompositeBandRep retains information about which band representations are included and with what multiplicity (the multiplicity of the ith brs-element being equaling to count(==(i), idxs)).

Example

julia> brs = calc_bandreps(2);
+ [2P₃, 4N₁, H₁H₂+H₄H₅, Γ₁+Γ₂+Γ₄+Γ₅, 2PA₃] (8 bands)
source
Crystalline.:⊚ — Method
(⊚)(op1::T, op2::T) where T<:SymOperation -->  Vector{Float64}

Compose two symmetry operations op1 $= \{W₁|w₁\}$ and op2 $= \{W₂|w₂\}$ and return the quotient of $w₁+W₁w₂$ and 1. This functionality complements op1*op2, which yields the translation modulo 1; accordingly, translation(op1*op2) + op1⊚op2 yields the translation component of the composition op1 and op2 without taking it modulo 1, i.e. including any "trivial" lattice translation.

Note that ⊚ can be auto-completed in Julia via \circledcirc+[tab]

source
Crystalline.CompositeBandRep_from_indices — Method
CompositeBandRep_from_indices(idxs::Vector{Int}, brs::Collection{<:NewBandRep})

Return a CompositeBandRep whose symmetry content is equal to the sum the band representations of brs over idxs. In terms of irrep multiplicity, this is equivalent to sum(brs[idxs]) in the sense that CompositeBandRep(idxs, brs) is equal to sum(brs[idxs]) for each irrep multiplicity.

The difference, and primary motivation for using CompositeBandRep, is that CompositeBandRep retains information about which band representations are included and with what multiplicity (the multiplicity of the ith brs-element being equaling to count(==(i), idxs)).

Example

julia> brs = calc_bandreps(2);
 
 julia> cbr = CompositeBandRep_from_indices([1, 1, 2, 6], brs)
 16-irrep CompositeBandRep{3}:
@@ -21,30 +21,30 @@
 
 julia> SymmetryVector(cbr)
 16-irrep SymmetryVector{3}:
- [2Z₁⁺+2Z₁⁻, Y₁⁺+3Y₁⁻, 2U₁⁺+2U₁⁻, 2X₁⁺+2X₁⁻, 3T₁⁺+T₁⁻, 2Γ₁⁺+2Γ₁⁻, 3V₁⁺+V₁⁻, R₁⁺+3R₁⁻] (4 bands)
source
Crystalline._find_equal_groups_in_sorted — Method
_find_equal_groups_in_sorted(v::AbstractVector) --> Vector{UnitRange}

Returns indices into groups of equal values in v. Input v must be sorted so that identical values are adjacent.

Example

_find_equal_groups_in_sorted([-4,1,1,3,3,3]) # returns [1:1, 2:3, 4:6]
source
Crystalline._findsubgroup — Method
_findsubgroup(opsᴳ::T, opsᴴ::T′[, cntr]) where T⁽′⁾<:AbstractVector{SymOperation}
-                                                  --> Tuple{Bool, Vector{Int}}

Returns a 2-tuple with elements:

  1. A boolean, indicating whether the group $H$ (with operators opsᴴ) is a subgroup of the group $G$ (with operators opsᴳ), i.e. whether $H < G$.
  2. An indexing vector idxsᴳ²ᴴ of opsᴳ into opsᴴ (empty if H is not a subgroup of G), such that all(isapprox(opsᴳ[idxsᴳ²ᴴ], opsᴴ, cntr).

If cntr is provided, comparison of operations in $G$ and $H$ is done in the associated primitive basis (i.e., cntr is passed to isapprox which compares operations in $G$ and $H$).

source
Crystalline._orbit — Method
_orbit(Ws, x)

Computes the orbit of a direct-space point x under a set of point-group operations Ws, i.e. computes the set {gx | g∈G} where g denotes elements of the group G composed of all operations in Ws (possibly iterated, to ensure full coverage).

It is important that Ws and x are given in the same basis.

[$W' = PWP⁻¹$ if the basis change is from coordinates r to r' = Pr, corresponding to a new set of basis vectors (x̂')ᵀ=x̂ᵀP; e.g., when going from a direct basis representation to a Cartesian one, the basis change matrix is P = [R₁ R₂ R₃], with Rᵢ inserted as column vectors]

source
Crystalline.can_intersect — Method
can_intersect(
+ [2Z₁⁺+2Z₁⁻, Y₁⁺+3Y₁⁻, 2U₁⁺+2U₁⁻, 2X₁⁺+2X₁⁻, 3T₁⁺+T₁⁻, 2Γ₁⁺+2Γ₁⁻, 3V₁⁺+V₁⁻, R₁⁺+3R₁⁻] (4 bands)
source
Crystalline._find_equal_groups_in_sorted — Method
_find_equal_groups_in_sorted(v::AbstractVector) --> Vector{UnitRange}

Returns indices into groups of equal values in v. Input v must be sorted so that identical values are adjacent.

Example

_find_equal_groups_in_sorted([-4,1,1,3,3,3]) # returns [1:1, 2:3, 4:6]
source
Crystalline._findsubgroup — Method
_findsubgroup(opsᴳ::T, opsᴴ::T′[, cntr]) where T⁽′⁾<:AbstractVector{SymOperation}
+                                                --> Tuple{Bool, Vector{Int}}

Returns a 2-tuple with elements:

  1. A boolean, indicating whether the group $H$ (with operators opsᴴ) is a subgroup of the group $G$ (with operators opsᴳ), i.e. whether $H < G$.
  2. An indexing vector idxsᴳ²ᴴ of opsᴳ into opsᴴ (empty if H is not a subgroup of G), such that all(isapprox(opsᴳ[idxsᴳ²ᴴ], opsᴴ, cntr).

If cntr is provided, comparison of operations in $G$ and $H$ is done in the associated primitive basis (i.e., cntr is passed to isapprox which compares operations in $G$ and $H$).

source
Crystalline._orbit — Method
_orbit(Ws, x)

Computes the orbit of a direct-space point x under a set of point-group operations Ws, i.e. computes the set {gx | g∈G} where g denotes elements of the group G composed of all operations in Ws (possibly iterated, to ensure full coverage).

It is important that Ws and x are given in the same basis.

[$W' = PWP⁻¹$ if the basis change is from coordinates r to r' = Pr, corresponding to a new set of basis vectors (x̂')ᵀ=x̂ᵀP; e.g., when going from a direct basis representation to a Cartesian one, the basis change matrix is P = [R₁ R₂ R₃], with Rᵢ inserted as column vectors]

source
Crystalline.can_intersect — Method
can_intersect(
     v::Crystalline.AbstractVec{D},
     v′::Crystalline.AbstractVec{D};
     atol
 ) -> NamedTuple{(:bool, :αβγ, :αβγ′, :L), <:Tuple{Bool, Any, Any, Any}}
-

Check whether two AbstractVecs v and v′ can intersect, i.e., whether there exist free parameters such that they are equivalent modulo an integer lattice vector.

Returns a NamedTuple (; bool, αβγ, αβγ′, L). If bool = true, kv and kv′ are compatible in the sense that v(αβγ) == v′(αβγ′) + L if bool == true where L is an integer-valued lattice vector. If bool = false, they are incompatible (and zero-valued vectors are returned for αβγ, αβγ′, and L).

Extended help

  • The keyword argument atol (default, 1.0e-12) specifies the absolute tolerance for the comparison.
  • If both v and v′ are not special, i.e., both have free parameters, the intersection point may not be unique (e.g., for co-linear v and v′).
  • The implementation currently only checks the immediately adjacent lattice vectors for equivalence; if there is equivalence, but the the required elements of L would have |Lᵢ| > 1, the currently implementation will not identify the equivalence.
  • This operation is usually only meaningful if the bases of kv and kv′ agree and are primitive.
source
Crystalline.compact_print_matrix — Function
compact_print_matrix(io, X::Matrix, prerow)
+

Check whether two AbstractVecs v and v′ can intersect, i.e., whether there exist free parameters such that they are equivalent modulo an integer lattice vector.

Returns a NamedTuple (; bool, αβγ, αβγ′, L). If bool = true, kv and kv′ are compatible in the sense that v(αβγ) == v′(αβγ′) + L if bool == true where L is an integer-valued lattice vector. If bool = false, they are incompatible (and zero-valued vectors are returned for αβγ, αβγ′, and L).

Extended help

  • The keyword argument atol (default, 1.0e-12) specifies the absolute tolerance for the comparison.
  • If both v and v′ are not special, i.e., both have free parameters, the intersection point may not be unique (e.g., for co-linear v and v′).
  • The implementation currently only checks the immediately adjacent lattice vectors for equivalence; if there is equivalence, but the the required elements of L would have |Lᵢ| > 1, the currently implementation will not identify the equivalence.
  • This operation is usually only meaningful if the bases of kv and kv′ agree and are primitive.
source
Crystalline.compact_print_matrix — Function
compact_print_matrix(io, X::Matrix, prerow)
 compact_print_matrix(io, X::Matrix, prerow, elformat)
-

Print a matrix using PrettyTables, allowing a prerow input to be printed before each row of the matrix. elformat is applied to each element of the matrix before printing.

source
Crystalline.corep_orthogonality_factor — Method
corep_orthogonality_factor(
+

Print a matrix using PrettyTables, allowing a prerow input to be printed before each row of the matrix. elformat is applied to each element of the matrix before printing.

source
Crystalline.corep_orthogonality_factor — Method
corep_orthogonality_factor(
     ir::Crystalline.AbstractIrrep
 ) -> Int64
-

–> Int

Return a multiplicative factor for use in checking the orthogonality relations of "physically real" irreps (coreps).

For such "physically real" irreps, the conventional orthogonality relations (by conventional we mean orthogonality relations that sum only over unitary operations, i.e. no "gray" operations/products with time-inversion) still hold if we include a multiplicative factor f that depends on the underlying reality type r of the corep, such that f(REAL) = 1, f(COMPLEX) = 2, and f(PSEUDOREAL) = 4. If the provided irrep is not a corep (i.e. has iscorep(ir) = false), the multiplicative factor is 1.

References

See e.g. Bradley & Cracknell Eq. (7.4.10).

source
Crystalline.find_compatible — Method
find_compatible(
+

–> Int

Return a multiplicative factor for use in checking the orthogonality relations of "physically real" irreps (coreps).

For such "physically real" irreps, the conventional orthogonality relations (by conventional we mean orthogonality relations that sum only over unitary operations, i.e. no "gray" operations/products with time-inversion) still hold if we include a multiplicative factor f that depends on the underlying reality type r of the corep, such that f(REAL) = 1, f(COMPLEX) = 2, and f(PSEUDOREAL) = 4. If the provided irrep is not a corep (i.e. has iscorep(ir) = false), the multiplicative factor is 1.

References

See e.g. Bradley & Cracknell Eq. (7.4.10).

source
Crystalline.find_principal_rotations — Method
find_principal_rotations(
     ops::AbstractArray{SymOperation{D}, 1};
     include_improper
 ) -> Vector{Int64}
-

Return the the indices of the "maximal" rotations among a set of operations ops, i.e. those of maximal order (the "principal rotations").

Keyword arguments

  • include_improper (=false): if true, improper rotations are included in the consideration. If the order of improper and proper rotations is identical, only the indices of the proper rotations are returned. If the maximal (signed) rotation order is -2 (a mirror), it is ignored, and the index of the identity operation is returned.
source
Crystalline.findequiv — Method
findequiv(op::SymOperation, ops::AbstractVector{SymOperation{D}}, cntr::Char) 
-                                            --> Tuple{Int, Vector{Float64}}

Search for an operator op′ in ops which is equivalent, modulo differences by primitive lattice translations Δw, to op. Return the index of op′ in ops, as well as the primitive translation difference Δw. If no match is found returns nothing.

The small irreps of op at wavevector k, Dⱼᵏ[op], can be computed from the small irreps of op′, Dⱼᵏ[op′], via Dⱼᵏ[op] = exp(2πik⋅Δw)Dⱼᵏ[op′]

source
Crystalline.fractionify! — Function
fractionify!(io::IO, x::Real, forcesign::Bool=true, tol::Real=1e-6)

Write a string representation of the nearest fraction (within a tolerance tol) of x to io. If forcesign is true, the sign character of x is printed whether + or - (otherwise, only printed if -).

source
Crystalline.freeparams — Method
freeparams(v::Crystalline.AbstractVec) -> Any
-

Return a vector whose entries are true (false) if the free parameters α,β,γ, respectively, occur with nonzero (zero) coefficients in v.

source
Crystalline.induce_bandrep — Method
induce_bandrep(siteir::SiteIrrep, h::SymOperation, kv::KVec)

Return the band representation induced by the provided SiteIrrep evaluated at kv and for a SymOperation h.

source
Crystalline.isapproxin — Method
isapproxin(x, itr, optargs...; kwargs...) --> Bool

Determine whether x ∈ itr with approximate equality.

source
Crystalline.iscorep — Method
iscorep(ir::Crystalline.AbstractIrrep) -> Any
-

–> Bool

Return whether the provided irrep has been made "physically real" (i.e. is a corep) so that it differs from the underlying irrep (i.e. whether the irrep and "derived" corep differ).

For an irrep that has not been passed to realify, this is always false. For an irrep produced by realify, this can be either false or true: if the reality type is REAL it is false; if the reality type is PSEUDOREAL or COMPLEX it is true.

source
Crystalline.matching_littlegroups — Method
matching_littlegroups(brs::BandRepSet, ::Val{D}=Val(3))

Finds the matching little groups for each k-point referenced in brs. This is mainly a a convenience accessor, since e.g. littlegroup(::SpaceGroup, ::KVec) could also return the required little groups. The benefit here is that the resulting operator sorting of the returned little group is identical to the operator sortings assumed in lgirreps and littlegroups.

Returns a Vector{LittleGroup{D}} (unlike littlegroups, which returns a Dict{String, LittleGroup{D}}).

Note 1

Unlike the operations returned by spacegroup, the returned little groups do not include copies of operators that would be identical when transformed to a primitive basis. The operators are, however, still given in a conventional basis.

source
Crystalline.parsefraction — Method
parsefraction(str::AbstractString, T::Type=Float64)

Parse a string str, allowing fraction inputs (e.g. "1/2"), return as a type T (default, Float64).

source
Crystalline.permute_multtable — Method
permute_multtable(
+

Return the the indices of the "maximal" rotations among a set of operations ops, i.e. those of maximal order (the "principal rotations").

Keyword arguments

  • include_improper (=false): if true, improper rotations are included in the consideration. If the order of improper and proper rotations is identical, only the indices of the proper rotations are returned. If the maximal (signed) rotation order is -2 (a mirror), it is ignored, and the index of the identity operation is returned.
source
Crystalline.findequiv — Method
findequiv(op::SymOperation, ops::AbstractVector{SymOperation{D}}, cntr::Char) 
+                                            --> Tuple{Int, Vector{Float64}}

Search for an operator op′ in ops which is equivalent, modulo differences by primitive lattice translations Δw, to op. Return the index of op′ in ops, as well as the primitive translation difference Δw. If no match is found returns nothing.

The small irreps of op at wavevector k, Dⱼᵏ[op], can be computed from the small irreps of op′, Dⱼᵏ[op′], via Dⱼᵏ[op] = exp(2πik⋅Δw)Dⱼᵏ[op′]

source
Crystalline.fractionify! — Function
fractionify!(io::IO, x::Real, forcesign::Bool=true, tol::Real=1e-6)

Write a string representation of the nearest fraction (within a tolerance tol) of x to io. If forcesign is true, the sign character of x is printed whether + or - (otherwise, only printed if -).

source
Crystalline.freeparams — Method
freeparams(v::Crystalline.AbstractVec) -> Any
+

Return a vector whose entries are true (false) if the free parameters α,β,γ, respectively, occur with nonzero (zero) coefficients in v.

source
Crystalline.induce_bandrep — Method
induce_bandrep(siteir::SiteIrrep, h::SymOperation, kv::KVec)

Return the band representation induced by the provided SiteIrrep evaluated at kv and for a SymOperation h.

source
Crystalline.isapproxin — Method
isapproxin(x, itr, optargs...; kwargs...) --> Bool

Determine whether x ∈ itr with approximate equality.

source
Crystalline.iscorep — Method
iscorep(ir::Crystalline.AbstractIrrep) -> Any
+

–> Bool

Return whether the provided irrep has been made "physically real" (i.e. is a corep) so that it differs from the underlying irrep (i.e. whether the irrep and "derived" corep differ).

For an irrep that has not been passed to realify, this is always false. For an irrep produced by realify, this can be either false or true: if the reality type is REAL it is false; if the reality type is PSEUDOREAL or COMPLEX it is true.

source
Crystalline.matching_littlegroups — Method
matching_littlegroups(brs::BandRepSet, ::Val{D}=Val(3))

Finds the matching little groups for each k-point referenced in brs. This is mainly a a convenience accessor, since e.g. littlegroup(::SpaceGroup, ::KVec) could also return the required little groups. The benefit here is that the resulting operator sorting of the returned little group is identical to the operator sortings assumed in lgirreps and littlegroups.

Returns a Vector{LittleGroup{D}} (unlike littlegroups, which returns a Dict{String, LittleGroup{D}}).

Note 1

Unlike the operations returned by spacegroup, the returned little groups do not include copies of operators that would be identical when transformed to a primitive basis. The operators are, however, still given in a conventional basis.

source
Crystalline.parsefraction — Method
parsefraction(str::AbstractString, T::Type=Float64)

Parse a string str, allowing fraction inputs (e.g. "1/2"), return as a type T (default, Float64).

source
Crystalline.permute_multtable — Method
permute_multtable(
     mt::Matrix{Int64},
     P::AbstractVector{Int64}
 ) -> Any
@@ -52,5 +52,5 @@
 mt  = MultTable(pg)
 P   = [2,3,1,4,5,8,6,7] # permutation of operator indices
 mt′ = permute_multtable(mt.table, P)
-mt′ == MultTable(pg[P]).table
source
Crystalline.reduce_dict_of_vectors — Method
reduce_dict_of_vectors([f=identity,] d::Dict{_, <:Vector})  -->  Vector{T}

Return the concatenated vector of all of vectors in d under the element-wise application of f. Effectively flattens a Dict of Vectors to a single Vector.

Note that application of f to vector-elements of d must return a stable type T.

source
Crystalline.reduce_orbits! — Method
reduce_orbits!(orbits::Vector{WyckoffPosition}, cntr::Char, conv_or_prim::Bool=true])

Update orbits in-place to contain only those Wyckoff positions that are not equivalent in a primitive basis (as determined by the centering type cntr). Returns the updated orbits.

If conv_or_prim = true (default), the Wyckoff positions are returned in the original, conventional basis; if conv_or_prim = false, they are returned in a primitive basis.

source
Crystalline.rotation_order — Method
rotation_order(W::Matrix{<:Real}) --> Int
-rotation_order(op::SymOperation)  --> Int

Determine the integer rotation order of a point group operation, input either as a matrix W or op::SymOperation.

The rotation order of

  • Proper rotations is positive.
  • Improper (mirrors, inversion, roto-inversions) is negative.
source
Crystalline.rotation_order_3d — Method
rotation_order_3d(detW::Real, trW::Real) --> Int

Determine the integer rotation order of a 3D point group operation with a 3×3 matrix representation W (alternatively specified by its determinant detW and its trace trW).

The rotation order of

  • Proper rotations is positive.
  • Improper (mirrors, inversion, roto-inversions) is negative.
source
Crystalline.uniquetol — Method
uniquetol(a; kwargs)

Computes approximate-equality unique with tolerance specifiable via keyword arguments kwargs in O(n²) runtime.

Copied from https://github.com/JuliaLang/julia/issues/19147#issuecomment-256981994

source
Crystalline.wyckbasis — Method
wyckbasis(brs::BandRepSet) --> Vector{Vector{Int}}

Computes the (band representation) basis for bands generated by localized orbitals placed at the Wyckoff positions. Any band representation that can be expanded on this basis with positive integer coefficients correspond to a trivial insulators (i.e. deformable to atomic limit). Conversely, bands that cannot are topological, either fragily (some negative coefficients) or strongly (fractional coefficients).

source
+mt′ == MultTable(pg[P]).tablesource
Crystalline.reduce_dict_of_vectors — Method
reduce_dict_of_vectors([f=identity,] d::Dict{_, <:Vector})  -->  Vector{T}

Return the concatenated vector of all of vectors in d under the element-wise application of f. Effectively flattens a Dict of Vectors to a single Vector.

Note that application of f to vector-elements of d must return a stable type T.

source
Crystalline.reduce_orbits! — Method
reduce_orbits!(orbits::Vector{WyckoffPosition}, cntr::Char, conv_or_prim::Bool=true])

Update orbits in-place to contain only those Wyckoff positions that are not equivalent in a primitive basis (as determined by the centering type cntr). Returns the updated orbits.

If conv_or_prim = true (default), the Wyckoff positions are returned in the original, conventional basis; if conv_or_prim = false, they are returned in a primitive basis.

source
Crystalline.reduce_translation_to_unitrange — Method
reduce_translation_to_unitrange_q(w::AbstractVector{<:Real}) --> :: typeof(w)

Reduce the components of the vector w to range [0.0, 1.0[, incorporating a tolerance atol in the reduction.

source
Crystalline.rotation_order — Method
rotation_order(W::Matrix{<:Real}) --> Int
+rotation_order(op::SymOperation)  --> Int

Determine the integer rotation order of a point group operation, input either as a matrix W or op::SymOperation.

The rotation order of

  • Proper rotations is positive.
  • Improper (mirrors, inversion, roto-inversions) is negative.
source
Crystalline.rotation_order_3d — Method
rotation_order_3d(detW::Real, trW::Real) --> Int

Determine the integer rotation order of a 3D point group operation with a 3×3 matrix representation W (alternatively specified by its determinant detW and its trace trW).

The rotation order of

  • Proper rotations is positive.
  • Improper (mirrors, inversion, roto-inversions) is negative.
source
Crystalline.uniquetol — Method
uniquetol(a; kwargs)

Computes approximate-equality unique with tolerance specifiable via keyword arguments kwargs in O(n²) runtime.

Copied from https://github.com/JuliaLang/julia/issues/19147#issuecomment-256981994

source
Crystalline.wyckbasis — Method
wyckbasis(brs::BandRepSet) --> Vector{Vector{Int}}

Computes the (band representation) basis for bands generated by localized orbitals placed at the Wyckoff positions. Any band representation that can be expanded on this basis with positive integer coefficients correspond to a trivial insulators (i.e. deformable to atomic limit). Conversely, bands that cannot are topological, either fragily (some negative coefficients) or strongly (fractional coefficients).

source
diff --git a/previews/PR49/irreps/index.html b/previews/PR49/irreps/index.html index d83e4f21..6b11cf39 100644 --- a/previews/PR49/irreps/index.html +++ b/previews/PR49/irreps/index.html @@ -356,4 +356,4 @@ "Γ₃" => COMPLEX "Γ₄" => COMPLEX "Γ₅" => COMPLEX - "Γ₆" => COMPLEX

The reality type can be computed ab initio via calc_reality, using the Frobenius criterion for PGIrreps and SiteIrreps and the Herring criterion for LGIrreps.

Data sources

Point group irreps are obtained from the Bilbao Crystallographic Server's Representations PG program and little group irreps of space groups are obtained from ISOTROPY's 2011 ISO-IR dataset.

If these functionalities are used in published research, please cite the original publications (listed in associated function docstrings).

+ "Γ₆" => COMPLEX

The reality type can be computed ab initio via calc_reality, using the Frobenius criterion for PGIrreps and SiteIrreps and the Herring criterion for LGIrreps.

Data sources

Point group irreps are obtained from the Bilbao Crystallographic Server's Representations PG program and little group irreps of space groups are obtained from ISOTROPY's 2011 ISO-IR dataset.

If these functionalities are used in published research, please cite the original publications (listed in associated function docstrings).

diff --git a/previews/PR49/lattices/index.html b/previews/PR49/lattices/index.html index 8e0112d6..dea46314 100644 --- a/previews/PR49/lattices/index.html +++ b/previews/PR49/lattices/index.html @@ -1,13 +1,13 @@ -Lattices · Crystalline.jl

Isosurfaces with space group symmetry

Crystalline.UnityFourierLattice — Type
UnityFourierLattice{D} <: AbstractFourierLattice{D}

A general D-dimensional Fourier (plane wave) lattice specified by orbits of reciprocal lattice vectors (orbits) and coefficient interrelations (orbitcoefs)). The norm of all elements in orbitcoefs is unity. orbits (and associated coefficients) are sorted in order of increasing norm (low to high).

source
Crystalline.ModulatedFourierLattice — Type
ModulatedFourierLattice{D} <: AbstractFourierLattice{D}

A D-dimensional concrete Fourier (plane wave) lattice, derived from a UnityFourierLattice{D} by scaling and modulating its orbit coefficients by complex numbers; in general, the coefficients do not have unit norm.

source
Crystalline.levelsetlattice — Function
levelsetlattice(sgnum::Integer, D::Integer=2, idxmax::NTuple=ntuple(i->2,D))
+Lattices · Crystalline.jl
Isosurfaces with space group symmetry
Crystalline.UnityFourierLattice — Type
UnityFourierLattice{D} <: AbstractFourierLattice{D}
A general D-dimensional Fourier (plane wave) lattice specified by orbits of reciprocal lattice vectors (orbits) and coefficient interrelations (orbitcoefs)). The norm of all elements in orbitcoefs is unity. orbits (and associated coefficients) are sorted in order of increasing norm (low to high).
source
Crystalline.ModulatedFourierLattice — Type
ModulatedFourierLattice{D} <: AbstractFourierLattice{D}
A D-dimensional concrete Fourier (plane wave) lattice, derived from  a UnityFourierLattice{D} by scaling and modulating its orbit coefficients  by complex numbers; in general, the coefficients do not have unit norm.
source
Crystalline.levelsetlattice — Function
levelsetlattice(sgnum::Integer, D::Integer=2, idxmax::NTuple=ntuple(i->2,D))
     --> UnityFourierLattice{D}
Compute a "neutral"/uninitialized Fourier lattice basis, a UnityFourierLattice, consistent with the symmetries of the space group sgnum in dimension D.  The resulting lattice flat is expanded in a Fourier basis split into symmetry-derived orbits, with intra-orbit coefficients constrained by the symmetries of the space-group. The inter-orbit coefficients are, however, free and unconstrained.
The Fourier resolution along each reciprocal lattice vector is controlled by idxmax: e.g., if D = 2 and idxmax = (2, 3), the resulting Fourier lattice may contain  reciprocal lattice vectors (k₁, k₂) with k₁∈[0,±1,±2] and k₂∈[0,±1,±2,±3], referred  to a 𝐆-basis.
This "neutral" lattice can, and usually should, be subsequently modulated by modulate (which modulates the inter-orbit coefficients, which may eliminate "synthetic symmetries" that can exist in the "neutral" configuration, due to all  inter-orbit coefficients being set to unity).
Examples
Compute a UnityFourierLattice, modulate it with random inter-orbit coefficients  via modulate, and finally plot it (via PyPlot.jl):
julia> uflat = levelsetlattice(16, Val(2))
 julia> flat  = modulate(uflat)
 julia> Rs    = directbasis(16, Val(2)) 
 julia> using PyPlot
-julia> plot(flat, Rs)
source
Crystalline.modulate — Function
modulate(flat::UnityFourierLattice{D},
 modulation::AbstractVector{ComplexF64}=rand(ComplexF64, length(getcoefs(flat))),
 expon::Union{Nothing, Real}=nothing, Gs::Union{ReciprocalBasis{D}, Nothing}=nothing)
-                        --> ModulatedFourierLattice{D}
Derive a concrete, modulated Fourier lattice from a UnityFourierLattice flat (containing the interrelations between orbit coefficients), by  multiplying the "normalized" orbit coefficients by a modulation, a complex modulating vector (in general, should be complex; otherwise restores unintended symmetry to the lattice). Distinct modulation vectors produce distinct  realizations of the same lattice described by the original flat. By default, a random complex vector is used.
An exponent expon can be provided, which introduces a penalty term to short- wavelength features (i.e. high-|G| orbits) by dividing the orbit coefficients by |G|^expon; producing a "simpler" and "smoother" lattice boundary when expon > 0 (reverse for expon < 0). This basically amounts to a  continuous "simplifying" operation on the lattice (it is not necessarily a  smoothing operation; it simply suppresses "high-frequency" components). If expon = nothing, no rescaling is performed. If Gs is provided as nothing, the orbit norm is computed in the reciprocal lattice basis (and, so, may not strictly speaking be a norm if the lattice basis is not cartesian); to account for the basis explicitly, Gs must be provided as a ReciprocalBasis, see also normscale.
source
Bravais.primitivize — Method
primitivize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat)
Given flat referred to a conventional basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated primitive basis. 
Specifically, if flat refers to a direct conventional basis Rs $≡ (\mathbf{a} \mathbf{b} \mathbf{c})$ [with coordinate vectors $\mathbf{r} ≡ (r_1, r_2, r_3)^{\mathrm{T}}$] then flat′ refers to a direct primitive basis Rs′ $≡ (\mathbf{a}' \mathbf{b}' \mathbf{c}') ≡ (\mathbf{a} \mathbf{b} \mathbf{c})\mathbf{P}$ [with coordinate vectors  $\mathbf{r}' ≡ (r_1', r_2', r_3')^{\mathrm{T}} = \mathbf{P}^{-1}\mathbf{r}$], where $\mathbf{P}$ denotes the basis-change matrix obtained from primitivebasismatrix(...).
To compute the associated primitive basis vectors, see primitivize(::DirectBasis, ::Char) [specifically, Rs′ = primitivize(Rs, cntr)].
Examples
A centered ('c') lattice from plane group 5 in 2D, plotted in its  conventional and primitive basis (requires using PyPlot):
julia> sgnum = 5; D = 2; cntr = centering(sgnum, D)  # 'c' (body-centered)
+                        --> ModulatedFourierLattice{D}
Derive a concrete, modulated Fourier lattice from a UnityFourierLattice flat (containing the interrelations between orbit coefficients), by  multiplying the "normalized" orbit coefficients by a modulation, a complex modulating vector (in general, should be complex; otherwise restores unintended symmetry to the lattice). Distinct modulation vectors produce distinct  realizations of the same lattice described by the original flat. By default, a random complex vector is used.
An exponent expon can be provided, which introduces a penalty term to short- wavelength features (i.e. high-|G| orbits) by dividing the orbit coefficients by |G|^expon; producing a "simpler" and "smoother" lattice boundary when expon > 0 (reverse for expon < 0). This basically amounts to a  continuous "simplifying" operation on the lattice (it is not necessarily a  smoothing operation; it simply suppresses "high-frequency" components). If expon = nothing, no rescaling is performed. If Gs is provided as nothing, the orbit norm is computed in the reciprocal lattice basis (and, so, may not strictly speaking be a norm if the lattice basis is not cartesian); to account for the basis explicitly, Gs must be provided as a ReciprocalBasis, see also normscale.
source
Bravais.primitivize — Method
primitivize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat)
Given flat referred to a conventional basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated primitive basis. 
Specifically, if flat refers to a direct conventional basis Rs $≡ (\mathbf{a} \mathbf{b} \mathbf{c})$ [with coordinate vectors $\mathbf{r} ≡ (r_1, r_2, r_3)^{\mathrm{T}}$] then flat′ refers to a direct primitive basis Rs′ $≡ (\mathbf{a}' \mathbf{b}' \mathbf{c}') ≡ (\mathbf{a} \mathbf{b} \mathbf{c})\mathbf{P}$ [with coordinate vectors  $\mathbf{r}' ≡ (r_1', r_2', r_3')^{\mathrm{T}} = \mathbf{P}^{-1}\mathbf{r}$], where $\mathbf{P}$ denotes the basis-change matrix obtained from primitivebasismatrix(...).
To compute the associated primitive basis vectors, see primitivize(::DirectBasis, ::Char) [specifically, Rs′ = primitivize(Rs, cntr)].
Examples
A centered ('c') lattice from plane group 5 in 2D, plotted in its  conventional and primitive basis (requires using PyPlot):
julia> sgnum = 5; D = 2; cntr = centering(sgnum, D)  # 'c' (body-centered)
 
 julia> Rs   = directbasis(sgnum, Val(D))     # conventional basis (rectangular)
 julia> flat = levelsetlattice(sgnum, Val(D)) # Fourier lattice in basis of Rs
@@ -18,5 +18,5 @@
 julia> flat′ = primitivize(flat, cntr)  # Fourier lattice in basis of Rs′
 
 julia> using PyPlot
-julia> plot(flat′, Rs′)
source
Bravais.conventionalize — Method
conventionalize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat′)
Given flat referred to a primitive basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated conventional basis. 
See also the complementary method primitivize(::AbstractFourierLattice, ::Char) for additional details.
source
Crystalline.AbstractFourierLattice — Method
(flat::AbstractFourierLattice)(xyz) --> Float64
-(flat::AbstractFourierLattice)(xyzs...) --> Float64
Evaluate an AbstractFourierLattice at the point xyz and return its real part, i.e.
\[    \mathop{\mathrm{Re}}\sum_i c_i \exp(2\pi i\mathbf{G}_i\cdot\mathbf{r})\]
with $\mathrm{G}_i$ denoting reciprocal lattice vectors in the allowed orbits of flat, with $c_i$ denoting the associated coefficients (and $\mathbf{r} \equiv$ xyz).
xyz may be any iterable object with dimension matching flat consisting of real numbers (e.g., a Tuple, Vector, or SVector). Alternatively, the coordinates can be supplied individually (i.e., as flat(x, y, z)).
source

+julia> plot(flat′, Rs′)
source
Bravais.conventionalize — Method
conventionalize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat′)

Given flat referred to a primitive basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated conventional basis.

See also the complementary method primitivize(::AbstractFourierLattice, ::Char) for additional details.

source
Crystalline.AbstractFourierLattice — Method
(flat::AbstractFourierLattice)(xyz) --> Float64
+(flat::AbstractFourierLattice)(xyzs...) --> Float64

Evaluate an AbstractFourierLattice at the point xyz and return its real part, i.e.

\[ \mathop{\mathrm{Re}}\sum_i c_i \exp(2\pi i\mathbf{G}_i\cdot\mathbf{r})\]

with $\mathrm{G}_i$ denoting reciprocal lattice vectors in the allowed orbits of flat, with $c_i$ denoting the associated coefficients (and $\mathbf{r} \equiv$ xyz).

xyz may be any iterable object with dimension matching flat consisting of real numbers (e.g., a Tuple, Vector, or SVector). Alternatively, the coordinates can be supplied individually (i.e., as flat(x, y, z)).

source
diff --git a/previews/PR49/operations/index.html b/previews/PR49/operations/index.html index c9656591..d5e576c4 100644 --- a/previews/PR49/operations/index.html +++ b/previews/PR49/operations/index.html @@ -19,4 +19,4 @@ └ 0 1 0 ╵ 0 ┘

Operator inverses

The operator inverse is defined as $\{\mathbf{W}|\mathbf{w}\} = \{\mathbf{W}^{-1}|-\mathbf{W}^{-1}\mathbf{w}\}$ and can be computed via

inv(op1) # inv(3₁₁₁⁺)
3₁₁₁⁻ ──────────────────────────── (y,z,x)
  ┌ 0  1  0 ╷ -0 ┐
  │ 0  0  1 ┆ -0 │
- └ 1  0  0 ╵ -0 ┘

Action of symmetry operators

A SymOperation can act on vectors in direct (RVec) or reciprocal (KVec) space. When acting in reciprocal space, translation parts of a SymOperation have no effect.

Magnetic symmetry operations

Magnetic symmetry operations that may incorporate composition with an anti-unitary time-reversal operation can be created via MSymOperation (see also mspacegroup).

+ └ 1 0 0 ╵ -0 ┘

Action of symmetry operators

A SymOperation can act on vectors in direct (RVec) or reciprocal (KVec) space. When acting in reciprocal space, translation parts of a SymOperation have no effect.

Magnetic symmetry operations

Magnetic symmetry operations that may incorporate composition with an anti-unitary time-reversal operation can be created via MSymOperation (see also mspacegroup).

diff --git a/previews/PR49/search_index.js b/previews/PR49/search_index.js index d726d0d2..bf9ec05f 100644 --- a/previews/PR49/search_index.js +++ b/previews/PR49/search_index.js @@ -1,3 +1,3 @@ var documenterSearchIndex = {"docs": -[{"location":"operations/#Symmetry-operations","page":"Symmetry operations","title":"Symmetry operations","text":"","category":"section"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"A SymOperation{D} is a representation of a spatial symmetry operation g=mathbfWmathbfw, composed of a rotational mathbfW and a translation part mathbfw. The rotational and translation parts are assumed to share the same basis setting; by default, operations returned by Crystalline.jl are in the conventional setting of the International Tables of Crystallography, Volume A (ITA).","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"SymOperations can be constructed in two ways, either by explicitly specifying the mathbfW and mathbfw:","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"using Crystalline, StaticArrays\nW, w = (@SMatrix [1 0 0; 0 0 1; 0 1 0]), (@SVector [0, 0.5, 0])\nop = SymOperation(W, w)","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"or by its equivalent triplet form","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"op = SymOperation{3}(\"x,z+1/2,y\")","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"There is also a string macro accessor @S_str that allows triplet input via S\"x,z+1/2,y\".","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"In the above output, three equivalent notations for the symmetry operation are given: first, the Seitz notation {m₀₋₁₁|0,½,0}, then the triplet notation (x,z+1/2,y), and finally the explicit matrix notation.","category":"page"},{"location":"operations/#Components","page":"Symmetry operations","title":"Components","text":"","category":"section"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"The rotation and translation parts mathbfW and mathbfw of a SymOperation{D} mathbfWmathbfw can be accessed via rotation and translation, returning an SMatrix{D, D, Float64} and an SVector{D, Float64}, respectively. The \"augmented\" matrix mathbfWmathbfw can similarly be obtained via matrix.","category":"page"},{"location":"operations/#Operator-composition","page":"Symmetry operations","title":"Operator composition","text":"","category":"section"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"Composition of two operators g_1 and g_2 is defined by ","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"g_1 circ g_2 = mathbfW_1mathbfw_1 circ mathbfW_2mathbfw_2 = mathbfW_1mathbfW_2mathbfw_1 + mathbfW_1mathbfw_2","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"We can compose two SymOperations in Crystalline via:","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"op1 = S\"z,x,y\" # 3₁₁₁⁺\nop2 = S\"z,y,x\" # m₋₁₀₁\nop1 * op2","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"which is accessed by an overloaded call to Base.*, i.e. the multiplication operator (this enables us to also call derived methods of *, such as integer powers (e.g., S\"-y,x-y,z\"^3 == S\"x,y,z\"). Note that composition is taken modulo integer lattice translations by default, such that","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"op2′ = S\"z,y,x+1\" # {m₋₁₀₁|001}\nop1 * op2′ # equivalent to compose(op1, op2′, true)","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"rather than S\"x+1,z,y\", which is the result of direct application of the above composition rule. To compute \"unreduced\" composition, the more precise compose variant of * can be used with an optional third argument false:","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"compose(op1, op2′, false)","category":"page"},{"location":"operations/#Operator-inverses","page":"Symmetry operations","title":"Operator inverses","text":"","category":"section"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"The operator inverse is defined as mathbfWmathbfw = mathbfW^-1-mathbfW^-1mathbfw and can be computed via","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"inv(op1) # inv(3₁₁₁⁺)","category":"page"},{"location":"operations/#Action-of-symmetry-operators","page":"Symmetry operations","title":"Action of symmetry operators","text":"","category":"section"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"A SymOperation can act on vectors in direct (RVec) or reciprocal (KVec) space. When acting in reciprocal space, translation parts of a SymOperation have no effect.","category":"page"},{"location":"operations/#Magnetic-symmetry-operations","page":"Symmetry operations","title":"Magnetic symmetry operations","text":"","category":"section"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"Magnetic symmetry operations that may incorporate composition with an anti-unitary time-reversal operation can be created via MSymOperation (see also mspacegroup).","category":"page"},{"location":"internal-api/#Internal-API","page":"Internal API","title":"Internal API","text":"","category":"section"},{"location":"internal-api/","page":"Internal API","title":"Internal API","text":"This page lists unexported functionality from Crystalline, that may be of interest to developers.","category":"page"},{"location":"internal-api/","page":"Internal API","title":"Internal API","text":"","category":"page"},{"location":"internal-api/","page":"Internal API","title":"Internal API","text":"CurrentModule = Crystalline","category":"page"},{"location":"internal-api/#Unexported,-internal-functionality","page":"Internal API","title":"Unexported, internal functionality","text":"","category":"section"},{"location":"internal-api/","page":"Internal API","title":"Internal API","text":"Modules = [Crystalline]\nPrivate = true\nPublic = false\nOrder = [:type, :function, :constant]","category":"page"},{"location":"internal-api/#Crystalline.AbstractFourierLattice-Tuple{Any}","page":"Internal API","title":"Crystalline.AbstractFourierLattice","text":"(flat::AbstractFourierLattice)(xyz) --> Float64\n(flat::AbstractFourierLattice)(xyzs...) --> Float64\n\nEvaluate an AbstractFourierLattice at the point xyz and return its real part, i.e.\n\n mathopmathrmResum_i c_i exp(2pi imathbfG_icdotmathbfr)\n\nwith mathrmG_i denoting reciprocal lattice vectors in the allowed orbits of flat, with c_i denoting the associated coefficients (and mathbfr equiv xyz).\n\nxyz may be any iterable object with dimension matching flat consisting of real numbers (e.g., a Tuple, Vector, or SVector). Alternatively, the coordinates can be supplied individually (i.e., as flat(x, y, z)).\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.AbstractGroup","page":"Internal API","title":"Crystalline.AbstractGroup","text":"abstract type AbstractGroup{D, O} <: AbstractArray{O, 1}\n\nThe abstract supertype of all group structures, with assumed group elements of type O and embedding dimension D.\n\nMinimum interface includes definitions of: - num(::AbstractGroup), returning an integer or tuple of integers. - operations(::AbstractGroup), returning a set of operations. or, alternatively, fields with names num and operations, behaving accordingly.\n\n\n\n\n\n","category":"type"},{"location":"internal-api/#Crystalline.AbstractIrrep","page":"Internal API","title":"Crystalline.AbstractIrrep","text":"AbstractIrrep{D}\n\nAbstract supertype for irreps of dimensionality D: must have fields cdml, matrices, g (underlying group), reality (and possibly translations). May overload a function irreps that returns the associated irrep matrices; if not, will simply be matrices.\n\n\n\n\n\n","category":"type"},{"location":"internal-api/#Crystalline.GenericGroup","page":"Internal API","title":"Crystalline.GenericGroup","text":"struct GenericGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}\n\noperations::Array{SymOperation{D}, 1} where D\n\n\n\n\n\n","category":"type"},{"location":"internal-api/#Crystalline.UnityFourierLattice","page":"Internal API","title":"Crystalline.UnityFourierLattice","text":"UnityFourierLattice{D} <: AbstractFourierLattice{D}\n\nA general D-dimensional Fourier (plane wave) lattice specified by orbits of reciprocal lattice vectors (orbits) and coefficient interrelations (orbitcoefs)). The norm of all elements in orbitcoefs is unity. orbits (and associated coefficients) are sorted in order of increasing norm (low to high).\n\n\n\n\n\n","category":"type"},{"location":"internal-api/#Base.parse-Union{Tuple{D}, Tuple{Type{<:SymmetryVector}, AbstractString, Array{Collection{LGIrrep{D}}, 1}}} where D","page":"Internal API","title":"Base.parse","text":"parse(::Type{SymmetryVector{D}}, \n s::AbstractString,\n lgirsv::Vector{Collection{LGIrrep{D}}}) -> SymmetryVector{D}\n\nParse a string s to a SymmetryVector over the irreps provided in lgirsv. The irrep labels of lgirsv and s must use the same convention.\n\nExample\n\njulia> brs = calc_bandreps(220);\n\njulia> lgirsv = irreps(brs); # irreps at P, H, Γ, & PA\n\njulia> s = \"[2P₃, 4N₁, H₁H₂+H₄H₅, Γ₁+Γ₂+Γ₄+Γ₅, 2PA₃]\";\n\njulia> parse(SymmetryVector, s, lgirsv)\n15-irrep SymmetryVector{3}:\n [2P₃, 4N₁, H₁H₂+H₄H₅, Γ₁+Γ₂+Γ₄+Γ₅, 2PA₃] (8 bands)\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.:⊚-Union{Tuple{T}, Tuple{T, T}} where T<:SymOperation","page":"Internal API","title":"Crystalline.:⊚","text":"(⊚)(op1::T, op2::T) where T<:SymOperation --> Vector{Float64}\n\nCompose two symmetry operations op1 = W₁w₁ and op2 = W₂w₂ and return the quotient of w₁+W₁w₂ and 1. This functionality complements op1*op2, which yields the translation modulo 1; accordingly, translation(op1*op2) + op1⊚op2 yields the translation component of the composition op1 and op2 without taking it modulo 1, i.e. including any \"trivial\" lattice translation.\n\nNote that ⊚ can be auto-completed in Julia via \\circledcirc+[tab]\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.CompositeBandRep_from_indices-Tuple{Vector{Int64}, Collection{<:NewBandRep}}","page":"Internal API","title":"Crystalline.CompositeBandRep_from_indices","text":"CompositeBandRep_from_indices(idxs::Vector{Int}, brs::Collection{<:NewBandRep})\n\nReturn a CompositeBandRep whose symmetry content is equal to the sum the band representations of brs over idxs. In terms of irrep multiplicity, this is equivalent to sum(brs[idxs]) in the sense that CompositeBandRep(idxs, brs) is equal to sum(brs[idxs]) for each irrep multiplicity. \n\nThe difference, and primary motivation for using CompositeBandRep, is that CompositeBandRep retains information about which band representations are included and with what multiplicity (the multiplicity of the ith brs-element being equaling to count(==(i), idxs)).\n\nExample\n\njulia> brs = calc_bandreps(2);\n\njulia> cbr = CompositeBandRep_from_indices([1, 1, 2, 6], brs)\n16-irrep CompositeBandRep{3}:\n (1f|Aᵤ) + (1h|Aᵤ) + 2(1h|Ag) (4 bands)\n\njulia> cbr == brs[1] + brs[1] + brs[2] + brs[6]\ntrue\n\njulia> SymmetryVector(cbr)\n16-irrep SymmetryVector{3}:\n [2Z₁⁺+2Z₁⁻, Y₁⁺+3Y₁⁻, 2U₁⁺+2U₁⁻, 2X₁⁺+2X₁⁻, 3T₁⁺+T₁⁻, 2Γ₁⁺+2Γ₁⁻, 3V₁⁺+V₁⁻, R₁⁺+3R₁⁻] (4 bands)\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline._find_equal_groups_in_sorted-Tuple{AbstractVector}","page":"Internal API","title":"Crystalline._find_equal_groups_in_sorted","text":"_find_equal_groups_in_sorted(v::AbstractVector) --> Vector{UnitRange}\n\nReturns indices into groups of equal values in v. Input v must be sorted so that identical values are adjacent.\n\nExample\n\n_find_equal_groups_in_sorted([-4,1,1,3,3,3]) # returns [1:1, 2:3, 4:6]\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline._findsubgroup-Union{Tuple{D}, Tuple{AbstractArray{SymOperation{D}, 1}, AbstractArray{SymOperation{D}, 1}}, Tuple{AbstractArray{SymOperation{D}, 1}, AbstractArray{SymOperation{D}, 1}, Union{Nothing, Char}}} where D","page":"Internal API","title":"Crystalline._findsubgroup","text":"_findsubgroup(opsᴳ::T, opsᴴ::T′[, cntr]) where T⁽′⁾<:AbstractVector{SymOperation}\n --> Tuple{Bool, Vector{Int}}\n\nReturns a 2-tuple with elements:\n\nA boolean, indicating whether the group H (with operators opsᴴ) is a subgroup of the group G (with operators opsᴳ), i.e. whether H G.\nAn indexing vector idxsᴳ²ᴴ of opsᴳ into opsᴴ (empty if H is not a subgroup of G), such that all(isapprox(opsᴳ[idxsᴳ²ᴴ], opsᴴ, cntr).\n\nIf cntr is provided, comparison of operations in G and H is done in the associated primitive basis (i.e., cntr is passed to isapprox which compares operations in G and H).\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline._orbit-Tuple{AbstractVector{<:AbstractMatrix{<:Real}}, AbstractVector{<:Real}}","page":"Internal API","title":"Crystalline._orbit","text":"_orbit(Ws, x)\n\nComputes the orbit of a direct-space point x under a set of point-group operations Ws, i.e. computes the set {gx | g∈G} where g denotes elements of the group G composed of all operations in Ws (possibly iterated, to ensure full coverage).\n\nIt is important that Ws and x are given in the same basis. \n\n[W = PWP¹ if the basis change is from coordinates r to r' = Pr, corresponding to a new set of basis vectors (x̂')ᵀ=x̂ᵀP; e.g., when going from a direct basis representation to a Cartesian one, the basis change matrix is P = [R₁ R₂ R₃], with Rᵢ inserted as column vectors]\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.can_intersect-Union{Tuple{T}, Tuple{D}, Tuple{T, T}} where {D, T<:Crystalline.AbstractVec{D}}","page":"Internal API","title":"Crystalline.can_intersect","text":"can_intersect(\n v::Crystalline.AbstractVec{D},\n v′::Crystalline.AbstractVec{D};\n atol\n) -> NamedTuple{(:bool, :αβγ, :αβγ′, :L), <:Tuple{Bool, Any, Any, Any}}\n\n\nCheck whether two AbstractVecs v and v′ can intersect, i.e., whether there exist free parameters such that they are equivalent modulo an integer lattice vector.\n\nReturns a NamedTuple (; bool, αβγ, αβγ′, L). If bool = true, kv and kv′ are compatible in the sense that v(αβγ) == v′(αβγ′) + L if bool == true where L is an integer-valued lattice vector. If bool = false, they are incompatible (and zero-valued vectors are returned for αβγ, αβγ′, and L).\n\nExtended help\n\nThe keyword argument atol (default, 1.0e-12) specifies the absolute tolerance for the comparison.\nIf both v and v′ are not special, i.e., both have free parameters, the intersection point may not be unique (e.g., for co-linear v and v′).\nThe implementation currently only checks the immediately adjacent lattice vectors for equivalence; if there is equivalence, but the the required elements of L would have |Lᵢ| > 1, the currently implementation will not identify the equivalence.\nThis operation is usually only meaningful if the bases of kv and kv′ agree and are primitive.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.compact_print_matrix","page":"Internal API","title":"Crystalline.compact_print_matrix","text":"compact_print_matrix(io, X::Matrix, prerow)\ncompact_print_matrix(io, X::Matrix, prerow, elformat)\n\n\nPrint a matrix using PrettyTables, allowing a prerow input to be printed before each row of the matrix. elformat is applied to each element of the matrix before printing.\n\n\n\n\n\n","category":"function"},{"location":"internal-api/#Crystalline.corep_orthogonality_factor-Tuple{Crystalline.AbstractIrrep}","page":"Internal API","title":"Crystalline.corep_orthogonality_factor","text":"corep_orthogonality_factor(\n ir::Crystalline.AbstractIrrep\n) -> Int64\n\n\n–> Int\n\nReturn a multiplicative factor for use in checking the orthogonality relations of \"physically real\" irreps (coreps).\n\nFor such \"physically real\" irreps, the conventional orthogonality relations (by conventional we mean orthogonality relations that sum only over unitary operations, i.e. no \"gray\" operations/products with time-inversion) still hold if we include a multiplicative factor f that depends on the underlying reality type r of the corep, such that f(REAL) = 1, f(COMPLEX) = 2, and f(PSEUDOREAL) = 4. If the provided irrep is not a corep (i.e. has iscorep(ir) = false), the multiplicative factor is 1.\n\nReferences\n\nSee e.g. Bradley & Cracknell Eq. (7.4.10).\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.find_compatible-Union{Tuple{D}, Tuple{KVec{D}, AbstractArray{KVec{D}, 1}}} where D","page":"Internal API","title":"Crystalline.find_compatible","text":"find_compatible(\n kv::KVec{D},\n kvs′::AbstractArray{KVec{D}, 1}\n) -> Vector{Int64}\n\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.find_principal_rotations-Union{Tuple{AbstractArray{SymOperation{D}, 1}}, Tuple{D}} where D","page":"Internal API","title":"Crystalline.find_principal_rotations","text":"find_principal_rotations(\n ops::AbstractArray{SymOperation{D}, 1};\n include_improper\n) -> Vector{Int64}\n\n\nReturn the the indices of the \"maximal\" rotations among a set of operations ops, i.e. those of maximal order (the \"principal rotations\").\n\nKeyword arguments\n\ninclude_improper (=false): if true, improper rotations are included in the consideration. If the order of improper and proper rotations is identical, only the indices of the proper rotations are returned. If the maximal (signed) rotation order is -2 (a mirror), it is ignored, and the index of the identity operation is returned.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.findequiv-Union{Tuple{D}, Tuple{SymOperation{D}, AbstractArray{SymOperation{D}, 1}, Char}} where D","page":"Internal API","title":"Crystalline.findequiv","text":"findequiv(op::SymOperation, ops::AbstractVector{SymOperation{D}}, cntr::Char) \n --> Tuple{Int, Vector{Float64}}\n\nSearch for an operator op′ in ops which is equivalent, modulo differences by primitive lattice translations Δw, to op. Return the index of op′ in ops, as well as the primitive translation difference Δw. If no match is found returns nothing.\n\nThe small irreps of op at wavevector k, Dⱼᵏ[op], can be computed from the small irreps of op′, Dⱼᵏ[op′], via Dⱼᵏ[op] = exp(2πik⋅Δw)Dⱼᵏ[op′]\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.fractionify!","page":"Internal API","title":"Crystalline.fractionify!","text":"fractionify!(io::IO, x::Real, forcesign::Bool=true, tol::Real=1e-6)\n\nWrite a string representation of the nearest fraction (within a tolerance tol) of x to io. If forcesign is true, the sign character of x is printed whether + or - (otherwise, only printed if -).\n\n\n\n\n\n","category":"function"},{"location":"internal-api/#Crystalline.freeparams-Tuple{Crystalline.AbstractVec}","page":"Internal API","title":"Crystalline.freeparams","text":"freeparams(v::Crystalline.AbstractVec) -> Any\n\n\nReturn a vector whose entries are true (false) if the free parameters α,β,γ, respectively, occur with nonzero (zero) coefficients in v.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.induce_bandrep-Union{Tuple{D}, Tuple{SiteIrrep{D}, SymOperation{D}, KVec{D}}} where D","page":"Internal API","title":"Crystalline.induce_bandrep","text":"induce_bandrep(siteir::SiteIrrep, h::SymOperation, kv::KVec)\n\nReturn the band representation induced by the provided SiteIrrep evaluated at kv and for a SymOperation h.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.isapproxin-Tuple{Any, Any, Vararg{Any}}","page":"Internal API","title":"Crystalline.isapproxin","text":"isapproxin(x, itr, optargs...; kwargs...) --> Bool\n\nDetermine whether x ∈ itr with approximate equality.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.iscorep-Tuple{Crystalline.AbstractIrrep}","page":"Internal API","title":"Crystalline.iscorep","text":"iscorep(ir::Crystalline.AbstractIrrep) -> Any\n\n\n–> Bool\n\nReturn whether the provided irrep has been made \"physically real\" (i.e. is a corep) so that it differs from the underlying irrep (i.e. whether the irrep and \"derived\" corep differ).\n\nFor an irrep that has not been passed to realify, this is always false. For an irrep produced by realify, this can be either false or true: if the reality type is REAL it is false; if the reality type is PSEUDOREAL or COMPLEX it is true.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.matching_littlegroups-Union{Tuple{BandRepSet}, Tuple{D}, Tuple{BandRepSet, Val{D}}} where D","page":"Internal API","title":"Crystalline.matching_littlegroups","text":"matching_littlegroups(brs::BandRepSet, ::Val{D}=Val(3))\n\nFinds the matching little groups for each k-point referenced in brs. This is mainly a a convenience accessor, since e.g. littlegroup(::SpaceGroup, ::KVec) could also return the required little groups. The benefit here is that the resulting operator sorting of the returned little group is identical to the operator sortings assumed in lgirreps and littlegroups.\n\nReturns a Vector{LittleGroup{D}} (unlike littlegroups, which returns a Dict{String, LittleGroup{D}}).\n\nNote 1\n\nUnlike the operations returned by spacegroup, the returned little groups do not include copies of operators that would be identical when transformed to a primitive basis. The operators are, however, still given in a conventional basis.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.nfreeparams-Tuple{Crystalline.AbstractVec}","page":"Internal API","title":"Crystalline.nfreeparams","text":"nfreeparams(v::Crystalline.AbstractVec) -> Int64\n\n\nReturn total number of free parameters occuring in v.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.parsefraction-Union{Tuple{AbstractString}, Tuple{T}, Tuple{AbstractString, Type{T}}} where T","page":"Internal API","title":"Crystalline.parsefraction","text":"parsefraction(str::AbstractString, T::Type=Float64)\n\nParse a string str, allowing fraction inputs (e.g. \"1/2\"), return as a type T (default, Float64).\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.permute_multtable-Tuple{Matrix{Int64}, AbstractVector{Int64}}","page":"Internal API","title":"Crystalline.permute_multtable","text":"permute_multtable(\n mt::Matrix{Int64},\n P::AbstractVector{Int64}\n) -> Any\n\n\n–> Matrix{Int}\n\nReturns a multiplication table derived from mt but under a reordering permutation P of the operator indices in mt. In practice, this corresponds to a permutation of the rows and columns of mt as well as a subsequent relabelling of elements via P.\n\nExample\n\npg = pointgroup(\"-4m2\", Val(3))\nmt = MultTable(pg)\nP = [2,3,1,4,5,8,6,7] # permutation of operator indices\nmt′ = permute_multtable(mt.table, P)\nmt′ == MultTable(pg[P]).table\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.reduce_dict_of_vectors-Union{Tuple{F}, Tuple{F, Dict{<:Any, <:AbstractVector}}} where F","page":"Internal API","title":"Crystalline.reduce_dict_of_vectors","text":"reduce_dict_of_vectors([f=identity,] d::Dict{_, <:Vector}) --> Vector{T}\n\nReturn the concatenated vector of all of vectors in d under the element-wise application of f. Effectively flattens a Dict of Vectors to a single Vector.\n\nNote that application of f to vector-elements of d must return a stable type T.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.reduce_orbits!-Union{Tuple{D}, Tuple{AbstractArray{WyckoffPosition{D}, 1}, Char}, Tuple{AbstractArray{WyckoffPosition{D}, 1}, Char, Bool}} where D","page":"Internal API","title":"Crystalline.reduce_orbits!","text":"reduce_orbits!(orbits::Vector{WyckoffPosition}, cntr::Char, conv_or_prim::Bool=true])\n\nUpdate orbits in-place to contain only those Wyckoff positions that are not equivalent in a primitive basis (as determined by the centering type cntr). Returns the updated orbits. \n\nIf conv_or_prim = true (default), the Wyckoff positions are returned in the original, conventional basis; if conv_or_prim = false, they are returned in a primitive basis.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.reduce_translation_to_unitrange-Tuple{AbstractVector{<:Real}}","page":"Internal API","title":"Crystalline.reduce_translation_to_unitrange","text":"reduce_translation_to_unitrange_q(w::AbstractVector{<:Real}) --> :: typeof(w)\n\nReduce the components of the vector w to range [0.0, 1.0[, incorporating a tolerance atol in the reduction.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.rotation_order-Tuple{AbstractMatrix{<:Real}}","page":"Internal API","title":"Crystalline.rotation_order","text":"rotation_order(W::Matrix{<:Real}) --> Int\nrotation_order(op::SymOperation) --> Int\n\nDetermine the integer rotation order of a point group operation, input either as a matrix W or op::SymOperation.\n\nThe rotation order of\n\nProper rotations is positive.\nImproper (mirrors, inversion, roto-inversions) is negative.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.rotation_order_3d-Tuple{Real, Real}","page":"Internal API","title":"Crystalline.rotation_order_3d","text":"rotation_order_3d(detW::Real, trW::Real) --> Int\n\nDetermine the integer rotation order of a 3D point group operation with a 3×3 matrix representation W (alternatively specified by its determinant detW and its trace trW).\n\nThe rotation order of\n\nProper rotations is positive.\nImproper (mirrors, inversion, roto-inversions) is negative.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.uniquetol-Union{Tuple{AbstractArray{T}}, Tuple{T}} where T","page":"Internal API","title":"Crystalline.uniquetol","text":"uniquetol(a; kwargs)\n\nComputes approximate-equality unique with tolerance specifiable via keyword arguments kwargs in O(n²) runtime.\n\nCopied from https://github.com/JuliaLang/julia/issues/19147#issuecomment-256981994\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.wyckbasis-Tuple{BandRepSet}","page":"Internal API","title":"Crystalline.wyckbasis","text":"wyckbasis(brs::BandRepSet) --> Vector{Vector{Int}}\n\nComputes the (band representation) basis for bands generated by localized orbitals placed at the Wyckoff positions. Any band representation that can be expanded on this basis with positive integer coefficients correspond to a trivial insulators (i.e. deformable to atomic limit). Conversely, bands that cannot are topological, either fragily (some negative coefficients) or strongly (fractional coefficients).\n\n\n\n\n\n","category":"method"},{"location":"api/#Public-API","page":"API","title":"Public API","text":"","category":"section"},{"location":"api/","page":"API","title":"API","text":"","category":"page"},{"location":"api/","page":"API","title":"API","text":"CurrentModule = Crystalline","category":"page"},{"location":"api/#Exported-types","page":"API","title":"Exported types","text":"","category":"section"},{"location":"api/","page":"API","title":"API","text":"Modules = [Crystalline]\nPrivate = false\nOrder = [:type]","category":"page"},{"location":"api/#Crystalline.BandRep","page":"API","title":"Crystalline.BandRep","text":"struct BandRep <: AbstractVector{Int64}\n\nwyckpos::String\nsitesym::String\nlabel::String\ndim::Int64\nspinful::Bool\nirvec::Vector{Int64}\nirlabs::Vector{String}\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.BandRepSet","page":"API","title":"Crystalline.BandRepSet","text":"struct BandRepSet <: AbstractVector{BandRep}\n\nsgnum::Int64\nbandreps::Vector{BandRep}\nkvs::Vector{<:KVec}\nklabs::Vector{String}\nirlabs::Vector{String}\nspinful::Bool\ntimereversal::Bool\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.CharacterTable","page":"API","title":"Crystalline.CharacterTable","text":"struct CharacterTable{D} <: Crystalline.AbstractCharacterTable\n\nops::Array{SymOperation{D}, 1} where D\nirlabs::Vector{String}\ntable::Matrix{ComplexF64}\ntag::String\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.Collection","page":"API","title":"Crystalline.Collection","text":"Collection{T} <: AbstractVector{T}\n\nA wrapper around a Vector{T}, that allows custom printing and dispatch rules of custom T (e.g., AbstractIrrep & NewBandRep).\n\nIn Crystalline, it is assumed that all elements of the wrapped vector are associated with the same space or point group. Accordingly, if T implements dim or num, either must return the same value for each element of the Collection (and is equal to dim(::Collection) and num(::Collection)).\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.CompositeBandRep","page":"API","title":"Crystalline.CompositeBandRep","text":"CompositeBandRep{D} <: AbstractSymmetryVector{D}\n\nA type representing a linear rational-coefficient combination of NewBandRep{D}s. \n\nAlthough the coefficients may be rational numbers in general, their superposition must correspond to integer-valued irrep multiplicities and band occupation numbers; in particular, if they do not, conversion to a SymmetryVector will error.\n\nSee also CompositeBandRep_from_indices for construction from a vector included indices into brs.\n\nFields\n\ncoefs::Vector{Rational{Int}}: a coefficient vector associated with each band representation in brs; the coefficient of the ith band representation brs[i] is coefs[i].\nbrs::Collection{NewBandRep{D}}: the band representations referenced by coefs.\n\nExample\n\nFragile symmetry vector\n\nAs a first example, we build a CompositeBandRep representing a fragilely topological configuration (i.e., featuring negative integer coefficients):\n\njulia> brs = calc_bandreps(2);\n\njulia> coefs = [0, 0, 1, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, -1];\n\njulia> cbr = CompositeBandRep(coefs, brs)\n16-irrep CompositeBandRep{3}:\n (1g|Ag) + (1f|Aᵤ) + (1e|Ag) - (1a|Aᵤ) (2 bands)\n\nWe can build the associated SymmetryVector to inspect the associated irrep content:\n\njulia> SymmetryVector(cbr)\n [2Z₁⁺, 2Y₁⁻, 2U₁⁻, 2X₁⁺, 2T₁⁺, 2Γ₁⁺, 2V₁⁺, 2R₁⁺] (2 bands)\n\nSimilarly, we can confirm that cbr is indeed a simple linear combination of the associated band representations:\n\njulia> sum(c * brs[i] for (i, c) in enumerate(coefs)) == cbr\ntrue\n\nAnd we can even do simple arithmetic with cbr (a CompositeBandRep is an element of a monoid:\n\njulia> cbr + 2cbr\n3(1g|Ag) + 3(1f|Aᵤ) + 3(1e|Ag) - 3(1a|Aᵤ) (6 bands)\n\nNontrivial symmetry vector\n\nThe coefficients of a CompositeBandRep can be non-integer, provided the associated irrep multiplicities of the overall summation are integer. Accordingly, a CompositeBandRep may also be used to represent a topologically nontrivial symmetry vector (and, by extension, any physical symmetry vector):\n\njulia> coefs = [-1//4, 0, -1//4, 0, -1//4, 0, 1//4, 0, 1//4, 0, 1//4, 0, -1//4, 0, 1//4, 1];\n\njulia> cbr = CompositeBandRep{3}(coefs, brs)\n16-irrep CompositeBandRep{3}:\n -(1/4)×(1h|Ag) - (1/4)×(1g|Ag) - (1/4)×(1f|Ag) + (1/4)×(1e|Ag) + (1/4)×(1d|Ag) + (1/4)×(1c|Ag) - (1/4)×(1b|Ag) + (1/4)×(1a|Ag) + (1a|Aᵤ) (1 band)\n\njulia> SymmetryVector(cbr)\n16-irrep SymmetryVector{3}:\n [Z₁⁺, Y₁⁻, U₁⁻, X₁⁻, T₁⁻, Γ₁⁻, V₁⁻, R₁⁻] (1 band)\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.KVec-Union{Tuple{AbstractString}, Tuple{D}} where D","page":"API","title":"Crystalline.KVec","text":"KVec{D}(str::AbstractString) --> KVec{D}\nKVec(str::AbstractString) --> KVec\nKVec(::AbstractVector, ::AbstractMatrix) --> KVec\n\nReturn a KVec by parsing the string representations str, supplied in one of the following formats:\n\n\"($1,$2,$3)\"\n\"[$1,$2,$3]\"\n\"$1,$2,$3\"\n\nwhere the coordinates $1,$2, and $3 are strings that may contain fractions, decimal numbers, and \"free\" parameters {'α','β','γ'} (or, alternatively and equivalently, {'u','v','w'} or {'x','y','z'}).\n\nFractions such as 1/2 and decimal numbers can be parsed: but use of any other special operator besides / will produce undefined behavior (e.g. do not use *).\n\nExample\n\njulia> KVec(\"0.25,α,0\")\n[1/4, α, 0]\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.LGIrrep","page":"API","title":"Crystalline.LGIrrep","text":"struct LGIrrep{D} <: Crystalline.AbstractIrrep{D}\n\ncdml::String\ng::LittleGroup\nmatrices::Vector{Matrix{ComplexF64}}\ntranslations::Vector{Vector{Float64}}\nreality::Reality\niscorep::Bool\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.LittleGroup","page":"API","title":"Crystalline.LittleGroup","text":"struct LittleGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}\n\nnum::Int64\nkv::KVec\nklab::String\noperations::Array{SymOperation{D}, 1} where D\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.MSpaceGroup","page":"API","title":"Crystalline.MSpaceGroup","text":"struct MSpaceGroup{D} <: Crystalline.AbstractGroup{D, MSymOperation{D}}\n\nnum::Tuple{Int64, Int64}\noperations::Array{MSymOperation{D}, 1} where D\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.MSymOperation","page":"API","title":"Crystalline.MSymOperation","text":"struct MSymOperation{D} <: Crystalline.AbstractOperation{D}\n\nop::SymOperation\ntr::Bool\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.ModulatedFourierLattice","page":"API","title":"Crystalline.ModulatedFourierLattice","text":"ModulatedFourierLattice{D} <: AbstractFourierLattice{D}\n\nA D-dimensional concrete Fourier (plane wave) lattice, derived from a UnityFourierLattice{D} by scaling and modulating its orbit coefficients by complex numbers; in general, the coefficients do not have unit norm.\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.MultTable","page":"API","title":"Crystalline.MultTable","text":"struct MultTable{O} <: AbstractArray{O, 2}\n\noperations::Vector\ntable::Matrix{Int64}\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.MultTable-Tuple{Any}","page":"API","title":"Crystalline.MultTable","text":"MultTable(ops::AbstractVector, modτ=true)\n\nCompute the multiplication (or Cayley) table of ops, an iterable of SymOperations.\n\nA MultTable is returned, which contains symmetry operations resulting from composition of row and col operators; the table of indices give the symmetry operators relative to the ordering of ops.\n\nKeyword arguments\n\nmodτ (default: true): whether composition of operations is taken modulo lattice\n\nvectors (true) or not (false).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.PGIrrep","page":"API","title":"Crystalline.PGIrrep","text":"struct PGIrrep{D} <: Crystalline.AbstractIrrep{D}\n\ncdml::String\ng::PointGroup\nmatrices::Vector{Matrix{ComplexF64}}\nreality::Reality\niscorep::Bool\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.PointGroup","page":"API","title":"Crystalline.PointGroup","text":"struct PointGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}\n\nnum::Int64\nlabel::String\noperations::Array{SymOperation{D}, 1} where D\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.RVec-Union{Tuple{AbstractString}, Tuple{D}} where D","page":"API","title":"Crystalline.RVec","text":"RVec{D}(str::AbstractString) --> RVec{D}\nRVec(str::AbstractString) --> RVec\nRVec(::AbstractVector, ::AbstractMatrix) --> RVec\n\nReturn a RVec by parsing the string representations str, supplied in one of the following formats:\n\n\"($1,$2,$3)\"\n\"[$1,$2,$3]\"\n\"$1,$2,$3\"\n\nwhere the coordinates $1,$2, and $3 are strings that may contain fractions, decimal numbers, and \"free\" parameters {'α','β','γ'} (or, alternatively and equivalently, {'u','v','w'} or {'x','y','z'}).\n\nFractions such as 1/2 and decimal numbers can be parsed: but use of any other special operator besides / will produce undefined behavior (e.g. do not use *).\n\nExample\n\njulia> RVec(\"0.25,α,0\")\n[1/4, α, 0]\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.Reality","page":"API","title":"Crystalline.Reality","text":"Reality <: Enum{Int8}\n\nEnum type with instances\n\nREAL = 1\nPSEUDOREAL = -1\nCOMPLEX = 0\n\nThe return value of reality(::AbstractIrrep) and calc_reality is an instance of Reality. The reality type of an irrep is relevant for constructing \"physically real\" irreps (co-reps) via realify.\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.SiteGroup","page":"API","title":"Crystalline.SiteGroup","text":"struct SiteGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}\n\nnum::Int64\nwp::WyckoffPosition\noperations::Array{SymOperation{D}, 1} where D\ncosets::Array{SymOperation{D}, 1} where D\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.SiteIrrep","page":"API","title":"Crystalline.SiteIrrep","text":"struct SiteIrrep{D} <: Crystalline.AbstractIrrep{D}\n\ncdml::String\ng::SiteGroup\nmatrices::Vector{Matrix{ComplexF64}}\nreality::Reality\niscorep::Bool\npglabel::String\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.SpaceGroup","page":"API","title":"Crystalline.SpaceGroup","text":"struct SpaceGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}\n\nnum::Int64\noperations::Array{SymOperation{D}, 1} where D\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.SubperiodicGroup","page":"API","title":"Crystalline.SubperiodicGroup","text":"struct SubperiodicGroup{D, P} <: Crystalline.AbstractGroup{D, SymOperation{D}}\n\nnum::Int64\noperations::Array{SymOperation{D}, 1} where D\n\nA subperiodic group of embedding dimension D and periodicity dimension P. \n\nFields: \n\noperations: the SymOperations of the finite factor group GT, where G is the\n\nsubperiodic group and T is the translation group of the associated lattice.\n\nnum: the canonical number of the group, following the International Tables for\n\nCrystallography, Volume E.\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.SymOperation","page":"API","title":"Crystalline.SymOperation","text":"struct SymOperation{D} <: Crystalline.AbstractOperation{D}\n\nrotation::Crystalline.SquareStaticMatrices.SqSMatrix{D, Float64} where D\ntranslation::StaticArraysCore.SVector{D, Float64} where D\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.SymmetryVector-Tuple{Crystalline.AbstractSymmetryVector}","page":"API","title":"Crystalline.SymmetryVector","text":"SymmetryVector(n::AbstractSymmetryVector) -> SymmetryVector\n\nReturn a SymmetryVector realization of n. If n is already a SymmetryVector, return n directly; usually, the returned value will directly reference information in n (i.e., will not be a copy).\n\n\n\n\n\n","category":"method"},{"location":"api/#Exported-methods","page":"API","title":"Exported methods","text":"","category":"section"},{"location":"api/","page":"API","title":"API","text":"Modules = [Crystalline]\nPrivate = false\nOrder = [:function]","category":"page"},{"location":"api/#Base.inv-Tuple{T} where T<:SymOperation","page":"API","title":"Base.inv","text":"inv(op::SymOperation{D}) --> SymOperation{D}\n\nCompute the inverse {W|w}⁻¹ ≡ {W⁻¹|-W⁻¹w} of an operator op ≡ {W|w}.\n\n\n\n\n\n","category":"method"},{"location":"api/#Base.isapprox-Union{Tuple{T}, Tuple{D}, Tuple{T, T}, Tuple{T, T, Union{Nothing, Char, AbstractMatrix{<:Real}}}, Tuple{T, T, Union{Nothing, Char, AbstractMatrix{<:Real}}, Bool}} where {D, T<:Crystalline.AbstractVec{D}}","page":"API","title":"Base.isapprox","text":"isapprox(v1::T, v2::T, \n [cntr::Union{Char, Nothing, AbstractMatrix{<:Real}}, modw::Bool];\n kwargs...) --> Bool\n\nCompute approximate equality of two vector quantities v1 and v2 of type, T = Union{<:AbstractVec, <:AbstractPoint}. \n\nIf modw = true, equivalence is considered modulo lattice vectors. If v1 and v2 are in the conventional setting of a non-primitive lattice, the centering type cntr (see Bravais.centering) should be given to ensure that the relevant (primitive) lattice vectors are used in the comparison.\n\nOptional arguments\n\ncntr: if not provided, the comparison will not account for equivalence by primitive lattice vectors (equivalent to setting cntr=nothing), only equivalence by lattice vectors in the basis of v1 and v2. cntr may also be provided as a D×D AbstractMatrix to give the relevant transformation matrix directly.\nmodw: whether vectors that differ by multiples of a lattice vector are considered equivalent.\nkwargs...: optional keyword arguments (e.g., atol and rtol) to be forwarded to Base.isapprox.\n\n\n\n\n\n","category":"method"},{"location":"api/#Base.position-Tuple{Crystalline.AbstractGroup}","page":"API","title":"Base.position","text":"position(x::Union{AbstractGroup, AbstractIrrep})\n\nIf a position is associated with x, return it; if no position is associated, return nothing.\n\nApplicable cases include LittleGroup (return the associated k-vector) and SiteGroup (returns the associated Wyckoff position), as well as their associated irrep types (LGIrrep and SiteIrrep).\n\n\n\n\n\n","category":"method"},{"location":"api/#Bravais.cartesianize-Union{Tuple{D}, Tuple{SymOperation{D}, DirectBasis{D}}} where D","page":"API","title":"Bravais.cartesianize","text":"cartesianize(op::SymOperation{D}, Rs::DirectBasis{D}) --> SymOperation{D}\n\nConverts opˡ from a lattice basis to a Cartesian basis, by computing the transformed operators opᶜ = 𝐑*opˡ*𝐑⁻¹ via the Cartesian basis matrix 𝐑 (whose columns are the DirectBasis vectors Rs[i]). \n\nNote 1\n\nThe matrix 𝐑 maps vectors coefficients in a lattice basis 𝐯ˡ to coefficients in a Cartesian basis 𝐯ᶜ as 𝐯ˡ = 𝐑⁻¹𝐯ᶜ and vice versa as 𝐯ᶜ = 𝐑𝐯ˡ. Since a general transformation P transforms an \"original\" vectors with coefficients 𝐯 to new coefficients 𝐯′ via 𝐯′ = P⁻¹𝐯 and since we here here consider the lattice basis as the \"original\" basis we have P = 𝐑⁻¹. As such, the transformation of the operator op transforms as opᶜ = P⁻¹*opˡ*P, i.e. opᶜ = transform(opˡ,P) = transform(opˡ,𝐑⁻¹).\n\nNote 2\n\nThe display (e.g. Seitz and xyzt notation) of SymOperations e.g. in the REPL implicitly assumes integer coefficients for its point-group matrix: as a consequence, displaying SymOperations in a Cartesian basis may produce undefined behavior. The matrix representation remains valid, however.\n\n\n\n\n\n","category":"method"},{"location":"api/#Bravais.centering-Union{Tuple{Union{LittleGroup{D}, SpaceGroup{D}}}, Tuple{D}} where D","page":"API","title":"Bravais.centering","text":"centering(g::AbstractGroup) --> Char\n\nReturn the conventional centering type of a group. \n\nFor groups without lattice structure (e.g., point groups), return nothing.\n\n\n\n\n\n","category":"method"},{"location":"api/#Bravais.conventionalize-Union{Tuple{D}, Tuple{Crystalline.AbstractFourierLattice{D}, Char}} where D","page":"API","title":"Bravais.conventionalize","text":"conventionalize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat′)\n\nGiven flat referred to a primitive basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated conventional basis. \n\nSee also the complementary method primitivize(::AbstractFourierLattice, ::Char) for additional details.\n\n\n\n\n\n","category":"method"},{"location":"api/#Bravais.conventionalize-Union{Tuple{D}, Tuple{Crystalline.AbstractVec{D}, Char}} where D","page":"API","title":"Bravais.conventionalize","text":"conventionalize(v′::AbstractVec, cntr::Char) --> v::typeof(v′)\n\nTransforms a primitive coordinate vector v′ back to a standard conventional basis (specified by the centering type cntr), returning the conventional coordinate vector v.\n\nSee also primitivize and transform.\n\n\n\n\n\n","category":"method"},{"location":"api/#Bravais.conventionalize-Union{Tuple{D}, Tuple{SymOperation{D}, Char}, Tuple{SymOperation{D}, Char, Bool}} where D","page":"API","title":"Bravais.conventionalize","text":"conventionalize(op′::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)\n\nReturn a symmetry operation op = Ww in a conventional setting, transformed from an input symmetry operation op′ Ww in a primitive setting.\n\nSee primitivize(::SymOperation, ::Char, ::Bool) for description of the centering argument cntr and optional argument modw.\n\n\n\n\n\n","category":"method"},{"location":"api/#Bravais.primitivize-Union{Tuple{D}, Tuple{Crystalline.AbstractFourierLattice{D}, Char}} where D","page":"API","title":"Bravais.primitivize","text":"primitivize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat)\n\nGiven flat referred to a conventional basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated primitive basis. \n\nSpecifically, if flat refers to a direct conventional basis Rs (mathbfa mathbfb mathbfc) [with coordinate vectors mathbfr (r_1 r_2 r_3)^mathrmT] then flat′ refers to a direct primitive basis Rs′ (mathbfa mathbfb mathbfc) (mathbfa mathbfb mathbfc)mathbfP [with coordinate vectors mathbfr (r_1 r_2 r_3)^mathrmT = mathbfP^-1mathbfr], where mathbfP denotes the basis-change matrix obtained from primitivebasismatrix(...).\n\nTo compute the associated primitive basis vectors, see primitivize(::DirectBasis, ::Char) [specifically, Rs′ = primitivize(Rs, cntr)].\n\nExamples\n\nA centered ('c') lattice from plane group 5 in 2D, plotted in its conventional and primitive basis (requires using PyPlot):\n\njulia> sgnum = 5; D = 2; cntr = centering(sgnum, D) # 'c' (body-centered)\n\njulia> Rs = directbasis(sgnum, Val(D)) # conventional basis (rectangular)\njulia> flat = levelsetlattice(sgnum, Val(D)) # Fourier lattice in basis of Rs\njulia> flat = modulate(flat) # modulate the lattice coefficients\njulia> plot(flat, Rs)\n\njulia> Rs′ = primitivize(Rs, cntr) # primitive basis (oblique)\njulia> flat′ = primitivize(flat, cntr) # Fourier lattice in basis of Rs′\n\njulia> using PyPlot\njulia> plot(flat′, Rs′)\n\n\n\n\n\n","category":"method"},{"location":"api/#Bravais.primitivize-Union{Tuple{D}, Tuple{Crystalline.AbstractVec{D}, Char}} where D","page":"API","title":"Bravais.primitivize","text":"primitivize(v::AbstractVec, cntr::Char) --> v′::typeof(v)\n\nTransforms a conventional coordinate vector v to a standard primitive basis (specified by the centering type cntr), returning the primitive coordinate vector v′.\n\nNote that a basis change matrix mathbfP (as returned e.g. by Bravais.primitivebasismatrix) transforms direct coordinate vectors (RVec) as mathbfr = mathbfP^-1mathbfr but transforms reciprocal coordinates (KVec) as mathbfk = mathbfP^textTmathbfk [ITA6]. Recall also the distinction between transforming a basis and the coordinates of a vector.\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th edition (2016): Secs. 1.5.1.2 and 1.5.2.1.\n\n\n\n\n\n","category":"method"},{"location":"api/#Bravais.primitivize-Union{Tuple{D}, Tuple{SymOperation{D}, Char}, Tuple{SymOperation{D}, Char, Bool}} where D","page":"API","title":"Bravais.primitivize","text":"primitivize(op::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)\n\nReturn a symmetry operation op′ Ww in a primitive setting, transformed from an input symmetry operation op = Ww in a conventional setting. The operations Ww and Ww are related by a transformation Pp via (cf. Section 1.5.2.3 of [ITA6]):\n\nWw = Pp¹WwPp\n\nwhere P and p are the basis change matrix and origin shifts, respectively. The relevant transformation Pp is inferred from the centering type, as provided by cntr (see also Bravais.centering).\n\nBy default, translation parts of op′, i.e. w are reduced modulo 1 (modw = true); to disable this, set modw = false.\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016).\n\n\n\n\n\n","category":"method"},{"location":"api/#Bravais.transform-Tuple{Crystalline.AbstractVec, AbstractMatrix{<:Real}}","page":"API","title":"Bravais.transform","text":"transform(v::AbstractVec, P::AbstractMatrix) --> v′::typeof(v)\n\nReturn a transformed coordinate vector v′ from an original coordinate vector v using a basis change matrix P.\n\nNote that a basis change matrix mathbfP transforms direct coordinate vectors (RVec) as mathbfr = mathbfP^-1mathbfr but transforms reciprocal coordinates (KVec) as mathbfk = mathbfP^mathrmTmathbfk [ITA6]\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th edition (2016): Secs. 1.5.1.2 and 1.5.2.1.\n\n\n\n\n\n","category":"method"},{"location":"api/#Bravais.transform-Union{Tuple{D}, Tuple{SymOperation{D}, AbstractMatrix{<:Real}}, Tuple{SymOperation{D}, AbstractMatrix{<:Real}, Union{Nothing, AbstractVector{<:Real}}}, Tuple{SymOperation{D}, AbstractMatrix{<:Real}, Union{Nothing, AbstractVector{<:Real}}, Bool}} where D","page":"API","title":"Bravais.transform","text":"transform(op::SymOperation, P::AbstractMatrix{<:Real}, \n p::Union{AbstractVector{<:Real}, Nothing}=nothing,\n modw::Bool=true) --> SymOperation\n\nTransforms a op = mathbfWmathbfw by a rotation matrix P and a translation vector p (can be nothing for zero-translations), producing a new symmetry operation op′ = mathbfWmathbfw (cf. Section 1.5.2.3 of [ITA6])\n\nmathbfWmathbfw = mathbfPmathbfp^-1mathbfWmathbfw\nmathbfPmathbfp\n\nwith\n\nmathbfW = mathbfP^-1mathbfWmathbfP\ntext and \nmathbfw = mathbfP^-1(mathbfw+mathbfWmathbfp-mathbfp)\n\nBy default, the translation part of op′, i.e. mathbfw, is reduced to the range 01), i.e. computed modulo 1. This can be disabled by setting modw = false (default, modw = true).\n\nSee also Bravais.primitivize(::SymOperation, ::Char, ::Bool) and Bravais.conventionalize(::SymOperation, ::Char, ::Bool).\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.:⊕-Union{Tuple{T}, Tuple{T, T, Vararg{T}}} where T<:Crystalline.AbstractIrrep","page":"API","title":"Crystalline.:⊕","text":"⊕(ir1::T, ir2::T, ir3::T...) where T<:AbstractIrrep --> T\n\nCompute the representation obtained from direct sum of the irreps ir1, ir2, ir3, etc. The resulting representation is reducible and has dimension irdim(ir1) + irdim(ir2) + irdim(ir3) + ….\n\nThe groups of the provided irreps must be identical. If T isa LGIrrep, the irrep translation factors must also be identical (due to an implementation detail of the LGIrrep type).\n\nAlso provided via Base.:+.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.bandreps","page":"API","title":"Crystalline.bandreps","text":"bandreps(sgnum::Integer, D::Integer=3; \n allpaths::Bool=false, spinful::Bool=false, timereversal::Bool=true)\n\nReturns the elementary band representations (EBRs) as a BandRepSet for space group sgnum and dimension D.\n\nKeyword arguments\n\nallpaths: include a minimal sufficient set (false, default) or all (true) k-vectors. \nspinful: single- (false, default) or double-valued (true) irreps, as appropriate for spinless and spinful particles, respectively. Only available for D=3.\ntimereversal: assume presence (true, default) or absence (false) of time-reversal symmetry.\n\nReferences\n\n3D EBRs are obtained from the Bilbao Crystallographic Server's BANDREP program; please reference the original research papers noted there if used in published work.\n\n\n\n\n\n","category":"function"},{"location":"api/#Crystalline.basisdim-Tuple{BandRepSet}","page":"API","title":"Crystalline.basisdim","text":"basisdim(brs::BandRepSet) --> Int\n\nReturn the dimension of the (linearly independent parts) of a band representation set. This is d^textbs = d^textai in the notation of Po, Watanabe, & Vishwanath, Nature Commun. 8, 50 (2017), or equivalently, the rank of stack(brs) over the ring of integers. This is the number of linearly independent basis vectors that span the expansions of a band structure viewed as symmetry data.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.calc_bandreps-Union{Tuple{Integer}, Tuple{D}, Tuple{Integer, Val{D}}} where D","page":"API","title":"Crystalline.calc_bandreps","text":"calc_bandreps(sgnum::Integer, Dᵛ::Val{D}=Val(3);\n timereversal::Bool=true,\n allpaths::Bool=false)\n\nCompute the band representations of space group sgnum in dimension D, returning a BandRepSet.\n\nKeyword arguments\n\ntimereversal (default, true): whether the irreps used to induce the band representations are assumed to be time-reversal invariant (i.e., are coreps, see realify).\nallpaths (default, false): whether the band representations are projected to all distinct k-points returned by lgirreps (allpaths = false), including high-symmetry k-lines and -plane, or only to the maximal k-points (allpaths = true), i.e., just to high-symmetry points.\n\nNotes\n\nAll band representations associated with maximal Wyckoff positions are returned, irregardless of whether they are elementary (i.e., no regard is made to whether the band representation is \"composite\"). As such, the returned band representations generally are a superset of the set of elementary band representations (and so contain all elementary band representations).\n\nImplementation\n\nThe implementation is based on Cano, Bradlyn, Wang, Elcoro, et al., Phys. Rev. B 97, 035139 (2018), Sections II.C-D.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.calc_reality-Union{Tuple{D}, Tuple{LGIrrep{D}, AbstractArray{SymOperation{D}, 1}}, Tuple{LGIrrep{D}, AbstractArray{SymOperation{D}, 1}, Union{Nothing, Vector{<:Real}}}} where D","page":"API","title":"Crystalline.calc_reality","text":"calc_reality(lgir::LGIrrep, \n sgops::AbstractVector{SymOperation{D}},\n αβγ::Union{Vector{<:Real},Nothing}=nothing) --> ::(Enum Reality)\n\nCompute and return the reality of a lgir::LGIrrep using the Herring criterion.\n\nThe computed value is one of three integers in 1-10. In practice, this value is returned via a member of the Enum Reality, which has instances REAL = 1, PSEUDOREAL = -1, and COMPLEX = 0.\n\nOptional arguments\n\nAs a sanity check, a value of αβγ can be provided to check for invariance along a symmetry symmetry line/plane/general point in k-space. The reality must be invariant to this choice.\n\nNote\n\nThe provided space group operations sgops must be the set reduced by primitive translation vectors; i.e. using spacegroup(...) directly is not allowable in general (since the irreps we reference only include these \"reduced\" operations). This reduced set of operations can be obtained e.g. from the Γ point irreps of ISOTROPY's dataset, or alternatively, from reduce_ops(spacegroup(...), true).\n\nImplementation\n\nThe Herring criterion evaluates the following sum\n\n χ(βb²)g_0M(k)\n\nover symmetry operations βb that take k -k. Here g_0 is the order of the point group of the space group and M(k) is the order of star(k) [both in a primitive basis].\n\nSee e.g. Cornwell, p. 150-152 & 187-188 (which we mainly followed), Inui Eq. (13.48), Dresselhaus, p. 618, or Herring's original paper.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.characters-Union{Tuple{AbstractVector{<:Crystalline.AbstractIrrep{D}}}, Tuple{D}, Tuple{AbstractVector{<:Crystalline.AbstractIrrep{D}}, Union{Nothing, AbstractVector{<:Real}}}} where D","page":"API","title":"Crystalline.characters","text":"characters(irs::AbstractVector{<:AbstractIrrep}, αβγ=nothing)\n\nCompute the character table associated with vector of AbstractIrreps irs, returning a CharacterTable.\n\nOptional arguments\n\nOptionally, an αβγ::AbstractVector{<:Real} variable can be passed to evaluate the irrep (and associated characters) with concrete free parameters (e.g., for LGIrreps, a concrete k-vector sampled from a \"line-irrep\"). Defaults to nothing, indicating it being either irrelevant (e.g., for PGIrreps) or all free parameters implicitly set to zero.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.classcharacters-Union{Tuple{AbstractVector{<:Crystalline.AbstractIrrep{D}}}, Tuple{D}, Tuple{AbstractVector{<:Crystalline.AbstractIrrep{D}}, Union{Nothing, AbstractVector{<:Real}}}} where D","page":"API","title":"Crystalline.classcharacters","text":"classcharacters(irs::AbstractVector{<:AbstractIrrep}, αβγ=nothing)\n\nCompute the character table associated with the conjugacy classes of a vector of AbstractIrreps irs, returning a ClassCharacterTable.\n\nSince characters depend only on the conjugacy class (this is not true for ray, or projective, irreps), the class-specific characters often more succintly communicate the same information as the characters for each operation (as returned by characters).\n\nSee also: classes.\n\nOptional arguments\n\nOptionally, an αβγ::AbstractVector{<:Real} variable can be passed to evaluate the irrep (and associated characters) with concrete free parameters (e.g., for LGIrreps, a concrete k-vector sampled from a \"line-irrep\"). Defaults to nothing, indicating it being either irrelevant (e.g., for PGIrreps) or all free parameters implicitly set to zero.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.classes-Union{Tuple{AbstractArray{SymOperation{D}, 1}}, Tuple{D}, Tuple{AbstractArray{SymOperation{D}, 1}, Union{Nothing, Char}}, Tuple{AbstractArray{SymOperation{D}, 1}, Union{Nothing, Char}, Bool}} where D","page":"API","title":"Crystalline.classes","text":"classes(ops::AbstractVector{SymOperation{D}}, [cntr::Union{Char, Nothing}])\n --> Vector{Vector{SymOperation{D}}}\n\nReturn the conjugacy classes of a group G defined by symmetry operations ops.\n\nDefinitions\n\nTwo elements a and b in G are considered conjugate if there exists a g G such that gag^-1 = b. This defines an equivalence relation sim, i.e., we say that a sim b if a and b are conjugate. The conjugacy classes of G are the distinct equivalence classes that can be identified under this equivalence relation, i.e. the grouping of G into subsets that are equivalent under conjugacy.\n\nExtended help\n\nIf ops describe operations in a crystal system that is not primitive (i.e., if its centering type is not p or P) but is presented in a conventional setting, the centering symbol cntr must be given. If ops is not in a centered crystal system, or if ops is already reduced to a primitive setting, cntr should be given as nothing (default behavior) or, alternatively, as P or p (depending on dimensionality).\n\nA single-argument calls to classes with SpaceGroup or LittleGroup types will assume that ops is provided in a conventional setting, i.e., will forward the method call to classes(ops, centering(ops, dim(ops))). To avoid this behavior (if ops was already reduced to a primitive setting prior to calling classes), cntr should be provided explicitly as nothing.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.classification-Tuple{AbstractVector{<:Integer}}","page":"API","title":"Crystalline.classification","text":"classification(brs_or_F::Union{BandRepSet, Smith}) --> String\n\nReturn the symmetry indicator group X^textBS of an EBR basis F_or_brs, provided as a BandRepSet or Smith decomposition.\n\nTechnically, the calculation answers the question \"what direct product of mathbbZ_n groups is the the quotient group X^textBS = textBStextAI isomorphic to?\" (see Po, Watanabe, & Vishwanath, Nature Commun. 8, 50 (2017) for more information).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.compose-Union{Tuple{D}, Tuple{SymOperation{D}, KVec{D}}, Tuple{SymOperation{D}, KVec{D}, Bool}} where D","page":"API","title":"Crystalline.compose","text":"compose(op::SymOperation, kv::KVec[, checkabc::Bool=true]) --> KVec\n\nReturn the composition op = mathbfWmathbfw and a reciprocal-space vector kv = mathbfk.\n\nThe operation is assumed to be specified the direct lattice basis, and kv in the reciprocal lattice basis. If both were specified in the Cartesian basis, op would act directly via its rotation part. However, because of the different bases, it now acts as:\n\n mathbfk = (mathbfW^textT)^-1mathbfk\n\nNote the transposition and inverse of mathbfW, arising as a result of the implicit real-space basis of mathbfWmathbfw versus the reciprocal-space basis of mathbfk. Note also that the composition of mathbfWmathbfw with mathbfk is invariant under mathbfw, i.e., translations do not act in reciprocal space.\n\nExtended help\n\nIf checkabc = false, the free part of KVec is not transformed (can be improve performance in situations when kabc is zero, and several transformations are requested).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.compose-Union{Tuple{D}, Tuple{SymOperation{D}, RVec{D}}} where D","page":"API","title":"Crystalline.compose","text":"compose(op::SymOperation, rv::RVec) --> RVec\n\nReturn the composition of op = mathbfWmathbfw and a real-space vector rv = mathbfr.\n\nThe operation is taken to act directly, returning\n\n mathbfr = mathbfWmathbfwmathbfr = mathbfWmathbfr + mathbfw\n\nThe corresponding inverse action mathbfWmathbfw^-1mathbfr = mathbfW^-1mathbfr - mathbfW^-1mathbfw can be obtained via compose(inv(op), rv).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.compose-Union{Tuple{T}, Tuple{T, T}, Tuple{T, T, Bool}} where T<:SymOperation","page":"API","title":"Crystalline.compose","text":"compose(op1::T, op2::T, modτ::Bool=true) where T<:SymOperation\n\nCompose two symmetry operations op1 = W₁w₁ and op2 = W₂w₂ using the composition rule (in Seitz notation)\n\nW₁w₁W₂w₂ = W₁W₂w₁+W₁w₂\n\nBy default, the translation part of the W₁W₂w₁+W₁w₂ is reduced to the range 01, i.e. computed modulo 1. This can be toggled off (or on) by the Boolean flag modτ (enabled, i.e. true, by default). Returns another SymOperation.\n\nThe multiplication operator * is overloaded for SymOperations to call compose, in the manner op1 * op2 = compose(op1, op2, modτ=true).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.conjugacy_relations-Union{Tuple{D}, Tuple{Crystalline.GroupRelationGraph{D}, Integer, Integer}} where D","page":"API","title":"Crystalline.conjugacy_relations","text":"conjugacy_relations(gr::GroupRelationGraph, sgnumᴳ, sgnumᴴ) --> Vector{<:ConjugacyTransform}\n\nGiven a graph gr representing a sub- or supergroup relation, return the possible transformations that make up the conjugacy classes between the groups sgnumᴳ and sgnumᴴ.\n\nThe returned transforms bring G into the setting of H via transform(G, P, p), where P and p denote one of the possible conjugacy transforms in the returned vector. Note that the transforms need not preserve volume: accordingly, some operations may be redundant after transformation (use reduce_ops or unique! to remove these).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.cosets-Tuple{SiteGroup}","page":"API","title":"Crystalline.cosets","text":"cosets(g::SiteGroup) -> Array{SymOperation{D}, 1} where D\n\n\nReturn the left coset representatives of a SiteGroup g (in its parent space group).\n\nThe cosets generate the orbit of the Wyckoff position position(g) (see also orbit(::SiteGroup)) and furnish a left-coset decomposition of the underlying space group, jointly with the operations in g itself.\n\nSee also cosets(::AbstractVector, ::AbstractVector). This method is equivalent (but may return different representatives in general) to cosets(spacegroup(sgnum), g).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.cosets-Union{Tuple{T}, Tuple{AbstractVector{T}, AbstractVector{T}}} where T<:Crystalline.AbstractOperation","page":"API","title":"Crystalline.cosets","text":"cosets(G, H)\n\nFor a subgroup H =H of G = G, find a set of (left) coset representatives g_i of H in G, such that (see e.g., Inui et al., Section 2.7)\n\n G = bigcup_i g_i H\n\nThe identity operation 1 is always included in g_i.\n\nExample\n\njulia> G = pointgroup(\"6mm\");\n\njulia> H = pointgroup(\"3\");\n\njulia> Q = cosets(G, H)\n4-element Vector{SymOperation{3}}:\n 1\n 2₀₀₁\n m₁₁₀\n m₋₁₁₀\n\nTo generate the associated cosets, simply compose the representatives with H:\n\njulia> [compose.(Ref(q), H) for q in Q]\n4-element Vector{Vector{SymOperation{3}}}:\n [1, 3₀₀₁⁺, 3₀₀₁⁻]\n [2₀₀₁, 6₀₀₁⁻, 6₀₀₁⁺]\n [m₁₁₀, m₁₀₀, m₀₁₀]\n [m₋₁₁₀, m₁₂₀, m₂₁₀]\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.dim-Tuple{BandRep}","page":"API","title":"Crystalline.dim","text":"dim(BR::BandRep) --> Int\n\nReturn the number of bands included in the provided BandRep.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.dim-Union{Tuple{Crystalline.AbstractGroup{D}}, Tuple{D}} where D","page":"API","title":"Crystalline.dim","text":"dim(g::AbstractGroup) -> Int\n\nReturn the dimensionality of the coordinate space of the group g. This is a statically known number, either equaling 1, 2, or 3.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.find_isomorphic_parent_pointgroup-Union{Tuple{AbstractArray{SymOperation{D}, 1}}, Tuple{D}} where D","page":"API","title":"Crystalline.find_isomorphic_parent_pointgroup","text":"find_isomorphic_parent_pointgroup(g::AbstractVector{SymOperation{D}}) \n --> PointGroup{D}, Vector{Int}, Bool\n\nGiven a group g (or a collection of operators, defining a group), identifies a \"parent\" point group that is isomorphic to g.\n\nThree variables are returned:\n\npg: the identified \"parent\" point group, with operators sorted to match the sorting of g's operators.\nIᵖ²ᵍ: a permutation vector which transforms the standard sorting of point group operations (as returned by pointgroup(::String)) to the operator sorting of g.\nequal: a boolean, identifying whether the point group parts of g operations are identical (true) or merely isomorphic to the point group operations in g. In practice, this indicates whether pg and g are in the same setting or not.\n\nImplementation\n\nThe identification is made partly on the basis of comparison of operators (this is is sufficient for the equal = true case) and partly on the basis of comparison of multiplication tables (equal = false case); the latter can be combinatorially slow if the sorting of operators is unlucky (i.e., if permutation between sortings in g and pg differ by many pairwise permutations).\n\nBeyond mere isomorphisms of multiplication tables, the search also guarantees that all rotation orders are shared between pg and g; similarly, the rotation senses (e.g., 4⁺ & 4⁻ have opposite rotation senses or directions) are shared. This disambiguates point groups that are intrinsically isomorphic to eachother, e.g. \"m\" and \"-1\", but which still differ in their spatial interpretation.\n\nProperties\n\nThe following properties hold for g, pg, and Iᵖ²ᵍ:\n\npg, Iᵖ²ᵍ, equal = find_isomorphic_parent_pointgroup(g)\n@assert MultTable(pg) == MultTable(pointgroup(g))\npg′ = pointgroup(label(pg), dim(pg)) # \"standard\" sorting\n@assert pg′[Iᵖ²ᵍ] == pg\n\nIf equal = true, the following also holds:\n\npointgroup(g) == operations(pg) == operations(pg′)[Iᵖ²ᵍ]\n\nExample\n\nsgnum = 141\nwp = wyckoffs(sgnum, Val(3))[end] # 4a Wyckoff position\nsg = spacegroup(sgnum, Val(3))\nsiteg = sitegroup(sg, wp)\npg, Iᵖ²ᵍ, equal = find_isomorphic_parent_pointgroup(siteg)\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.find_representation","page":"API","title":"Crystalline.find_representation","text":"find_representation(symvals::AbstractVector{Number}, \n lgirs::AbstractVector{<:AbstractIrrep},\n αβγ::Union{AbstractVector{<:Real},Nothing}=nothing,\n assert_return_T::Type{<:Union{Integer, AbstractFloat}}=Int),\n atol::Real=DEFAULT_ATOL,\n maxresnorm::Real=1e-3,\n verbose::Bool=false)\n\n --> Vector{assert_return_T}\n\nFrom a vector (or vector of vectors) of symmetry eigenvalues symvals sampled along all the operations of a group gᵢ, whose irreps are contained in irs (evaluated with optional free parameters αβγ), return the multiplicities of each irrep.\n\nOptionally, the multiciplities' element type can be specified via the assert_return_T argument (performing checked conversion; returns nothing if representation in assert_return_T is impossible). This can be useful if one suspects a particular band to transform like a fraction of an irrep (i.e., the specified symmetry data is incomplete).\n\nIf no valid set of multiplicities exist (i.e., is solvable, and has real-valued and assert_return_T representible type), the sentinel value nothing is returned. Optional debugging information can in this case be shown by setting verbose=true.\n\nExtended help\n\nEffectively, this applies the projection operator P⁽ʲ⁾ of each irrep's character set χ⁽ʲ⁾(gᵢ) (j = 1, ... , Nⁱʳʳ) to the symmetry data sᵢ ≡ symvals:\n\nP⁽ʲ⁾ ≡ (dⱼ/|g|) ∑ᵢ χ⁽ʲ⁾(gᵢ)*gᵢ [characters χ⁽ʲ⁾(gᵢ), irrep dimension dⱼ]\nP⁽ʲ⁾s = (dⱼ/|g|) ∑ᵢ χ⁽ʲ⁾(gᵢ)*sᵢ = nⱼ, [number of bands that transform like jth irrep]\n\nreturning the irrep multiplicities mⱼ ≡ nⱼ/dⱼ.\n\n\n\n\n\n","category":"function"},{"location":"api/#Crystalline.findmaximal-Union{Tuple{AbstractArray{SiteGroup{D}, 1}}, Tuple{D}} where D","page":"API","title":"Crystalline.findmaximal","text":"findmaximal(sitegs::AbstractVector{<:SiteGroup})\n\nGiven an AbstractVector{<:SiteGroup} over the distinct Wyckoff positions of a space group, return those SiteGroups that are associated with a maximal Wyckoff positions.\n\nResults are returned as a view into the input vector (i.e. as an AbstractVector{<:SiteGroup}). The associated Wyckoff positions can be retrieved via position.\n\nDefinition\n\nA Wyckoff position is maximal if its site symmetry group has higher order than the site symmetry groups of any \"nearby\" Wyckoff positions (i.e. Wyckoff positions that can be connected, i.e. made equivalent, through parameter variation to the considered Wyckoff position).\n\nExample\n\njulia> sgnum = 5;\n\njulia> D = 2;\n\njulia> sg = spacegroup(sgnum, Val(D));\n\njulia> sitegs = sitegroups(sg)\n2-element Vector{SiteGroup{2}}:\n [1] (4b: [α, β])\n [1, m₁₀] (2a: [0, β])\n\njulia> only(findmaximal(sitegs))\nSiteGroup{2} ⋕5 (c1m1) at 2a = [0, β] with 2 operations:\n 1\n m₁₀\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.generate-Union{Tuple{AbstractArray{SymOperation{D}, 1}}, Tuple{D}} where D","page":"API","title":"Crystalline.generate","text":"generate(\n gens::AbstractArray{SymOperation{D}, 1};\n cntr,\n modτ,\n Nmax\n) -> Crystalline.GenericGroup\n\n\nReturn the group generated from a finite set of generators gens.\n\nKeyword arguments\n\ncntr (default, nothing): check equivalence of operations modulo primitive lattice vectors (see also isapprox(::SymOperation, ::SymOperation, cntr::Union{Nothing, Char}); only nonequivalent operations are included in the returned group.\nmodτ (default, true): the group composition operation can either be taken modulo lattice vectors (true) or not (false, useful e.g. for site symmetry groups). In this case, the provided generators will also be taken modulo integer lattice translations.\nNmax (default, 256): the maximum size of the generated group. This is essentially a cutoff set to ensure halting of execution in case the provided set of generators do not define a finite group (especially relevant if modτ=false). If more operations than Nmax are generated, the method throws an overflow error.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.generators-Union{Tuple{Integer}, Tuple{D}, Tuple{Integer, Type{SpaceGroup{D}}}} where D","page":"API","title":"Crystalline.generators","text":"generators(num::Integer, T::Type{AbstractGroup{D}}[, optargs])\ngenerators(pgiuc::String, T::PointGroup{D}}) --> Vector{SymOperation{D}}\n\nReturn the generators of the group type T which may be a SpaceGroup{D} or a PointGroup{D} parameterized by its dimensionality D. Depending on T, the group is determined by inputting as the first argument:\n\nSpaceGroup{D}: the space group number num::Integer.\nPointGroup{D}: the point group IUC label pgiuc::String (see also [pointgroup(::String)) or the canonical point group number num::Integer, which can optionally be supplemented by an integer-valued setting choice setting::Integer (see also pointgroup(::Integer, ::Integer, ::Integer)]).\nSubperiodicGroup{D}: the subperiodic group number num::Integer.\n\nSetting choices match those in spacegroup, pointgroup, and subperiodicgroup.\n\nIterated composition of the returned symmetry operations will generate all operations of the associated space or point group (see generate). As an example, generate(generators(num,SpaceGroup{D}))andspacegroup(num, D)` return identical operations (with different sorting typically); and similarly so for point and subperiodic groups.\n\nExample\n\nGenerators of space group 200:\n\njulia> generators(200, SpaceGroup{3})\n4-element Vector{SymOperation{3}}:\n 2₀₀₁\n 2₀₁₀\n 3₁₁₁⁺\n -1\n\nGenerators of point group m-3m:\n\njulia> generators(\"2/m\", PointGroup{3})\n2-element Vector{SymOperation{3}}:\n 2₀₁₀\n -1\n\nGenerators of the Frieze group 𝓅2mg:\n\njulia> generators(7, SubperiodicGroup{2, 1})\n2-element Vector{SymOperation{2}}:\n 2\n {m₁₀|½,0}\n\nCiting\n\nPlease cite the original data sources if used in published work:\n\nSpace groups: Aroyo et al., Z. Kristallogr. Cryst. Mater. 221, 15 (2006);\nPoint group: Bilbao Crystallographic Server's 2D and 3D GENPOS;\nSubperiodic groups: Bilbao Crystallographic Server's SUBPERIODIC GENPOS.\n\nExtended help\n\nNote that the returned generators are not guaranteed to be the smallest possible set of generators; i.e., there may exist other generators with fewer elements (an example is space group 168 (P6), for which the returned generators are [2₀₀₁, 3₀₀₁⁺] even though the group could be generated by just [6₀₀₁⁺]). The returned generators, additionally, are not guaranteed to be minimal, i.e., they may include proper subsets that generate the group themselves (e.g., in space group 75 (P4), the returned generators are [2₀₀₁, 4₀₀₁⁺] although the subset [4₀₀₁⁺] is sufficient to generate the group). The motivation for this is to expose as similar generators as possible for similar crystal systems (see e.g. Section 8.3.5 of the International Tables of Crystallography, Vol. A, Ed. 5 (ITA) for further background).\n\nNote also that, contrary to conventions in ITA, the identity operation is excluded among the returned generators (except in space group 1) since it composes trivially and adds no additional context.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.generators-Union{Tuple{P}, Tuple{D}, Tuple{Integer, Type{SubperiodicGroup{D, P}}}} where {D, P}","page":"API","title":"Crystalline.generators","text":"generators(num::Integer, ::Type{SubperiodicGroup{D,P}}) --> ::Vector{SymOperation{D}}\n\nReturn a canonical set of generators for the subperiodic group num of embedding dimension D and periodicity dimension P. See also subperiodicgroup.\n\nSee also generators(::Integer, ::Type{SpaceGroup}) and information therein.\n\nExample\n\njulia> generators(7, SubperiodicGroup{2, 1})\n2-element Vector{SymOperation{2}}:\n 2\n {m₁₀|½,0}\n\nData sources\n\nThe generators returned by this function were originally retrieved from the Bilbao Crystallographic Database, SUBPERIODIC GENPOS.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.irreps-Tuple{Crystalline.AbstractSymmetryVector}","page":"API","title":"Crystalline.irreps","text":"irreps(n::AbstractSymmetryVector{D}) -> AbstractVector{<:Collection{<:AbstractIrrep{D}}}\n\nReturn the irreps referenced by n. \n\nThe returned value is an AbstractVector of Collection{<:AbstractIrrep}s, with irreps for distinct groups, usually associated with specific k-manifolds, belonging to the same Collection.\n\nSee also multiplicities(::AbstractSymmetryVector).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.is_abelian-Union{Tuple{AbstractArray{SymOperation{D}, 1}}, Tuple{D}, Tuple{AbstractArray{SymOperation{D}, 1}, Union{Nothing, Char}}} where D","page":"API","title":"Crystalline.is_abelian","text":"is_abelian(ops::AbstractVector{SymOperation}, [cntr::Union{Char, Nothing}]) --> Bool\n\nReturn the whether the group composed of the elements ops is Abelian.\n\nA group G is Abelian if all its elements commute mutually, i.e., if g = hgh^-1 for all gh G.\n\nSee discussion of the setting argument cntr in classes.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.isnormal-Union{Tuple{D}, Tuple{AbstractArray{SymOperation{D}, 1}, AbstractArray{SymOperation{D}, 1}}} where D","page":"API","title":"Crystalline.isnormal","text":"isnormal(opsᴳ::AbstractVector{<:SymOperation},\n opsᴴ::AbstractVector{<:SymOperation};\n verbose::Bool=false) --> Bool\n\nDetermine whether the operations in group H are normal in the group G (each with operations opsᴳ and opsᴴ), in the sense that \n\nghg¹ H gG hH\n\nReturns a Boolean answer (true if normal, false if not).\n\nNote\n\nThis compares space groups rather than space group types, i.e. the comparison assumes a matching setting choice between H and G. To compare space group types with different conventional settings, they must first be transformed to a shared setting.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.israyrep","page":"API","title":"Crystalline.israyrep","text":"israyrep(lgir::LGIrrep, αβγ=nothing) -> (::Bool, ::Matrix)\n\nComputes whether a given little group irrep ir is a ray representation by computing the coefficients αᵢⱼ in DᵢDⱼ=αᵢⱼDₖ; if any αᵢⱼ differ from unity, we consider the little group irrep a ray representation (as opposed to the simpler \"vector\" representations where DᵢDⱼ=Dₖ). The function returns a boolean (true => ray representation) and the coefficient matrix αᵢⱼ.\n\n\n\n\n\n","category":"function"},{"location":"api/#Crystalline.issubgroup-Union{Tuple{D}, Tuple{AbstractArray{SymOperation{D}, 1}, AbstractArray{SymOperation{D}, 1}}} where D","page":"API","title":"Crystalline.issubgroup","text":"issubgroup(opsᴳ::T, opsᴴ::T′) where T⁽′⁾<:AbstractVector{SymOperation} --> Bool\n\nDetermine whether the operations in group H are a subgroup of the group G (each with operations opsᴳ and opsᴴ, respectively), i.e. whether HG. Specifically, this requires that G and H are both groups and that for every hH there exists an element gG such that h=g.\n\nReturns a Boolean answer (true if normal, false if not).\n\nNote\n\nThis compares space groups rather than space group types, i.e. the comparison assumes a matching setting choice between H and G. To compare space group types with different conventional settings, they must first be transformed to a shared setting.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.issymmorph","page":"API","title":"Crystalline.issymmorph","text":"issymmorph(sgnum::Integer, D::Integer=3) --> Bool\n\nReturn whether the space group with number sgnum and dimensionality D is symmorphic (true) or nonsymmorphic (false).\n\nEquivalent to issymmorph(spacegroup(sgnum, D)) but uses memoization for performance.\n\n\n\n\n\n","category":"function"},{"location":"api/#Crystalline.issymmorph-Tuple{Crystalline.AbstractGroup}","page":"API","title":"Crystalline.issymmorph","text":"issymmorph(sg::Union{SpaceGroup, LittleGroup}) --> Bool\n\nReturn whether a given space group sg is symmorphic (true) or nonsymmorphic (false).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.issymmorph-Union{Tuple{D}, Tuple{SymOperation{D}, Char}} where D","page":"API","title":"Crystalline.issymmorph","text":"issymmorph(op::SymOperation, cntr::Char) --> Bool\n\nReturn whether a given symmetry operation op is symmorphic (true) or nonsymmorphic (false). \n\nThe operation is assumed provided in conventional basis with centering type cntr: checking symmorphism is then equivalent to checking whether the operation's translation part is zero or a lattice vector in the associated primitive basis.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.iuc","page":"API","title":"Crystalline.iuc","text":"iuc(sgnum::Integer, D::Integer=3) --> String\n\nReturn the IUC (International Union of Crystallography) notation for space group number sgnum in dimension D (1, 2, or 3), as used in the International Tables of Crystallography.\n\nThe notation is sometimes also known as the Hermann-Mauguin notation.\n\n\n\n\n\n","category":"function"},{"location":"api/#Crystalline.levelsetlattice-Union{Tuple{Integer}, Tuple{D′}, Tuple{Integer, Integer}, Tuple{Integer, Integer, NTuple{D′, Int64}}} where D′","page":"API","title":"Crystalline.levelsetlattice","text":"levelsetlattice(sgnum::Integer, D::Integer=2, idxmax::NTuple=ntuple(i->2,D))\n --> UnityFourierLattice{D}\n\nCompute a \"neutral\"/uninitialized Fourier lattice basis, a UnityFourierLattice, consistent with the symmetries of the space group sgnum in dimension D. The resulting lattice flat is expanded in a Fourier basis split into symmetry-derived orbits, with intra-orbit coefficients constrained by the symmetries of the space-group. The inter-orbit coefficients are, however, free and unconstrained.\n\nThe Fourier resolution along each reciprocal lattice vector is controlled by idxmax: e.g., if D = 2 and idxmax = (2, 3), the resulting Fourier lattice may contain reciprocal lattice vectors (k₁, k₂) with k₁∈[0,±1,±2] and k₂∈[0,±1,±2,±3], referred to a 𝐆-basis.\n\nThis \"neutral\" lattice can, and usually should, be subsequently modulated by modulate (which modulates the inter-orbit coefficients, which may eliminate \"synthetic symmetries\" that can exist in the \"neutral\" configuration, due to all inter-orbit coefficients being set to unity).\n\nExamples\n\nCompute a UnityFourierLattice, modulate it with random inter-orbit coefficients via modulate, and finally plot it (via PyPlot.jl):\n\njulia> uflat = levelsetlattice(16, Val(2))\njulia> flat = modulate(uflat)\njulia> Rs = directbasis(16, Val(2)) \njulia> using PyPlot\njulia> plot(flat, Rs)\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.lgirreps-Union{Tuple{Integer}, Tuple{D}, Tuple{Integer, Val{D}}, Tuple{Integer, Val{D}, JLD2.JLDFile}, Tuple{Integer, Val{D}, JLD2.JLDFile, JLD2.JLDFile}} where D","page":"API","title":"Crystalline.lgirreps","text":"lgirreps(sgnum::Integer, D::Union{Val{Int}, Integer}=Val(3))\n -> Dict{String, Collection{LGIrrep{D}}}\n\nFor given space group number sgnum and dimension D, return the associated little group (or \"small\") irreps (LGIrrep{D}s) at high-symmetry k-points, lines, and planes. \n\nReturns a Dict with little group k-point labels as keys and vectors of LGIrrep{D}s as values.\n\nNotes\n\nThe returned irreps are complex in general. Real irreps (as needed in time-reversal invariant settings) can subsequently be obtained with the realify method.\nReturned irreps are spinless.\nThe irrep labelling follows CDML conventions.\nIrreps along lines or planes may depend on free parameters αβγ that parametrize the k point. To evaluate the irreps at a particular value of αβγ and return the associated matrices, use (lgir::LGIrrep)(αβγ). If αβγ is an empty tuple in this call, the matrices associated with lgir will be evaluated assuming αβγ = [0,0,...].\n\nReferences\n\nThe underlying data is sourced from the ISOTROPY ISO-IR dataset. Please cite the original reference material associated with ISO-IR:\n\nStokes, Hatch, & Campbell, ISO-IR, ISOTROPY Software Suite.\nStokes, Campbell, & Cordes, Acta Cryst. A. 69, 388-395 (2013).\n\nThe ISO-IR dataset is occasionally missing some k-points that lie outside the basic domain but still resides in the representation domain (i.e. k-points with postscripted 'A', 'B', etc. labels, such as 'ZA'). In such cases, the missing irreps may instead have been manually sourced from the Bilbao Crystallographic Database.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.littlegroup","page":"API","title":"Crystalline.littlegroup","text":"littlegroup(sg::SpaceGroup, kv::KVec) -> LittleGroup\nlittlegroup(\n sg::SpaceGroup,\n kv::KVec,\n klab::String\n) -> LittleGroup\n\n\nReturn the little group associated with space group sg at the k-vector kv.\n\nOptionally, an associated k-vector label klab can be provided; if not provided, the empty string is used as label.\n\n\n\n\n\n","category":"function"},{"location":"api/#Crystalline.littlegroups-Union{Tuple{Integer}, Tuple{D}, Tuple{Integer, Val{D}}, Tuple{Integer, Val{D}, JLD2.JLDFile}} where D","page":"API","title":"Crystalline.littlegroups","text":"littlegroups(sgnum::Integer, D::Union{Val{Int}, Integer}=Val(3)) \n -> Dict{String, LittleGroup{D}}\n\nFor given space group number sgnum and dimension D, return the associated little groups (LittleGroups{D}s) at high-symmetry k-points, lines, and planes (see also lgirreps).\n\nReturns a Dict with little group k-point labels as keys and vectors of LittleGroup{D}s as values.\n\nNotes\n\nA conventional crystallographic setting is assumed (as in spacegroup).\n\nUnlike spacegroup, \"centering\"-copies of symmetry operations are not included in the returned LittleGroups; as an example, space group 110 (body-centered, with centering symbol 'I') has a centering translation [1/2,1/2,1/2] in the conventional setting: the symmetry operations returned by spacegroup thus includes e.g. both {1|0} and {1|½,½,½} while the symmetry operations returned by littlegroups only include {1|0} (and so on).\n\nCurrently, only D = 3 is supported.\n\nReferences\n\nThe underlying data is sourced from the ISOTROPY dataset: see also lgirreps.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.matrix-Tuple{Crystalline.AbstractOperation}","page":"API","title":"Crystalline.matrix","text":"matrix(op::AbstractOperation{D}) --> SMatrix{D, D+1, Float64}\n\nReturn the D×D+1 matrix representation of op.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.maximal_subgroups-Union{Tuple{Integer}, Tuple{D}, Tuple{Integer, Type{SpaceGroup{D}}}} where D","page":"API","title":"Crystalline.maximal_subgroups","text":"maximal_subgroups(num::Integer, AG::Type{<:AbstractGroup}=SpaceGrop{3}; kind)\n\nReturns the graph structure of the maximal subgroups as a GroupRelationGraph for a group of type AG and number num.\n\nVisualization\n\nThe resulting group structure can be plotted using Makie.jl (e.g., GLMakie.jl) using plot(::GroupRelationGraph):\n\njulia> using Crystalline\njulia> gr = maximal_subgroups(112, SpaceGroup{3})\njulia> using GraphMakie, GLMakie\njulia> plot(gr)\n\nKeyword arguments\n\nkind (default, Crystalline.TRANSLATIONENGLEICHE): to return klassengleiche relations, set kind = Crystalline.KLASSENGLEICHE). For klassengleiche relationships, only a selection of reasonably low-index relationships are returned.\n\nData sources\n\nThe group relationships returned by this function were retrieved from the Bilbao Crystallographic Server's MAXSUB program. Please cite the original reference work associated with MAXSUB:\n\nAroyo et al., Z. Kristallogr. Cryst. Mater. 221, 15 (2006).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.minimal_supergroups-Union{Tuple{Integer}, Tuple{D}, Tuple{Integer, Type{SpaceGroup{D}}}} where D","page":"API","title":"Crystalline.minimal_supergroups","text":"minimal_supergroups(num::Integer, AG::Type{<:AbstractGroup}=SpaceGrop{3}; kind)\n\nReturns the graph structure of the minimal supergroups as a GroupRelationGraph for a group of type AG and number num.\n\nVisualization\n\nThe resulting group structure can be plotted using Makie.jl (e.g., GLMakie.jl) using plot(::GroupRelationGraph):\n\njulia> using Crystalline\njulia> gr = minimal_supergroups(112, SpaceGroup{3})\njulia> using GraphMakie, GLMakie\njulia> plot(gr)\n\nKeyword arguments\n\nkind (default, Crystalline.TRANSLATIONENGLEICHE): to return klassengleiche relations, set kind = Crystalline.KLASSENGLEICHE). For klassengleiche relationships, only a selection of reasonably low-index relationships are returned.\n\nData sources\n\nThe group relationships returned by this function were retrieved from the Bilbao Crystallographic Server's MAXSUB program. Please cite the original reference work associated with MAXSUB:\n\nAroyo et al., Z. Kristallogr. Cryst. Mater. 221, 15 (2006).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.modulate-Union{Tuple{Crystalline.AbstractFourierLattice{D}}, Tuple{D}, Tuple{Crystalline.AbstractFourierLattice{D}, Union{Nothing, AbstractVector{ComplexF64}}}, Tuple{Crystalline.AbstractFourierLattice{D}, Union{Nothing, AbstractVector{ComplexF64}}, Union{Nothing, Real}}, Tuple{Crystalline.AbstractFourierLattice{D}, Union{Nothing, AbstractVector{ComplexF64}}, Union{Nothing, Real}, Union{Nothing, ReciprocalBasis{D}}}} where D","page":"API","title":"Crystalline.modulate","text":"modulate(flat::UnityFourierLattice{D},\nmodulation::AbstractVector{ComplexF64}=rand(ComplexF64, length(getcoefs(flat))),\nexpon::Union{Nothing, Real}=nothing, Gs::Union{ReciprocalBasis{D}, Nothing}=nothing)\n --> ModulatedFourierLattice{D}\n\nDerive a concrete, modulated Fourier lattice from a UnityFourierLattice flat (containing the interrelations between orbit coefficients), by multiplying the \"normalized\" orbit coefficients by a modulation, a complex modulating vector (in general, should be complex; otherwise restores unintended symmetry to the lattice). Distinct modulation vectors produce distinct realizations of the same lattice described by the original flat. By default, a random complex vector is used.\n\nAn exponent expon can be provided, which introduces a penalty term to short- wavelength features (i.e. high-|G| orbits) by dividing the orbit coefficients by |G|^expon; producing a \"simpler\" and \"smoother\" lattice boundary when expon > 0 (reverse for expon < 0). This basically amounts to a continuous \"simplifying\" operation on the lattice (it is not necessarily a smoothing operation; it simply suppresses \"high-frequency\" components). If expon = nothing, no rescaling is performed. If Gs is provided as nothing, the orbit norm is computed in the reciprocal lattice basis (and, so, may not strictly speaking be a norm if the lattice basis is not cartesian); to account for the basis explicitly, Gs must be provided as a ReciprocalBasis, see also normscale.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.mspacegroup-Union{Tuple{D}, Tuple{Integer, Integer}, Tuple{Integer, Integer, Val{D}}} where D","page":"API","title":"Crystalline.mspacegroup","text":"mspacegroup(BNS₁, BNS₂)\nmspacegroup(OG₃) --> MSpaceGroup{3}\n\nReturn the magnetic space group with BNS numbers (BNS₁, BNS₂) or the sequential OG number OG₃ (from 1 to 1651).\n\nData sources\n\nThe data underlying this function was retrieved from ISOTROPY's compilation of Daniel Litvin's magnetic space group tables (http://www.bk.psu.edu/faculty/litvin/Download.html).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.mulliken-Union{Tuple{PGIrrep{D}}, Tuple{D}} where D","page":"API","title":"Crystalline.mulliken","text":"mulliken(pgir::PGIrrep{D}) -> String\n\n\nReturn the Mulliken label of a point group irrep pgir.\n\nNotes\n\nThis functionality is a simple mapping between the tabulated CDML point group irrep labels and associated Mulliken labels [1], using the listings from the Bilbao Crystallographic Database [2].\n\nIgnoring subscript, the rough rules associated with assignment of Mulliken labels are:\n\nIrrep dimensionality: \n1D irreps: if a real irrep, assign A or B (B if antisymmetric under a principal rotation); if a complex irrep, assigned label ¹E or ²E.\n2D irreps: assign label E.\n3D irreps: assign label T.\nu and g subscripts: if the group contains inversion, indicate whether irrep is symmetric (g ~ gerade) or antisymmetric (u ~ ungerade) under inversion.\nPrime superscripts: if the group contains a mirror m aligned with a principal rotation axis, but does not contain inversion, indicate whether irrep is symmetric (′) or antisymmetric (′′) under this mirror.\nNumeral subscripts: the rules for assignment of numeral subscripts are too complicated in general - and indeed, we are unaware of a general coherent rule – to describe here.\n\nReferences\n\n[1]: Mulliken, Report on Notation for the Spectra of Polyatomic Molecules, J. Chem. Phys. 23, 1997 (1955).\n\n[2]: Bilbao Crystallographic Database's Representations PG program.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.multiplicities-Tuple{Crystalline.AbstractSymmetryVector}","page":"API","title":"Crystalline.multiplicities","text":"multiplicities(n::AbstractSymmetryVector) -> AbstractVector{<:AbstractVector{Int}}\n\nReturn the multiplicities of the irreps referenced by n.\n\nSee also irreps(::AbstractSymmetryVector).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.nontrivial_factors-Tuple{Smith}","page":"API","title":"Crystalline.nontrivial_factors","text":"nontrivial_factors(F::Smith) -> Any\n\n\nReturn the nontrivial (i.e., ≠ {0,1}) elementary factors of an EBR basis, provided as a BandRepSet or Smith decomposition.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.normscale!-Union{Tuple{D}, Tuple{ModulatedFourierLattice{D}, Real}, Tuple{ModulatedFourierLattice{D}, Real, Union{Nothing, ReciprocalBasis{D}}}} where D","page":"API","title":"Crystalline.normscale!","text":"normscale!(flat::ModulatedFourierLattice, expon::Real,\n Gs::Union{ReciprocalBasis, Nothing} = nothing) --> ModulatedFourierLattice\n\nIn-place equivalent of normscale: mutates flat.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.normscale-Union{Tuple{D}, Tuple{ModulatedFourierLattice{D}, Real}, Tuple{ModulatedFourierLattice{D}, Real, Union{Nothing, ReciprocalBasis{D}}}} where D","page":"API","title":"Crystalline.normscale","text":"normscale(flat::ModulatedFourierLattice, expon::Real, \n Gs::Union{ReciprocalBasis, Nothing} = nothing) --> ModulatedFourierLattice\n\nApplies inverse-orbit norm rescaling of expansion coefficients with a norm exponent expon. If Gs is nothing, the orbit norm is computed in the lattice basis (and, so, is not strictly a norm); by providing Gs as ReciprocalBasis, the norm is evaluated correctly in cartesian setting. See further discussion in modulate.\n\nAn in-place equivalent is provided in normscale!.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.num-Tuple{Crystalline.AbstractGroup}","page":"API","title":"Crystalline.num","text":"num(g::AbstractGroup) -> Int\n\nReturn the conventional number assigned to the group g.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.occupation-Tuple{Crystalline.AbstractSymmetryVector}","page":"API","title":"Crystalline.occupation","text":"occupation(n::AbstractSymmetryVector) -> Int\n\nReturn the occupation of (i.e., number of bands contained within) n.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.operations-Tuple{Crystalline.AbstractGroup}","page":"API","title":"Crystalline.operations","text":"operations(g::AbstractGroup) -> Vector{<:AbstractOperation}\n\nReturn an Vector containing the operations of the group g.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.orbit-Tuple{SiteGroup}","page":"API","title":"Crystalline.orbit","text":"orbit(g::SiteGroup) --> Vector{WyckoffPosition}\n\nCompute the orbit of the Wyckoff position associated with the site symmetry group g.\n\nExtended help\n\nThe orbit of a Wyckoff position mathbfr in a space group G is defined as the set of inequivalent points in the unit cell that can be obtained by applying the elements of G to mathbfr. Equivalently, every element of the orbit of mathbfr can be written as the composition of a coset representative of the Wyckoff position's site group in G with mathbfr.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.orbit-Union{Tuple{D}, Tuple{AbstractArray{SymOperation{D}, 1}, Union{Crystalline.AbstractVec{D}, AbstractPoint{D}}}, Tuple{AbstractArray{SymOperation{D}, 1}, Union{Crystalline.AbstractVec{D}, AbstractPoint{D}}, Union{Nothing, AbstractMatrix{<:Real}}}} where D","page":"API","title":"Crystalline.orbit","text":"orbit(g::AbstractVector{<:SymOperation}, kv::KVec, cntr::Char) --> Vector{KVec{D}}\norbit(lg::LittleGroup)\norbit(lgir::LGIrrep)\n\nReturn the orbit of of the reciprocal-space vector kv under the action of the group g, also known as the star of k.\n\nThe orbit of kv in g is the set of inequivalent k-points obtained by composition of all the symmetry operations of g with kv. Two reciprocal vectors mathbfk and mathbfk are equivalent if they differ by a primitive reciprocal lattice vector.\n\nIf kv and g are specified in a conventional basis but refer to a non-primitive lattice, the centering type cntr must be provided to ensure that only equivalence by primitive (not conventional) reciprocal lattice vectors are considered. If the centering type of the group g can be inferred from g (e.g., if g is a SpaceGroup), orbit will assume a conventional setting and use the inferred centering type; otherwise, if cntr is neither explicitly set nor inferrable, a primitive setting is assumed.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.pgirreps","page":"API","title":"Crystalline.pgirreps","text":"pgirreps(iuclab::String, ::Val{D}=Val(3); mullikken::Bool=false) where D ∈ (1,2,3)\npgirreps(iuclab::String, D; mullikken::Bool=false)\n\nReturn the (crystallographic) point group irreps of the IUC label iuclab of dimension D as a Vector{PGIrrep{D}}.\n\nSee Crystalline.PG_IUC2NUM[D] for possible IUC labels in dimension D.\n\nNotation\n\nThe irrep labelling follows the conventions of CDML [1] [which occasionally differ from those in e.g. Bradley and Cracknell, The Mathematical Theory of Symmetry in Solids (1972)].\n\nTo use Mulliken (\"spectroscopist\") irrep labels instead, set the keyword argument mulliken = true (default, false). See also mulliken.\n\nData sources\n\nThe data is sourced from the Bilbao Crystallographic Server [2]. If you are using this functionality in an explicit fashion, please cite the original reference [3].\n\nReferences\n\n[1]: Cracknell, Davies, Miller, & Love, Kronecher Product Tables 1 (1979).\n\n[2]: Bilbao Crystallographic Database's Representations PG program.\n\n[3]: Elcoro et al., J. of Appl. Cryst. 50, 1457 (2017)\n\n\n\n\n\n","category":"function"},{"location":"api/#Crystalline.pointgroup-Union{Tuple{AbstractArray{SymOperation{D}, 1}}, Tuple{D}} where D","page":"API","title":"Crystalline.pointgroup","text":"pointgroup(ops:AbstractVector{SymOperation{D}})\npointgroup(sg::AbstractGroup)\n\nComputes the point group associated with a space group sg (characterized by a set of operators ops, which, jointly with lattice translations generate the space group), obtained by \"taking away\" any translational parts and then reducing to the resulting unique rotational operations. (technically, in the language of Bradley & Cracknell, this is the so-called isogonal point group of sg; see Sec. 1.5).\n\nReturns a Vector of SymOperations.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.pointgroup-Union{Tuple{AbstractString}, Tuple{D}, Tuple{AbstractString, Val{D}}} where D","page":"API","title":"Crystalline.pointgroup","text":"pointgroup(iuclab::String, ::Union{Val{D}, Integer}=Val(3)) --> PointGroup{D}\n\nReturn the symmetry operations associated with the point group identified with label iuclab in dimension D as a PointGroup{D}.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.pointgroup-Union{Tuple{Integer}, Tuple{D}, Tuple{Integer, Val{D}}, Tuple{Integer, Val{D}, Integer}} where D","page":"API","title":"Crystalline.pointgroup","text":"pointgroup(pgnum::Integer, ::Union{Val{D}, Integer}=Val(3), setting::Integer=1)\n --> PointGroup{D}\n\nReturn the symmetry operations associated with the point group identfied with canonical number pgnum in dimension D as a PointGroup{D}. The connection between a point group's numbering and its IUC label is enumerated in Crystalline.PG_NUM2IUC[D] and Crystalline.IUC2NUM[D].\n\nCertain point groups feature in multiple setting variants: e.g., IUC labels 321 and 312 both correspond to pgnum = 18 and correspond to the same group structure expressed in two different settings. The setting argument allows choosing between these setting variations.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.realify!-Tuple{AbstractDict{<:AbstractString, <:AbstractVector{<:Crystalline.AbstractIrrep}}}","page":"API","title":"Crystalline.realify!","text":"realify!(lgirsd::AbstractDict{<:AbstractIrrep, <:AbstractVector{<:AbstractIrrep}})\n\nApply realify to each value of lgirsd in-place, returning the mutated lgirsd.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.realify-Tuple{AbstractDict{<:AbstractString, <:AbstractVector{<:Crystalline.AbstractIrrep}}}","page":"API","title":"Crystalline.realify","text":"realify(lgirsd::AbstractDict{<:AbstractIrrep, <:AbstractVector{<:AbstractIrrep}}) \n --> Dict{<:AbstractIrrep, <:AbstractVector{<:AbstractIrrep}}\n\nApply realify to each value of lgirsd, returning a new Dict of realified irreps.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.realify-Union{Tuple{AbstractArray{LGIrrep{D}, 1}}, Tuple{D}} where D","page":"API","title":"Crystalline.realify","text":"realify(lgirs::AbstractVector{<:LGIrrep}; verbose::Bool=false)\n --> AbstractVector{<:LGIrrep}\n\nFrom lgirs, a vector of LGIrreps, determine the associated (gray) co-representations, i.e. the \"real\", or \"physical\" irreps that are relevant in scenarios with time-reversal symmetry.\n\nFor LGIrrep that are REAL, or that characterize a k-point 𝐤 which is not equivalent to -𝐤 (i.e. its star does not include both 𝐤 and -𝐤; equivalently, the little group includes time-reversal symmetry), the associated co-representations are just the original irreps themselves. For PSEUDOREAL and COMPLEX LGIrreps where ±𝐤 are equivalent, the associated co-representations are built from pairs of irreps that \"stick\" together. This method computes this pairing and sets the LGIrrep field iscorep to true, to indicate that the resulting \"paired irrep\" (i.e. the co-representation) should be doubled with itself (PSEUDOREAL reality) or its complex conjugate (COMPLEX reality).\n\nBackground\n\nFor background, see p. 650-652 (and p. 622-626 for point groups) in Bradley & Cracknell's book. Their discussion is for magnetic groups (the \"realified\" irreps are, in fact, simply co-representations of the \"gray\" magnetic groups). Cornwell's book also explicates this at some length as does Inui et al. (p. 296-299).\n\nKeyword arguments\n\nverbose::Bool: if set to true, prints details about mapping from small irrep to small\n\ncorep for each LGIrrep (default: false).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.realify-Union{Tuple{AbstractVector{T}}, Tuple{T}} where T<:Crystalline.AbstractIrrep","page":"API","title":"Crystalline.realify","text":"realify(pgirs::AbstractVector{T}) where T<:AbstractIrrep --> Vector{T}\n\nReturn physically real irreps (coreps) from a set of conventional irreps (as produced by e.g. pgirreps). Fallback method for point-group-like AbstractIrreps.\n\nExample\n\njulia> pgirs = pgirreps(\"4\", Val(3));\njulia> characters(pgirs)\nCharacterTable{3}: ⋕9 (4)\n───────┬────────────────────\n │ Γ₁ Γ₂ Γ₃ Γ₄ \n───────┼────────────────────\n 1 │ 1 1 1 1\n 2₀₀₁ │ 1 1 -1 -1\n 4₀₀₁⁺ │ 1 -1 1im -1im\n 4₀₀₁⁻ │ 1 -1 -1im 1im\n───────┴────────────────────\n\njulia> characters(realify(pgirs))\nCharacterTable{3}: ⋕9 (4)\n───────┬──────────────\n │ Γ₁ Γ₂ Γ₃Γ₄ \n───────┼──────────────\n 1 │ 1 1 2\n 2₀₀₁ │ 1 1 -2\n 4₀₀₁⁺ │ 1 -1 0\n 4₀₀₁⁻ │ 1 -1 0\n───────┴──────────────\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.reality-Tuple{Crystalline.AbstractIrrep}","page":"API","title":"Crystalline.reality","text":"reality(ir::AbstractIrrep) --> Reality\n\nReturn the reality of ir (see []Reality](@ref)).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.reduce_ops-Union{Tuple{Pdim}, Tuple{D}, Tuple{AbstractArray{SymOperation{D}, 1}, Char}, Tuple{AbstractArray{SymOperation{D}, 1}, Char, Bool}, Tuple{AbstractArray{SymOperation{D}, 1}, Char, Bool, Bool}, Tuple{AbstractArray{SymOperation{D}, 1}, Char, Bool, Bool, Val{Pdim}}} where {D, Pdim}","page":"API","title":"Crystalline.reduce_ops","text":"reduce_ops(ops::AbstractVector{SymOperation{D}},\n cntr::Char,\n conv_or_prim::Bool=true,\n modw::Bool=true) --> Vector{SymOperation{D}}\n\nReduce the operations ops, removing operations that are identical in the primitive basis associated with the centering cntr. \n\nIf conv_or_prim = false, the reduced operations are returned in the primitive basis associated with cntr; otherwise, in the conventional. If modw = true, the comparison in the primitive basis is done modulo unit primitive lattice vectors; otherwise not. A final argument of type ::Val{P} can be specified to indicate a subperiodic group of periodicity dimension P, different from the spatial embedding dimension D.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.rotation-Tuple{Crystalline.AbstractOperation}","page":"API","title":"Crystalline.rotation","text":"rotation(op::AbstractOperation{D}) --> SMatrix{D, D, Float64}\n\nReturn the D×Drotation part ofop`.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.schoenflies-Tuple{Integer}","page":"API","title":"Crystalline.schoenflies","text":"schoenflies(sgnum::Integer) --> String\n\nReturn the Schoenflies notation for space group number sgnum in dimension 3.\n\nNote that Schoenflies notation is well-defined only for 3D point and space groups.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.seitz-Union{Tuple{SymOperation{D}}, Tuple{D}} where D","page":"API","title":"Crystalline.seitz","text":"seitz(op::SymOperation) --> String\n\nComputes the correponding Seitz notation for a symmetry operation in triplet/xyzt form.\n\nImplementation based on ITA5 Table 11.2.1.1, with 3D point group parts inferred from the trace and determinant of the matrix mathbW in the triplet mathbfWmathbfw.\n\ndetW/trW -3 -2 -1 0 1 2 3\n1 2 3 4 6 1\n-1 -1 -6 -4 -3 m \n\nwith the elements of the table giving the type of symmetry operation in in Hermann-Mauguin notation. The rotation axis and the rotation sense are computed following the rules in ITA6 Sec. 1.2.2.4(1)(b-c). See also .\n\nNote that the orientation of the axis (i.e. its sign) does not necessarily match the orientation picked in Tables 1.4.2.1-5 of ITA6; it is a matter of (arbitrary) convention, and the conventions have not been explicated in ITA.\n\n2D operations are treated by the same procedure, by elevation in a third dimension; 1D operations by a simple inspection of sign.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.sitegroup-Union{Tuple{D}, Tuple{SpaceGroup{D}, WyckoffPosition{D}}} where D","page":"API","title":"Crystalline.sitegroup","text":"sitegroup(\n sg::SpaceGroup{D},\n wp::WyckoffPosition{D}\n) -> SiteGroup\n\n\nReturn the site symmetry group g::SiteGroup for a Wyckoff position wp in space group sg (or with space group number sgnum; in this case, the dimensionality is inferred from wp).\n\ng is a group of operations that are isomorphic to the those listed in sg (in the sense that they might differ by lattice vectors) and that leave the Wyckoff position wp invariant, such that all(op -> wp == compose(op, wp), g) == true.\n\nThe returned SiteGroup also contains the coset representatives of the Wyckoff position (that are again isomorphic to those featured in sg), accessible via cosets, which e.g. generate the orbit of the Wyckoff position (see orbit(::SiteGroup)) and define a left-coset decomposition of sg jointly with the elements in g.\n\nExample\n\njulia> sgnum = 16;\n\njulia> D = 2;\n\njulia> wp = wyckoffs(sgnum, D)[3] # pick a Wyckoff position\n2b: [1/3, 2/3]\n\njulia> sg = spacegroup(sgnum, D);\n\njulia> g = sitegroup(sg, wp)\nSiteGroup{2} ⋕16 (p6) at 2b = [1/3, 2/3] with 3 operations:\n 1\n {3⁺|1,1}\n {3⁻|0,1}\n\nThe group structure of a SiteGroup can be inspected with MultTable:\n\njulia> MultTable(g)\n3×3 MultTable{SymOperation{2}}:\n──────────┬──────────────────────────────\n │ 1 {3⁺|1,1} {3⁻|0,1} \n──────────┼──────────────────────────────\n 1 │ 1 {3⁺|1,1} {3⁻|0,1} \n {3⁺|1,1} │ {3⁺|1,1} {3⁻|0,1} 1\n {3⁻|0,1} │ {3⁻|0,1} 1 {3⁺|1,1}\n──────────┴──────────────────────────────\n\nThe original space group can be reconstructed from a left-coset decomposition, using the operations and cosets contained in a SiteGroup:\n\njulia> ops = [opʰ*opᵍ for opʰ in cosets(g) for opᵍ in g];\n\njulia> Set(sg) == Set(ops)\ntrue\n\nTerminology\n\nMathematically, the site symmetry group is a stabilizer group for a Wyckoff position, in the same sense that the little group of k is a stabilizer group for a k-point.\n\nSee also sitegroups for calculation of all site symmetry groups of a given space group.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.sitegroups-Union{Tuple{SpaceGroup{D}}, Tuple{D}} where D","page":"API","title":"Crystalline.sitegroups","text":"sitegroups(sg::SpaceGroup{D}) -> Any\n\n\nReturn all site symmetry groups associated with a space group, specified either as sg :: SpaceGroup{D} or by its conventional number sgnum and dimension D.\n\nSee also sitegroup for calculation of the site symmetry group of a specific Wyckoff position.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.siteirreps-Union{Tuple{SiteGroup{D}}, Tuple{D}} where D","page":"API","title":"Crystalline.siteirreps","text":"siteirreps(sitegroup::SiteGroup; mulliken::Bool=false]) --> Vector{PGIrrep}\n\nReturn the site symmetry irreps associated with the provided SiteGroup, obtained from a search over isomorphic point groups. The SiteIrreps are in general a permutation of the irreps of the associated isomorphic point group.\n\nBy default, the labels of the site symmetry irreps are given in the CDML notation; to use the Mulliken notation, set the keyword argument mulliken to true (default, false).\n\nExample\n\njulia> sgnum = 16;\n\njulia> sg = spacegroup(sgnum, 2);\n\njulia> wp = wyckoffs(sgnum, 2)[3] # pick the third Wyckoff position\n2b: [1/3, 2/3]\n\njulia> siteg = sitegroup(sg, wp)\nSiteGroup{2} ⋕16 (p6) at 2b = [1/3, 2/3] with 3 operations:\n 1\n {3⁺|1,1}\n {3⁻|0,1}\n\njulia> siteirs = siteirreps(siteg)\n3-element Collection{SiteIrrep{2}} for ⋕16 (p6) at 2b = [1/3, 2/3]:\nΓ₁ ─┬─────────────────────────────────────────────\n ├─ 1: ────────────────────────────────── (x,y)\n │ 1\n │\n ├─ {3⁺|1,1}: ──────────────────── (-y+1,x-y+1)\n │ 1\n │\n ├─ {3⁻|0,1}: ───────────────────── (-x+y,-x+1)\n │ 1\n └─────────────────────────────────────────────\nΓ₂ ─┬─────────────────────────────────────────────\n ├─ 1: ────────────────────────────────── (x,y)\n │ 1\n │\n ├─ {3⁺|1,1}: ──────────────────── (-y+1,x-y+1)\n │ exp(0.6667iπ)\n │\n ├─ {3⁻|0,1}: ───────────────────── (-x+y,-x+1)\n │ exp(-0.6667iπ)\n └─────────────────────────────────────────────\nΓ₃ ─┬─────────────────────────────────────────────\n ├─ 1: ────────────────────────────────── (x,y)\n │ 1\n │\n ├─ {3⁺|1,1}: ──────────────────── (-y+1,x-y+1)\n │ exp(-0.6667iπ)\n │\n ├─ {3⁻|0,1}: ───────────────────── (-x+y,-x+1)\n │ exp(0.6667iπ)\n └─────────────────────────────────────────────\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.spacegroup-Union{Tuple{Any}, Tuple{D}, Tuple{Any, Val{D}}} where D","page":"API","title":"Crystalline.spacegroup","text":"spacegroup(sgnum::Integer, ::Val{D}=Val(3))\nspacegroup(sgnum::Integer, D::Integer) --> SpaceGroup{D}\n\nReturn the space group symmetry operations for a given space group number sgnum and dimensionality D as a SpaceGroup{D}. The returned symmetry operations are specified relative to the conventional basis vectors, i.e. are not necessarily primitive (see centering). If desired, operations for the primitive unit cell can subsequently be generated using primitivize or Crystalline.reduce_ops.\n\nThe default choices for the conventional basis vectors follow the conventions of the Bilbao Crystallographic Server (or, equivalently, the International Tables of Crystallography), which are:\n\nUnique axis b (cell choice 1) for monoclinic space groups.\nObverse triple hexagonal unit cell for rhombohedral space groups.\nOrigin choice 2: inversion centers are placed at (0,0,0). (relevant for certain centrosymmetric space groups with two possible choices; e.g., in the orthorhombic, tetragonal or cubic crystal systems).\n\nSee also directbasis.\n\nData sources\n\nThe symmetry operations returned by this function were originally retrieved from the Bilbao Crystallographic Server, SPACEGROUP GENPOS. The associated citation is: (Aroyo et al., Z. Kristallogr. Cryst. Mater. 221, 15 (2006).).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.subduction_count-Union{Tuple{T}, Tuple{T, T}, Tuple{T, T, Union{Nothing, AbstractVector{<:Real}}}} where T<:Crystalline.AbstractIrrep","page":"API","title":"Crystalline.subduction_count","text":"subduction_count(Dᴳᵢ, Dᴴⱼ[, αβγᴴⱼ]) --> Int\n\nFor two groups G and H, where H is a subgroup of G, i.e. HG, with associated irreducible representations Dᴳᵢ = D^G_i(g) and Dᴴⱼ = D^H_j(g) over operations gG and hHG, compute the compatibility relation between the two irreps from the subduction reduction formula (or \"magic\" formula/Schur orthogonality relation), returning how many times n^GH_ij the subduced representation D^G_iH contains the irrep D^H_j; in other words, this gives the compatibility between the two irreps.\n\nOptionally, a vector αβγᴴⱼ may be provided, to evaluate the characters/irreps of Dᴳᵢ at a concrete value of (αβγ). This is e.g. meaningful for LGIrreps at non-special k-vectors. Defaults to nothing.\n\nThe result is computed using the reduction formula [see e.g. Eq. (15) of arXiv:1706.09272v2]:\n\nn^GH_ij = H^-1 sum_h chi^G_i(h)chi^H_j(h)^*\n\nExample\n\nConsider the two compatible k-vectors Γ (a point) and Σ (a line) in space group 207:\n\nlgirsd = lgirreps(207, Val(3));\nΓ_lgirs = lgirsd[\"Γ\"]; # at Γ ≡ [0.0, 0.0, 0.0]\nΣ_lgirs = lgirsd[\"Σ\"]; # at Σ ≡ [α, α, 0.0]\n\nWe can test their compatibility via:\n\n[[subduction_count(Γi, Σj) for Γi in Γ_lgirs] for Σj in Σ_lgirs]\n> # Γ₁ Γ₂ Γ₃ Γ₄ Γ₅\n> [ 1, 0, 1, 1, 2] # Σ₁\n> [ 0, 1, 1, 2, 1] # Σ₂\n\nWith following enterpretatation for compatibility relations between irreps at Γ and Σ:\n\nCompatibility relation Degeneracies\nΓ₁ → Σ₁ 1 → 1\nΓ₂ → Σ₂ 1 → 1\nΓ₃ → Σ₁ + Σ₂ 2 → 1 + 1\nΓ₄ → Σ₁ + 2Σ₂ 3 → 1 + 2\nΓ₅ → 2Σ₁ + Σ₂ 3 → 2 + 1\n\nwhere, in this case, all the small irreps are one-dimensional.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.subperiodicgroup-Union{Tuple{Integer}, Tuple{P}, Tuple{D}, Tuple{Integer, Val{D}}, Tuple{Integer, Val{D}, Val{P}}} where {D, P}","page":"API","title":"Crystalline.subperiodicgroup","text":"subperiodicgroup(num::Integer, ::Val{D}=Val(3), ::Val{P}=Val(2))\nsubperiodicgroup(num::Integer, D::Integer, P::Integer)\n --> ::SubperiodicGroup{D,P}\n\nReturn the operations of the subperiodic group num of embedding dimension D and periodicity dimension P as a SubperiodicGroup{D,P}.\n\nThe setting choices are those of the International Tables for Crystallography, Volume E.\n\nAllowed combinations of D and P and their associated group names are:\n\nD = 3, P = 2: Layer groups (num = 1, …, 80).\nD = 3, P = 1: Rod groups (num = 1, …, 75).\nD = 2, P = 1: Frieze groups (num = 1, …, 7).\n\nExample\n\njulia> subperiodicgroup(7, Val(2), Val(1))\nSubperiodicGroup{2, 1} ⋕7 (𝓅2mg) with 4 operations:\n 1\n 2\n {m₁₀|½,0}\n {m₀₁|½,0}\n\nData sources\n\nThe symmetry operations returned by this function were originally retrieved from the Bilbao Crystallographic Database, SUBPERIODIC GENPOS.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.surface_basis-Tuple{DirectBasis{3}, AbstractVector{<:Real}}","page":"API","title":"Crystalline.surface_basis","text":"surface_basis(Rs, n; cartesian=true)\n\nCompute a basis for the surface-cell obtained from terminating a 3D lattice Rs over a surface surface specified by its normal vector n (or Miller indices if cartesian=false).\n\nOutput\n\nThe function returns a tuple (rs³ᴰ, rs′²ᴰ, P), whose elements are described below:\n\nrs³ᴰ: a DirectBasis{3}, whose first two basis vectors lie in the plane of the surface, and whose third vector is (positively) aligned with the surface normal. All basis vectors correspond to points in the original direct lattice.\nrs′²ᴰ: a DirectBasis{2}, whose basis vectors are given in the local coordinate system of the surface unit cell; effectively, this is (xy)-components of rs³ᴰ after a rotation that takes n to hatmathbfz. The first basis vector is aligned with the hatmathbfx-direction of the local coordinate system.\nP: a rotation matrix that takes rs³ᴰ to the local n-to-hatmathbfz rotated coordinate system of rs′²ᴰ. In particular, defining rs′³ᴰ = transform.(DirectPoint.(rs³ᴰ), Ref(P)), the following holds: \t- rs′³ᴰ[i] ≈ [rs′²ᴰ[i]..., 0] for i ∈ 1:2, \t- rs′³ᴰ[3] is (positively) aligned with [0,0,1]. To transform the other way, i.e., from surface-local to lattice-global coordinates, simply use P⁻¹ = transpose(P) instead.\n\nThe returned basis is right-handed.\n\nKeyword arguments\n\ncartesian :: Bool = true: whether the surface normal n is specified in Cartesian coordinates (true) or in the basis of the reciprocal lattice vectors (false), i.e., corresponding to the Cartesian vector n[1]*Gs[1] + n[2]*Gs[2] + n[3]*Gs with Gs denoting the Cartesian representation of the reciprocal lattice vectors, i.e., Gs = reciprocalbasis(Rs). The latter case (false) is a specification of the surface in terms of its Miller indices: the coordinates of n can then equivalently be interpreted as the inverse of the surface's intercept with each of the axes spanned by Rs.\n\nExample\n\njulia> sgnum = 195; # P23, a cubic lattice\n\njulia> Rs = directbasis(sgnum, 3)\nDirectBasis{3} (cubic):\n [1.0, 0.0, 0.0]\n [0.0, 1.0, 0.0]\n [0.0, 0.0, 1.0]\n\njulia> n = [1,1,1]; # project along 111 direction\n\njulia> rs³ᴰ, rs′²ᴰ, P = surface_basis(Rs, n; cartesian=true);\n\njulia> rs³ᴰ # the surface basis in the original coordinate system\nDirectBasis{3} (hexagonal):\n [1.0, -1.5700924586837747e-16, -0.9999999999999998]\n [-0.9999999999999998, 0.9999999999999997, 0.0]\n [1.0, 1.0, 1.0]\n\njulia> rs′²ᴰ # the in-plane surface vectors in a local \"surface coordinate system\"\nDirectBasis{2} (hexagonal):\n [1.414213562373095, 0.0]\n [-0.7071067811865475, 1.2247448713915887]\n\njulia> DirectBasis(transform.(DirectPoint.(rs³ᴰ), Ref(P))) # from rs³ᴰ to rs′²ᴰ coordinates \nDirectBasis{3} (hexagonal):\n [1.414213562373095, -1.1102230246251563e-16, 0.0]\n [-0.7071067811865476, 1.2247448713915885, 0.0]\n [0.0, -1.1102230246251563e-16, 1.7320508075688772]\n\nwarning: Warning\nThis function will likely be moved from Crystalline to Bravais.jl at some point in the future.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.translation-Tuple{Crystalline.AbstractOperation}","page":"API","title":"Crystalline.translation","text":"translation(op::AbstractOperation{D}) --> SVector{D, Float64}\n\nReturn the D-dimensional translation part of op.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.wyckoffs-Union{Tuple{Integer}, Tuple{D}, Tuple{Integer, Val{D}}} where D","page":"API","title":"Crystalline.wyckoffs","text":"wyckoffs(sgnum::Integer) -> Vector{WyckoffPosition{3}}\nwyckoffs(sgnum::Integer, ::Val{D}) -> Any\n\n\nReturn the Wyckoff positions of space group sgnum in dimension D as a Vector{WyckoffPosition{D}.\n\nThe positions are given in the conventional basis setting, following the conventions of the Bilbao Crystallographic Server (from which the underlying data is sourced [1]).\n\nExample\n\njulia> wps = wyckoffs(16, 2)\n4-element Vector{WyckoffPosition{2}}:\n 6d: [α, β]\n 3c: [1/2, 0]\n 2b: [1/3, 2/3]\n 1a: [0, 0]\n\nReferences\n\n[1]: Aroyo, et al., Z. Kristallogr. 221, 15-27 (2006)\n\n\n\n\n\n","category":"method"},{"location":"api/#Exported-macros","page":"API","title":"Exported macros","text":"","category":"section"},{"location":"api/","page":"API","title":"API","text":"Modules = [Crystalline]\nPrivate = false\nOrder = [:macro]","category":"page"},{"location":"api/#Crystalline.@S_str-Tuple{Any}","page":"API","title":"Crystalline.@S_str","text":"@S_str -> SymOperation\n\nConstruct a SymOperation from a triplet form given as a string.\n\nExample\n\njulia> S\"-y,x\"\n4⁺ ──────────────────────────────── (-y,x)\n ┌ 0 -1 ╷ 0 ┐\n └ 1 0 ╵ 0 ┘\n\n\n\n\n\n","category":"macro"},{"location":"api/#Exported-constants","page":"API","title":"Exported constants","text":"","category":"section"},{"location":"api/","page":"API","title":"API","text":"Modules = [Crystalline]\nPrivate = false\nOrder = [:constant]","category":"page"},{"location":"api/#Crystalline.ENANTIOMORPHIC_PAIRS","page":"API","title":"Crystalline.ENANTIOMORPHIC_PAIRS","text":"ENANTIOMORPHIC_PAIRS :: NTuple{11, Pair{Int,Int}}\n\nReturn the space group numbers of the 11 enantiomorphic space group pairs in 3D.\n\nThe space group types associated with each such pair (sgnum, sgnum') are related by a mirror transformation: i.e. there exists a transformation mathbbP = mathbfPmathbfp between the two groups G = g and G = g such that G = mathbbP^-1GmathbbP where mathbfP is improper (i.e. mathrmdetmathbfP 0).\n\nWe define distinct space group types as those that cannot be related by a proper transformation (i.e. with mathrmdetmathbfP 0). With that view, there are 230 space group types. If the condition is relaxed to allow improper rotations, there are 230-11 = 219 distinct affine space group types. See e.g. ITA5 Section 8.2.2.\n\nThe enantiomorphic space group types are also chiral space group types in 3D. There are no enantiomorphic pairs in lower dimensions; in 3D all enantiomorphic pairs involve screw symmetries, whose direction is inverted between pairs (i.e. have opposite handedness).\n\n\n\n\n\n","category":"constant"},{"location":"api/#Crystalline.MAX_MSGNUM","page":"API","title":"Crystalline.MAX_MSGNUM","text":"MAX_MSGNUM :: Tuple{Int,Int,Int}\n\nAnalogous to MAX_SUBGNUM, but for the number of magnetic space groups.\n\n\n\n\n\n","category":"constant"},{"location":"api/#Crystalline.MAX_MSUBGNUM","page":"API","title":"Crystalline.MAX_MSUBGNUM","text":"MAX_MSUBGNUM :: Tuple{Int,Int,Int}\n\nAnalogous to MAX_SUBGNUM, but for the number of magnetic subperiodic groups.\n\n\n\n\n\n","category":"constant"},{"location":"api/#Crystalline.MAX_SGNUM","page":"API","title":"Crystalline.MAX_SGNUM","text":"MAX_SGNUM :: Tuple{Int,Int,Int}\n\nReturn the number of distinct space group types across dimensions 1, 2, and 3 (indexable by dimensionality).\n\n\n\n\n\n","category":"constant"},{"location":"api/#Crystalline.MAX_SUBGNUM","page":"API","title":"Crystalline.MAX_SUBGNUM","text":"MAX_SUBGNUM :: ImmutableDict\n\nAn immutable dictionary with values v::Int and keys k::Tuple{Int,Int}, where v is the number of distinct subperiodic group types for a given key k = (D,P) describing a subperiodic group of dimensionality D and periodicity P:\n\nlayer groups: (D,P) = (3,2)\nrod groups: (D,P) = (3,1)\nfrieze groups: (D,P) = (2,1)\n\n\n\n\n\n","category":"constant"},{"location":"groups/#Groups","page":"Groups","title":"Groups","text":"","category":"section"},{"location":"groups/","page":"Groups","title":"Groups","text":"All groups in Crystalline are concrete instances of the abstract supertype Crystalline.AbstractGroup{D}, referring to a group in D dimensions. Crystalline.AbstractGroup{D} is itself a subtype of AbstractVector{SymOperation{D}}. Crystalline currently supports five group types: SpaceGroup, PointGroup, LittleGroup, SubperiodicGroup, SiteGroup, and MSpaceGroup.","category":"page"},{"location":"groups/#Example:-space-groups","page":"Groups","title":"Example: space groups","text":"","category":"section"},{"location":"groups/","page":"Groups","title":"Groups","text":"The one, two, and three-dimensional space groups are accessible via spacegroup, which takes the space group number sgnum and dimensino D as input (ideally, the dimension is provided as a Val{D} for the sake of type stability) and returns a SpaceGroup{D} structure:","category":"page"},{"location":"groups/","page":"Groups","title":"Groups","text":"using Crystalline\n\nD = 3 # dimension\nsgnum = 16 # space group number (≤2 in 1D, ≤17 in 2D, ≤230 in 3D)\nsg = spacegroup(sgnum, D) # where practical, `spacegroup` should be called with a `Val{D}` dimension to ensure type stability; here we have D::Int instead for simplicity","category":"page"},{"location":"groups/","page":"Groups","title":"Groups","text":"By default, the returned operations are given in the conventional setting of the International Tables of Crystallography, Volume A (ITA). Conversion to a primitive basis (in the CDML setting) can be accomplished via primitivize.","category":"page"},{"location":"groups/","page":"Groups","title":"Groups","text":"In addition to space groups, Crystalline.jl provides access to the operations of point groups (pointgroup), little groups (littlegroups), subperiodic groups (subperiodicgroup; including rod, layer, and frieze groups), site symmetry groups (sitegroup and sitegroups), and magnetic space groups (mspacegroup).","category":"page"},{"location":"groups/#Multiplication-tables","page":"Groups","title":"Multiplication tables","text":"","category":"section"},{"location":"groups/","page":"Groups","title":"Groups","text":"We can compute the multiplication table of a space group (under the previously defined notion of operator composition) using MultTable:","category":"page"},{"location":"groups/","page":"Groups","title":"Groups","text":"MultTable(sg)","category":"page"},{"location":"groups/","page":"Groups","title":"Groups","text":"Alternatively, exploiting overloading of the *-operator, \"raw\" multiplication tables can be constructed via a simple outer product:","category":"page"},{"location":"groups/","page":"Groups","title":"Groups","text":"sg .* permutedims(sg) # equivalent to `reshape(kron(sg, sg), (length(sg), length(sg)))`","category":"page"},{"location":"groups/#Symmorphic-vs.-nonsymorphic-space-groups","page":"Groups","title":"Symmorphic vs. nonsymorphic space groups","text":"","category":"section"},{"location":"groups/","page":"Groups","title":"Groups","text":"To determine whether a space group is symmorphic or not, use issymmorph taking either a SpaceGroup, LittleGroup, or SubperiodicGroup (or a SpaceGroup identified by its number and dimensionality; in this case, using tabulated look-up). To test whether a given SymOperation is symmorphic in a given centering setting, use issymmorph(::SymOperation, ::Char)","category":"page"},{"location":"groups/#Group-generators","page":"Groups","title":"Group generators","text":"","category":"section"},{"location":"groups/","page":"Groups","title":"Groups","text":"Generators of SpaceGroups, PointGroups, and SubperiodicGroups are accessible via generators, e.g.:","category":"page"},{"location":"groups/","page":"Groups","title":"Groups","text":"ops = generators(sgnum, SpaceGroup{D})","category":"page"},{"location":"groups/","page":"Groups","title":"Groups","text":"To generate a group from a list of generators, we can use the generate method. As an example, we can verify that ops in fact returns symmetry operations identical to those in sg:","category":"page"},{"location":"groups/","page":"Groups","title":"Groups","text":"generate(ops)","category":"page"},{"location":"groups/#Magnetic-space-groups","page":"Groups","title":"Magnetic space groups","text":"","category":"section"},{"location":"groups/","page":"Groups","title":"Groups","text":"Magnetic space groups are accessible via mspacegroup.","category":"page"},{"location":"lattices/#Isosurfaces-with-space-group-symmetry","page":"Lattices","title":"Isosurfaces with space group symmetry","text":"","category":"section"},{"location":"lattices/","page":"Lattices","title":"Lattices","text":"CurrentModule = Crystalline","category":"page"},{"location":"lattices/","page":"Lattices","title":"Lattices","text":"UnityFourierLattice\nModulatedFourierLattice\nlevelsetlattice\nmodulate\nprimitivize(::AbstractFourierLattice, ::Char)\nconventionalize(::AbstractFourierLattice, ::Char)\nAbstractFourierLattice(::Any)","category":"page"},{"location":"lattices/#Crystalline.UnityFourierLattice-lattices","page":"Lattices","title":"Crystalline.UnityFourierLattice","text":"UnityFourierLattice{D} <: AbstractFourierLattice{D}\n\nA general D-dimensional Fourier (plane wave) lattice specified by orbits of reciprocal lattice vectors (orbits) and coefficient interrelations (orbitcoefs)). The norm of all elements in orbitcoefs is unity. orbits (and associated coefficients) are sorted in order of increasing norm (low to high).\n\n\n\n\n\n","category":"type"},{"location":"lattices/#Crystalline.ModulatedFourierLattice-lattices","page":"Lattices","title":"Crystalline.ModulatedFourierLattice","text":"ModulatedFourierLattice{D} <: AbstractFourierLattice{D}\n\nA D-dimensional concrete Fourier (plane wave) lattice, derived from a UnityFourierLattice{D} by scaling and modulating its orbit coefficients by complex numbers; in general, the coefficients do not have unit norm.\n\n\n\n\n\n","category":"type"},{"location":"lattices/#Crystalline.levelsetlattice-lattices","page":"Lattices","title":"Crystalline.levelsetlattice","text":"levelsetlattice(sgnum::Integer, D::Integer=2, idxmax::NTuple=ntuple(i->2,D))\n --> UnityFourierLattice{D}\n\nCompute a \"neutral\"/uninitialized Fourier lattice basis, a UnityFourierLattice, consistent with the symmetries of the space group sgnum in dimension D. The resulting lattice flat is expanded in a Fourier basis split into symmetry-derived orbits, with intra-orbit coefficients constrained by the symmetries of the space-group. The inter-orbit coefficients are, however, free and unconstrained.\n\nThe Fourier resolution along each reciprocal lattice vector is controlled by idxmax: e.g., if D = 2 and idxmax = (2, 3), the resulting Fourier lattice may contain reciprocal lattice vectors (k₁, k₂) with k₁∈[0,±1,±2] and k₂∈[0,±1,±2,±3], referred to a 𝐆-basis.\n\nThis \"neutral\" lattice can, and usually should, be subsequently modulated by modulate (which modulates the inter-orbit coefficients, which may eliminate \"synthetic symmetries\" that can exist in the \"neutral\" configuration, due to all inter-orbit coefficients being set to unity).\n\nExamples\n\nCompute a UnityFourierLattice, modulate it with random inter-orbit coefficients via modulate, and finally plot it (via PyPlot.jl):\n\njulia> uflat = levelsetlattice(16, Val(2))\njulia> flat = modulate(uflat)\njulia> Rs = directbasis(16, Val(2)) \njulia> using PyPlot\njulia> plot(flat, Rs)\n\n\n\n\n\n","category":"function"},{"location":"lattices/#Crystalline.modulate-lattices","page":"Lattices","title":"Crystalline.modulate","text":"modulate(flat::UnityFourierLattice{D},\nmodulation::AbstractVector{ComplexF64}=rand(ComplexF64, length(getcoefs(flat))),\nexpon::Union{Nothing, Real}=nothing, Gs::Union{ReciprocalBasis{D}, Nothing}=nothing)\n --> ModulatedFourierLattice{D}\n\nDerive a concrete, modulated Fourier lattice from a UnityFourierLattice flat (containing the interrelations between orbit coefficients), by multiplying the \"normalized\" orbit coefficients by a modulation, a complex modulating vector (in general, should be complex; otherwise restores unintended symmetry to the lattice). Distinct modulation vectors produce distinct realizations of the same lattice described by the original flat. By default, a random complex vector is used.\n\nAn exponent expon can be provided, which introduces a penalty term to short- wavelength features (i.e. high-|G| orbits) by dividing the orbit coefficients by |G|^expon; producing a \"simpler\" and \"smoother\" lattice boundary when expon > 0 (reverse for expon < 0). This basically amounts to a continuous \"simplifying\" operation on the lattice (it is not necessarily a smoothing operation; it simply suppresses \"high-frequency\" components). If expon = nothing, no rescaling is performed. If Gs is provided as nothing, the orbit norm is computed in the reciprocal lattice basis (and, so, may not strictly speaking be a norm if the lattice basis is not cartesian); to account for the basis explicitly, Gs must be provided as a ReciprocalBasis, see also normscale.\n\n\n\n\n\n","category":"function"},{"location":"lattices/#Bravais.primitivize-Tuple{Crystalline.AbstractFourierLattice, Char}-lattices","page":"Lattices","title":"Bravais.primitivize","text":"primitivize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat)\n\nGiven flat referred to a conventional basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated primitive basis. \n\nSpecifically, if flat refers to a direct conventional basis Rs (mathbfa mathbfb mathbfc) [with coordinate vectors mathbfr (r_1 r_2 r_3)^mathrmT] then flat′ refers to a direct primitive basis Rs′ (mathbfa mathbfb mathbfc) (mathbfa mathbfb mathbfc)mathbfP [with coordinate vectors mathbfr (r_1 r_2 r_3)^mathrmT = mathbfP^-1mathbfr], where mathbfP denotes the basis-change matrix obtained from primitivebasismatrix(...).\n\nTo compute the associated primitive basis vectors, see primitivize(::DirectBasis, ::Char) [specifically, Rs′ = primitivize(Rs, cntr)].\n\nExamples\n\nA centered ('c') lattice from plane group 5 in 2D, plotted in its conventional and primitive basis (requires using PyPlot):\n\njulia> sgnum = 5; D = 2; cntr = centering(sgnum, D) # 'c' (body-centered)\n\njulia> Rs = directbasis(sgnum, Val(D)) # conventional basis (rectangular)\njulia> flat = levelsetlattice(sgnum, Val(D)) # Fourier lattice in basis of Rs\njulia> flat = modulate(flat) # modulate the lattice coefficients\njulia> plot(flat, Rs)\n\njulia> Rs′ = primitivize(Rs, cntr) # primitive basis (oblique)\njulia> flat′ = primitivize(flat, cntr) # Fourier lattice in basis of Rs′\n\njulia> using PyPlot\njulia> plot(flat′, Rs′)\n\n\n\n\n\n","category":"method"},{"location":"lattices/#Bravais.conventionalize-Tuple{Crystalline.AbstractFourierLattice, Char}-lattices","page":"Lattices","title":"Bravais.conventionalize","text":"conventionalize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat′)\n\nGiven flat referred to a primitive basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated conventional basis. \n\nSee also the complementary method primitivize(::AbstractFourierLattice, ::Char) for additional details.\n\n\n\n\n\n","category":"method"},{"location":"lattices/#Crystalline.AbstractFourierLattice-Tuple{Any}-lattices","page":"Lattices","title":"Crystalline.AbstractFourierLattice","text":"(flat::AbstractFourierLattice)(xyz) --> Float64\n(flat::AbstractFourierLattice)(xyzs...) --> Float64\n\nEvaluate an AbstractFourierLattice at the point xyz and return its real part, i.e.\n\n mathopmathrmResum_i c_i exp(2pi imathbfG_icdotmathbfr)\n\nwith mathrmG_i denoting reciprocal lattice vectors in the allowed orbits of flat, with c_i denoting the associated coefficients (and mathbfr equiv xyz).\n\nxyz may be any iterable object with dimension matching flat consisting of real numbers (e.g., a Tuple, Vector, or SVector). Alternatively, the coordinates can be supplied individually (i.e., as flat(x, y, z)).\n\n\n\n\n\n","category":"method"},{"location":"bandreps/#Elementary-band-representations","page":"Band representations","title":"Elementary band representations","text":"","category":"section"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"Crystalline.jl provides an interface to access the elementary band representations (EBRs) hosted by the Bilbao Crystallographic Server's BANDREP program via bandreps. Please cite the original research (listed in the associated docstrings).","category":"page"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"As an example, we can obtain the all inequivalent EBRs in space group 219 (F-43c) with:","category":"page"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"using Crystalline\n\nbrs = bandreps(219, 3) # space group 219 (dimension 3)","category":"page"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"which returns a BandRepSet, which itself is an AbstractVector of BandReps. This allows us to index into brs easily:","category":"page"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"brs[1] # obtain the EBR induced by Wyckoff position 8a with irrep A","category":"page"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"By default, bandreps returns the spinless EBRs with time-reversal symmetry. This behavior can be controlled with the keyword arguments spinful (default, false) and timereversal (default, true). By default, only minimal paths are included in the sampling of k-vectors; additional paths can be obtained by setting the keyword argument allpaths = true (default, false).","category":"page"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"The distinct topological classes identifiable from symmetry can can be calculated via classification, which uses the Smith normal form's principle factors:","category":"page"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"classification(brs)","category":"page"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"Which demonstrates that the symmetry indicator group of spinless particles with time-reversal symmetry in space group 219 is trivial.","category":"page"},{"location":"bandreps/#Topology-and-associated-bases","page":"Band representations","title":"Topology and associated bases","text":"","category":"section"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"The SymmetryBases.jl package provides tools to analyze topology of symmetry vectors and compute associated Hilbert bases.","category":"page"},{"location":"bandreps/#API","page":"Band representations","title":"API","text":"","category":"section"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"CurrentModule = Crystalline","category":"page"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"bandreps\nclassification\nnontrivial_factors\nbasisdim","category":"page"},{"location":"bandreps/#Crystalline.bandreps-bandreps","page":"Band representations","title":"Crystalline.bandreps","text":"bandreps(sgnum::Integer, D::Integer=3; \n allpaths::Bool=false, spinful::Bool=false, timereversal::Bool=true)\n\nReturns the elementary band representations (EBRs) as a BandRepSet for space group sgnum and dimension D.\n\nKeyword arguments\n\nallpaths: include a minimal sufficient set (false, default) or all (true) k-vectors. \nspinful: single- (false, default) or double-valued (true) irreps, as appropriate for spinless and spinful particles, respectively. Only available for D=3.\ntimereversal: assume presence (true, default) or absence (false) of time-reversal symmetry.\n\nReferences\n\n3D EBRs are obtained from the Bilbao Crystallographic Server's BANDREP program; please reference the original research papers noted there if used in published work.\n\n\n\n\n\n","category":"function"},{"location":"bandreps/#Crystalline.classification-bandreps","page":"Band representations","title":"Crystalline.classification","text":"classification(brs_or_F::Union{BandRepSet, Smith}) --> String\n\nReturn the symmetry indicator group X^textBS of an EBR basis F_or_brs, provided as a BandRepSet or Smith decomposition.\n\nTechnically, the calculation answers the question \"what direct product of mathbbZ_n groups is the the quotient group X^textBS = textBStextAI isomorphic to?\" (see Po, Watanabe, & Vishwanath, Nature Commun. 8, 50 (2017) for more information).\n\n\n\n\n\n","category":"function"},{"location":"bandreps/#Crystalline.nontrivial_factors-bandreps","page":"Band representations","title":"Crystalline.nontrivial_factors","text":"nontrivial_factors(F::Smith) -> Any\n\n\nReturn the nontrivial (i.e., ≠ {0,1}) elementary factors of an EBR basis, provided as a BandRepSet or Smith decomposition.\n\n\n\n\n\n","category":"function"},{"location":"bandreps/#Crystalline.basisdim-bandreps","page":"Band representations","title":"Crystalline.basisdim","text":"basisdim(brs::BandRepSet) --> Int\n\nReturn the dimension of the (linearly independent parts) of a band representation set. This is d^textbs = d^textai in the notation of Po, Watanabe, & Vishwanath, Nature Commun. 8, 50 (2017), or equivalently, the rank of stack(brs) over the ring of integers. This is the number of linearly independent basis vectors that span the expansions of a band structure viewed as symmetry data.\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.jl","page":"Bravais types & bases","title":"Bravais.jl","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"Bravais types, basis systems, and transformations between conventional and primitive settings.","category":"page"},{"location":"bravais/#API","page":"Bravais types & bases","title":"API","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"CurrentModule = Bravais","category":"page"},{"location":"bravais/#Types","page":"Bravais types & bases","title":"Types","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"AbstractBasis\nDirectBasis\nReciprocalBasis\nAbstractPoint\nDirectPoint\nReciprocalPoint","category":"page"},{"location":"bravais/#Bravais.AbstractBasis","page":"Bravais types & bases","title":"Bravais.AbstractBasis","text":"AbstractBasis <: StaticVector{D, SVector{D, T}}\n\nAbstract supertype of a D-dimensional basis in D-dimensional space with coordinate values of type T.\n\n\n\n\n\n","category":"type"},{"location":"bravais/#Bravais.DirectBasis","page":"Bravais types & bases","title":"Bravais.DirectBasis","text":"DirectBasis{D} <: AbstractBasis{D}\n\nA wrapper type over D distinct D-dimensional vectors (given as a SVector{D, SVector{D,Float64}}), defining a lattice basis in direct space.\n\n\n\n\n\n","category":"type"},{"location":"bravais/#Bravais.ReciprocalBasis","page":"Bravais types & bases","title":"Bravais.ReciprocalBasis","text":"ReciprocalBasis{D} <: AbstractBasis{D}\n\nA wrapper type over D distinct D-dimensional vectors (given as a SVector{D, SVector{D,Float64}}), defining a lattice basis in reciprocal space.\n\n\n\n\n\n","category":"type"},{"location":"bravais/#Bravais.AbstractPoint","page":"Bravais types & bases","title":"Bravais.AbstractPoint","text":"AbstractPoint{D, T} <: StaticVector{D, T}\n\nAbstract supertype of a D-dimensional point with elements of type T.\n\n\n\n\n\n","category":"type"},{"location":"bravais/#Bravais.DirectPoint","page":"Bravais types & bases","title":"Bravais.DirectPoint","text":"DirectPoint{D} <: AbstractPoint{D}\n\nA wrapper type over an SVector{D, Float64}, defining a single point in D-dimensional direct space. \n\nThe coordinates of a DirectPoint are generally assumed specified relative to an associated DirectBasis. To convert to Cartesian coordinates, see cartesianize.\n\n\n\n\n\n","category":"type"},{"location":"bravais/#Bravais.ReciprocalPoint","page":"Bravais types & bases","title":"Bravais.ReciprocalPoint","text":"ReciprocalPoint{D} <: AbstractPoint{D}\n\nA wrapper type over an SVector{D, Float64}, defining a single point in D-dimensional reciprocal space. \n\nThe coordinates of a ReciprocalPoint are generally assumed specified relative to an associated ReciprocalBasis. To convert to Cartesian coordinates, see cartesianize.\n\n\n\n\n\n","category":"type"},{"location":"bravais/#Crystal-systems-and-Bravais-types","page":"Bravais types & bases","title":"Crystal systems & Bravais types","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"crystalsystem\nbravaistype\ncentering","category":"page"},{"location":"bravais/#Bravais.crystalsystem","page":"Bravais types & bases","title":"Bravais.crystalsystem","text":"crystalsystem(Rs::DirectBasis{D}) --> String\ncrystalsystem(Gs::ReciprocalBasis{D}) --> String\n\nDetermine the crystal system of a point lattice with DirectBasis Rs, assuming the conventional setting choice defined in the International Tables of Crystallography [ITA6].\n\nIf a ReciprocalBasis Gs is provided for the associated reciprocal point lattice, the crystal system is determined by first transforming to the direct lattice.\n\nThere are 4 crystal systems in 2D and 7 in 3D (see Section 2.1.2(iii) of [ITA5]):\n\nD System Conditions Free parameters\n1D linear none a\n2D square a=b & γ=90° a\n rectangular γ=90° a,b\n hexagonal a=b & γ=120° a\n oblique none a,b,γ\n3D cubic a=b=c & α=β=γ=90° a\n hexagonal a=b & α=β=90° & γ=120° a,c\n trigonal a=b & α=β=90° & γ=120° a,c (a,α for hR)\n tetragonal a=b & α=β=γ=90° a,c\n orthorhombic α=β=γ=90° a,b,c\n monoclinic α=γ=90° a,b,c,β≥90°\n triclinic none a,b,c,α,β,γ\n\nThe 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).\n\n[ITA6]: M.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]).\n\n[ITA5]: T. Hahn, International Tables of Crystallography, Vol. A, 5th ed. (2005).\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.bravaistype","page":"Bravais types & bases","title":"Bravais.bravaistype","text":"bravaistype(sgnum::Integer, D::Integer=3; normalize::Bool=false) --> String\n\nReturn the Bravais type of sgnum in dimension D as a string (as the concatenation of the single-character crystal abbreviation and the centering type).\n\nKeyword arguments\n\nnormalize: 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.\nThis only affects space groups 38-41 (normalizing their conventional Bravais types from \"oA\" to \"oC\").\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.centering","page":"Bravais types & bases","title":"Bravais.centering","text":"centering(g::AbstractGroup) --> Char\n\nReturn the conventional centering type of a group. \n\nFor groups without lattice structure (e.g., point groups), return nothing.\n\n\n\n\n\ncentering(sgnum::Integer, D::Integer=3) --> Char\n\nReturn the conventional centering type cntr of the space group with number sgnum and dimension D.\n\nThe 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).\n\nPossible values of cntr, depending on dimensionality D, are (see ITA Sec. 9.1.4):\n\nD = 1:\ncntr = 'p': no centering (primitive)\nD = 2:\ncntr = 'p': no centring (primitive)\ncntr = 'c': face centered\nD = 3: \ncntr = 'P': no centring (primitive)\ncntr = 'I': body centred (innenzentriert)\ncntr = 'F': all-face centred\ncntr = 'A' or 'C': one-face centred, (b,c) or (a,b)\ncntr = 'R': hexagonal cell rhombohedrally centred\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Basis-construction","page":"Bravais types & bases","title":"Basis construction","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"crystal\ndirectbasis\nreciprocalbasis\nnigglibasis","category":"page"},{"location":"bravais/#Bravais.crystal","page":"Bravais types & bases","title":"Bravais.crystal","text":"crystal(a, b, c, α, β, γ) --> DirectBasis{3}\n\nCalculate basis vectors mathbfR_1, mathbfR_2, mathbfR_3 in a 3D Cartesian basis for a right-handed coordinate system with specified basis vector lengths a, b, c (associated with mathbfR_1, mathbfR_2, & mathbfR_3, respectively) and specified interaxial angles α = (mathbfR_2mathbfR_3), β = (mathbfR_3mathbfR_1), γ = (mathbfR_1mathbfR_2), with denoting the angle between two vectors.\n\nFor definiteness, the mathbfR_1 basis vector is oriented along the x-axis of the Cartesian coordinate system, and the mathbfR_2 axis is placed in the xy-plane.\n\n\n\n\n\ncrystal(a, b, γ) --> DirectBasis{2}\n\nCalculate basis vectors mathbfR_1, mathbfR_2 in a 2D Cartesian basis for a right-handed coordinate system with specified basis vector lengths a, b (associated with mathbfR_1 & mathbfR_2, respectively) and specified interaxial angle γ = (mathbfR_1mathbfR_2).\n\nFor definiteness, the mathbfR_1 basis vector is oriented along the x-axis of the Cartesian coordinate system.\n\n\n\n\n\ncrystal(a) --> DirectBasis{1}\n\nReturn a one-dimensional crystal with lattice period a.\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.directbasis","page":"Bravais types & bases","title":"Bravais.directbasis","text":"directbasis(sgnum, D=3; abclims, αβγlims)\ndirectbasis(sgnum, Val(D); abclims, αβγlims) --> DirectBasis{D}\n\nReturn 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.\n\nLimits 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).\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.reciprocalbasis","page":"Bravais types & bases","title":"Bravais.reciprocalbasis","text":"reciprocalbasis(Rs) --> ::ReciprocalBasis{D}\n\nReturn 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).\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.nigglibasis","page":"Bravais types & bases","title":"Bravais.nigglibasis","text":"nigglibasis(Rs; rtol=1e-5, max_iterations=200)\n\nGiven a set of primitive basis vectors Rs, return a basis Rs′ for the corresponding Niggli-reduced unit cell, as well as a transformation matrix P, such that Rs′ = transform(Rs, P) (see transform).\n\nDefinition\n\nA Niggli-reduced basis (mathbfa mathbfb mathbfc) represents a unique choice of basis for any given lattice (or, more precisely, a unique choice of the basis vector lengths mathbfa mathbfb mathbfc, and mutual angles between mathbfa mathbfb mathbfc). This uniqueness is one of the main motivations for computing the Niggli reduction procedure, as it enables easy comparison of lattices. Additionally, the associated Niggli-reduced basis vectors (mathbfa mathbfb mathbfc), fulfil several conditions [3]:\n\n\"Main\" conditions:\nThe basis vectors are sorted by increasing length: mathbfa mathbfb mathbfc.\nThe angles between basis vectors are either all acute or all non-acute.\n\"Special\" conditions:\nSeveral special conditions, applied in \"special\" cases, such as mathbfa = mathbfb or \\mathbf{b}\\cdot\\mathbf{c} = \\tfrac{1}{2}|\\mathbf{b}|^2. See Ref. [3] for details.\n\nEquivalently, the Niggli-reduced basis fulfils the following geometric conditions (Section 9.3.1 of Ref. [3]):\n\nThe basis vectors are sorted by increasing length.\nThe basis vectors have least possible total length, i.e., ``|\\mathbf{a}| + |\\mathbf{b}|\n|\\mathbf{c}|`` is minimum. I.e., the associated Niggli cell is a Buerger cell.\nThe associated Buerger cell has maximum deviation among all other Buerger cells, i.e., the basis vector angles α β γ maximize 90 - α + 90 - β + 90 - γ.\n\nKeyword arguments\n\nrtol :: Real: relative tolerance used in the Grosse-Kunstleve approach for floating point comparisons (default: 1e-5).\nmax_iterations :: Int: maximum number of iterations in which to cycle the Krivy-Gruber steps (default: 200).\n\nImplementation\n\nImplementation follows the algorithm originally described by Krivy & Gruber [1], with the stability modificiations proposed by Grosse-Kunstleve et al. [2] (without which the algorithm proposed in [1] simply does not work on floating point hardware).\n\n[1] I. Krivy & B. Gruber. A unified algorithm for determinign the reduced (Niggli) cell, Acta Crystallogr. A 32, 297 (1976). [2] R.W. Grosse-Kunstleve, N.K. Sauter, & P.D. Adams, Numerically stable algorithms for the computation of reduced unit cells, Acta Crystallogr. A 60, 1 (2004) [3] Sections 9.2 & 9.3, International Tables of Crystallography, Volume A, 5th ed. (2005).\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Transformations","page":"Bravais types & bases","title":"Transformations","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"primitivebasismatrix\ntransform\nprimitivize\nconventionalize\ncartesianize\ncartesianize!\nlatticize\nlatticize!","category":"page"},{"location":"bravais/#Bravais.primitivebasismatrix","page":"Bravais types & bases","title":"Bravais.primitivebasismatrix","text":"primitivebasismatrix(cntr::Char, ::Val{D}=Val(3)) --> SMatrix{D,D,Float64}\nprimitivebasismatrix(cntr::Char, ::Val{D}, ::Val{P}) --> SMatrix{D,D,Float64}\n\nReturn the transformation matrix mathbfP that transforms a conventional unit cell with centering cntr to the corresponding primitive unit cell (in dimension D and periodicity P) in CDML setting.\n\nIf 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).\n\nTransformations in direct and reciprocal space\n\nBases\n\nThe returned transformation matrix mathbfP transforms a direct-space conventional basis (mathbfa mathbfb mathbfc) to the direct-space primitive basis\n\n (mathbfa mathbfb mathbfc) =\n (mathbfa mathbfb mathbfc)mathbfP\n\nAnalogously, mathbfP transforms a reciprocal-space conventional basis (mathbfa^* mathbfb^* mathbfc^*) to \n\n(mathbfa^*prime mathbfb^*prime mathbfc^*prime) =\n(mathbfa^* mathbfb^* mathbfc^*)(mathbfP^-1)^textT\n\nsee also transform(::DirectBasis, ::AbstractMatrix{<:Real}) and transform(::ReciprocalBasis, ::AbstractMatrix{<:Real})).\n\nCoordinates\n\nThe coordinates of a point in either direct or reciprocal space, each referred to a basis, also transform under mathbfP. Concretely, direct- and reciprocal-space conventional points mathbfr = (r_1 r_2 r_3)^textT and mathbfk = (k_1 k_2 k_3)^textT, respectively, transform to a primitive setting under mathbfP according to:\n\nmathbfr = mathbfP^-1mathbfr\nmathbfk = mathbfP^textTmathbfk\n\nSee also transform(::DirectPoint, ::AbstractMatrix{<:Real}) and transform(::ReciprocalPoint, ::AbstractMatrix{<:Real})).\n\nSetting conventions\n\nThe setting choice for the primitive cell implied by the returned mathbfP 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]\n\nNote 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.\n\nThe setting choice is usually referred to as the CDML primitive setting, or, less frequently and more ambiguously, as the crystallographic primitive setting.\n\n[CDML]: Cracknell, Davies, Miller, & Love, Kroenecker Product Tables, Vol. 1 (1979).\n\n[BCS]: Bilbao Crystallographic Server, KVEC.\n\n[Aroyo]: Aroyo et al., Acta Cryst. A70, 126 (2014): Table 2 gives (mathbfP^-1)^textT.\n\n[ITB2]: Hahn, International Tables of Crystallography, Vol. B, 2nd edition (2001).\n\n[spglib]: Spglib documentation: Transformation to the primitive setting. Thus, Bravais.jl and Spglib.jl transform to identical primitive settings and are hence mutually compatible.\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.transform","page":"Bravais types & bases","title":"Bravais.transform","text":"transform(v::AbstractVec, P::AbstractMatrix) --> v′::typeof(v)\n\nReturn a transformed coordinate vector v′ from an original coordinate vector v using a basis change matrix P.\n\nNote that a basis change matrix mathbfP transforms direct coordinate vectors (RVec) as mathbfr = mathbfP^-1mathbfr but transforms reciprocal coordinates (KVec) as mathbfk = mathbfP^mathrmTmathbfk [ITA6]\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th edition (2016): Secs. 1.5.1.2 and 1.5.2.1.\n\n\n\n\n\ntransform(op::SymOperation, P::AbstractMatrix{<:Real}, \n p::Union{AbstractVector{<:Real}, Nothing}=nothing,\n modw::Bool=true) --> SymOperation\n\nTransforms a op = mathbfWmathbfw by a rotation matrix P and a translation vector p (can be nothing for zero-translations), producing a new symmetry operation op′ = mathbfWmathbfw (cf. Section 1.5.2.3 of [ITA6])\n\nmathbfWmathbfw = mathbfPmathbfp^-1mathbfWmathbfw\nmathbfPmathbfp\n\nwith\n\nmathbfW = mathbfP^-1mathbfWmathbfP\ntext and \nmathbfw = mathbfP^-1(mathbfw+mathbfWmathbfp-mathbfp)\n\nBy default, the translation part of op′, i.e. mathbfw, is reduced to the range 01), i.e. computed modulo 1. This can be disabled by setting modw = false (default, modw = true).\n\nSee also Bravais.primitivize(::SymOperation, ::Char, ::Bool) and Bravais.conventionalize(::SymOperation, ::Char, ::Bool).\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016).\n\n\n\n\n\ntransform(Rs::DirectBasis, P::AbstractMatrix{<:Real})\n\nTransform a direct basis Rs = (mathbfa mathbfb mathbfc) under the transformation matrix P = mathbfP, returning Rs′ = (mathbfa mathbfb mathbfc) = (mathbfa mathbfb mathbfc) mathbfP.\n\n\n\n\n\ntransform(Gs::ReciprocalBasis, P::AbstractMatrix{<:Real})\n\nTransform a reciprocal basis Gs = (mathbfa^* mathbfb^* mathbfc^*) under the transformation matrix P = mathbfP, returning Gs′ = (mathbfa^*prime mathbfb^*prime mathbfc^*prime) = (mathbfa^* mathbfb^* mathbfc^*)(mathbfP^-1)^textT.\n\n\n\n\n\ntransform(r::DirectPoint, P::AbstractMatrix{<:Real}) --> r′::typeof(r)\n\nTransform a point in direct space r = (r_1 r_2 r_3)^textT under the transformation matrix P = mathbfP, returning r′ = (r_1 r_2 r_3)^textT = mathbfP^-1(r_1 r_2 r_3)^textT.\n\n\n\n\n\ntransform(k::ReciprocalPoint, P::AbstractMatrix{<:Real}) --> k′::typeof(k)\n\nTransform a point in reciprocal space k = (k_1 k_2 k_3)^textT under the transformation matrix P = mathbfP, returning k′ = (k_1 k_2 k_3)^textT = mathbfP^textT(k_1 k_2 k_3)^textT.\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.primitivize","page":"Bravais types & bases","title":"Bravais.primitivize","text":"primitivize(v::AbstractVec, cntr::Char) --> v′::typeof(v)\n\nTransforms a conventional coordinate vector v to a standard primitive basis (specified by the centering type cntr), returning the primitive coordinate vector v′.\n\nNote that a basis change matrix mathbfP (as returned e.g. by Bravais.primitivebasismatrix) transforms direct coordinate vectors (RVec) as mathbfr = mathbfP^-1mathbfr but transforms reciprocal coordinates (KVec) as mathbfk = mathbfP^textTmathbfk [ITA6]. Recall also the distinction between transforming a basis and the coordinates of a vector.\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th edition (2016): Secs. 1.5.1.2 and 1.5.2.1.\n\n\n\n\n\nprimitivize(op::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)\n\nReturn a symmetry operation op′ Ww in a primitive setting, transformed from an input symmetry operation op = Ww in a conventional setting. The operations Ww and Ww are related by a transformation Pp via (cf. Section 1.5.2.3 of [ITA6]):\n\nWw = Pp¹WwPp\n\nwhere P and p are the basis change matrix and origin shifts, respectively. The relevant transformation Pp is inferred from the centering type, as provided by cntr (see also Bravais.centering).\n\nBy default, translation parts of op′, i.e. w are reduced modulo 1 (modw = true); to disable this, set modw = false.\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016).\n\n\n\n\n\nprimitivize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat)\n\nGiven flat referred to a conventional basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated primitive basis. \n\nSpecifically, if flat refers to a direct conventional basis Rs (mathbfa mathbfb mathbfc) [with coordinate vectors mathbfr (r_1 r_2 r_3)^mathrmT] then flat′ refers to a direct primitive basis Rs′ (mathbfa mathbfb mathbfc) (mathbfa mathbfb mathbfc)mathbfP [with coordinate vectors mathbfr (r_1 r_2 r_3)^mathrmT = mathbfP^-1mathbfr], where mathbfP denotes the basis-change matrix obtained from primitivebasismatrix(...).\n\nTo compute the associated primitive basis vectors, see primitivize(::DirectBasis, ::Char) [specifically, Rs′ = primitivize(Rs, cntr)].\n\nExamples\n\nA centered ('c') lattice from plane group 5 in 2D, plotted in its conventional and primitive basis (requires using PyPlot):\n\njulia> sgnum = 5; D = 2; cntr = centering(sgnum, D) # 'c' (body-centered)\n\njulia> Rs = directbasis(sgnum, Val(D)) # conventional basis (rectangular)\njulia> flat = levelsetlattice(sgnum, Val(D)) # Fourier lattice in basis of Rs\njulia> flat = modulate(flat) # modulate the lattice coefficients\njulia> plot(flat, Rs)\n\njulia> Rs′ = primitivize(Rs, cntr) # primitive basis (oblique)\njulia> flat′ = primitivize(flat, cntr) # Fourier lattice in basis of Rs′\n\njulia> using PyPlot\njulia> plot(flat′, Rs′)\n\n\n\n\n\nprimitivize(V::Union{AbstractBasis, AbstractPoint}, \n cntr_or_sgnum::Union{Char, <:Integer}) --> V′::typeof(V)\n\nReturn the primitive basis or point V′ associated with the input conventional AbstractBasis or AbstractPoint V.\n\nThe 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)).\n\n\n\n\n\nprimitivize(Rs::DirectBasis, cntr_or_sgnum::Union{Char, <:Integer}) --> Rs′::typeof(Rs)\n\nReturn the primitive direct basis Rs′ corresponding to the input conventional direct basis Rs.\n\n\n\n\n\nprimitivize(Gs::ReciprocalBasis, cntr_or_sgnum::Union{Char, <:Integer}) --> Gs′::typeof(Gs)\n\nReturn the primitive reciprocal basis Gs′ corresponding to the input conventional reciprocal basis Gs.\n\n\n\n\n\nprimitivize(r::DirectPoint, cntr_or_sgnum::Union{Char, <:Integer}) --> r′::typeof(r)\n\nReturn the direct point r′ with coordinates in a primitive basis, corresponding to the input point r with coordinates in a conventional basis. \n\n\n\n\n\nprimitivize(k::ReciprocalPoint, cntr_or_sgnum::Union{Char, <:Integer}) --> k′::typeof(k)\n\nReturn the reciprocal point k′ with coordinates in a primitive basis, corresponding to the input point k with coordinates in a conventional basis. \n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.conventionalize","page":"Bravais types & bases","title":"Bravais.conventionalize","text":"conventionalize(v′::AbstractVec, cntr::Char) --> v::typeof(v′)\n\nTransforms a primitive coordinate vector v′ back to a standard conventional basis (specified by the centering type cntr), returning the conventional coordinate vector v.\n\nSee also primitivize and transform.\n\n\n\n\n\nconventionalize(op′::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)\n\nReturn a symmetry operation op = Ww in a conventional setting, transformed from an input symmetry operation op′ Ww in a primitive setting.\n\nSee primitivize(::SymOperation, ::Char, ::Bool) for description of the centering argument cntr and optional argument modw.\n\n\n\n\n\nconventionalize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat′)\n\nGiven flat referred to a primitive basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated conventional basis. \n\nSee also the complementary method primitivize(::AbstractFourierLattice, ::Char) for additional details.\n\n\n\n\n\nconventionalize(V′::Union{AbstractBasis, AbstractPoint}, \n cntr_or_sgnum::Union{Char, <:Integer}) --> V::typeof(V′)\n\nReturn the conventional basis or point V associated with the input primitive AbstractBasis or AbstractPoint V′.\n\nThe 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)).\n\n\n\n\n\nconventionalize(Rs′::DirectBasis, cntr_or_sgnum::Union{Char, <:Integer}) --> Rs::typeof(Rs′)\n\nReturn the conventional direct basis Rs corresponding to the input primitive direct basis Rs′.\n\n\n\n\n\nconventionalize(Gs′::ReciprocalBasis, cntr_or_sgnum::Union{Char, <:Integer}) --> Gs::typeof(Gs′)\n\nReturn the conventional reciprocal basis Gs corresponding to the input primitive reciprocal basis Gs′.\n\n\n\n\n\nconventionalize(r′::DirectPoint, cntr_or_sgnum::Union{Char, <:Integer}) --> r::typeof(r′)\n\nReturn the direct point r with coordinates in a conventional basis, corresponding to the input point r′ with coordinates in a primitive basis.\n\n\n\n\n\nconventionalize(k′::ReciprocalPoint, cntr_or_sgnum::Union{Char, <:Integer}) --> k::typeof(k′)\n\nReturn the reciprocal point k with coordinates in a conventional basis, corresponding to the input point k′ with coordinates in a primitive basis. \n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.cartesianize","page":"Bravais types & bases","title":"Bravais.cartesianize","text":"cartesianize\n\nTransform an object with coordinates in an lattice basis to an object with coordinates in a Cartesian basis.\n\nDepending on the object, the basis may be inferrable directly from the object; if not, it must be supplied explicitly. @doc \n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.cartesianize!","page":"Bravais types & bases","title":"Bravais.cartesianize!","text":"cartesianize!\n\nIn-place transform an object with coordinates in an lattice basis to an object with coordinates in a Cartesian basis.\n\nDepending on the object, the basis may be inferrable directly from the object; if not, it must be supplied explicitly.\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.latticize","page":"Bravais types & bases","title":"Bravais.latticize","text":"latticize\n\nTransform an object with coordinates in a Cartesian basis to an object with coordinates in a lattice basis.\n\nDepending on the object, the basis may be inferrable directly from the object; if not, it must be supplied explicitly.\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.latticize!","page":"Bravais types & bases","title":"Bravais.latticize!","text":"latticize!\n\nIn-place transform object with coordinates in a Cartesian basis to an object with coordinates in a lattice basis.\n\nDepending on the object, the basis may be inferrable directly from the object; if not, it must be supplied explicitly.\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Miscellaneous","page":"Bravais types & bases","title":"Miscellaneous","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"volume\nmetricmatrix","category":"page"},{"location":"bravais/#Bravais.volume","page":"Bravais types & bases","title":"Bravais.volume","text":"volume(Vs::AbstractBasis)\n\nReturn the volume V of the unit cell associated with the basis Vs::AbstractBasis{D}.\n\nThe volume is computed as V = sqrtmathrmdetmathbfG with with mathbfG denoting the metric matrix of Vs (cf. the International Tables of Crystallography, Volume A, Section 5.2.2.3).\n\nSee also metricmatrix.\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.metricmatrix","page":"Bravais types & bases","title":"Bravais.metricmatrix","text":"metricmatrix(Vs::AbstractBasis)\n\nReturn 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.\n\nEquivalently, 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.\n\nSee also volume.\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Crystalline.jl-extensions-of-Bravais.jl-functions","page":"Bravais types & bases","title":"Crystalline.jl extensions of Bravais.jl functions","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"CurrentModule = Crystalline","category":"page"},{"location":"bravais/#SymOperation","page":"Bravais types & bases","title":"SymOperation","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"transform(::SymOperation, ::AbstractMatrix{<:Real}, ::Union{AbstractVector{<:Real}, Nothing}, ::Bool=true)\nprimitivize(::SymOperation, ::Char, ::Bool)\nconventionalize(::SymOperation, ::Char, ::Bool)","category":"page"},{"location":"bravais/#Bravais.transform-2","page":"Bravais types & bases","title":"Bravais.transform","text":"transform(op::SymOperation, P::AbstractMatrix{<:Real}, \n p::Union{AbstractVector{<:Real}, Nothing}=nothing,\n modw::Bool=true) --> SymOperation\n\nTransforms a op = mathbfWmathbfw by a rotation matrix P and a translation vector p (can be nothing for zero-translations), producing a new symmetry operation op′ = mathbfWmathbfw (cf. Section 1.5.2.3 of [ITA6])\n\nmathbfWmathbfw = mathbfPmathbfp^-1mathbfWmathbfw\nmathbfPmathbfp\n\nwith\n\nmathbfW = mathbfP^-1mathbfWmathbfP\ntext and \nmathbfw = mathbfP^-1(mathbfw+mathbfWmathbfp-mathbfp)\n\nBy default, the translation part of op′, i.e. mathbfw, is reduced to the range 01), i.e. computed modulo 1. This can be disabled by setting modw = false (default, modw = true).\n\nSee also Bravais.primitivize(::SymOperation, ::Char, ::Bool) and Bravais.conventionalize(::SymOperation, ::Char, ::Bool).\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016).\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.primitivize-Tuple{SymOperation, Char, Bool}","page":"Bravais types & bases","title":"Bravais.primitivize","text":"primitivize(op::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)\n\nReturn a symmetry operation op′ Ww in a primitive setting, transformed from an input symmetry operation op = Ww in a conventional setting. The operations Ww and Ww are related by a transformation Pp via (cf. Section 1.5.2.3 of [ITA6]):\n\nWw = Pp¹WwPp\n\nwhere P and p are the basis change matrix and origin shifts, respectively. The relevant transformation Pp is inferred from the centering type, as provided by cntr (see also Bravais.centering).\n\nBy default, translation parts of op′, i.e. w are reduced modulo 1 (modw = true); to disable this, set modw = false.\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016).\n\n\n\n\n\n","category":"method"},{"location":"bravais/#Bravais.conventionalize-Tuple{SymOperation, Char, Bool}","page":"Bravais types & bases","title":"Bravais.conventionalize","text":"conventionalize(op′::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)\n\nReturn a symmetry operation op = Ww in a conventional setting, transformed from an input symmetry operation op′ Ww in a primitive setting.\n\nSee primitivize(::SymOperation, ::Char, ::Bool) for description of the centering argument cntr and optional argument modw.\n\n\n\n\n\n","category":"method"},{"location":"bravais/#AbstractVec","page":"Bravais types & bases","title":"AbstractVec","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"transform(::Crystalline.AbstractVec, ::AbstractMatrix{<:Real})\nprimitivize(::Crystalline.AbstractVec, ::Char)\nconventionalize(::Crystalline.AbstractVec, ::Char)","category":"page"},{"location":"bravais/#Bravais.transform-Tuple{Crystalline.AbstractVec, AbstractMatrix{<:Real}}","page":"Bravais types & bases","title":"Bravais.transform","text":"transform(v::AbstractVec, P::AbstractMatrix) --> v′::typeof(v)\n\nReturn a transformed coordinate vector v′ from an original coordinate vector v using a basis change matrix P.\n\nNote that a basis change matrix mathbfP transforms direct coordinate vectors (RVec) as mathbfr = mathbfP^-1mathbfr but transforms reciprocal coordinates (KVec) as mathbfk = mathbfP^mathrmTmathbfk [ITA6]\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th edition (2016): Secs. 1.5.1.2 and 1.5.2.1.\n\n\n\n\n\n","category":"method"},{"location":"bravais/#Bravais.primitivize-Tuple{Crystalline.AbstractVec, Char}","page":"Bravais types & bases","title":"Bravais.primitivize","text":"primitivize(v::AbstractVec, cntr::Char) --> v′::typeof(v)\n\nTransforms a conventional coordinate vector v to a standard primitive basis (specified by the centering type cntr), returning the primitive coordinate vector v′.\n\nNote that a basis change matrix mathbfP (as returned e.g. by Bravais.primitivebasismatrix) transforms direct coordinate vectors (RVec) as mathbfr = mathbfP^-1mathbfr but transforms reciprocal coordinates (KVec) as mathbfk = mathbfP^textTmathbfk [ITA6]. Recall also the distinction between transforming a basis and the coordinates of a vector.\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th edition (2016): Secs. 1.5.1.2 and 1.5.2.1.\n\n\n\n\n\n","category":"method"},{"location":"bravais/#Bravais.conventionalize-Tuple{Crystalline.AbstractVec, Char}","page":"Bravais types & bases","title":"Bravais.conventionalize","text":"conventionalize(v′::AbstractVec, cntr::Char) --> v::typeof(v′)\n\nTransforms a primitive coordinate vector v′ back to a standard conventional basis (specified by the centering type cntr), returning the conventional coordinate vector v.\n\nSee also primitivize and transform.\n\n\n\n\n\n","category":"method"},{"location":"bravais/#AbstractFourierLattice","page":"Bravais types & bases","title":"AbstractFourierLattice","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"primitivize(::AbstractFourierLattice, ::Char)\nconventionalize(::AbstractFourierLattice, ::Char)","category":"page"},{"location":"bravais/#Bravais.primitivize-Tuple{Crystalline.AbstractFourierLattice, Char}","page":"Bravais types & bases","title":"Bravais.primitivize","text":"primitivize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat)\n\nGiven flat referred to a conventional basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated primitive basis. \n\nSpecifically, if flat refers to a direct conventional basis Rs (mathbfa mathbfb mathbfc) [with coordinate vectors mathbfr (r_1 r_2 r_3)^mathrmT] then flat′ refers to a direct primitive basis Rs′ (mathbfa mathbfb mathbfc) (mathbfa mathbfb mathbfc)mathbfP [with coordinate vectors mathbfr (r_1 r_2 r_3)^mathrmT = mathbfP^-1mathbfr], where mathbfP denotes the basis-change matrix obtained from primitivebasismatrix(...).\n\nTo compute the associated primitive basis vectors, see primitivize(::DirectBasis, ::Char) [specifically, Rs′ = primitivize(Rs, cntr)].\n\nExamples\n\nA centered ('c') lattice from plane group 5 in 2D, plotted in its conventional and primitive basis (requires using PyPlot):\n\njulia> sgnum = 5; D = 2; cntr = centering(sgnum, D) # 'c' (body-centered)\n\njulia> Rs = directbasis(sgnum, Val(D)) # conventional basis (rectangular)\njulia> flat = levelsetlattice(sgnum, Val(D)) # Fourier lattice in basis of Rs\njulia> flat = modulate(flat) # modulate the lattice coefficients\njulia> plot(flat, Rs)\n\njulia> Rs′ = primitivize(Rs, cntr) # primitive basis (oblique)\njulia> flat′ = primitivize(flat, cntr) # Fourier lattice in basis of Rs′\n\njulia> using PyPlot\njulia> plot(flat′, Rs′)\n\n\n\n\n\n","category":"method"},{"location":"bravais/#Bravais.conventionalize-Tuple{Crystalline.AbstractFourierLattice, Char}","page":"Bravais types & bases","title":"Bravais.conventionalize","text":"conventionalize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat′)\n\nGiven flat referred to a primitive basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated conventional basis. \n\nSee also the complementary method primitivize(::AbstractFourierLattice, ::Char) for additional details.\n\n\n\n\n\n","category":"method"},{"location":"#Crystalline.jl","page":"Home","title":"Crystalline.jl","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"","category":"page"},{"location":"","page":"Home","title":"Home","text":"Documentation for Crystalline.jl and Bravais.jl.","category":"page"},{"location":"","page":"Home","title":"Home","text":"note: Note\nCrystalline.jl remains a work-in-progress research package. Breaking changes are likely (but will respect semver conventions).","category":"page"},{"location":"","page":"Home","title":"Home","text":"Pages = [\"operations.md\",\n \"groups.md\",\n \"irreps.md\",\n \"bravais.md\",\n \"bandreps.md\",\n \"lattices.md\",\n \"api.md\",\n \"internal-api.md\"]","category":"page"},{"location":"irreps/#Irreducible-representations","page":"Irreps","title":"Irreducible representations","text":"","category":"section"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"Crystalline.jl provides easy access to crystallographic point group irreps, site symmetry group irreps, and the little group irreps of space groups. Currently, we only provide access to spinless (or \"single-valued\") irreps.","category":"page"},{"location":"irreps/#Point-group-irreps","page":"Irreps","title":"Point group irreps","text":"","category":"section"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"Irreps for the crystallographic point groups are accessible via pgirreps, with the point group specified either by IUC label and dimensionality. As an example, we may load the irreps of the 6mm (C₆ᵥ in Schoenflies notation; see also schoenflies(::PointGroup)) point group in 3D.","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"using Crystalline\n\npgirs = pgirreps(\"6mm\", Val(3))","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"Frequently, the character table of the associated irreps is more informative than the irrep matrices themselves. We can construct this table using characters, which returns a CharacterTable:","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"characters(pgirs)","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"The characters are functions of the conjugacy class (i.e., the characters of operations in the same conjugacy class are equal). Thus, a more compact representation of the character table can be achieved by a class-resolved table, achievable via classcharacters:","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"classcharacters(pgirs)","category":"page"},{"location":"irreps/#Notation","page":"Irreps","title":"Notation","text":"","category":"section"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"The default point group irrep labeling follows the Bilbao Crystallographic Server's labeling, which in turn follows the 1963 labelling of Koster, Dimmock, Wheeler, & Statz [2] (which is also followed e.g. by CDML [1] labeling as well as Bradley and Cracknell's book). Associated Muliken (or \"spectroscopist's\") notation can be obtained via mulliken.","category":"page"},{"location":"irreps/#Little-group-irreps","page":"Irreps","title":"Little group irreps","text":"","category":"section"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"Little group irreps, sometimes called ''small'' irreps, are accessible via lgirreps and provided with CDML [1] labels (courtesy of ISOTROPY). As an example, we can obtain the irreps of space group 183 (P6mm; the trivial 3D extension of plane group 17, which in turn is the space group extension of point group 6mm from above) by:","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"using Crystalline\n\nlgirsd = lgirreps(183, Val(3))","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"which returns a dictionary of LGIrreps, indexed by k-labels given as Strings, corresponding to different little groups. In general, we include all the little groups included in ISOTROPY; unfortunately, there is no strict guarantee that this includes a full listing of all inequivalent irreps (although it is typically true). The listing typically contains both special points, lines, and planes (and also always the general point).","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"We can inspect the little group irreps of any particular k-point, accessing it via its canonical label. As before, we can inspect the associated character tables to get an overview of the irreps:","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"lgirs = lgirsd[\"Γ\"] # little group irreps at the Γ point\ncharacters(lgirs)","category":"page"},{"location":"irreps/#Space-group-irreps","page":"Irreps","title":"Space group irreps","text":"","category":"section"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"We currently do not provide access to \"full\" space group irreps. They can, however, be readily built by induction from little group irreps. Specifically, every little group irrep D_mathbfk^alpha associated with the little group G_mathbfk, induces a space group irrep, sometimes denoted ^*D_mathbfk^alpha or D^alpha_mathbfkuparrow G, in the full space group G:[Inui]","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":" ^*D_mathbfk^alpha(g)_ij\n =\n begincases\n D_mathbfk^alpha(h_i^-1gh_j) textif h_i^-1gh_j in G_mathbfk\n boldsymbol0_d_mathbfk^alphatimes d_mathbfk^alpha textotherwise\n endcases","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"where d_mathbfk^alpha is the dimension of the little group irrep D^alpha_mathbfk, boldsymbol0_d_mathbfk^alphatimes d_mathbfk^alpha is a d_mathbfk^alphatimes d_mathbfk^alpha zero matrix, and h_i and h_j iterate over the (left) coset representatives of G_mathbfk in G (of which there are mathrmstarmathbfk, i.e., the order of the star of mathbfk). The induced irrep ^*D_mathbfk^alpha is consequently a d_mathbfk^alphamathrmstarmathbfktimes d_mathbfk^alphamathrmstarmathbfk matrix.","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"[Inui]: Inui, Tanabe, & Onodera, Group Theory and its Applications in Physics, Springer (1990). Section 11.9.","category":"page"},{"location":"irreps/#Site-symmetry-irreps","page":"Irreps","title":"Site symmetry irreps","text":"","category":"section"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"To obtain irreps associated with a given site symmetry group (see SiteGroup), use siteirreps which obtains the irreps associated with the site symmetry group by identifying a \"parent\" point group which is isomorphic to the provided site symmetry group, and then returning a suitable permutation of the point group's irreps.","category":"page"},{"location":"irreps/#Time-reversal-symmetry-and-\"physically-real\"-irreps","page":"Irreps","title":"Time-reversal symmetry & \"physically real\" irreps","text":"","category":"section"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"Irreps returned in Crystalline.jl do not assume time-reversal symmetry by default. To incorporate time-reversal symmetry (or, equivalently, to obtain associated \"physically real\" irreps - or, more technically, co-representations), which may cause irreps to \"stick together\", see realify (which takes a vector of PGIrreps or LGIrreps).","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"As an example, the Γ₃, Γ₄, Γ₅, and Γ₆ irreps of point group 6 (C₆) are intrinsically complex in the absence of time-reversal symmetry:","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"using Crystalline\n\npgirs = pgirreps(\"6\", Val(3))\ncharacters(pgirs)","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"When time-reversal symmetry is incorporated, the irreps stick together pairwise and have real characters:","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"pgirs′ = realify(pgirs)\ncharacters(pgirs′)","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"To inspect the reality type of a given irrep, see reality. Possible types are REAL, COMPLEX, and PSEUDOREAL (the latter does not arise for point groups):","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"label.(pgirs) .=> reality.(pgirs)","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"The reality type can be computed ab initio via calc_reality, using the Frobenius criterion for PGIrreps and SiteIrreps and the Herring criterion for LGIrreps.","category":"page"},{"location":"irreps/#Data-sources","page":"Irreps","title":"Data sources","text":"","category":"section"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"Point group irreps are obtained from the Bilbao Crystallographic Server's Representations PG program and little group irreps of space groups are obtained from ISOTROPY's 2011 ISO-IR dataset.","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"If these functionalities are used in published research, please cite the original publications (listed in associated function docstrings).","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"[1]: Cracknell, A.P., Davies, B.L., Miller, S.C., & Love, W.F., Kronecker Product Tables, Vol. 1. General Introduction and Tables of Irreducible Representations of Space Groups, New York: IFI/Plenum (1979).","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"[2]: Koster, G.F., Dimmock, J.O., Wheeler, R.G., & Statz, H., Properties of the Thirty-two Point Groups, Cambridge: MIT Press (1963).","category":"page"}] +[{"location":"operations/#Symmetry-operations","page":"Symmetry operations","title":"Symmetry operations","text":"","category":"section"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"A SymOperation{D} is a representation of a spatial symmetry operation g=mathbfWmathbfw, composed of a rotational mathbfW and a translation part mathbfw. The rotational and translation parts are assumed to share the same basis setting; by default, operations returned by Crystalline.jl are in the conventional setting of the International Tables of Crystallography, Volume A (ITA).","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"SymOperations can be constructed in two ways, either by explicitly specifying the mathbfW and mathbfw:","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"using Crystalline, StaticArrays\nW, w = (@SMatrix [1 0 0; 0 0 1; 0 1 0]), (@SVector [0, 0.5, 0])\nop = SymOperation(W, w)","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"or by its equivalent triplet form","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"op = SymOperation{3}(\"x,z+1/2,y\")","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"There is also a string macro accessor @S_str that allows triplet input via S\"x,z+1/2,y\".","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"In the above output, three equivalent notations for the symmetry operation are given: first, the Seitz notation {m₀₋₁₁|0,½,0}, then the triplet notation (x,z+1/2,y), and finally the explicit matrix notation.","category":"page"},{"location":"operations/#Components","page":"Symmetry operations","title":"Components","text":"","category":"section"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"The rotation and translation parts mathbfW and mathbfw of a SymOperation{D} mathbfWmathbfw can be accessed via rotation and translation, returning an SMatrix{D, D, Float64} and an SVector{D, Float64}, respectively. The \"augmented\" matrix mathbfWmathbfw can similarly be obtained via matrix.","category":"page"},{"location":"operations/#Operator-composition","page":"Symmetry operations","title":"Operator composition","text":"","category":"section"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"Composition of two operators g_1 and g_2 is defined by ","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"g_1 circ g_2 = mathbfW_1mathbfw_1 circ mathbfW_2mathbfw_2 = mathbfW_1mathbfW_2mathbfw_1 + mathbfW_1mathbfw_2","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"We can compose two SymOperations in Crystalline via:","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"op1 = S\"z,x,y\" # 3₁₁₁⁺\nop2 = S\"z,y,x\" # m₋₁₀₁\nop1 * op2","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"which is accessed by an overloaded call to Base.*, i.e. the multiplication operator (this enables us to also call derived methods of *, such as integer powers (e.g., S\"-y,x-y,z\"^3 == S\"x,y,z\"). Note that composition is taken modulo integer lattice translations by default, such that","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"op2′ = S\"z,y,x+1\" # {m₋₁₀₁|001}\nop1 * op2′ # equivalent to compose(op1, op2′, true)","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"rather than S\"x+1,z,y\", which is the result of direct application of the above composition rule. To compute \"unreduced\" composition, the more precise compose variant of * can be used with an optional third argument false:","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"compose(op1, op2′, false)","category":"page"},{"location":"operations/#Operator-inverses","page":"Symmetry operations","title":"Operator inverses","text":"","category":"section"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"The operator inverse is defined as mathbfWmathbfw = mathbfW^-1-mathbfW^-1mathbfw and can be computed via","category":"page"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"inv(op1) # inv(3₁₁₁⁺)","category":"page"},{"location":"operations/#Action-of-symmetry-operators","page":"Symmetry operations","title":"Action of symmetry operators","text":"","category":"section"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"A SymOperation can act on vectors in direct (RVec) or reciprocal (KVec) space. When acting in reciprocal space, translation parts of a SymOperation have no effect.","category":"page"},{"location":"operations/#Magnetic-symmetry-operations","page":"Symmetry operations","title":"Magnetic symmetry operations","text":"","category":"section"},{"location":"operations/","page":"Symmetry operations","title":"Symmetry operations","text":"Magnetic symmetry operations that may incorporate composition with an anti-unitary time-reversal operation can be created via MSymOperation (see also mspacegroup).","category":"page"},{"location":"internal-api/#Internal-API","page":"Internal API","title":"Internal API","text":"","category":"section"},{"location":"internal-api/","page":"Internal API","title":"Internal API","text":"This page lists unexported functionality from Crystalline, that may be of interest to developers.","category":"page"},{"location":"internal-api/","page":"Internal API","title":"Internal API","text":"","category":"page"},{"location":"internal-api/","page":"Internal API","title":"Internal API","text":"CurrentModule = Crystalline","category":"page"},{"location":"internal-api/#Unexported,-internal-functionality","page":"Internal API","title":"Unexported, internal functionality","text":"","category":"section"},{"location":"internal-api/","page":"Internal API","title":"Internal API","text":"Modules = [Crystalline]\nPrivate = true\nPublic = false\nOrder = [:type, :function, :constant]","category":"page"},{"location":"internal-api/#Crystalline.AbstractFourierLattice-Tuple{Any}","page":"Internal API","title":"Crystalline.AbstractFourierLattice","text":"(flat::AbstractFourierLattice)(xyz) --> Float64\n(flat::AbstractFourierLattice)(xyzs...) --> Float64\n\nEvaluate an AbstractFourierLattice at the point xyz and return its real part, i.e.\n\n mathopmathrmResum_i c_i exp(2pi imathbfG_icdotmathbfr)\n\nwith mathrmG_i denoting reciprocal lattice vectors in the allowed orbits of flat, with c_i denoting the associated coefficients (and mathbfr equiv xyz).\n\nxyz may be any iterable object with dimension matching flat consisting of real numbers (e.g., a Tuple, Vector, or SVector). Alternatively, the coordinates can be supplied individually (i.e., as flat(x, y, z)).\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.AbstractGroup","page":"Internal API","title":"Crystalline.AbstractGroup","text":"abstract type AbstractGroup{D, O} <: AbstractArray{O, 1}\n\nThe abstract supertype of all group structures, with assumed group elements of type O and embedding dimension D.\n\nMinimum interface includes definitions of: - num(::AbstractGroup), returning an integer or tuple of integers. - operations(::AbstractGroup), returning a set of operations. or, alternatively, fields with names num and operations, behaving accordingly.\n\n\n\n\n\n","category":"type"},{"location":"internal-api/#Crystalline.AbstractIrrep","page":"Internal API","title":"Crystalline.AbstractIrrep","text":"AbstractIrrep{D}\n\nAbstract supertype for irreps of dimensionality D: must have fields cdml, matrices, g (underlying group), reality (and possibly translations). May overload a function irreps that returns the associated irrep matrices; if not, will simply be matrices.\n\n\n\n\n\n","category":"type"},{"location":"internal-api/#Crystalline.GenericGroup","page":"Internal API","title":"Crystalline.GenericGroup","text":"struct GenericGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}\n\noperations::Array{SymOperation{D}, 1} where D\n\n\n\n\n\n","category":"type"},{"location":"internal-api/#Crystalline.UnityFourierLattice","page":"Internal API","title":"Crystalline.UnityFourierLattice","text":"UnityFourierLattice{D} <: AbstractFourierLattice{D}\n\nA general D-dimensional Fourier (plane wave) lattice specified by orbits of reciprocal lattice vectors (orbits) and coefficient interrelations (orbitcoefs)). The norm of all elements in orbitcoefs is unity. orbits (and associated coefficients) are sorted in order of increasing norm (low to high).\n\n\n\n\n\n","category":"type"},{"location":"internal-api/#Base.parse-Union{Tuple{D}, Tuple{Type{<:SymmetryVector}, AbstractString, Array{Collection{LGIrrep{D}}, 1}}} where D","page":"Internal API","title":"Base.parse","text":"parse(::Type{SymmetryVector{D}}, \n s::AbstractString,\n lgirsv::Vector{Collection{LGIrrep{D}}}) -> SymmetryVector{D}\n\nParse a string s to a SymmetryVector over the irreps provided in lgirsv. The irrep labels of lgirsv and s must use the same convention.\n\nExample\n\njulia> brs = calc_bandreps(220);\n\njulia> lgirsv = irreps(brs); # irreps at P, H, Γ, & PA\n\njulia> s = \"[2P₃, 4N₁, H₁H₂+H₄H₅, Γ₁+Γ₂+Γ₄+Γ₅, 2PA₃]\";\n\njulia> parse(SymmetryVector, s, lgirsv)\n15-irrep SymmetryVector{3}:\n [2P₃, 4N₁, H₁H₂+H₄H₅, Γ₁+Γ₂+Γ₄+Γ₅, 2PA₃] (8 bands)\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.:⊚-Union{Tuple{T}, Tuple{T, T}} where T<:SymOperation","page":"Internal API","title":"Crystalline.:⊚","text":"(⊚)(op1::T, op2::T) where T<:SymOperation --> Vector{Float64}\n\nCompose two symmetry operations op1 = W₁w₁ and op2 = W₂w₂ and return the quotient of w₁+W₁w₂ and 1. This functionality complements op1*op2, which yields the translation modulo 1; accordingly, translation(op1*op2) + op1⊚op2 yields the translation component of the composition op1 and op2 without taking it modulo 1, i.e. including any \"trivial\" lattice translation.\n\nNote that ⊚ can be auto-completed in Julia via \\circledcirc+[tab]\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.CompositeBandRep_from_indices-Tuple{Vector{Int64}, Collection{<:NewBandRep}}","page":"Internal API","title":"Crystalline.CompositeBandRep_from_indices","text":"CompositeBandRep_from_indices(idxs::Vector{Int}, brs::Collection{<:NewBandRep})\n\nReturn a CompositeBandRep whose symmetry content is equal to the sum the band representations of brs over idxs. In terms of irrep multiplicity, this is equivalent to sum(brs[idxs]) in the sense that CompositeBandRep(idxs, brs) is equal to sum(brs[idxs]) for each irrep multiplicity. \n\nThe difference, and primary motivation for using CompositeBandRep, is that CompositeBandRep retains information about which band representations are included and with what multiplicity (the multiplicity of the ith brs-element being equaling to count(==(i), idxs)).\n\nExample\n\njulia> brs = calc_bandreps(2);\n\njulia> cbr = CompositeBandRep_from_indices([1, 1, 2, 6], brs)\n16-irrep CompositeBandRep{3}:\n (1f|Aᵤ) + (1h|Aᵤ) + 2(1h|Ag) (4 bands)\n\njulia> cbr == brs[1] + brs[1] + brs[2] + brs[6]\ntrue\n\njulia> SymmetryVector(cbr)\n16-irrep SymmetryVector{3}:\n [2Z₁⁺+2Z₁⁻, Y₁⁺+3Y₁⁻, 2U₁⁺+2U₁⁻, 2X₁⁺+2X₁⁻, 3T₁⁺+T₁⁻, 2Γ₁⁺+2Γ₁⁻, 3V₁⁺+V₁⁻, R₁⁺+3R₁⁻] (4 bands)\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline._find_equal_groups_in_sorted-Tuple{AbstractVector}","page":"Internal API","title":"Crystalline._find_equal_groups_in_sorted","text":"_find_equal_groups_in_sorted(v::AbstractVector) --> Vector{UnitRange}\n\nReturns indices into groups of equal values in v. Input v must be sorted so that identical values are adjacent.\n\nExample\n\n_find_equal_groups_in_sorted([-4,1,1,3,3,3]) # returns [1:1, 2:3, 4:6]\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline._findsubgroup-Union{Tuple{D}, Tuple{AbstractArray{SymOperation{D}, 1}, AbstractArray{SymOperation{D}, 1}}, Tuple{AbstractArray{SymOperation{D}, 1}, AbstractArray{SymOperation{D}, 1}, Union{Nothing, Char}}} where D","page":"Internal API","title":"Crystalline._findsubgroup","text":"_findsubgroup(opsᴳ::T, opsᴴ::T′[, cntr]) where T⁽′⁾<:AbstractVector{SymOperation}\n --> Tuple{Bool, Vector{Int}}\n\nReturns a 2-tuple with elements:\n\nA boolean, indicating whether the group H (with operators opsᴴ) is a subgroup of the group G (with operators opsᴳ), i.e. whether H G.\nAn indexing vector idxsᴳ²ᴴ of opsᴳ into opsᴴ (empty if H is not a subgroup of G), such that all(isapprox(opsᴳ[idxsᴳ²ᴴ], opsᴴ, cntr).\n\nIf cntr is provided, comparison of operations in G and H is done in the associated primitive basis (i.e., cntr is passed to isapprox which compares operations in G and H).\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline._orbit-Tuple{AbstractVector{<:AbstractMatrix{<:Real}}, AbstractVector{<:Real}}","page":"Internal API","title":"Crystalline._orbit","text":"_orbit(Ws, x)\n\nComputes the orbit of a direct-space point x under a set of point-group operations Ws, i.e. computes the set {gx | g∈G} where g denotes elements of the group G composed of all operations in Ws (possibly iterated, to ensure full coverage).\n\nIt is important that Ws and x are given in the same basis. \n\n[W = PWP¹ if the basis change is from coordinates r to r' = Pr, corresponding to a new set of basis vectors (x̂')ᵀ=x̂ᵀP; e.g., when going from a direct basis representation to a Cartesian one, the basis change matrix is P = [R₁ R₂ R₃], with Rᵢ inserted as column vectors]\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.can_intersect-Union{Tuple{T}, Tuple{D}, Tuple{T, T}} where {D, T<:Crystalline.AbstractVec{D}}","page":"Internal API","title":"Crystalline.can_intersect","text":"can_intersect(\n v::Crystalline.AbstractVec{D},\n v′::Crystalline.AbstractVec{D};\n atol\n) -> NamedTuple{(:bool, :αβγ, :αβγ′, :L), <:Tuple{Bool, Any, Any, Any}}\n\n\nCheck whether two AbstractVecs v and v′ can intersect, i.e., whether there exist free parameters such that they are equivalent modulo an integer lattice vector.\n\nReturns a NamedTuple (; bool, αβγ, αβγ′, L). If bool = true, kv and kv′ are compatible in the sense that v(αβγ) == v′(αβγ′) + L if bool == true where L is an integer-valued lattice vector. If bool = false, they are incompatible (and zero-valued vectors are returned for αβγ, αβγ′, and L).\n\nExtended help\n\nThe keyword argument atol (default, 1.0e-12) specifies the absolute tolerance for the comparison.\nIf both v and v′ are not special, i.e., both have free parameters, the intersection point may not be unique (e.g., for co-linear v and v′).\nThe implementation currently only checks the immediately adjacent lattice vectors for equivalence; if there is equivalence, but the the required elements of L would have |Lᵢ| > 1, the currently implementation will not identify the equivalence.\nThis operation is usually only meaningful if the bases of kv and kv′ agree and are primitive.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.compact_print_matrix","page":"Internal API","title":"Crystalline.compact_print_matrix","text":"compact_print_matrix(io, X::Matrix, prerow)\ncompact_print_matrix(io, X::Matrix, prerow, elformat)\n\n\nPrint a matrix using PrettyTables, allowing a prerow input to be printed before each row of the matrix. elformat is applied to each element of the matrix before printing.\n\n\n\n\n\n","category":"function"},{"location":"internal-api/#Crystalline.corep_orthogonality_factor-Tuple{Crystalline.AbstractIrrep}","page":"Internal API","title":"Crystalline.corep_orthogonality_factor","text":"corep_orthogonality_factor(\n ir::Crystalline.AbstractIrrep\n) -> Int64\n\n\n–> Int\n\nReturn a multiplicative factor for use in checking the orthogonality relations of \"physically real\" irreps (coreps).\n\nFor such \"physically real\" irreps, the conventional orthogonality relations (by conventional we mean orthogonality relations that sum only over unitary operations, i.e. no \"gray\" operations/products with time-inversion) still hold if we include a multiplicative factor f that depends on the underlying reality type r of the corep, such that f(REAL) = 1, f(COMPLEX) = 2, and f(PSEUDOREAL) = 4. If the provided irrep is not a corep (i.e. has iscorep(ir) = false), the multiplicative factor is 1.\n\nReferences\n\nSee e.g. Bradley & Cracknell Eq. (7.4.10).\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.find_compatible-Union{Tuple{D}, Tuple{KVec{D}, AbstractArray{KVec{D}, 1}}} where D","page":"Internal API","title":"Crystalline.find_compatible","text":"find_compatible(\n kv::KVec{D},\n kvs′::AbstractArray{KVec{D}, 1}\n) -> Vector{Int64}\n\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.find_principal_rotations-Union{Tuple{AbstractArray{SymOperation{D}, 1}}, Tuple{D}} where D","page":"Internal API","title":"Crystalline.find_principal_rotations","text":"find_principal_rotations(\n ops::AbstractArray{SymOperation{D}, 1};\n include_improper\n) -> Vector{Int64}\n\n\nReturn the the indices of the \"maximal\" rotations among a set of operations ops, i.e. those of maximal order (the \"principal rotations\").\n\nKeyword arguments\n\ninclude_improper (=false): if true, improper rotations are included in the consideration. If the order of improper and proper rotations is identical, only the indices of the proper rotations are returned. If the maximal (signed) rotation order is -2 (a mirror), it is ignored, and the index of the identity operation is returned.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.findequiv-Union{Tuple{D}, Tuple{SymOperation{D}, AbstractArray{SymOperation{D}, 1}, Char}} where D","page":"Internal API","title":"Crystalline.findequiv","text":"findequiv(op::SymOperation, ops::AbstractVector{SymOperation{D}}, cntr::Char) \n --> Tuple{Int, Vector{Float64}}\n\nSearch for an operator op′ in ops which is equivalent, modulo differences by primitive lattice translations Δw, to op. Return the index of op′ in ops, as well as the primitive translation difference Δw. If no match is found returns nothing.\n\nThe small irreps of op at wavevector k, Dⱼᵏ[op], can be computed from the small irreps of op′, Dⱼᵏ[op′], via Dⱼᵏ[op] = exp(2πik⋅Δw)Dⱼᵏ[op′]\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.fractionify!","page":"Internal API","title":"Crystalline.fractionify!","text":"fractionify!(io::IO, x::Real, forcesign::Bool=true, tol::Real=1e-6)\n\nWrite a string representation of the nearest fraction (within a tolerance tol) of x to io. If forcesign is true, the sign character of x is printed whether + or - (otherwise, only printed if -).\n\n\n\n\n\n","category":"function"},{"location":"internal-api/#Crystalline.freeparams-Tuple{Crystalline.AbstractVec}","page":"Internal API","title":"Crystalline.freeparams","text":"freeparams(v::Crystalline.AbstractVec) -> Any\n\n\nReturn a vector whose entries are true (false) if the free parameters α,β,γ, respectively, occur with nonzero (zero) coefficients in v.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.induce_bandrep-Union{Tuple{D}, Tuple{SiteIrrep{D}, SymOperation{D}, KVec{D}}} where D","page":"Internal API","title":"Crystalline.induce_bandrep","text":"induce_bandrep(siteir::SiteIrrep, h::SymOperation, kv::KVec)\n\nReturn the band representation induced by the provided SiteIrrep evaluated at kv and for a SymOperation h.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.isapproxin-Tuple{Any, Any, Vararg{Any}}","page":"Internal API","title":"Crystalline.isapproxin","text":"isapproxin(x, itr, optargs...; kwargs...) --> Bool\n\nDetermine whether x ∈ itr with approximate equality.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.iscorep-Tuple{Crystalline.AbstractIrrep}","page":"Internal API","title":"Crystalline.iscorep","text":"iscorep(ir::Crystalline.AbstractIrrep) -> Any\n\n\n–> Bool\n\nReturn whether the provided irrep has been made \"physically real\" (i.e. is a corep) so that it differs from the underlying irrep (i.e. whether the irrep and \"derived\" corep differ).\n\nFor an irrep that has not been passed to realify, this is always false. For an irrep produced by realify, this can be either false or true: if the reality type is REAL it is false; if the reality type is PSEUDOREAL or COMPLEX it is true.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.matching_littlegroups-Union{Tuple{BandRepSet}, Tuple{D}, Tuple{BandRepSet, Val{D}}} where D","page":"Internal API","title":"Crystalline.matching_littlegroups","text":"matching_littlegroups(brs::BandRepSet, ::Val{D}=Val(3))\n\nFinds the matching little groups for each k-point referenced in brs. This is mainly a a convenience accessor, since e.g. littlegroup(::SpaceGroup, ::KVec) could also return the required little groups. The benefit here is that the resulting operator sorting of the returned little group is identical to the operator sortings assumed in lgirreps and littlegroups.\n\nReturns a Vector{LittleGroup{D}} (unlike littlegroups, which returns a Dict{String, LittleGroup{D}}).\n\nNote 1\n\nUnlike the operations returned by spacegroup, the returned little groups do not include copies of operators that would be identical when transformed to a primitive basis. The operators are, however, still given in a conventional basis.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.nfreeparams-Tuple{Crystalline.AbstractVec}","page":"Internal API","title":"Crystalline.nfreeparams","text":"nfreeparams(v::Crystalline.AbstractVec) -> Int64\n\n\nReturn total number of free parameters occuring in v.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.parsefraction-Union{Tuple{AbstractString}, Tuple{T}, Tuple{AbstractString, Type{T}}} where T","page":"Internal API","title":"Crystalline.parsefraction","text":"parsefraction(str::AbstractString, T::Type=Float64)\n\nParse a string str, allowing fraction inputs (e.g. \"1/2\"), return as a type T (default, Float64).\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.permute_multtable-Tuple{Matrix{Int64}, AbstractVector{Int64}}","page":"Internal API","title":"Crystalline.permute_multtable","text":"permute_multtable(\n mt::Matrix{Int64},\n P::AbstractVector{Int64}\n) -> Any\n\n\n–> Matrix{Int}\n\nReturns a multiplication table derived from mt but under a reordering permutation P of the operator indices in mt. In practice, this corresponds to a permutation of the rows and columns of mt as well as a subsequent relabelling of elements via P.\n\nExample\n\npg = pointgroup(\"-4m2\", Val(3))\nmt = MultTable(pg)\nP = [2,3,1,4,5,8,6,7] # permutation of operator indices\nmt′ = permute_multtable(mt.table, P)\nmt′ == MultTable(pg[P]).table\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.reduce_dict_of_vectors-Union{Tuple{F}, Tuple{F, Dict{<:Any, <:AbstractVector}}} where F","page":"Internal API","title":"Crystalline.reduce_dict_of_vectors","text":"reduce_dict_of_vectors([f=identity,] d::Dict{_, <:Vector}) --> Vector{T}\n\nReturn the concatenated vector of all of vectors in d under the element-wise application of f. Effectively flattens a Dict of Vectors to a single Vector.\n\nNote that application of f to vector-elements of d must return a stable type T.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.reduce_orbits!-Union{Tuple{D}, Tuple{AbstractArray{WyckoffPosition{D}, 1}, Char}, Tuple{AbstractArray{WyckoffPosition{D}, 1}, Char, Bool}} where D","page":"Internal API","title":"Crystalline.reduce_orbits!","text":"reduce_orbits!(orbits::Vector{WyckoffPosition}, cntr::Char, conv_or_prim::Bool=true])\n\nUpdate orbits in-place to contain only those Wyckoff positions that are not equivalent in a primitive basis (as determined by the centering type cntr). Returns the updated orbits. \n\nIf conv_or_prim = true (default), the Wyckoff positions are returned in the original, conventional basis; if conv_or_prim = false, they are returned in a primitive basis.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.reduce_translation_to_unitrange-Tuple{AbstractVector{<:Real}}","page":"Internal API","title":"Crystalline.reduce_translation_to_unitrange","text":"reduce_translation_to_unitrange_q(w::AbstractVector{<:Real}) --> :: typeof(w)\n\nReduce the components of the vector w to range [0.0, 1.0[, incorporating a tolerance atol in the reduction.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.rotation_order-Tuple{AbstractMatrix{<:Real}}","page":"Internal API","title":"Crystalline.rotation_order","text":"rotation_order(W::Matrix{<:Real}) --> Int\nrotation_order(op::SymOperation) --> Int\n\nDetermine the integer rotation order of a point group operation, input either as a matrix W or op::SymOperation.\n\nThe rotation order of\n\nProper rotations is positive.\nImproper (mirrors, inversion, roto-inversions) is negative.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.rotation_order_3d-Tuple{Real, Real}","page":"Internal API","title":"Crystalline.rotation_order_3d","text":"rotation_order_3d(detW::Real, trW::Real) --> Int\n\nDetermine the integer rotation order of a 3D point group operation with a 3×3 matrix representation W (alternatively specified by its determinant detW and its trace trW).\n\nThe rotation order of\n\nProper rotations is positive.\nImproper (mirrors, inversion, roto-inversions) is negative.\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.uniquetol-Union{Tuple{AbstractArray{T}}, Tuple{T}} where T","page":"Internal API","title":"Crystalline.uniquetol","text":"uniquetol(a; kwargs)\n\nComputes approximate-equality unique with tolerance specifiable via keyword arguments kwargs in O(n²) runtime.\n\nCopied from https://github.com/JuliaLang/julia/issues/19147#issuecomment-256981994\n\n\n\n\n\n","category":"method"},{"location":"internal-api/#Crystalline.wyckbasis-Tuple{BandRepSet}","page":"Internal API","title":"Crystalline.wyckbasis","text":"wyckbasis(brs::BandRepSet) --> Vector{Vector{Int}}\n\nComputes the (band representation) basis for bands generated by localized orbitals placed at the Wyckoff positions. Any band representation that can be expanded on this basis with positive integer coefficients correspond to a trivial insulators (i.e. deformable to atomic limit). Conversely, bands that cannot are topological, either fragily (some negative coefficients) or strongly (fractional coefficients).\n\n\n\n\n\n","category":"method"},{"location":"api/#Public-API","page":"API","title":"Public API","text":"","category":"section"},{"location":"api/","page":"API","title":"API","text":"","category":"page"},{"location":"api/","page":"API","title":"API","text":"CurrentModule = Crystalline","category":"page"},{"location":"api/#Exported-types","page":"API","title":"Exported types","text":"","category":"section"},{"location":"api/","page":"API","title":"API","text":"Modules = [Crystalline]\nPrivate = false\nOrder = [:type]","category":"page"},{"location":"api/#Crystalline.BandRep","page":"API","title":"Crystalline.BandRep","text":"struct BandRep <: AbstractVector{Int64}\n\nwyckpos::String\nsitesym::String\nlabel::String\ndim::Int64\nspinful::Bool\nirvec::Vector{Int64}\nirlabs::Vector{String}\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.BandRepSet","page":"API","title":"Crystalline.BandRepSet","text":"struct BandRepSet <: AbstractVector{BandRep}\n\nsgnum::Int64\nbandreps::Vector{BandRep}\nkvs::Vector{<:KVec}\nklabs::Vector{String}\nirlabs::Vector{String}\nspinful::Bool\ntimereversal::Bool\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.CharacterTable","page":"API","title":"Crystalline.CharacterTable","text":"struct CharacterTable{D} <: Crystalline.AbstractCharacterTable\n\nops::Array{SymOperation{D}, 1} where D\nirlabs::Vector{String}\ntable::Matrix{ComplexF64}\ntag::String\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.Collection","page":"API","title":"Crystalline.Collection","text":"Collection{T} <: AbstractVector{T}\n\nA wrapper around a Vector{T}, that allows custom printing and dispatch rules of custom T (e.g., AbstractIrrep & NewBandRep).\n\nIn Crystalline, it is assumed that all elements of the wrapped vector are associated with the same space or point group. Accordingly, if T implements dim or num, either must return the same value for each element of the Collection (and is equal to dim(::Collection) and num(::Collection)).\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.CompositeBandRep","page":"API","title":"Crystalline.CompositeBandRep","text":"CompositeBandRep{D} <: AbstractSymmetryVector{D}\n\nA type representing a linear rational-coefficient combination of NewBandRep{D}s. \n\nAlthough the coefficients may be rational numbers in general, their superposition must correspond to integer-valued irrep multiplicities and band occupation numbers; in particular, if they do not, conversion to a SymmetryVector will error.\n\nSee also CompositeBandRep_from_indices for construction from a vector included indices into brs.\n\nFields\n\ncoefs::Vector{Rational{Int}}: a coefficient vector associated with each band representation in brs; the coefficient of the ith band representation brs[i] is coefs[i].\nbrs::Collection{NewBandRep{D}}: the band representations referenced by coefs.\n\nExample\n\nFragile symmetry vector\n\nAs a first example, we build a CompositeBandRep representing a fragilely topological configuration (i.e., featuring negative integer coefficients):\n\njulia> brs = calc_bandreps(2);\n\njulia> coefs = [0, 0, 1, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, -1];\n\njulia> cbr = CompositeBandRep(coefs, brs)\n16-irrep CompositeBandRep{3}:\n (1g|Ag) + (1f|Aᵤ) + (1e|Ag) - (1a|Aᵤ) (2 bands)\n\nWe can build the associated SymmetryVector to inspect the associated irrep content:\n\njulia> SymmetryVector(cbr)\n [2Z₁⁺, 2Y₁⁻, 2U₁⁻, 2X₁⁺, 2T₁⁺, 2Γ₁⁺, 2V₁⁺, 2R₁⁺] (2 bands)\n\nSimilarly, we can confirm that cbr is indeed a simple linear combination of the associated band representations:\n\njulia> sum(c * brs[i] for (i, c) in enumerate(coefs)) == cbr\ntrue\n\nAnd we can even do simple arithmetic with cbr (a CompositeBandRep is an element of a monoid:\n\njulia> cbr + 2cbr\n3(1g|Ag) + 3(1f|Aᵤ) + 3(1e|Ag) - 3(1a|Aᵤ) (6 bands)\n\nNontrivial symmetry vector\n\nThe coefficients of a CompositeBandRep can be non-integer, provided the associated irrep multiplicities of the overall summation are integer. Accordingly, a CompositeBandRep may also be used to represent a topologically nontrivial symmetry vector (and, by extension, any physical symmetry vector):\n\njulia> coefs = [-1//4, 0, -1//4, 0, -1//4, 0, 1//4, 0, 1//4, 0, 1//4, 0, -1//4, 0, 1//4, 1];\n\njulia> cbr = CompositeBandRep{3}(coefs, brs)\n16-irrep CompositeBandRep{3}:\n -(1/4)×(1h|Ag) - (1/4)×(1g|Ag) - (1/4)×(1f|Ag) + (1/4)×(1e|Ag) + (1/4)×(1d|Ag) + (1/4)×(1c|Ag) - (1/4)×(1b|Ag) + (1/4)×(1a|Ag) + (1a|Aᵤ) (1 band)\n\njulia> SymmetryVector(cbr)\n16-irrep SymmetryVector{3}:\n [Z₁⁺, Y₁⁻, U₁⁻, X₁⁻, T₁⁻, Γ₁⁻, V₁⁻, R₁⁻] (1 band)\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.KVec-Union{Tuple{AbstractString}, Tuple{D}} where D","page":"API","title":"Crystalline.KVec","text":"KVec{D}(str::AbstractString) --> KVec{D}\nKVec(str::AbstractString) --> KVec\nKVec(::AbstractVector, ::AbstractMatrix) --> KVec\n\nReturn a KVec by parsing the string representations str, supplied in one of the following formats:\n\n\"($1,$2,$3)\"\n\"[$1,$2,$3]\"\n\"$1,$2,$3\"\n\nwhere the coordinates $1,$2, and $3 are strings that may contain fractions, decimal numbers, and \"free\" parameters {'α','β','γ'} (or, alternatively and equivalently, {'u','v','w'} or {'x','y','z'}).\n\nFractions such as 1/2 and decimal numbers can be parsed: but use of any other special operator besides / will produce undefined behavior (e.g. do not use *).\n\nExample\n\njulia> KVec(\"0.25,α,0\")\n[1/4, α, 0]\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.LGIrrep","page":"API","title":"Crystalline.LGIrrep","text":"struct LGIrrep{D} <: Crystalline.AbstractIrrep{D}\n\ncdml::String\ng::LittleGroup\nmatrices::Vector{Matrix{ComplexF64}}\ntranslations::Vector{Vector{Float64}}\nreality::Reality\niscorep::Bool\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.LittleGroup","page":"API","title":"Crystalline.LittleGroup","text":"struct LittleGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}\n\nnum::Int64\nkv::KVec\nklab::String\noperations::Array{SymOperation{D}, 1} where D\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.MSpaceGroup","page":"API","title":"Crystalline.MSpaceGroup","text":"struct MSpaceGroup{D} <: Crystalline.AbstractGroup{D, MSymOperation{D}}\n\nnum::Tuple{Int64, Int64}\noperations::Array{MSymOperation{D}, 1} where D\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.MSymOperation","page":"API","title":"Crystalline.MSymOperation","text":"struct MSymOperation{D} <: Crystalline.AbstractOperation{D}\n\nop::SymOperation\ntr::Bool\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.ModulatedFourierLattice","page":"API","title":"Crystalline.ModulatedFourierLattice","text":"ModulatedFourierLattice{D} <: AbstractFourierLattice{D}\n\nA D-dimensional concrete Fourier (plane wave) lattice, derived from a UnityFourierLattice{D} by scaling and modulating its orbit coefficients by complex numbers; in general, the coefficients do not have unit norm.\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.MultTable","page":"API","title":"Crystalline.MultTable","text":"struct MultTable{O} <: AbstractArray{O, 2}\n\noperations::Vector\ntable::Matrix{Int64}\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.MultTable-Tuple{Any}","page":"API","title":"Crystalline.MultTable","text":"MultTable(ops::AbstractVector, modτ=true)\n\nCompute the multiplication (or Cayley) table of ops, an iterable of SymOperations.\n\nA MultTable is returned, which contains symmetry operations resulting from composition of row and col operators; the table of indices give the symmetry operators relative to the ordering of ops.\n\nKeyword arguments\n\nmodτ (default: true): whether composition of operations is taken modulo lattice\n\nvectors (true) or not (false).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.PGIrrep","page":"API","title":"Crystalline.PGIrrep","text":"struct PGIrrep{D} <: Crystalline.AbstractIrrep{D}\n\ncdml::String\ng::PointGroup\nmatrices::Vector{Matrix{ComplexF64}}\nreality::Reality\niscorep::Bool\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.PointGroup","page":"API","title":"Crystalline.PointGroup","text":"struct PointGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}\n\nnum::Int64\nlabel::String\noperations::Array{SymOperation{D}, 1} where D\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.RVec-Union{Tuple{AbstractString}, Tuple{D}} where D","page":"API","title":"Crystalline.RVec","text":"RVec{D}(str::AbstractString) --> RVec{D}\nRVec(str::AbstractString) --> RVec\nRVec(::AbstractVector, ::AbstractMatrix) --> RVec\n\nReturn a RVec by parsing the string representations str, supplied in one of the following formats:\n\n\"($1,$2,$3)\"\n\"[$1,$2,$3]\"\n\"$1,$2,$3\"\n\nwhere the coordinates $1,$2, and $3 are strings that may contain fractions, decimal numbers, and \"free\" parameters {'α','β','γ'} (or, alternatively and equivalently, {'u','v','w'} or {'x','y','z'}).\n\nFractions such as 1/2 and decimal numbers can be parsed: but use of any other special operator besides / will produce undefined behavior (e.g. do not use *).\n\nExample\n\njulia> RVec(\"0.25,α,0\")\n[1/4, α, 0]\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.Reality","page":"API","title":"Crystalline.Reality","text":"Reality <: Enum{Int8}\n\nEnum type with instances\n\nREAL = 1\nPSEUDOREAL = -1\nCOMPLEX = 0\n\nThe return value of reality(::AbstractIrrep) and calc_reality is an instance of Reality. The reality type of an irrep is relevant for constructing \"physically real\" irreps (co-reps) via realify.\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.SiteGroup","page":"API","title":"Crystalline.SiteGroup","text":"struct SiteGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}\n\nnum::Int64\nwp::WyckoffPosition\noperations::Array{SymOperation{D}, 1} where D\ncosets::Array{SymOperation{D}, 1} where D\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.SiteIrrep","page":"API","title":"Crystalline.SiteIrrep","text":"struct SiteIrrep{D} <: Crystalline.AbstractIrrep{D}\n\ncdml::String\ng::SiteGroup\nmatrices::Vector{Matrix{ComplexF64}}\nreality::Reality\niscorep::Bool\npglabel::String\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.SpaceGroup","page":"API","title":"Crystalline.SpaceGroup","text":"struct SpaceGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}\n\nnum::Int64\noperations::Array{SymOperation{D}, 1} where D\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.SubperiodicGroup","page":"API","title":"Crystalline.SubperiodicGroup","text":"struct SubperiodicGroup{D, P} <: Crystalline.AbstractGroup{D, SymOperation{D}}\n\nnum::Int64\noperations::Array{SymOperation{D}, 1} where D\n\nA subperiodic group of embedding dimension D and periodicity dimension P. \n\nFields: \n\noperations: the SymOperations of the finite factor group GT, where G is the\n\nsubperiodic group and T is the translation group of the associated lattice.\n\nnum: the canonical number of the group, following the International Tables for\n\nCrystallography, Volume E.\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.SymOperation","page":"API","title":"Crystalline.SymOperation","text":"struct SymOperation{D} <: Crystalline.AbstractOperation{D}\n\nrotation::Crystalline.SquareStaticMatrices.SqSMatrix{D, Float64} where D\ntranslation::StaticArraysCore.SVector{D, Float64} where D\n\n\n\n\n\n","category":"type"},{"location":"api/#Crystalline.SymmetryVector-Tuple{Crystalline.AbstractSymmetryVector}","page":"API","title":"Crystalline.SymmetryVector","text":"SymmetryVector(n::AbstractSymmetryVector) -> SymmetryVector\n\nReturn a SymmetryVector realization of n. If n is already a SymmetryVector, return n directly; usually, the returned value will directly reference information in n (i.e., will not be a copy).\n\n\n\n\n\n","category":"method"},{"location":"api/#Exported-methods","page":"API","title":"Exported methods","text":"","category":"section"},{"location":"api/","page":"API","title":"API","text":"Modules = [Crystalline]\nPrivate = false\nOrder = [:function]","category":"page"},{"location":"api/#Base.inv-Tuple{T} where T<:SymOperation","page":"API","title":"Base.inv","text":"inv(op::SymOperation{D}) --> SymOperation{D}\n\nCompute the inverse {W|w}⁻¹ ≡ {W⁻¹|-W⁻¹w} of an operator op ≡ {W|w}.\n\n\n\n\n\n","category":"method"},{"location":"api/#Base.isapprox-Union{Tuple{T}, Tuple{D}, Tuple{T, T}, Tuple{T, T, Union{Nothing, Char, AbstractMatrix{<:Real}}}, Tuple{T, T, Union{Nothing, Char, AbstractMatrix{<:Real}}, Bool}} where {D, T<:Crystalline.AbstractVec{D}}","page":"API","title":"Base.isapprox","text":"isapprox(v1::T, v2::T, \n [cntr::Union{Char, Nothing, AbstractMatrix{<:Real}}, modw::Bool];\n kwargs...) --> Bool\n\nCompute approximate equality of two vector quantities v1 and v2 of type, T = Union{<:AbstractVec, <:AbstractPoint}. \n\nIf modw = true, equivalence is considered modulo lattice vectors. If v1 and v2 are in the conventional setting of a non-primitive lattice, the centering type cntr (see Bravais.centering) should be given to ensure that the relevant (primitive) lattice vectors are used in the comparison.\n\nOptional arguments\n\ncntr: if not provided, the comparison will not account for equivalence by primitive lattice vectors (equivalent to setting cntr=nothing), only equivalence by lattice vectors in the basis of v1 and v2. cntr may also be provided as a D×D AbstractMatrix to give the relevant transformation matrix directly.\nmodw: whether vectors that differ by multiples of a lattice vector are considered equivalent.\nkwargs...: optional keyword arguments (e.g., atol and rtol) to be forwarded to Base.isapprox.\n\n\n\n\n\n","category":"method"},{"location":"api/#Base.position-Tuple{Crystalline.AbstractGroup}","page":"API","title":"Base.position","text":"position(x::Union{AbstractGroup, AbstractIrrep})\n\nIf a position is associated with x, return it; if no position is associated, return nothing.\n\nApplicable cases include LittleGroup (return the associated k-vector) and SiteGroup (returns the associated Wyckoff position), as well as their associated irrep types (LGIrrep and SiteIrrep).\n\n\n\n\n\n","category":"method"},{"location":"api/#Bravais.cartesianize-Union{Tuple{D}, Tuple{SymOperation{D}, DirectBasis{D}}} where D","page":"API","title":"Bravais.cartesianize","text":"cartesianize(op::SymOperation{D}, Rs::DirectBasis{D}) --> SymOperation{D}\n\nConverts opˡ from a lattice basis to a Cartesian basis, by computing the transformed operators opᶜ = 𝐑*opˡ*𝐑⁻¹ via the Cartesian basis matrix 𝐑 (whose columns are the DirectBasis vectors Rs[i]). \n\nNote 1\n\nThe matrix 𝐑 maps vectors coefficients in a lattice basis 𝐯ˡ to coefficients in a Cartesian basis 𝐯ᶜ as 𝐯ˡ = 𝐑⁻¹𝐯ᶜ and vice versa as 𝐯ᶜ = 𝐑𝐯ˡ. Since a general transformation P transforms an \"original\" vectors with coefficients 𝐯 to new coefficients 𝐯′ via 𝐯′ = P⁻¹𝐯 and since we here here consider the lattice basis as the \"original\" basis we have P = 𝐑⁻¹. As such, the transformation of the operator op transforms as opᶜ = P⁻¹*opˡ*P, i.e. opᶜ = transform(opˡ,P) = transform(opˡ,𝐑⁻¹).\n\nNote 2\n\nThe display (e.g. Seitz and xyzt notation) of SymOperations e.g. in the REPL implicitly assumes integer coefficients for its point-group matrix: as a consequence, displaying SymOperations in a Cartesian basis may produce undefined behavior. The matrix representation remains valid, however.\n\n\n\n\n\n","category":"method"},{"location":"api/#Bravais.centering-Union{Tuple{Union{LittleGroup{D}, SpaceGroup{D}}}, Tuple{D}} where D","page":"API","title":"Bravais.centering","text":"centering(g::AbstractGroup) --> Char\n\nReturn the conventional centering type of a group. \n\nFor groups without lattice structure (e.g., point groups), return nothing.\n\n\n\n\n\n","category":"method"},{"location":"api/#Bravais.conventionalize-Union{Tuple{D}, Tuple{Crystalline.AbstractFourierLattice{D}, Char}} where D","page":"API","title":"Bravais.conventionalize","text":"conventionalize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat′)\n\nGiven flat referred to a primitive basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated conventional basis. \n\nSee also the complementary method primitivize(::AbstractFourierLattice, ::Char) for additional details.\n\n\n\n\n\n","category":"method"},{"location":"api/#Bravais.conventionalize-Union{Tuple{D}, Tuple{Crystalline.AbstractVec{D}, Char}} where D","page":"API","title":"Bravais.conventionalize","text":"conventionalize(v′::AbstractVec, cntr::Char) --> v::typeof(v′)\n\nTransforms a primitive coordinate vector v′ back to a standard conventional basis (specified by the centering type cntr), returning the conventional coordinate vector v.\n\nSee also primitivize and transform.\n\n\n\n\n\n","category":"method"},{"location":"api/#Bravais.conventionalize-Union{Tuple{D}, Tuple{SymOperation{D}, Char}, Tuple{SymOperation{D}, Char, Bool}} where D","page":"API","title":"Bravais.conventionalize","text":"conventionalize(op′::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)\n\nReturn a symmetry operation op = Ww in a conventional setting, transformed from an input symmetry operation op′ Ww in a primitive setting.\n\nSee primitivize(::SymOperation, ::Char, ::Bool) for description of the centering argument cntr and optional argument modw.\n\n\n\n\n\n","category":"method"},{"location":"api/#Bravais.primitivize-Union{Tuple{D}, Tuple{Crystalline.AbstractFourierLattice{D}, Char}} where D","page":"API","title":"Bravais.primitivize","text":"primitivize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat)\n\nGiven flat referred to a conventional basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated primitive basis. \n\nSpecifically, if flat refers to a direct conventional basis Rs (mathbfa mathbfb mathbfc) [with coordinate vectors mathbfr (r_1 r_2 r_3)^mathrmT] then flat′ refers to a direct primitive basis Rs′ (mathbfa mathbfb mathbfc) (mathbfa mathbfb mathbfc)mathbfP [with coordinate vectors mathbfr (r_1 r_2 r_3)^mathrmT = mathbfP^-1mathbfr], where mathbfP denotes the basis-change matrix obtained from primitivebasismatrix(...).\n\nTo compute the associated primitive basis vectors, see primitivize(::DirectBasis, ::Char) [specifically, Rs′ = primitivize(Rs, cntr)].\n\nExamples\n\nA centered ('c') lattice from plane group 5 in 2D, plotted in its conventional and primitive basis (requires using PyPlot):\n\njulia> sgnum = 5; D = 2; cntr = centering(sgnum, D) # 'c' (body-centered)\n\njulia> Rs = directbasis(sgnum, Val(D)) # conventional basis (rectangular)\njulia> flat = levelsetlattice(sgnum, Val(D)) # Fourier lattice in basis of Rs\njulia> flat = modulate(flat) # modulate the lattice coefficients\njulia> plot(flat, Rs)\n\njulia> Rs′ = primitivize(Rs, cntr) # primitive basis (oblique)\njulia> flat′ = primitivize(flat, cntr) # Fourier lattice in basis of Rs′\n\njulia> using PyPlot\njulia> plot(flat′, Rs′)\n\n\n\n\n\n","category":"method"},{"location":"api/#Bravais.primitivize-Union{Tuple{D}, Tuple{Crystalline.AbstractVec{D}, Char}} where D","page":"API","title":"Bravais.primitivize","text":"primitivize(v::AbstractVec, cntr::Char) --> v′::typeof(v)\n\nTransforms a conventional coordinate vector v to a standard primitive basis (specified by the centering type cntr), returning the primitive coordinate vector v′.\n\nNote that a basis change matrix mathbfP (as returned e.g. by Bravais.primitivebasismatrix) transforms direct coordinate vectors (RVec) as mathbfr = mathbfP^-1mathbfr but transforms reciprocal coordinates (KVec) as mathbfk = mathbfP^textTmathbfk [ITA6]. Recall also the distinction between transforming a basis and the coordinates of a vector.\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th edition (2016): Secs. 1.5.1.2 and 1.5.2.1.\n\n\n\n\n\n","category":"method"},{"location":"api/#Bravais.primitivize-Union{Tuple{D}, Tuple{SymOperation{D}, Char}, Tuple{SymOperation{D}, Char, Bool}} where D","page":"API","title":"Bravais.primitivize","text":"primitivize(op::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)\n\nReturn a symmetry operation op′ Ww in a primitive setting, transformed from an input symmetry operation op = Ww in a conventional setting. The operations Ww and Ww are related by a transformation Pp via (cf. Section 1.5.2.3 of [ITA6]):\n\nWw = Pp¹WwPp\n\nwhere P and p are the basis change matrix and origin shifts, respectively. The relevant transformation Pp is inferred from the centering type, as provided by cntr (see also Bravais.centering).\n\nBy default, translation parts of op′, i.e. w are reduced modulo 1 (modw = true); to disable this, set modw = false.\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016).\n\n\n\n\n\n","category":"method"},{"location":"api/#Bravais.transform-Tuple{Crystalline.AbstractVec, AbstractMatrix{<:Real}}","page":"API","title":"Bravais.transform","text":"transform(v::AbstractVec, P::AbstractMatrix) --> v′::typeof(v)\n\nReturn a transformed coordinate vector v′ from an original coordinate vector v using a basis change matrix P.\n\nNote that a basis change matrix mathbfP transforms direct coordinate vectors (RVec) as mathbfr = mathbfP^-1mathbfr but transforms reciprocal coordinates (KVec) as mathbfk = mathbfP^mathrmTmathbfk [ITA6]\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th edition (2016): Secs. 1.5.1.2 and 1.5.2.1.\n\n\n\n\n\n","category":"method"},{"location":"api/#Bravais.transform-Union{Tuple{D}, Tuple{SymOperation{D}, AbstractMatrix{<:Real}}, Tuple{SymOperation{D}, AbstractMatrix{<:Real}, Union{Nothing, AbstractVector{<:Real}}}, Tuple{SymOperation{D}, AbstractMatrix{<:Real}, Union{Nothing, AbstractVector{<:Real}}, Bool}} where D","page":"API","title":"Bravais.transform","text":"transform(op::SymOperation, P::AbstractMatrix{<:Real}, \n p::Union{AbstractVector{<:Real}, Nothing}=nothing,\n modw::Bool=true) --> SymOperation\n\nTransforms a op = mathbfWmathbfw by a rotation matrix P and a translation vector p (can be nothing for zero-translations), producing a new symmetry operation op′ = mathbfWmathbfw (cf. Section 1.5.2.3 of [ITA6])\n\nmathbfWmathbfw = mathbfPmathbfp^-1mathbfWmathbfw\nmathbfPmathbfp\n\nwith\n\nmathbfW = mathbfP^-1mathbfWmathbfP\ntext and \nmathbfw = mathbfP^-1(mathbfw+mathbfWmathbfp-mathbfp)\n\nBy default, the translation part of op′, i.e. mathbfw, is reduced to the range 01), i.e. computed modulo 1. This can be disabled by setting modw = false (default, modw = true).\n\nSee also Bravais.primitivize(::SymOperation, ::Char, ::Bool) and Bravais.conventionalize(::SymOperation, ::Char, ::Bool).\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.:⊕-Union{Tuple{T}, Tuple{T, T, Vararg{T}}} where T<:Crystalline.AbstractIrrep","page":"API","title":"Crystalline.:⊕","text":"⊕(ir1::T, ir2::T, ir3::T...) where T<:AbstractIrrep --> T\n\nCompute the representation obtained from direct sum of the irreps ir1, ir2, ir3, etc. The resulting representation is reducible and has dimension irdim(ir1) + irdim(ir2) + irdim(ir3) + ….\n\nThe groups of the provided irreps must be identical. If T isa LGIrrep, the irrep translation factors must also be identical (due to an implementation detail of the LGIrrep type).\n\nAlso provided via Base.:+.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.bandreps","page":"API","title":"Crystalline.bandreps","text":"bandreps(sgnum::Integer, D::Integer=3; \n allpaths::Bool=false, spinful::Bool=false, timereversal::Bool=true)\n\nReturns the elementary band representations (EBRs) as a BandRepSet for space group sgnum and dimension D.\n\nKeyword arguments\n\nallpaths: include a minimal sufficient set (false, default) or all (true) k-vectors. \nspinful: single- (false, default) or double-valued (true) irreps, as appropriate for spinless and spinful particles, respectively. Only available for D=3.\ntimereversal: assume presence (true, default) or absence (false) of time-reversal symmetry.\n\nReferences\n\n3D EBRs are obtained from the Bilbao Crystallographic Server's BANDREP program; please reference the original research papers noted there if used in published work.\n\n\n\n\n\n","category":"function"},{"location":"api/#Crystalline.basisdim-Tuple{BandRepSet}","page":"API","title":"Crystalline.basisdim","text":"basisdim(brs::BandRepSet) --> Int\n\nReturn the dimension of the (linearly independent parts) of a band representation set. This is d^textbs = d^textai in the notation of Po, Watanabe, & Vishwanath, Nature Commun. 8, 50 (2017), or equivalently, the rank of stack(brs) over the ring of integers. This is the number of linearly independent basis vectors that span the expansions of a band structure viewed as symmetry data.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.calc_bandreps-Union{Tuple{Integer}, Tuple{D}, Tuple{Integer, Val{D}}} where D","page":"API","title":"Crystalline.calc_bandreps","text":"calc_bandreps(sgnum::Integer, Dᵛ::Val{D}=Val(3);\n timereversal::Bool=true,\n allpaths::Bool=false)\n\nCompute the band representations of space group sgnum in dimension D, returning a BandRepSet.\n\nKeyword arguments\n\ntimereversal (default, true): whether the irreps used to induce the band representations are assumed to be time-reversal invariant (i.e., are coreps, see realify).\nallpaths (default, false): whether the band representations are projected to all distinct k-points returned by lgirreps (allpaths = false), including high-symmetry k-lines and -plane, or only to the maximal k-points (allpaths = true), i.e., just to high-symmetry points.\n\nNotes\n\nAll band representations associated with maximal Wyckoff positions are returned, irregardless of whether they are elementary (i.e., no regard is made to whether the band representation is \"composite\"). As such, the returned band representations generally are a superset of the set of elementary band representations (and so contain all elementary band representations).\n\nImplementation\n\nThe implementation is based on Cano, Bradlyn, Wang, Elcoro, et al., Phys. Rev. B 97, 035139 (2018), Sections II.C-D.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.calc_reality-Union{Tuple{D}, Tuple{LGIrrep{D}, AbstractArray{SymOperation{D}, 1}}, Tuple{LGIrrep{D}, AbstractArray{SymOperation{D}, 1}, Union{Nothing, Vector{<:Real}}}} where D","page":"API","title":"Crystalline.calc_reality","text":"calc_reality(lgir::LGIrrep, \n sgops::AbstractVector{SymOperation{D}},\n αβγ::Union{Vector{<:Real},Nothing}=nothing) --> ::(Enum Reality)\n\nCompute and return the reality of a lgir::LGIrrep using the Herring criterion.\n\nThe computed value is one of three integers in 1-10. In practice, this value is returned via a member of the Enum Reality, which has instances REAL = 1, PSEUDOREAL = -1, and COMPLEX = 0.\n\nOptional arguments\n\nAs a sanity check, a value of αβγ can be provided to check for invariance along a symmetry symmetry line/plane/general point in k-space. The reality must be invariant to this choice.\n\nNote\n\nThe provided space group operations sgops must be the set reduced by primitive translation vectors; i.e. using spacegroup(...) directly is not allowable in general (since the irreps we reference only include these \"reduced\" operations). This reduced set of operations can be obtained e.g. from the Γ point irreps of ISOTROPY's dataset, or alternatively, from reduce_ops(spacegroup(...), true).\n\nImplementation\n\nThe Herring criterion evaluates the following sum\n\n χ(βb²)g_0M(k)\n\nover symmetry operations βb that take k -k. Here g_0 is the order of the point group of the space group and M(k) is the order of star(k) [both in a primitive basis].\n\nSee e.g. Cornwell, p. 150-152 & 187-188 (which we mainly followed), Inui Eq. (13.48), Dresselhaus, p. 618, or Herring's original paper.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.characters-Union{Tuple{AbstractVector{<:Crystalline.AbstractIrrep{D}}}, Tuple{D}, Tuple{AbstractVector{<:Crystalline.AbstractIrrep{D}}, Union{Nothing, AbstractVector{<:Real}}}} where D","page":"API","title":"Crystalline.characters","text":"characters(irs::AbstractVector{<:AbstractIrrep}, αβγ=nothing)\n\nCompute the character table associated with vector of AbstractIrreps irs, returning a CharacterTable.\n\nOptional arguments\n\nOptionally, an αβγ::AbstractVector{<:Real} variable can be passed to evaluate the irrep (and associated characters) with concrete free parameters (e.g., for LGIrreps, a concrete k-vector sampled from a \"line-irrep\"). Defaults to nothing, indicating it being either irrelevant (e.g., for PGIrreps) or all free parameters implicitly set to zero.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.classcharacters-Union{Tuple{AbstractVector{<:Crystalline.AbstractIrrep{D}}}, Tuple{D}, Tuple{AbstractVector{<:Crystalline.AbstractIrrep{D}}, Union{Nothing, AbstractVector{<:Real}}}} where D","page":"API","title":"Crystalline.classcharacters","text":"classcharacters(irs::AbstractVector{<:AbstractIrrep}, αβγ=nothing)\n\nCompute the character table associated with the conjugacy classes of a vector of AbstractIrreps irs, returning a ClassCharacterTable.\n\nSince characters depend only on the conjugacy class (this is not true for ray, or projective, irreps), the class-specific characters often more succintly communicate the same information as the characters for each operation (as returned by characters).\n\nSee also: classes.\n\nOptional arguments\n\nOptionally, an αβγ::AbstractVector{<:Real} variable can be passed to evaluate the irrep (and associated characters) with concrete free parameters (e.g., for LGIrreps, a concrete k-vector sampled from a \"line-irrep\"). Defaults to nothing, indicating it being either irrelevant (e.g., for PGIrreps) or all free parameters implicitly set to zero.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.classes-Union{Tuple{AbstractArray{SymOperation{D}, 1}}, Tuple{D}, Tuple{AbstractArray{SymOperation{D}, 1}, Union{Nothing, Char}}, Tuple{AbstractArray{SymOperation{D}, 1}, Union{Nothing, Char}, Bool}} where D","page":"API","title":"Crystalline.classes","text":"classes(ops::AbstractVector{SymOperation{D}}, [cntr::Union{Char, Nothing}])\n --> Vector{Vector{SymOperation{D}}}\n\nReturn the conjugacy classes of a group G defined by symmetry operations ops.\n\nDefinitions\n\nTwo elements a and b in G are considered conjugate if there exists a g G such that gag^-1 = b. This defines an equivalence relation sim, i.e., we say that a sim b if a and b are conjugate. The conjugacy classes of G are the distinct equivalence classes that can be identified under this equivalence relation, i.e. the grouping of G into subsets that are equivalent under conjugacy.\n\nExtended help\n\nIf ops describe operations in a crystal system that is not primitive (i.e., if its centering type is not p or P) but is presented in a conventional setting, the centering symbol cntr must be given. If ops is not in a centered crystal system, or if ops is already reduced to a primitive setting, cntr should be given as nothing (default behavior) or, alternatively, as P or p (depending on dimensionality).\n\nA single-argument calls to classes with SpaceGroup or LittleGroup types will assume that ops is provided in a conventional setting, i.e., will forward the method call to classes(ops, centering(ops, dim(ops))). To avoid this behavior (if ops was already reduced to a primitive setting prior to calling classes), cntr should be provided explicitly as nothing.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.classification-Tuple{AbstractVector{<:Integer}}","page":"API","title":"Crystalline.classification","text":"classification(brs_or_F::Union{BandRepSet, Smith}) --> String\n\nReturn the symmetry indicator group X^textBS of an EBR basis F_or_brs, provided as a BandRepSet or Smith decomposition.\n\nTechnically, the calculation answers the question \"what direct product of mathbbZ_n groups is the the quotient group X^textBS = textBStextAI isomorphic to?\" (see Po, Watanabe, & Vishwanath, Nature Commun. 8, 50 (2017) for more information).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.compose-Union{Tuple{D}, Tuple{SymOperation{D}, KVec{D}}, Tuple{SymOperation{D}, KVec{D}, Bool}} where D","page":"API","title":"Crystalline.compose","text":"compose(op::SymOperation, kv::KVec[, checkabc::Bool=true]) --> KVec\n\nReturn the composition op = mathbfWmathbfw and a reciprocal-space vector kv = mathbfk.\n\nThe operation is assumed to be specified the direct lattice basis, and kv in the reciprocal lattice basis. If both were specified in the Cartesian basis, op would act directly via its rotation part. However, because of the different bases, it now acts as:\n\n mathbfk = (mathbfW^textT)^-1mathbfk\n\nNote the transposition and inverse of mathbfW, arising as a result of the implicit real-space basis of mathbfWmathbfw versus the reciprocal-space basis of mathbfk. Note also that the composition of mathbfWmathbfw with mathbfk is invariant under mathbfw, i.e., translations do not act in reciprocal space.\n\nExtended help\n\nIf checkabc = false, the free part of KVec is not transformed (can be improve performance in situations when kabc is zero, and several transformations are requested).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.compose-Union{Tuple{D}, Tuple{SymOperation{D}, RVec{D}}} where D","page":"API","title":"Crystalline.compose","text":"compose(op::SymOperation, rv::RVec) --> RVec\n\nReturn the composition of op = mathbfWmathbfw and a real-space vector rv = mathbfr.\n\nThe operation is taken to act directly, returning\n\n mathbfr = mathbfWmathbfwmathbfr = mathbfWmathbfr + mathbfw\n\nThe corresponding inverse action mathbfWmathbfw^-1mathbfr = mathbfW^-1mathbfr - mathbfW^-1mathbfw can be obtained via compose(inv(op), rv).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.compose-Union{Tuple{T}, Tuple{T, T}, Tuple{T, T, Bool}} where T<:SymOperation","page":"API","title":"Crystalline.compose","text":"compose(op1::T, op2::T, modτ::Bool=true) where T<:SymOperation\n\nCompose two symmetry operations op1 = W₁w₁ and op2 = W₂w₂ using the composition rule (in Seitz notation)\n\nW₁w₁W₂w₂ = W₁W₂w₁+W₁w₂\n\nBy default, the translation part of the W₁W₂w₁+W₁w₂ is reduced to the range 01, i.e. computed modulo 1. This can be toggled off (or on) by the Boolean flag modτ (enabled, i.e. true, by default). Returns another SymOperation.\n\nThe multiplication operator * is overloaded for SymOperations to call compose, in the manner op1 * op2 = compose(op1, op2, modτ=true).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.conjugacy_relations-Union{Tuple{D}, Tuple{Crystalline.GroupRelationGraph{D}, Integer, Integer}} where D","page":"API","title":"Crystalline.conjugacy_relations","text":"conjugacy_relations(gr::GroupRelationGraph, sgnumᴳ, sgnumᴴ) --> Vector{<:ConjugacyTransform}\n\nGiven a graph gr representing a sub- or supergroup relation, return the possible transformations that make up the conjugacy classes between the groups sgnumᴳ and sgnumᴴ.\n\nThe returned transforms bring G into the setting of H via transform(G, P, p), where P and p denote one of the possible conjugacy transforms in the returned vector. Note that the transforms need not preserve volume: accordingly, some operations may be redundant after transformation (use reduce_ops or unique! to remove these).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.cosets-Tuple{SiteGroup}","page":"API","title":"Crystalline.cosets","text":"cosets(g::SiteGroup) -> Array{SymOperation{D}, 1} where D\n\n\nReturn the left coset representatives of a SiteGroup g (in its parent space group).\n\nThe cosets generate the orbit of the Wyckoff position position(g) (see also orbit(::SiteGroup)) and furnish a left-coset decomposition of the underlying space group, jointly with the operations in g itself.\n\nSee also cosets(::AbstractVector, ::AbstractVector). This method is equivalent (but may return different representatives in general) to cosets(spacegroup(sgnum), g).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.cosets-Union{Tuple{T}, Tuple{AbstractVector{T}, AbstractVector{T}}} where T<:Crystalline.AbstractOperation","page":"API","title":"Crystalline.cosets","text":"cosets(G, H)\n\nFor a subgroup H =H of G = G, find a set of (left) coset representatives g_i of H in G, such that (see e.g., Inui et al., Section 2.7)\n\n G = bigcup_i g_i H\n\nThe identity operation 1 is always included in g_i.\n\nExample\n\njulia> G = pointgroup(\"6mm\");\n\njulia> H = pointgroup(\"3\");\n\njulia> Q = cosets(G, H)\n4-element Vector{SymOperation{3}}:\n 1\n 2₀₀₁\n m₁₁₀\n m₋₁₁₀\n\nTo generate the associated cosets, simply compose the representatives with H:\n\njulia> [compose.(Ref(q), H) for q in Q]\n4-element Vector{Vector{SymOperation{3}}}:\n [1, 3₀₀₁⁺, 3₀₀₁⁻]\n [2₀₀₁, 6₀₀₁⁻, 6₀₀₁⁺]\n [m₁₁₀, m₁₀₀, m₀₁₀]\n [m₋₁₁₀, m₁₂₀, m₂₁₀]\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.dim-Tuple{BandRep}","page":"API","title":"Crystalline.dim","text":"dim(BR::BandRep) --> Int\n\nReturn the number of bands included in the provided BandRep.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.dim-Union{Tuple{Crystalline.AbstractGroup{D}}, Tuple{D}} where D","page":"API","title":"Crystalline.dim","text":"dim(g::AbstractGroup) -> Int\n\nReturn the dimensionality of the coordinate space of the group g. This is a statically known number, either equaling 1, 2, or 3.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.find_isomorphic_parent_pointgroup-Union{Tuple{AbstractArray{SymOperation{D}, 1}}, Tuple{D}} where D","page":"API","title":"Crystalline.find_isomorphic_parent_pointgroup","text":"find_isomorphic_parent_pointgroup(g::AbstractVector{SymOperation{D}}) \n --> PointGroup{D}, Vector{Int}, Bool\n\nGiven a group g (or a collection of operators, defining a group), identifies a \"parent\" point group that is isomorphic to g.\n\nThree variables are returned:\n\npg: the identified \"parent\" point group, with operators sorted to match the sorting of g's operators.\nIᵖ²ᵍ: a permutation vector which transforms the standard sorting of point group operations (as returned by pointgroup(::String)) to the operator sorting of g.\nequal: a boolean, identifying whether the point group parts of g operations are identical (true) or merely isomorphic to the point group operations in g. In practice, this indicates whether pg and g are in the same setting or not.\n\nImplementation\n\nThe identification is made partly on the basis of comparison of operators (this is is sufficient for the equal = true case) and partly on the basis of comparison of multiplication tables (equal = false case); the latter can be combinatorially slow if the sorting of operators is unlucky (i.e., if permutation between sortings in g and pg differ by many pairwise permutations).\n\nBeyond mere isomorphisms of multiplication tables, the search also guarantees that all rotation orders are shared between pg and g; similarly, the rotation senses (e.g., 4⁺ & 4⁻ have opposite rotation senses or directions) are shared. This disambiguates point groups that are intrinsically isomorphic to eachother, e.g. \"m\" and \"-1\", but which still differ in their spatial interpretation.\n\nProperties\n\nThe following properties hold for g, pg, and Iᵖ²ᵍ:\n\npg, Iᵖ²ᵍ, equal = find_isomorphic_parent_pointgroup(g)\n@assert MultTable(pg) == MultTable(pointgroup(g))\npg′ = pointgroup(label(pg), dim(pg)) # \"standard\" sorting\n@assert pg′[Iᵖ²ᵍ] == pg\n\nIf equal = true, the following also holds:\n\npointgroup(g) == operations(pg) == operations(pg′)[Iᵖ²ᵍ]\n\nExample\n\nsgnum = 141\nwp = wyckoffs(sgnum, Val(3))[end] # 4a Wyckoff position\nsg = spacegroup(sgnum, Val(3))\nsiteg = sitegroup(sg, wp)\npg, Iᵖ²ᵍ, equal = find_isomorphic_parent_pointgroup(siteg)\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.find_representation","page":"API","title":"Crystalline.find_representation","text":"find_representation(symvals::AbstractVector{Number}, \n lgirs::AbstractVector{<:AbstractIrrep},\n αβγ::Union{AbstractVector{<:Real},Nothing}=nothing,\n assert_return_T::Type{<:Union{Integer, AbstractFloat}}=Int),\n atol::Real=DEFAULT_ATOL,\n maxresnorm::Real=1e-3,\n verbose::Bool=false)\n\n --> Vector{assert_return_T}\n\nFrom a vector (or vector of vectors) of symmetry eigenvalues symvals sampled along all the operations of a group gᵢ, whose irreps are contained in irs (evaluated with optional free parameters αβγ), return the multiplicities of each irrep.\n\nOptionally, the multiciplities' element type can be specified via the assert_return_T argument (performing checked conversion; returns nothing if representation in assert_return_T is impossible). This can be useful if one suspects a particular band to transform like a fraction of an irrep (i.e., the specified symmetry data is incomplete).\n\nIf no valid set of multiplicities exist (i.e., is solvable, and has real-valued and assert_return_T representible type), the sentinel value nothing is returned. Optional debugging information can in this case be shown by setting verbose=true.\n\nExtended help\n\nEffectively, this applies the projection operator P⁽ʲ⁾ of each irrep's character set χ⁽ʲ⁾(gᵢ) (j = 1, ... , Nⁱʳʳ) to the symmetry data sᵢ ≡ symvals:\n\nP⁽ʲ⁾ ≡ (dⱼ/|g|) ∑ᵢ χ⁽ʲ⁾(gᵢ)*gᵢ [characters χ⁽ʲ⁾(gᵢ), irrep dimension dⱼ]\nP⁽ʲ⁾s = (dⱼ/|g|) ∑ᵢ χ⁽ʲ⁾(gᵢ)*sᵢ = nⱼ, [number of bands that transform like jth irrep]\n\nreturning the irrep multiplicities mⱼ ≡ nⱼ/dⱼ.\n\n\n\n\n\n","category":"function"},{"location":"api/#Crystalline.findmaximal-Union{Tuple{AbstractArray{SiteGroup{D}, 1}}, Tuple{D}} where D","page":"API","title":"Crystalline.findmaximal","text":"findmaximal(sitegs::AbstractVector{<:SiteGroup})\n\nGiven an AbstractVector{<:SiteGroup} over the distinct Wyckoff positions of a space group, return those SiteGroups that are associated with a maximal Wyckoff positions.\n\nResults are returned as a view into the input vector (i.e. as an AbstractVector{<:SiteGroup}). The associated Wyckoff positions can be retrieved via position.\n\nDefinition\n\nA Wyckoff position is maximal if its site symmetry group has higher order than the site symmetry groups of any \"nearby\" Wyckoff positions (i.e. Wyckoff positions that can be connected, i.e. made equivalent, through parameter variation to the considered Wyckoff position).\n\nExample\n\njulia> sgnum = 5;\n\njulia> D = 2;\n\njulia> sg = spacegroup(sgnum, Val(D));\n\njulia> sitegs = sitegroups(sg)\n2-element Vector{SiteGroup{2}}:\n [1] (4b: [α, β])\n [1, m₁₀] (2a: [0, β])\n\njulia> only(findmaximal(sitegs))\nSiteGroup{2} ⋕5 (c1m1) at 2a = [0, β] with 2 operations:\n 1\n m₁₀\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.generate-Union{Tuple{AbstractArray{SymOperation{D}, 1}}, Tuple{D}} where D","page":"API","title":"Crystalline.generate","text":"generate(\n gens::AbstractArray{SymOperation{D}, 1};\n cntr,\n modτ,\n Nmax\n) -> Crystalline.GenericGroup\n\n\nReturn the group generated from a finite set of generators gens.\n\nKeyword arguments\n\ncntr (default, nothing): check equivalence of operations modulo primitive lattice vectors (see also isapprox(::SymOperation, ::SymOperation, cntr::Union{Nothing, Char}); only nonequivalent operations are included in the returned group.\nmodτ (default, true): the group composition operation can either be taken modulo lattice vectors (true) or not (false, useful e.g. for site symmetry groups). In this case, the provided generators will also be taken modulo integer lattice translations.\nNmax (default, 256): the maximum size of the generated group. This is essentially a cutoff set to ensure halting of execution in case the provided set of generators do not define a finite group (especially relevant if modτ=false). If more operations than Nmax are generated, the method throws an overflow error.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.generators-Union{Tuple{Integer}, Tuple{D}, Tuple{Integer, Type{SpaceGroup{D}}}} where D","page":"API","title":"Crystalline.generators","text":"generators(num::Integer, T::Type{AbstractGroup{D}}[, optargs])\ngenerators(pgiuc::String, T::PointGroup{D}}) --> Vector{SymOperation{D}}\n\nReturn the generators of the group type T which may be a SpaceGroup{D} or a PointGroup{D} parameterized by its dimensionality D. Depending on T, the group is determined by inputting as the first argument:\n\nSpaceGroup{D}: the space group number num::Integer.\nPointGroup{D}: the point group IUC label pgiuc::String (see also [pointgroup(::String)) or the canonical point group number num::Integer, which can optionally be supplemented by an integer-valued setting choice setting::Integer (see also pointgroup(::Integer, ::Integer, ::Integer)]).\nSubperiodicGroup{D}: the subperiodic group number num::Integer.\n\nSetting choices match those in spacegroup, pointgroup, and subperiodicgroup.\n\nIterated composition of the returned symmetry operations will generate all operations of the associated space or point group (see generate). As an example, generate(generators(num,SpaceGroup{D}))andspacegroup(num, D)` return identical operations (with different sorting typically); and similarly so for point and subperiodic groups.\n\nExample\n\nGenerators of space group 200:\n\njulia> generators(200, SpaceGroup{3})\n4-element Vector{SymOperation{3}}:\n 2₀₀₁\n 2₀₁₀\n 3₁₁₁⁺\n -1\n\nGenerators of point group m-3m:\n\njulia> generators(\"2/m\", PointGroup{3})\n2-element Vector{SymOperation{3}}:\n 2₀₁₀\n -1\n\nGenerators of the Frieze group 𝓅2mg:\n\njulia> generators(7, SubperiodicGroup{2, 1})\n2-element Vector{SymOperation{2}}:\n 2\n {m₁₀|½,0}\n\nCiting\n\nPlease cite the original data sources if used in published work:\n\nSpace groups: Aroyo et al., Z. Kristallogr. Cryst. Mater. 221, 15 (2006);\nPoint group: Bilbao Crystallographic Server's 2D and 3D GENPOS;\nSubperiodic groups: Bilbao Crystallographic Server's SUBPERIODIC GENPOS.\n\nExtended help\n\nNote that the returned generators are not guaranteed to be the smallest possible set of generators; i.e., there may exist other generators with fewer elements (an example is space group 168 (P6), for which the returned generators are [2₀₀₁, 3₀₀₁⁺] even though the group could be generated by just [6₀₀₁⁺]). The returned generators, additionally, are not guaranteed to be minimal, i.e., they may include proper subsets that generate the group themselves (e.g., in space group 75 (P4), the returned generators are [2₀₀₁, 4₀₀₁⁺] although the subset [4₀₀₁⁺] is sufficient to generate the group). The motivation for this is to expose as similar generators as possible for similar crystal systems (see e.g. Section 8.3.5 of the International Tables of Crystallography, Vol. A, Ed. 5 (ITA) for further background).\n\nNote also that, contrary to conventions in ITA, the identity operation is excluded among the returned generators (except in space group 1) since it composes trivially and adds no additional context.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.generators-Union{Tuple{P}, Tuple{D}, Tuple{Integer, Type{SubperiodicGroup{D, P}}}} where {D, P}","page":"API","title":"Crystalline.generators","text":"generators(num::Integer, ::Type{SubperiodicGroup{D,P}}) --> ::Vector{SymOperation{D}}\n\nReturn a canonical set of generators for the subperiodic group num of embedding dimension D and periodicity dimension P. See also subperiodicgroup.\n\nSee also generators(::Integer, ::Type{SpaceGroup}) and information therein.\n\nExample\n\njulia> generators(7, SubperiodicGroup{2, 1})\n2-element Vector{SymOperation{2}}:\n 2\n {m₁₀|½,0}\n\nData sources\n\nThe generators returned by this function were originally retrieved from the Bilbao Crystallographic Database, SUBPERIODIC GENPOS.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.irreps-Tuple{Crystalline.AbstractSymmetryVector}","page":"API","title":"Crystalline.irreps","text":"irreps(n::AbstractSymmetryVector{D}) -> AbstractVector{<:Collection{<:AbstractIrrep{D}}}\n\nReturn the irreps referenced by n. \n\nThe returned value is an AbstractVector of Collection{<:AbstractIrrep}s, with irreps for distinct groups, usually associated with specific k-manifolds, belonging to the same Collection.\n\nSee also multiplicities(::AbstractSymmetryVector).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.is_abelian-Union{Tuple{AbstractArray{SymOperation{D}, 1}}, Tuple{D}, Tuple{AbstractArray{SymOperation{D}, 1}, Union{Nothing, Char}}} where D","page":"API","title":"Crystalline.is_abelian","text":"is_abelian(ops::AbstractVector{SymOperation}, [cntr::Union{Char, Nothing}]) --> Bool\n\nReturn the whether the group composed of the elements ops is Abelian.\n\nA group G is Abelian if all its elements commute mutually, i.e., if g = hgh^-1 for all gh G.\n\nSee discussion of the setting argument cntr in classes.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.isnormal-Union{Tuple{D}, Tuple{AbstractArray{SymOperation{D}, 1}, AbstractArray{SymOperation{D}, 1}}} where D","page":"API","title":"Crystalline.isnormal","text":"isnormal(opsᴳ::AbstractVector{<:SymOperation},\n opsᴴ::AbstractVector{<:SymOperation};\n verbose::Bool=false) --> Bool\n\nDetermine whether the operations in group H are normal in the group G (each with operations opsᴳ and opsᴴ), in the sense that \n\nghg¹ H gG hH\n\nReturns a Boolean answer (true if normal, false if not).\n\nNote\n\nThis compares space groups rather than space group types, i.e. the comparison assumes a matching setting choice between H and G. To compare space group types with different conventional settings, they must first be transformed to a shared setting.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.israyrep","page":"API","title":"Crystalline.israyrep","text":"israyrep(lgir::LGIrrep, αβγ=nothing) -> (::Bool, ::Matrix)\n\nComputes whether a given little group irrep ir is a ray representation by computing the coefficients αᵢⱼ in DᵢDⱼ=αᵢⱼDₖ; if any αᵢⱼ differ from unity, we consider the little group irrep a ray representation (as opposed to the simpler \"vector\" representations where DᵢDⱼ=Dₖ). The function returns a boolean (true => ray representation) and the coefficient matrix αᵢⱼ.\n\n\n\n\n\n","category":"function"},{"location":"api/#Crystalline.issubgroup-Union{Tuple{D}, Tuple{AbstractArray{SymOperation{D}, 1}, AbstractArray{SymOperation{D}, 1}}} where D","page":"API","title":"Crystalline.issubgroup","text":"issubgroup(opsᴳ::T, opsᴴ::T′) where T⁽′⁾<:AbstractVector{SymOperation} --> Bool\n\nDetermine whether the operations in group H are a subgroup of the group G (each with operations opsᴳ and opsᴴ, respectively), i.e. whether HG. Specifically, this requires that G and H are both groups and that for every hH there exists an element gG such that h=g.\n\nReturns a Boolean answer (true if normal, false if not).\n\nNote\n\nThis compares space groups rather than space group types, i.e. the comparison assumes a matching setting choice between H and G. To compare space group types with different conventional settings, they must first be transformed to a shared setting.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.issymmorph","page":"API","title":"Crystalline.issymmorph","text":"issymmorph(sgnum::Integer, D::Integer=3) --> Bool\n\nReturn whether the space group with number sgnum and dimensionality D is symmorphic (true) or nonsymmorphic (false).\n\nEquivalent to issymmorph(spacegroup(sgnum, D)) but uses memoization for performance.\n\n\n\n\n\n","category":"function"},{"location":"api/#Crystalline.issymmorph-Tuple{Crystalline.AbstractGroup}","page":"API","title":"Crystalline.issymmorph","text":"issymmorph(sg::Union{SpaceGroup, LittleGroup}) --> Bool\n\nReturn whether a given space group sg is symmorphic (true) or nonsymmorphic (false).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.issymmorph-Union{Tuple{D}, Tuple{SymOperation{D}, Char}} where D","page":"API","title":"Crystalline.issymmorph","text":"issymmorph(op::SymOperation, cntr::Char) --> Bool\n\nReturn whether a given symmetry operation op is symmorphic (true) or nonsymmorphic (false). \n\nThe operation is assumed provided in conventional basis with centering type cntr: checking symmorphism is then equivalent to checking whether the operation's translation part is zero or a lattice vector in the associated primitive basis.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.iuc","page":"API","title":"Crystalline.iuc","text":"iuc(sgnum::Integer, D::Integer=3) --> String\n\nReturn the IUC (International Union of Crystallography) notation for space group number sgnum in dimension D (1, 2, or 3), as used in the International Tables of Crystallography.\n\nThe notation is sometimes also known as the Hermann-Mauguin notation.\n\n\n\n\n\n","category":"function"},{"location":"api/#Crystalline.levelsetlattice-Union{Tuple{Integer}, Tuple{D′}, Tuple{Integer, Integer}, Tuple{Integer, Integer, NTuple{D′, Int64}}} where D′","page":"API","title":"Crystalline.levelsetlattice","text":"levelsetlattice(sgnum::Integer, D::Integer=2, idxmax::NTuple=ntuple(i->2,D))\n --> UnityFourierLattice{D}\n\nCompute a \"neutral\"/uninitialized Fourier lattice basis, a UnityFourierLattice, consistent with the symmetries of the space group sgnum in dimension D. The resulting lattice flat is expanded in a Fourier basis split into symmetry-derived orbits, with intra-orbit coefficients constrained by the symmetries of the space-group. The inter-orbit coefficients are, however, free and unconstrained.\n\nThe Fourier resolution along each reciprocal lattice vector is controlled by idxmax: e.g., if D = 2 and idxmax = (2, 3), the resulting Fourier lattice may contain reciprocal lattice vectors (k₁, k₂) with k₁∈[0,±1,±2] and k₂∈[0,±1,±2,±3], referred to a 𝐆-basis.\n\nThis \"neutral\" lattice can, and usually should, be subsequently modulated by modulate (which modulates the inter-orbit coefficients, which may eliminate \"synthetic symmetries\" that can exist in the \"neutral\" configuration, due to all inter-orbit coefficients being set to unity).\n\nExamples\n\nCompute a UnityFourierLattice, modulate it with random inter-orbit coefficients via modulate, and finally plot it (via PyPlot.jl):\n\njulia> uflat = levelsetlattice(16, Val(2))\njulia> flat = modulate(uflat)\njulia> Rs = directbasis(16, Val(2)) \njulia> using PyPlot\njulia> plot(flat, Rs)\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.lgirreps-Union{Tuple{Integer}, Tuple{D}, Tuple{Integer, Val{D}}, Tuple{Integer, Val{D}, JLD2.JLDFile}, Tuple{Integer, Val{D}, JLD2.JLDFile, JLD2.JLDFile}} where D","page":"API","title":"Crystalline.lgirreps","text":"lgirreps(sgnum::Integer, D::Union{Val{Int}, Integer}=Val(3))\n -> Dict{String, Collection{LGIrrep{D}}}\n\nFor given space group number sgnum and dimension D, return the associated little group (or \"small\") irreps (LGIrrep{D}s) at high-symmetry k-points, lines, and planes. \n\nReturns a Dict with little group k-point labels as keys and vectors of LGIrrep{D}s as values.\n\nNotes\n\nThe returned irreps are complex in general. Real irreps (as needed in time-reversal invariant settings) can subsequently be obtained with the realify method.\nReturned irreps are spinless.\nThe irrep labelling follows CDML conventions.\nIrreps along lines or planes may depend on free parameters αβγ that parametrize the k point. To evaluate the irreps at a particular value of αβγ and return the associated matrices, use (lgir::LGIrrep)(αβγ). If αβγ is an empty tuple in this call, the matrices associated with lgir will be evaluated assuming αβγ = [0,0,...].\n\nReferences\n\nThe underlying data is sourced from the ISOTROPY ISO-IR dataset. Please cite the original reference material associated with ISO-IR:\n\nStokes, Hatch, & Campbell, ISO-IR, ISOTROPY Software Suite.\nStokes, Campbell, & Cordes, Acta Cryst. A. 69, 388-395 (2013).\n\nThe ISO-IR dataset is occasionally missing some k-points that lie outside the basic domain but still resides in the representation domain (i.e. k-points with postscripted 'A', 'B', etc. labels, such as 'ZA'). In such cases, the missing irreps may instead have been manually sourced from the Bilbao Crystallographic Database.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.littlegroup","page":"API","title":"Crystalline.littlegroup","text":"littlegroup(sg::SpaceGroup, kv::KVec) -> LittleGroup\nlittlegroup(\n sg::SpaceGroup,\n kv::KVec,\n klab::String\n) -> LittleGroup\n\n\nReturn the little group associated with space group sg at the k-vector kv.\n\nOptionally, an associated k-vector label klab can be provided; if not provided, the empty string is used as label.\n\n\n\n\n\n","category":"function"},{"location":"api/#Crystalline.littlegroups-Union{Tuple{Integer}, Tuple{D}, Tuple{Integer, Val{D}}, Tuple{Integer, Val{D}, JLD2.JLDFile}} where D","page":"API","title":"Crystalline.littlegroups","text":"littlegroups(sgnum::Integer, D::Union{Val{Int}, Integer}=Val(3)) \n -> Dict{String, LittleGroup{D}}\n\nFor given space group number sgnum and dimension D, return the associated little groups (LittleGroups{D}s) at high-symmetry k-points, lines, and planes (see also lgirreps).\n\nReturns a Dict with little group k-point labels as keys and vectors of LittleGroup{D}s as values.\n\nNotes\n\nA conventional crystallographic setting is assumed (as in spacegroup).\n\nUnlike spacegroup, \"centering\"-copies of symmetry operations are not included in the returned LittleGroups; as an example, space group 110 (body-centered, with centering symbol 'I') has a centering translation [1/2,1/2,1/2] in the conventional setting: the symmetry operations returned by spacegroup thus includes e.g. both {1|0} and {1|½,½,½} while the symmetry operations returned by littlegroups only include {1|0} (and so on).\n\nCurrently, only D = 3 is supported.\n\nReferences\n\nThe underlying data is sourced from the ISOTROPY dataset: see also lgirreps.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.matrix-Tuple{Crystalline.AbstractOperation}","page":"API","title":"Crystalline.matrix","text":"matrix(op::AbstractOperation{D}) --> SMatrix{D, D+1, Float64}\n\nReturn the D×D+1 matrix representation of op.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.maximal_subgroups-Union{Tuple{Integer}, Tuple{D}, Tuple{Integer, Type{SpaceGroup{D}}}} where D","page":"API","title":"Crystalline.maximal_subgroups","text":"maximal_subgroups(num::Integer, AG::Type{<:AbstractGroup}=SpaceGrop{3}; kind)\n\nReturns the graph structure of the maximal subgroups as a GroupRelationGraph for a group of type AG and number num.\n\nVisualization\n\nThe resulting group structure can be plotted using Makie.jl (e.g., GLMakie.jl) using plot(::GroupRelationGraph):\n\njulia> using Crystalline\njulia> gr = maximal_subgroups(112, SpaceGroup{3})\njulia> using GraphMakie, GLMakie\njulia> plot(gr)\n\nKeyword arguments\n\nkind (default, Crystalline.TRANSLATIONENGLEICHE): to return klassengleiche relations, set kind = Crystalline.KLASSENGLEICHE). For klassengleiche relationships, only a selection of reasonably low-index relationships are returned.\n\nData sources\n\nThe group relationships returned by this function were retrieved from the Bilbao Crystallographic Server's MAXSUB program. Please cite the original reference work associated with MAXSUB:\n\nAroyo et al., Z. Kristallogr. Cryst. Mater. 221, 15 (2006).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.minimal_supergroups-Union{Tuple{Integer}, Tuple{D}, Tuple{Integer, Type{SpaceGroup{D}}}} where D","page":"API","title":"Crystalline.minimal_supergroups","text":"minimal_supergroups(num::Integer, AG::Type{<:AbstractGroup}=SpaceGrop{3}; kind)\n\nReturns the graph structure of the minimal supergroups as a GroupRelationGraph for a group of type AG and number num.\n\nVisualization\n\nThe resulting group structure can be plotted using Makie.jl (e.g., GLMakie.jl) using plot(::GroupRelationGraph):\n\njulia> using Crystalline\njulia> gr = minimal_supergroups(112, SpaceGroup{3})\njulia> using GraphMakie, GLMakie\njulia> plot(gr)\n\nKeyword arguments\n\nkind (default, Crystalline.TRANSLATIONENGLEICHE): to return klassengleiche relations, set kind = Crystalline.KLASSENGLEICHE). For klassengleiche relationships, only a selection of reasonably low-index relationships are returned.\n\nData sources\n\nThe group relationships returned by this function were retrieved from the Bilbao Crystallographic Server's MAXSUB program. Please cite the original reference work associated with MAXSUB:\n\nAroyo et al., Z. Kristallogr. Cryst. Mater. 221, 15 (2006).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.modulate-Union{Tuple{Crystalline.AbstractFourierLattice{D}}, Tuple{D}, Tuple{Crystalline.AbstractFourierLattice{D}, Union{Nothing, AbstractVector{ComplexF64}}}, Tuple{Crystalline.AbstractFourierLattice{D}, Union{Nothing, AbstractVector{ComplexF64}}, Union{Nothing, Real}}, Tuple{Crystalline.AbstractFourierLattice{D}, Union{Nothing, AbstractVector{ComplexF64}}, Union{Nothing, Real}, Union{Nothing, ReciprocalBasis{D}}}} where D","page":"API","title":"Crystalline.modulate","text":"modulate(flat::UnityFourierLattice{D},\nmodulation::AbstractVector{ComplexF64}=rand(ComplexF64, length(getcoefs(flat))),\nexpon::Union{Nothing, Real}=nothing, Gs::Union{ReciprocalBasis{D}, Nothing}=nothing)\n --> ModulatedFourierLattice{D}\n\nDerive a concrete, modulated Fourier lattice from a UnityFourierLattice flat (containing the interrelations between orbit coefficients), by multiplying the \"normalized\" orbit coefficients by a modulation, a complex modulating vector (in general, should be complex; otherwise restores unintended symmetry to the lattice). Distinct modulation vectors produce distinct realizations of the same lattice described by the original flat. By default, a random complex vector is used.\n\nAn exponent expon can be provided, which introduces a penalty term to short- wavelength features (i.e. high-|G| orbits) by dividing the orbit coefficients by |G|^expon; producing a \"simpler\" and \"smoother\" lattice boundary when expon > 0 (reverse for expon < 0). This basically amounts to a continuous \"simplifying\" operation on the lattice (it is not necessarily a smoothing operation; it simply suppresses \"high-frequency\" components). If expon = nothing, no rescaling is performed. If Gs is provided as nothing, the orbit norm is computed in the reciprocal lattice basis (and, so, may not strictly speaking be a norm if the lattice basis is not cartesian); to account for the basis explicitly, Gs must be provided as a ReciprocalBasis, see also normscale.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.mspacegroup-Union{Tuple{D}, Tuple{Integer, Integer}, Tuple{Integer, Integer, Val{D}}} where D","page":"API","title":"Crystalline.mspacegroup","text":"mspacegroup(BNS₁, BNS₂)\nmspacegroup(OG₃) --> MSpaceGroup{3}\n\nReturn the magnetic space group with BNS numbers (BNS₁, BNS₂) or the sequential OG number OG₃ (from 1 to 1651).\n\nData sources\n\nThe data underlying this function was retrieved from ISOTROPY's compilation of Daniel Litvin's magnetic space group tables (http://www.bk.psu.edu/faculty/litvin/Download.html).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.mulliken-Union{Tuple{PGIrrep{D}}, Tuple{D}} where D","page":"API","title":"Crystalline.mulliken","text":"mulliken(pgir::PGIrrep{D}) -> String\n\n\nReturn the Mulliken label of a point group irrep pgir.\n\nNotes\n\nThis functionality is a simple mapping between the tabulated CDML point group irrep labels and associated Mulliken labels [1], using the listings from the Bilbao Crystallographic Database [2].\n\nIgnoring subscript, the rough rules associated with assignment of Mulliken labels are:\n\nIrrep dimensionality: \n1D irreps: if a real irrep, assign A or B (B if antisymmetric under a principal rotation); if a complex irrep, assigned label ¹E or ²E.\n2D irreps: assign label E.\n3D irreps: assign label T.\nu and g subscripts: if the group contains inversion, indicate whether irrep is symmetric (g ~ gerade) or antisymmetric (u ~ ungerade) under inversion.\nPrime superscripts: if the group contains a mirror m aligned with a principal rotation axis, but does not contain inversion, indicate whether irrep is symmetric (′) or antisymmetric (′′) under this mirror.\nNumeral subscripts: the rules for assignment of numeral subscripts are too complicated in general - and indeed, we are unaware of a general coherent rule – to describe here.\n\nReferences\n\n[1]: Mulliken, Report on Notation for the Spectra of Polyatomic Molecules, J. Chem. Phys. 23, 1997 (1955).\n\n[2]: Bilbao Crystallographic Database's Representations PG program.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.multiplicities-Tuple{Crystalline.AbstractSymmetryVector}","page":"API","title":"Crystalline.multiplicities","text":"multiplicities(n::AbstractSymmetryVector) -> AbstractVector{<:AbstractVector{Int}}\n\nReturn the multiplicities of the irreps referenced by n.\n\nSee also irreps(::AbstractSymmetryVector).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.nontrivial_factors-Tuple{Smith}","page":"API","title":"Crystalline.nontrivial_factors","text":"nontrivial_factors(F::Smith) -> Any\n\n\nReturn the nontrivial (i.e., ≠ {0,1}) elementary factors of an EBR basis, provided as a BandRepSet or Smith decomposition.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.normscale!-Union{Tuple{D}, Tuple{ModulatedFourierLattice{D}, Real}, Tuple{ModulatedFourierLattice{D}, Real, Union{Nothing, ReciprocalBasis{D}}}} where D","page":"API","title":"Crystalline.normscale!","text":"normscale!(flat::ModulatedFourierLattice, expon::Real,\n Gs::Union{ReciprocalBasis, Nothing} = nothing) --> ModulatedFourierLattice\n\nIn-place equivalent of normscale: mutates flat.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.normscale-Union{Tuple{D}, Tuple{ModulatedFourierLattice{D}, Real}, Tuple{ModulatedFourierLattice{D}, Real, Union{Nothing, ReciprocalBasis{D}}}} where D","page":"API","title":"Crystalline.normscale","text":"normscale(flat::ModulatedFourierLattice, expon::Real, \n Gs::Union{ReciprocalBasis, Nothing} = nothing) --> ModulatedFourierLattice\n\nApplies inverse-orbit norm rescaling of expansion coefficients with a norm exponent expon. If Gs is nothing, the orbit norm is computed in the lattice basis (and, so, is not strictly a norm); by providing Gs as ReciprocalBasis, the norm is evaluated correctly in cartesian setting. See further discussion in modulate.\n\nAn in-place equivalent is provided in normscale!.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.num-Tuple{Crystalline.AbstractGroup}","page":"API","title":"Crystalline.num","text":"num(g::AbstractGroup) -> Int\n\nReturn the conventional number assigned to the group g.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.occupation-Tuple{Crystalline.AbstractSymmetryVector}","page":"API","title":"Crystalline.occupation","text":"occupation(n::AbstractSymmetryVector) -> Int\n\nReturn the occupation of (i.e., number of bands contained within) n.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.operations-Tuple{Crystalline.AbstractGroup}","page":"API","title":"Crystalline.operations","text":"operations(g::AbstractGroup) -> Vector{<:AbstractOperation}\n\nReturn an Vector containing the operations of the group g.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.orbit-Tuple{SiteGroup}","page":"API","title":"Crystalline.orbit","text":"orbit(g::SiteGroup) --> Vector{WyckoffPosition}\n\nCompute the orbit of the Wyckoff position associated with the site symmetry group g.\n\nExtended help\n\nThe orbit of a Wyckoff position mathbfr in a space group G is defined as the set of inequivalent points in the unit cell that can be obtained by applying the elements of G to mathbfr. Equivalently, every element of the orbit of mathbfr can be written as the composition of a coset representative of the Wyckoff position's site group in G with mathbfr.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.orbit-Union{Tuple{D}, Tuple{AbstractArray{SymOperation{D}, 1}, Union{Crystalline.AbstractVec{D}, AbstractPoint{D}}}, Tuple{AbstractArray{SymOperation{D}, 1}, Union{Crystalline.AbstractVec{D}, AbstractPoint{D}}, Union{Nothing, AbstractMatrix{<:Real}}}} where D","page":"API","title":"Crystalline.orbit","text":"orbit(g::AbstractVector{<:SymOperation}, kv::KVec, cntr::Char) --> Vector{KVec{D}}\norbit(lg::LittleGroup)\norbit(lgir::LGIrrep)\n\nReturn the orbit of of the reciprocal-space vector kv under the action of the group g, also known as the star of k.\n\nThe orbit of kv in g is the set of inequivalent k-points obtained by composition of all the symmetry operations of g with kv. Two reciprocal vectors mathbfk and mathbfk are equivalent if they differ by a primitive reciprocal lattice vector.\n\nIf kv and g are specified in a conventional basis but refer to a non-primitive lattice, the centering type cntr must be provided to ensure that only equivalence by primitive (not conventional) reciprocal lattice vectors are considered. If the centering type of the group g can be inferred from g (e.g., if g is a SpaceGroup), orbit will assume a conventional setting and use the inferred centering type; otherwise, if cntr is neither explicitly set nor inferrable, a primitive setting is assumed.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.pgirreps","page":"API","title":"Crystalline.pgirreps","text":"pgirreps(iuclab::String, ::Val{D}=Val(3); mullikken::Bool=false) where D ∈ (1,2,3)\npgirreps(iuclab::String, D; mullikken::Bool=false)\n\nReturn the (crystallographic) point group irreps of the IUC label iuclab of dimension D as a Vector{PGIrrep{D}}.\n\nSee Crystalline.PG_IUC2NUM[D] for possible IUC labels in dimension D.\n\nNotation\n\nThe irrep labelling follows the conventions of CDML [1] [which occasionally differ from those in e.g. Bradley and Cracknell, The Mathematical Theory of Symmetry in Solids (1972)].\n\nTo use Mulliken (\"spectroscopist\") irrep labels instead, set the keyword argument mulliken = true (default, false). See also mulliken.\n\nData sources\n\nThe data is sourced from the Bilbao Crystallographic Server [2]. If you are using this functionality in an explicit fashion, please cite the original reference [3].\n\nReferences\n\n[1]: Cracknell, Davies, Miller, & Love, Kronecher Product Tables 1 (1979).\n\n[2]: Bilbao Crystallographic Database's Representations PG program.\n\n[3]: Elcoro et al., J. of Appl. Cryst. 50, 1457 (2017)\n\n\n\n\n\n","category":"function"},{"location":"api/#Crystalline.pointgroup-Union{Tuple{AbstractArray{SymOperation{D}, 1}}, Tuple{D}} where D","page":"API","title":"Crystalline.pointgroup","text":"pointgroup(ops:AbstractVector{SymOperation{D}})\npointgroup(sg::AbstractGroup)\n\nComputes the point group associated with a space group sg (characterized by a set of operators ops, which, jointly with lattice translations generate the space group), obtained by \"taking away\" any translational parts and then reducing to the resulting unique rotational operations. (technically, in the language of Bradley & Cracknell, this is the so-called isogonal point group of sg; see Sec. 1.5).\n\nReturns a Vector of SymOperations.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.pointgroup-Union{Tuple{AbstractString}, Tuple{D}, Tuple{AbstractString, Val{D}}} where D","page":"API","title":"Crystalline.pointgroup","text":"pointgroup(iuclab::String, ::Union{Val{D}, Integer}=Val(3)) --> PointGroup{D}\n\nReturn the symmetry operations associated with the point group identified with label iuclab in dimension D as a PointGroup{D}.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.pointgroup-Union{Tuple{Integer}, Tuple{D}, Tuple{Integer, Val{D}}, Tuple{Integer, Val{D}, Integer}} where D","page":"API","title":"Crystalline.pointgroup","text":"pointgroup(pgnum::Integer, ::Union{Val{D}, Integer}=Val(3), setting::Integer=1)\n --> PointGroup{D}\n\nReturn the symmetry operations associated with the point group identfied with canonical number pgnum in dimension D as a PointGroup{D}. The connection between a point group's numbering and its IUC label is enumerated in Crystalline.PG_NUM2IUC[D] and Crystalline.IUC2NUM[D].\n\nCertain point groups feature in multiple setting variants: e.g., IUC labels 321 and 312 both correspond to pgnum = 18 and correspond to the same group structure expressed in two different settings. The setting argument allows choosing between these setting variations.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.realify!-Tuple{AbstractDict{<:AbstractString, <:AbstractVector{<:Crystalline.AbstractIrrep}}}","page":"API","title":"Crystalline.realify!","text":"realify!(lgirsd::AbstractDict{<:AbstractIrrep, <:AbstractVector{<:AbstractIrrep}})\n\nApply realify to each value of lgirsd in-place, returning the mutated lgirsd.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.realify-Tuple{AbstractDict{<:AbstractString, <:AbstractVector{<:Crystalline.AbstractIrrep}}}","page":"API","title":"Crystalline.realify","text":"realify(lgirsd::AbstractDict{<:AbstractIrrep, <:AbstractVector{<:AbstractIrrep}}) \n --> Dict{<:AbstractIrrep, <:AbstractVector{<:AbstractIrrep}}\n\nApply realify to each value of lgirsd, returning a new Dict of realified irreps.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.realify-Union{Tuple{AbstractArray{LGIrrep{D}, 1}}, Tuple{D}} where D","page":"API","title":"Crystalline.realify","text":"realify(lgirs::AbstractVector{<:LGIrrep}; verbose::Bool=false)\n --> AbstractVector{<:LGIrrep}\n\nFrom lgirs, a vector of LGIrreps, determine the associated (gray) co-representations, i.e. the \"real\", or \"physical\" irreps that are relevant in scenarios with time-reversal symmetry.\n\nFor LGIrrep that are REAL, or that characterize a k-point 𝐤 which is not equivalent to -𝐤 (i.e. its star does not include both 𝐤 and -𝐤; equivalently, the little group includes time-reversal symmetry), the associated co-representations are just the original irreps themselves. For PSEUDOREAL and COMPLEX LGIrreps where ±𝐤 are equivalent, the associated co-representations are built from pairs of irreps that \"stick\" together. This method computes this pairing and sets the LGIrrep field iscorep to true, to indicate that the resulting \"paired irrep\" (i.e. the co-representation) should be doubled with itself (PSEUDOREAL reality) or its complex conjugate (COMPLEX reality).\n\nBackground\n\nFor background, see p. 650-652 (and p. 622-626 for point groups) in Bradley & Cracknell's book. Their discussion is for magnetic groups (the \"realified\" irreps are, in fact, simply co-representations of the \"gray\" magnetic groups). Cornwell's book also explicates this at some length as does Inui et al. (p. 296-299).\n\nKeyword arguments\n\nverbose::Bool: if set to true, prints details about mapping from small irrep to small\n\ncorep for each LGIrrep (default: false).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.realify-Union{Tuple{AbstractVector{T}}, Tuple{T}} where T<:Crystalline.AbstractIrrep","page":"API","title":"Crystalline.realify","text":"realify(pgirs::AbstractVector{T}) where T<:AbstractIrrep --> Vector{T}\n\nReturn physically real irreps (coreps) from a set of conventional irreps (as produced by e.g. pgirreps). Fallback method for point-group-like AbstractIrreps.\n\nExample\n\njulia> pgirs = pgirreps(\"4\", Val(3));\njulia> characters(pgirs)\nCharacterTable{3}: ⋕9 (4)\n───────┬────────────────────\n │ Γ₁ Γ₂ Γ₃ Γ₄ \n───────┼────────────────────\n 1 │ 1 1 1 1\n 2₀₀₁ │ 1 1 -1 -1\n 4₀₀₁⁺ │ 1 -1 1im -1im\n 4₀₀₁⁻ │ 1 -1 -1im 1im\n───────┴────────────────────\n\njulia> characters(realify(pgirs))\nCharacterTable{3}: ⋕9 (4)\n───────┬──────────────\n │ Γ₁ Γ₂ Γ₃Γ₄ \n───────┼──────────────\n 1 │ 1 1 2\n 2₀₀₁ │ 1 1 -2\n 4₀₀₁⁺ │ 1 -1 0\n 4₀₀₁⁻ │ 1 -1 0\n───────┴──────────────\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.reality-Tuple{Crystalline.AbstractIrrep}","page":"API","title":"Crystalline.reality","text":"reality(ir::AbstractIrrep) --> Reality\n\nReturn the reality of ir (see []Reality](@ref)).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.reduce_ops-Union{Tuple{Pdim}, Tuple{D}, Tuple{AbstractArray{SymOperation{D}, 1}, Char}, Tuple{AbstractArray{SymOperation{D}, 1}, Char, Bool}, Tuple{AbstractArray{SymOperation{D}, 1}, Char, Bool, Bool}, Tuple{AbstractArray{SymOperation{D}, 1}, Char, Bool, Bool, Val{Pdim}}} where {D, Pdim}","page":"API","title":"Crystalline.reduce_ops","text":"reduce_ops(ops::AbstractVector{SymOperation{D}},\n cntr::Char,\n conv_or_prim::Bool=true,\n modw::Bool=true) --> Vector{SymOperation{D}}\n\nReduce the operations ops, removing operations that are identical in the primitive basis associated with the centering cntr. \n\nIf conv_or_prim = false, the reduced operations are returned in the primitive basis associated with cntr; otherwise, in the conventional. If modw = true, the comparison in the primitive basis is done modulo unit primitive lattice vectors; otherwise not. A final argument of type ::Val{P} can be specified to indicate a subperiodic group of periodicity dimension P, different from the spatial embedding dimension D.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.rotation-Tuple{Crystalline.AbstractOperation}","page":"API","title":"Crystalline.rotation","text":"rotation(op::AbstractOperation{D}) --> SMatrix{D, D, Float64}\n\nReturn the D×Drotation part ofop`.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.schoenflies-Tuple{Integer}","page":"API","title":"Crystalline.schoenflies","text":"schoenflies(sgnum::Integer) --> String\n\nReturn the Schoenflies notation for space group number sgnum in dimension 3.\n\nNote that Schoenflies notation is well-defined only for 3D point and space groups.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.seitz-Union{Tuple{SymOperation{D}}, Tuple{D}} where D","page":"API","title":"Crystalline.seitz","text":"seitz(op::SymOperation) --> String\n\nComputes the correponding Seitz notation for a symmetry operation in triplet/xyzt form.\n\nImplementation based on ITA5 Table 11.2.1.1, with 3D point group parts inferred from the trace and determinant of the matrix mathbW in the triplet mathbfWmathbfw.\n\ndetW/trW -3 -2 -1 0 1 2 3\n1 2 3 4 6 1\n-1 -1 -6 -4 -3 m \n\nwith the elements of the table giving the type of symmetry operation in in Hermann-Mauguin notation. The rotation axis and the rotation sense are computed following the rules in ITA6 Sec. 1.2.2.4(1)(b-c). See also .\n\nNote that the orientation of the axis (i.e. its sign) does not necessarily match the orientation picked in Tables 1.4.2.1-5 of ITA6; it is a matter of (arbitrary) convention, and the conventions have not been explicated in ITA.\n\n2D operations are treated by the same procedure, by elevation in a third dimension; 1D operations by a simple inspection of sign.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.sitegroup-Union{Tuple{D}, Tuple{SpaceGroup{D}, WyckoffPosition{D}}} where D","page":"API","title":"Crystalline.sitegroup","text":"sitegroup(\n sg::SpaceGroup{D},\n wp::WyckoffPosition{D}\n) -> SiteGroup\n\n\nReturn the site symmetry group g::SiteGroup for a Wyckoff position wp in space group sg (or with space group number sgnum; in this case, the dimensionality is inferred from wp).\n\ng is a group of operations that are isomorphic to the those listed in sg (in the sense that they might differ by lattice vectors) and that leave the Wyckoff position wp invariant, such that all(op -> wp == compose(op, wp), g) == true.\n\nThe returned SiteGroup also contains the coset representatives of the Wyckoff position (that are again isomorphic to those featured in sg), accessible via cosets, which e.g. generate the orbit of the Wyckoff position (see orbit(::SiteGroup)) and define a left-coset decomposition of sg jointly with the elements in g.\n\nExample\n\njulia> sgnum = 16;\n\njulia> D = 2;\n\njulia> wp = wyckoffs(sgnum, D)[3] # pick a Wyckoff position\n2b: [1/3, 2/3]\n\njulia> sg = spacegroup(sgnum, D);\n\njulia> g = sitegroup(sg, wp)\nSiteGroup{2} ⋕16 (p6) at 2b = [1/3, 2/3] with 3 operations:\n 1\n {3⁺|1,1}\n {3⁻|0,1}\n\nThe group structure of a SiteGroup can be inspected with MultTable:\n\njulia> MultTable(g)\n3×3 MultTable{SymOperation{2}}:\n──────────┬──────────────────────────────\n │ 1 {3⁺|1,1} {3⁻|0,1} \n──────────┼──────────────────────────────\n 1 │ 1 {3⁺|1,1} {3⁻|0,1} \n {3⁺|1,1} │ {3⁺|1,1} {3⁻|0,1} 1\n {3⁻|0,1} │ {3⁻|0,1} 1 {3⁺|1,1}\n──────────┴──────────────────────────────\n\nThe original space group can be reconstructed from a left-coset decomposition, using the operations and cosets contained in a SiteGroup:\n\njulia> ops = [opʰ*opᵍ for opʰ in cosets(g) for opᵍ in g];\n\njulia> Set(sg) == Set(ops)\ntrue\n\nTerminology\n\nMathematically, the site symmetry group is a stabilizer group for a Wyckoff position, in the same sense that the little group of k is a stabilizer group for a k-point.\n\nSee also sitegroups for calculation of all site symmetry groups of a given space group.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.sitegroups-Union{Tuple{SpaceGroup{D}}, Tuple{D}} where D","page":"API","title":"Crystalline.sitegroups","text":"sitegroups(sg::SpaceGroup{D}) -> Any\n\n\nReturn all site symmetry groups associated with a space group, specified either as sg :: SpaceGroup{D} or by its conventional number sgnum and dimension D.\n\nSee also sitegroup for calculation of the site symmetry group of a specific Wyckoff position.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.siteirreps-Union{Tuple{SiteGroup{D}}, Tuple{D}} where D","page":"API","title":"Crystalline.siteirreps","text":"siteirreps(sitegroup::SiteGroup; mulliken::Bool=false]) --> Vector{PGIrrep}\n\nReturn the site symmetry irreps associated with the provided SiteGroup, obtained from a search over isomorphic point groups. The SiteIrreps are in general a permutation of the irreps of the associated isomorphic point group.\n\nBy default, the labels of the site symmetry irreps are given in the CDML notation; to use the Mulliken notation, set the keyword argument mulliken to true (default, false).\n\nExample\n\njulia> sgnum = 16;\n\njulia> sg = spacegroup(sgnum, 2);\n\njulia> wp = wyckoffs(sgnum, 2)[3] # pick the third Wyckoff position\n2b: [1/3, 2/3]\n\njulia> siteg = sitegroup(sg, wp)\nSiteGroup{2} ⋕16 (p6) at 2b = [1/3, 2/3] with 3 operations:\n 1\n {3⁺|1,1}\n {3⁻|0,1}\n\njulia> siteirs = siteirreps(siteg)\n3-element Collection{SiteIrrep{2}} for ⋕16 (p6) at 2b = [1/3, 2/3]:\nΓ₁ ─┬─────────────────────────────────────────────\n ├─ 1: ────────────────────────────────── (x,y)\n │ 1\n │\n ├─ {3⁺|1,1}: ──────────────────── (-y+1,x-y+1)\n │ 1\n │\n ├─ {3⁻|0,1}: ───────────────────── (-x+y,-x+1)\n │ 1\n └─────────────────────────────────────────────\nΓ₂ ─┬─────────────────────────────────────────────\n ├─ 1: ────────────────────────────────── (x,y)\n │ 1\n │\n ├─ {3⁺|1,1}: ──────────────────── (-y+1,x-y+1)\n │ exp(0.6667iπ)\n │\n ├─ {3⁻|0,1}: ───────────────────── (-x+y,-x+1)\n │ exp(-0.6667iπ)\n └─────────────────────────────────────────────\nΓ₃ ─┬─────────────────────────────────────────────\n ├─ 1: ────────────────────────────────── (x,y)\n │ 1\n │\n ├─ {3⁺|1,1}: ──────────────────── (-y+1,x-y+1)\n │ exp(-0.6667iπ)\n │\n ├─ {3⁻|0,1}: ───────────────────── (-x+y,-x+1)\n │ exp(0.6667iπ)\n └─────────────────────────────────────────────\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.spacegroup-Union{Tuple{Any}, Tuple{D}, Tuple{Any, Val{D}}} where D","page":"API","title":"Crystalline.spacegroup","text":"spacegroup(sgnum::Integer, ::Val{D}=Val(3))\nspacegroup(sgnum::Integer, D::Integer) --> SpaceGroup{D}\n\nReturn the space group symmetry operations for a given space group number sgnum and dimensionality D as a SpaceGroup{D}. The returned symmetry operations are specified relative to the conventional basis vectors, i.e. are not necessarily primitive (see centering). If desired, operations for the primitive unit cell can subsequently be generated using primitivize or Crystalline.reduce_ops.\n\nThe default choices for the conventional basis vectors follow the conventions of the Bilbao Crystallographic Server (or, equivalently, the International Tables of Crystallography), which are:\n\nUnique axis b (cell choice 1) for monoclinic space groups.\nObverse triple hexagonal unit cell for rhombohedral space groups.\nOrigin choice 2: inversion centers are placed at (0,0,0). (relevant for certain centrosymmetric space groups with two possible choices; e.g., in the orthorhombic, tetragonal or cubic crystal systems).\n\nSee also directbasis.\n\nData sources\n\nThe symmetry operations returned by this function were originally retrieved from the Bilbao Crystallographic Server, SPACEGROUP GENPOS. The associated citation is: (Aroyo et al., Z. Kristallogr. Cryst. Mater. 221, 15 (2006).).\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.subduction_count-Union{Tuple{T}, Tuple{T, T}, Tuple{T, T, Union{Nothing, AbstractVector{<:Real}}}} where T<:Crystalline.AbstractIrrep","page":"API","title":"Crystalline.subduction_count","text":"subduction_count(Dᴳᵢ, Dᴴⱼ[, αβγᴴⱼ]) --> Int\n\nFor two groups G and H, where H is a subgroup of G, i.e. HG, with associated irreducible representations Dᴳᵢ = D^G_i(g) and Dᴴⱼ = D^H_j(g) over operations gG and hHG, compute the compatibility relation between the two irreps from the subduction reduction formula (or \"magic\" formula/Schur orthogonality relation), returning how many times n^GH_ij the subduced representation D^G_iH contains the irrep D^H_j; in other words, this gives the compatibility between the two irreps.\n\nOptionally, a vector αβγᴴⱼ may be provided, to evaluate the characters/irreps of Dᴳᵢ at a concrete value of (αβγ). This is e.g. meaningful for LGIrreps at non-special k-vectors. Defaults to nothing.\n\nThe result is computed using the reduction formula [see e.g. Eq. (15) of arXiv:1706.09272v2]:\n\nn^GH_ij = H^-1 sum_h chi^G_i(h)chi^H_j(h)^*\n\nExample\n\nConsider the two compatible k-vectors Γ (a point) and Σ (a line) in space group 207:\n\nlgirsd = lgirreps(207, Val(3));\nΓ_lgirs = lgirsd[\"Γ\"]; # at Γ ≡ [0.0, 0.0, 0.0]\nΣ_lgirs = lgirsd[\"Σ\"]; # at Σ ≡ [α, α, 0.0]\n\nWe can test their compatibility via:\n\n[[subduction_count(Γi, Σj) for Γi in Γ_lgirs] for Σj in Σ_lgirs]\n> # Γ₁ Γ₂ Γ₃ Γ₄ Γ₅\n> [ 1, 0, 1, 1, 2] # Σ₁\n> [ 0, 1, 1, 2, 1] # Σ₂\n\nWith following enterpretatation for compatibility relations between irreps at Γ and Σ:\n\nCompatibility relation Degeneracies\nΓ₁ → Σ₁ 1 → 1\nΓ₂ → Σ₂ 1 → 1\nΓ₃ → Σ₁ + Σ₂ 2 → 1 + 1\nΓ₄ → Σ₁ + 2Σ₂ 3 → 1 + 2\nΓ₅ → 2Σ₁ + Σ₂ 3 → 2 + 1\n\nwhere, in this case, all the small irreps are one-dimensional.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.subperiodicgroup-Union{Tuple{Integer}, Tuple{P}, Tuple{D}, Tuple{Integer, Val{D}}, Tuple{Integer, Val{D}, Val{P}}} where {D, P}","page":"API","title":"Crystalline.subperiodicgroup","text":"subperiodicgroup(num::Integer, ::Val{D}=Val(3), ::Val{P}=Val(2))\nsubperiodicgroup(num::Integer, D::Integer, P::Integer)\n --> ::SubperiodicGroup{D,P}\n\nReturn the operations of the subperiodic group num of embedding dimension D and periodicity dimension P as a SubperiodicGroup{D,P}.\n\nThe setting choices are those of the International Tables for Crystallography, Volume E.\n\nAllowed combinations of D and P and their associated group names are:\n\nD = 3, P = 2: Layer groups (num = 1, …, 80).\nD = 3, P = 1: Rod groups (num = 1, …, 75).\nD = 2, P = 1: Frieze groups (num = 1, …, 7).\n\nExample\n\njulia> subperiodicgroup(7, Val(2), Val(1))\nSubperiodicGroup{2, 1} ⋕7 (𝓅2mg) with 4 operations:\n 1\n 2\n {m₁₀|½,0}\n {m₀₁|½,0}\n\nData sources\n\nThe symmetry operations returned by this function were originally retrieved from the Bilbao Crystallographic Database, SUBPERIODIC GENPOS.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.surface_basis-Tuple{DirectBasis{3}, AbstractVector{<:Real}}","page":"API","title":"Crystalline.surface_basis","text":"surface_basis(Rs, n; cartesian=true)\n\nCompute a basis for the surface-cell obtained from terminating a 3D lattice Rs over a surface surface specified by its normal vector n (or Miller indices if cartesian=false).\n\nOutput\n\nThe function returns a tuple (rs³ᴰ, rs′²ᴰ, P), whose elements are described below:\n\nrs³ᴰ: a DirectBasis{3}, whose first two basis vectors lie in the plane of the surface, and whose third vector is (positively) aligned with the surface normal. All basis vectors correspond to points in the original direct lattice.\nrs′²ᴰ: a DirectBasis{2}, whose basis vectors are given in the local coordinate system of the surface unit cell; effectively, this is (xy)-components of rs³ᴰ after a rotation that takes n to hatmathbfz. The first basis vector is aligned with the hatmathbfx-direction of the local coordinate system.\nP: a rotation matrix that takes rs³ᴰ to the local n-to-hatmathbfz rotated coordinate system of rs′²ᴰ. In particular, defining rs′³ᴰ = transform.(DirectPoint.(rs³ᴰ), Ref(P)), the following holds: \t- rs′³ᴰ[i] ≈ [rs′²ᴰ[i]..., 0] for i ∈ 1:2, \t- rs′³ᴰ[3] is (positively) aligned with [0,0,1]. To transform the other way, i.e., from surface-local to lattice-global coordinates, simply use P⁻¹ = transpose(P) instead.\n\nThe returned basis is right-handed.\n\nKeyword arguments\n\ncartesian :: Bool = true: whether the surface normal n is specified in Cartesian coordinates (true) or in the basis of the reciprocal lattice vectors (false), i.e., corresponding to the Cartesian vector n[1]*Gs[1] + n[2]*Gs[2] + n[3]*Gs with Gs denoting the Cartesian representation of the reciprocal lattice vectors, i.e., Gs = reciprocalbasis(Rs). The latter case (false) is a specification of the surface in terms of its Miller indices: the coordinates of n can then equivalently be interpreted as the inverse of the surface's intercept with each of the axes spanned by Rs.\n\nExample\n\njulia> sgnum = 195; # P23, a cubic lattice\n\njulia> Rs = directbasis(sgnum, 3)\nDirectBasis{3} (cubic):\n [1.0, 0.0, 0.0]\n [0.0, 1.0, 0.0]\n [0.0, 0.0, 1.0]\n\njulia> n = [1,1,1]; # project along 111 direction\n\njulia> rs³ᴰ, rs′²ᴰ, P = surface_basis(Rs, n; cartesian=true);\n\njulia> rs³ᴰ # the surface basis in the original coordinate system\nDirectBasis{3} (hexagonal):\n [1.0, -1.5700924586837747e-16, -0.9999999999999998]\n [-0.9999999999999998, 0.9999999999999997, 0.0]\n [1.0, 1.0, 1.0]\n\njulia> rs′²ᴰ # the in-plane surface vectors in a local \"surface coordinate system\"\nDirectBasis{2} (hexagonal):\n [1.414213562373095, 0.0]\n [-0.7071067811865475, 1.2247448713915887]\n\njulia> DirectBasis(transform.(DirectPoint.(rs³ᴰ), Ref(P))) # from rs³ᴰ to rs′²ᴰ coordinates \nDirectBasis{3} (hexagonal):\n [1.414213562373095, -1.1102230246251563e-16, 0.0]\n [-0.7071067811865476, 1.2247448713915885, 0.0]\n [0.0, -1.1102230246251563e-16, 1.7320508075688772]\n\nwarning: Warning\nThis function will likely be moved from Crystalline to Bravais.jl at some point in the future.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.translation-Tuple{Crystalline.AbstractOperation}","page":"API","title":"Crystalline.translation","text":"translation(op::AbstractOperation{D}) --> SVector{D, Float64}\n\nReturn the D-dimensional translation part of op.\n\n\n\n\n\n","category":"method"},{"location":"api/#Crystalline.wyckoffs-Union{Tuple{Integer}, Tuple{D}, Tuple{Integer, Val{D}}} where D","page":"API","title":"Crystalline.wyckoffs","text":"wyckoffs(sgnum::Integer) -> Vector{WyckoffPosition{3}}\nwyckoffs(sgnum::Integer, ::Val{D}) -> Any\n\n\nReturn the Wyckoff positions of space group sgnum in dimension D as a Vector{WyckoffPosition{D}.\n\nThe positions are given in the conventional basis setting, following the conventions of the Bilbao Crystallographic Server (from which the underlying data is sourced [1]).\n\nExample\n\njulia> wps = wyckoffs(16, 2)\n4-element Vector{WyckoffPosition{2}}:\n 6d: [α, β]\n 3c: [1/2, 0]\n 2b: [1/3, 2/3]\n 1a: [0, 0]\n\nReferences\n\n[1]: Aroyo, et al., Z. Kristallogr. 221, 15-27 (2006)\n\n\n\n\n\n","category":"method"},{"location":"api/#Exported-macros","page":"API","title":"Exported macros","text":"","category":"section"},{"location":"api/","page":"API","title":"API","text":"Modules = [Crystalline]\nPrivate = false\nOrder = [:macro]","category":"page"},{"location":"api/#Crystalline.@S_str-Tuple{Any}","page":"API","title":"Crystalline.@S_str","text":"@S_str -> SymOperation\n\nConstruct a SymOperation from a triplet form given as a string.\n\nExample\n\njulia> S\"-y,x\"\n4⁺ ──────────────────────────────── (-y,x)\n ┌ 0 -1 ╷ 0 ┐\n └ 1 0 ╵ 0 ┘\n\n\n\n\n\n","category":"macro"},{"location":"api/#Exported-constants","page":"API","title":"Exported constants","text":"","category":"section"},{"location":"api/","page":"API","title":"API","text":"Modules = [Crystalline]\nPrivate = false\nOrder = [:constant]","category":"page"},{"location":"api/#Crystalline.ENANTIOMORPHIC_PAIRS","page":"API","title":"Crystalline.ENANTIOMORPHIC_PAIRS","text":"ENANTIOMORPHIC_PAIRS :: NTuple{11, Pair{Int,Int}}\n\nReturn the space group numbers of the 11 enantiomorphic space group pairs in 3D.\n\nThe space group types associated with each such pair (sgnum, sgnum') are related by a mirror transformation: i.e. there exists a transformation mathbbP = mathbfPmathbfp between the two groups G = g and G = g such that G = mathbbP^-1GmathbbP where mathbfP is improper (i.e. mathrmdetmathbfP 0).\n\nWe define distinct space group types as those that cannot be related by a proper transformation (i.e. with mathrmdetmathbfP 0). With that view, there are 230 space group types. If the condition is relaxed to allow improper rotations, there are 230-11 = 219 distinct affine space group types. See e.g. ITA5 Section 8.2.2.\n\nThe enantiomorphic space group types are also chiral space group types in 3D. There are no enantiomorphic pairs in lower dimensions; in 3D all enantiomorphic pairs involve screw symmetries, whose direction is inverted between pairs (i.e. have opposite handedness).\n\n\n\n\n\n","category":"constant"},{"location":"api/#Crystalline.MAX_MSGNUM","page":"API","title":"Crystalline.MAX_MSGNUM","text":"MAX_MSGNUM :: Tuple{Int,Int,Int}\n\nAnalogous to MAX_SUBGNUM, but for the number of magnetic space groups.\n\n\n\n\n\n","category":"constant"},{"location":"api/#Crystalline.MAX_MSUBGNUM","page":"API","title":"Crystalline.MAX_MSUBGNUM","text":"MAX_MSUBGNUM :: Tuple{Int,Int,Int}\n\nAnalogous to MAX_SUBGNUM, but for the number of magnetic subperiodic groups.\n\n\n\n\n\n","category":"constant"},{"location":"api/#Crystalline.MAX_SGNUM","page":"API","title":"Crystalline.MAX_SGNUM","text":"MAX_SGNUM :: Tuple{Int,Int,Int}\n\nReturn the number of distinct space group types across dimensions 1, 2, and 3 (indexable by dimensionality).\n\n\n\n\n\n","category":"constant"},{"location":"api/#Crystalline.MAX_SUBGNUM","page":"API","title":"Crystalline.MAX_SUBGNUM","text":"MAX_SUBGNUM :: ImmutableDict\n\nAn immutable dictionary with values v::Int and keys k::Tuple{Int,Int}, where v is the number of distinct subperiodic group types for a given key k = (D,P) describing a subperiodic group of dimensionality D and periodicity P:\n\nlayer groups: (D,P) = (3,2)\nrod groups: (D,P) = (3,1)\nfrieze groups: (D,P) = (2,1)\n\n\n\n\n\n","category":"constant"},{"location":"groups/#Groups","page":"Groups","title":"Groups","text":"","category":"section"},{"location":"groups/","page":"Groups","title":"Groups","text":"All groups in Crystalline are concrete instances of the abstract supertype Crystalline.AbstractGroup{D}, referring to a group in D dimensions. Crystalline.AbstractGroup{D} is itself a subtype of AbstractVector{SymOperation{D}}. Crystalline currently supports five group types: SpaceGroup, PointGroup, LittleGroup, SubperiodicGroup, SiteGroup, and MSpaceGroup.","category":"page"},{"location":"groups/#Example:-space-groups","page":"Groups","title":"Example: space groups","text":"","category":"section"},{"location":"groups/","page":"Groups","title":"Groups","text":"The one, two, and three-dimensional space groups are accessible via spacegroup, which takes the space group number sgnum and dimensino D as input (ideally, the dimension is provided as a Val{D} for the sake of type stability) and returns a SpaceGroup{D} structure:","category":"page"},{"location":"groups/","page":"Groups","title":"Groups","text":"using Crystalline\n\nD = 3 # dimension\nsgnum = 16 # space group number (≤2 in 1D, ≤17 in 2D, ≤230 in 3D)\nsg = spacegroup(sgnum, D) # where practical, `spacegroup` should be called with a `Val{D}` dimension to ensure type stability; here we have D::Int instead for simplicity","category":"page"},{"location":"groups/","page":"Groups","title":"Groups","text":"By default, the returned operations are given in the conventional setting of the International Tables of Crystallography, Volume A (ITA). Conversion to a primitive basis (in the CDML setting) can be accomplished via primitivize.","category":"page"},{"location":"groups/","page":"Groups","title":"Groups","text":"In addition to space groups, Crystalline.jl provides access to the operations of point groups (pointgroup), little groups (littlegroups), subperiodic groups (subperiodicgroup; including rod, layer, and frieze groups), site symmetry groups (sitegroup and sitegroups), and magnetic space groups (mspacegroup).","category":"page"},{"location":"groups/#Multiplication-tables","page":"Groups","title":"Multiplication tables","text":"","category":"section"},{"location":"groups/","page":"Groups","title":"Groups","text":"We can compute the multiplication table of a space group (under the previously defined notion of operator composition) using MultTable:","category":"page"},{"location":"groups/","page":"Groups","title":"Groups","text":"MultTable(sg)","category":"page"},{"location":"groups/","page":"Groups","title":"Groups","text":"Alternatively, exploiting overloading of the *-operator, \"raw\" multiplication tables can be constructed via a simple outer product:","category":"page"},{"location":"groups/","page":"Groups","title":"Groups","text":"sg .* permutedims(sg) # equivalent to `reshape(kron(sg, sg), (length(sg), length(sg)))`","category":"page"},{"location":"groups/#Symmorphic-vs.-nonsymorphic-space-groups","page":"Groups","title":"Symmorphic vs. nonsymorphic space groups","text":"","category":"section"},{"location":"groups/","page":"Groups","title":"Groups","text":"To determine whether a space group is symmorphic or not, use issymmorph taking either a SpaceGroup, LittleGroup, or SubperiodicGroup (or a SpaceGroup identified by its number and dimensionality; in this case, using tabulated look-up). To test whether a given SymOperation is symmorphic in a given centering setting, use issymmorph(::SymOperation, ::Char)","category":"page"},{"location":"groups/#Group-generators","page":"Groups","title":"Group generators","text":"","category":"section"},{"location":"groups/","page":"Groups","title":"Groups","text":"Generators of SpaceGroups, PointGroups, and SubperiodicGroups are accessible via generators, e.g.:","category":"page"},{"location":"groups/","page":"Groups","title":"Groups","text":"ops = generators(sgnum, SpaceGroup{D})","category":"page"},{"location":"groups/","page":"Groups","title":"Groups","text":"To generate a group from a list of generators, we can use the generate method. As an example, we can verify that ops in fact returns symmetry operations identical to those in sg:","category":"page"},{"location":"groups/","page":"Groups","title":"Groups","text":"generate(ops)","category":"page"},{"location":"groups/#Magnetic-space-groups","page":"Groups","title":"Magnetic space groups","text":"","category":"section"},{"location":"groups/","page":"Groups","title":"Groups","text":"Magnetic space groups are accessible via mspacegroup.","category":"page"},{"location":"lattices/#Isosurfaces-with-space-group-symmetry","page":"Lattices","title":"Isosurfaces with space group symmetry","text":"","category":"section"},{"location":"lattices/","page":"Lattices","title":"Lattices","text":"CurrentModule = Crystalline","category":"page"},{"location":"lattices/","page":"Lattices","title":"Lattices","text":"UnityFourierLattice\nModulatedFourierLattice\nlevelsetlattice\nmodulate\nprimitivize(::AbstractFourierLattice, ::Char)\nconventionalize(::AbstractFourierLattice, ::Char)\nAbstractFourierLattice(::Any)","category":"page"},{"location":"lattices/#Crystalline.UnityFourierLattice-lattices","page":"Lattices","title":"Crystalline.UnityFourierLattice","text":"UnityFourierLattice{D} <: AbstractFourierLattice{D}\n\nA general D-dimensional Fourier (plane wave) lattice specified by orbits of reciprocal lattice vectors (orbits) and coefficient interrelations (orbitcoefs)). The norm of all elements in orbitcoefs is unity. orbits (and associated coefficients) are sorted in order of increasing norm (low to high).\n\n\n\n\n\n","category":"type"},{"location":"lattices/#Crystalline.ModulatedFourierLattice-lattices","page":"Lattices","title":"Crystalline.ModulatedFourierLattice","text":"ModulatedFourierLattice{D} <: AbstractFourierLattice{D}\n\nA D-dimensional concrete Fourier (plane wave) lattice, derived from a UnityFourierLattice{D} by scaling and modulating its orbit coefficients by complex numbers; in general, the coefficients do not have unit norm.\n\n\n\n\n\n","category":"type"},{"location":"lattices/#Crystalline.levelsetlattice-lattices","page":"Lattices","title":"Crystalline.levelsetlattice","text":"levelsetlattice(sgnum::Integer, D::Integer=2, idxmax::NTuple=ntuple(i->2,D))\n --> UnityFourierLattice{D}\n\nCompute a \"neutral\"/uninitialized Fourier lattice basis, a UnityFourierLattice, consistent with the symmetries of the space group sgnum in dimension D. The resulting lattice flat is expanded in a Fourier basis split into symmetry-derived orbits, with intra-orbit coefficients constrained by the symmetries of the space-group. The inter-orbit coefficients are, however, free and unconstrained.\n\nThe Fourier resolution along each reciprocal lattice vector is controlled by idxmax: e.g., if D = 2 and idxmax = (2, 3), the resulting Fourier lattice may contain reciprocal lattice vectors (k₁, k₂) with k₁∈[0,±1,±2] and k₂∈[0,±1,±2,±3], referred to a 𝐆-basis.\n\nThis \"neutral\" lattice can, and usually should, be subsequently modulated by modulate (which modulates the inter-orbit coefficients, which may eliminate \"synthetic symmetries\" that can exist in the \"neutral\" configuration, due to all inter-orbit coefficients being set to unity).\n\nExamples\n\nCompute a UnityFourierLattice, modulate it with random inter-orbit coefficients via modulate, and finally plot it (via PyPlot.jl):\n\njulia> uflat = levelsetlattice(16, Val(2))\njulia> flat = modulate(uflat)\njulia> Rs = directbasis(16, Val(2)) \njulia> using PyPlot\njulia> plot(flat, Rs)\n\n\n\n\n\n","category":"function"},{"location":"lattices/#Crystalline.modulate-lattices","page":"Lattices","title":"Crystalline.modulate","text":"modulate(flat::UnityFourierLattice{D},\nmodulation::AbstractVector{ComplexF64}=rand(ComplexF64, length(getcoefs(flat))),\nexpon::Union{Nothing, Real}=nothing, Gs::Union{ReciprocalBasis{D}, Nothing}=nothing)\n --> ModulatedFourierLattice{D}\n\nDerive a concrete, modulated Fourier lattice from a UnityFourierLattice flat (containing the interrelations between orbit coefficients), by multiplying the \"normalized\" orbit coefficients by a modulation, a complex modulating vector (in general, should be complex; otherwise restores unintended symmetry to the lattice). Distinct modulation vectors produce distinct realizations of the same lattice described by the original flat. By default, a random complex vector is used.\n\nAn exponent expon can be provided, which introduces a penalty term to short- wavelength features (i.e. high-|G| orbits) by dividing the orbit coefficients by |G|^expon; producing a \"simpler\" and \"smoother\" lattice boundary when expon > 0 (reverse for expon < 0). This basically amounts to a continuous \"simplifying\" operation on the lattice (it is not necessarily a smoothing operation; it simply suppresses \"high-frequency\" components). If expon = nothing, no rescaling is performed. If Gs is provided as nothing, the orbit norm is computed in the reciprocal lattice basis (and, so, may not strictly speaking be a norm if the lattice basis is not cartesian); to account for the basis explicitly, Gs must be provided as a ReciprocalBasis, see also normscale.\n\n\n\n\n\n","category":"function"},{"location":"lattices/#Bravais.primitivize-Tuple{Crystalline.AbstractFourierLattice, Char}-lattices","page":"Lattices","title":"Bravais.primitivize","text":"primitivize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat)\n\nGiven flat referred to a conventional basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated primitive basis. \n\nSpecifically, if flat refers to a direct conventional basis Rs (mathbfa mathbfb mathbfc) [with coordinate vectors mathbfr (r_1 r_2 r_3)^mathrmT] then flat′ refers to a direct primitive basis Rs′ (mathbfa mathbfb mathbfc) (mathbfa mathbfb mathbfc)mathbfP [with coordinate vectors mathbfr (r_1 r_2 r_3)^mathrmT = mathbfP^-1mathbfr], where mathbfP denotes the basis-change matrix obtained from primitivebasismatrix(...).\n\nTo compute the associated primitive basis vectors, see primitivize(::DirectBasis, ::Char) [specifically, Rs′ = primitivize(Rs, cntr)].\n\nExamples\n\nA centered ('c') lattice from plane group 5 in 2D, plotted in its conventional and primitive basis (requires using PyPlot):\n\njulia> sgnum = 5; D = 2; cntr = centering(sgnum, D) # 'c' (body-centered)\n\njulia> Rs = directbasis(sgnum, Val(D)) # conventional basis (rectangular)\njulia> flat = levelsetlattice(sgnum, Val(D)) # Fourier lattice in basis of Rs\njulia> flat = modulate(flat) # modulate the lattice coefficients\njulia> plot(flat, Rs)\n\njulia> Rs′ = primitivize(Rs, cntr) # primitive basis (oblique)\njulia> flat′ = primitivize(flat, cntr) # Fourier lattice in basis of Rs′\n\njulia> using PyPlot\njulia> plot(flat′, Rs′)\n\n\n\n\n\n","category":"method"},{"location":"lattices/#Bravais.conventionalize-Tuple{Crystalline.AbstractFourierLattice, Char}-lattices","page":"Lattices","title":"Bravais.conventionalize","text":"conventionalize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat′)\n\nGiven flat referred to a primitive basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated conventional basis. \n\nSee also the complementary method primitivize(::AbstractFourierLattice, ::Char) for additional details.\n\n\n\n\n\n","category":"method"},{"location":"lattices/#Crystalline.AbstractFourierLattice-Tuple{Any}-lattices","page":"Lattices","title":"Crystalline.AbstractFourierLattice","text":"(flat::AbstractFourierLattice)(xyz) --> Float64\n(flat::AbstractFourierLattice)(xyzs...) --> Float64\n\nEvaluate an AbstractFourierLattice at the point xyz and return its real part, i.e.\n\n mathopmathrmResum_i c_i exp(2pi imathbfG_icdotmathbfr)\n\nwith mathrmG_i denoting reciprocal lattice vectors in the allowed orbits of flat, with c_i denoting the associated coefficients (and mathbfr equiv xyz).\n\nxyz may be any iterable object with dimension matching flat consisting of real numbers (e.g., a Tuple, Vector, or SVector). Alternatively, the coordinates can be supplied individually (i.e., as flat(x, y, z)).\n\n\n\n\n\n","category":"method"},{"location":"bandreps/#Elementary-band-representations","page":"Band representations","title":"Elementary band representations","text":"","category":"section"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"Crystalline.jl provides an interface to access the elementary band representations (EBRs) hosted by the Bilbao Crystallographic Server's BANDREP program via bandreps. Please cite the original research (listed in the associated docstrings).","category":"page"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"As an example, we can obtain the all inequivalent EBRs in space group 219 (F-43c) with:","category":"page"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"using Crystalline\n\nbrs = bandreps(219, 3) # space group 219 (dimension 3)","category":"page"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"which returns a BandRepSet, which itself is an AbstractVector of BandReps. This allows us to index into brs easily:","category":"page"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"brs[1] # obtain the EBR induced by Wyckoff position 8a with irrep A","category":"page"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"By default, bandreps returns the spinless EBRs with time-reversal symmetry. This behavior can be controlled with the keyword arguments spinful (default, false) and timereversal (default, true). By default, only minimal paths are included in the sampling of k-vectors; additional paths can be obtained by setting the keyword argument allpaths = true (default, false).","category":"page"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"The distinct topological classes identifiable from symmetry can can be calculated via classification, which uses the Smith normal form's principle factors:","category":"page"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"classification(brs)","category":"page"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"Which demonstrates that the symmetry indicator group of spinless particles with time-reversal symmetry in space group 219 is trivial.","category":"page"},{"location":"bandreps/#Topology-and-associated-bases","page":"Band representations","title":"Topology and associated bases","text":"","category":"section"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"The SymmetryBases.jl package provides tools to analyze topology of symmetry vectors and compute associated Hilbert bases.","category":"page"},{"location":"bandreps/#API","page":"Band representations","title":"API","text":"","category":"section"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"CurrentModule = Crystalline","category":"page"},{"location":"bandreps/","page":"Band representations","title":"Band representations","text":"bandreps\nclassification\nnontrivial_factors\nbasisdim","category":"page"},{"location":"bandreps/#Crystalline.bandreps-bandreps","page":"Band representations","title":"Crystalline.bandreps","text":"bandreps(sgnum::Integer, D::Integer=3; \n allpaths::Bool=false, spinful::Bool=false, timereversal::Bool=true)\n\nReturns the elementary band representations (EBRs) as a BandRepSet for space group sgnum and dimension D.\n\nKeyword arguments\n\nallpaths: include a minimal sufficient set (false, default) or all (true) k-vectors. \nspinful: single- (false, default) or double-valued (true) irreps, as appropriate for spinless and spinful particles, respectively. Only available for D=3.\ntimereversal: assume presence (true, default) or absence (false) of time-reversal symmetry.\n\nReferences\n\n3D EBRs are obtained from the Bilbao Crystallographic Server's BANDREP program; please reference the original research papers noted there if used in published work.\n\n\n\n\n\n","category":"function"},{"location":"bandreps/#Crystalline.classification-bandreps","page":"Band representations","title":"Crystalline.classification","text":"classification(brs_or_F::Union{BandRepSet, Smith}) --> String\n\nReturn the symmetry indicator group X^textBS of an EBR basis F_or_brs, provided as a BandRepSet or Smith decomposition.\n\nTechnically, the calculation answers the question \"what direct product of mathbbZ_n groups is the the quotient group X^textBS = textBStextAI isomorphic to?\" (see Po, Watanabe, & Vishwanath, Nature Commun. 8, 50 (2017) for more information).\n\n\n\n\n\n","category":"function"},{"location":"bandreps/#Crystalline.nontrivial_factors-bandreps","page":"Band representations","title":"Crystalline.nontrivial_factors","text":"nontrivial_factors(F::Smith) -> Any\n\n\nReturn the nontrivial (i.e., ≠ {0,1}) elementary factors of an EBR basis, provided as a BandRepSet or Smith decomposition.\n\n\n\n\n\n","category":"function"},{"location":"bandreps/#Crystalline.basisdim-bandreps","page":"Band representations","title":"Crystalline.basisdim","text":"basisdim(brs::BandRepSet) --> Int\n\nReturn the dimension of the (linearly independent parts) of a band representation set. This is d^textbs = d^textai in the notation of Po, Watanabe, & Vishwanath, Nature Commun. 8, 50 (2017), or equivalently, the rank of stack(brs) over the ring of integers. This is the number of linearly independent basis vectors that span the expansions of a band structure viewed as symmetry data.\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.jl","page":"Bravais types & bases","title":"Bravais.jl","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"Bravais types, basis systems, and transformations between conventional and primitive settings.","category":"page"},{"location":"bravais/#API","page":"Bravais types & bases","title":"API","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"CurrentModule = Bravais","category":"page"},{"location":"bravais/#Types","page":"Bravais types & bases","title":"Types","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"AbstractBasis\nDirectBasis\nReciprocalBasis\nAbstractPoint\nDirectPoint\nReciprocalPoint","category":"page"},{"location":"bravais/#Bravais.AbstractBasis","page":"Bravais types & bases","title":"Bravais.AbstractBasis","text":"AbstractBasis <: StaticVector{D, SVector{D, T}}\n\nAbstract supertype of a D-dimensional basis in D-dimensional space with coordinate values of type T.\n\n\n\n\n\n","category":"type"},{"location":"bravais/#Bravais.DirectBasis","page":"Bravais types & bases","title":"Bravais.DirectBasis","text":"DirectBasis{D} <: AbstractBasis{D}\n\nA wrapper type over D distinct D-dimensional vectors (given as a SVector{D, SVector{D, Float64}}), defining a lattice basis in direct space.\n\n\n\n\n\n","category":"type"},{"location":"bravais/#Bravais.ReciprocalBasis","page":"Bravais types & bases","title":"Bravais.ReciprocalBasis","text":"ReciprocalBasis{D} <: AbstractBasis{D}\n\nA wrapper type over D distinct D-dimensional vectors (given as a SVector{D, SVector{D, Float64}}), defining a lattice basis in reciprocal space.\n\n\n\n\n\n","category":"type"},{"location":"bravais/#Bravais.AbstractPoint","page":"Bravais types & bases","title":"Bravais.AbstractPoint","text":"AbstractPoint{D, T} <: StaticVector{D, T}\n\nAbstract supertype of a D-dimensional point with elements of type T.\n\n\n\n\n\n","category":"type"},{"location":"bravais/#Bravais.DirectPoint","page":"Bravais types & bases","title":"Bravais.DirectPoint","text":"DirectPoint{D} <: AbstractPoint{D}\n\nA wrapper type over an SVector{D, Float64}, defining a single point in D-dimensional direct space. \n\nThe coordinates of a DirectPoint are generally assumed specified relative to an associated DirectBasis. To convert to Cartesian coordinates, see cartesianize.\n\n\n\n\n\n","category":"type"},{"location":"bravais/#Bravais.ReciprocalPoint","page":"Bravais types & bases","title":"Bravais.ReciprocalPoint","text":"ReciprocalPoint{D} <: AbstractPoint{D}\n\nA wrapper type over an SVector{D, Float64}, defining a single point in D-dimensional reciprocal space. \n\nThe coordinates of a ReciprocalPoint are generally assumed specified relative to an associated ReciprocalBasis. To convert to Cartesian coordinates, see cartesianize.\n\n\n\n\n\n","category":"type"},{"location":"bravais/#Crystal-systems-and-Bravais-types","page":"Bravais types & bases","title":"Crystal systems & Bravais types","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"crystalsystem\nbravaistype\ncentering","category":"page"},{"location":"bravais/#Bravais.crystalsystem","page":"Bravais types & bases","title":"Bravais.crystalsystem","text":"crystalsystem(Rs::DirectBasis{D}) --> String\ncrystalsystem(Gs::ReciprocalBasis{D}) --> String\n\nDetermine the crystal system of a point lattice with DirectBasis Rs, assuming the conventional setting choice defined in the International Tables of Crystallography [ITA6].\n\nIf a ReciprocalBasis Gs is provided for the associated reciprocal point lattice, the crystal system is determined by first transforming to the direct lattice.\n\nThere are 4 crystal systems in 2D and 7 in 3D (see Section 2.1.2(iii) of [ITA5]):\n\nD System Conditions Free parameters\n1D linear none a\n2D square a=b & γ=90° a\n rectangular γ=90° a,b\n hexagonal a=b & γ=120° a\n oblique none a,b,γ\n3D cubic a=b=c & α=β=γ=90° a\n hexagonal a=b & α=β=90° & γ=120° a,c\n trigonal a=b & α=β=90° & γ=120° a,c (a,α for hR)\n tetragonal a=b & α=β=γ=90° a,c\n orthorhombic α=β=γ=90° a,b,c\n monoclinic α=γ=90° a,b,c,β≥90°\n triclinic none a,b,c,α,β,γ\n\nThe 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).\n\n[ITA6]: M.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]).\n\n[ITA5]: T. Hahn, International Tables of Crystallography, Vol. A, 5th ed. (2005).\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.bravaistype","page":"Bravais types & bases","title":"Bravais.bravaistype","text":"bravaistype(sgnum::Integer, D::Integer=3; normalize::Bool=false) --> String\n\nReturn the Bravais type of sgnum in dimension D as a string (as the concatenation of the single-character crystal abbreviation and the centering type).\n\nKeyword arguments\n\nnormalize: 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.\nThis only affects space groups 38-41 (normalizing their conventional Bravais types from \"oA\" to \"oC\").\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.centering","page":"Bravais types & bases","title":"Bravais.centering","text":"centering(g::AbstractGroup) --> Char\n\nReturn the conventional centering type of a group. \n\nFor groups without lattice structure (e.g., point groups), return nothing.\n\n\n\n\n\ncentering(sgnum::Integer, D::Integer=3) --> Char\n\nReturn the conventional centering type cntr of the space group with number sgnum and dimension D.\n\nThe 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).\n\nPossible values of cntr, depending on dimensionality D, are (see ITA Sec. 9.1.4):\n\nD = 1:\ncntr = 'p': no centering (primitive)\nD = 2:\ncntr = 'p': no centring (primitive)\ncntr = 'c': face centered\nD = 3: \ncntr = 'P': no centring (primitive)\ncntr = 'I': body centred (innenzentriert)\ncntr = 'F': all-face centred\ncntr = 'A' or 'C': one-face centred, (b,c) or (a,b)\ncntr = 'R': hexagonal cell rhombohedrally centred\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Basis-construction","page":"Bravais types & bases","title":"Basis construction","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"crystal\ndirectbasis\nreciprocalbasis\nnigglibasis","category":"page"},{"location":"bravais/#Bravais.crystal","page":"Bravais types & bases","title":"Bravais.crystal","text":"crystal(a, b, c, α, β, γ) --> DirectBasis{3}\n\nCalculate basis vectors mathbfR_1, mathbfR_2, mathbfR_3 in a 3D Cartesian basis for a right-handed coordinate system with specified basis vector lengths a, b, c (associated with mathbfR_1, mathbfR_2, & mathbfR_3, respectively) and specified interaxial angles α = (mathbfR_2mathbfR_3), β = (mathbfR_3mathbfR_1), γ = (mathbfR_1mathbfR_2), with denoting the angle between two vectors.\n\nFor definiteness, the mathbfR_1 basis vector is oriented along the x-axis of the Cartesian coordinate system, and the mathbfR_2 axis is placed in the xy-plane.\n\n\n\n\n\ncrystal(a, b, γ) --> DirectBasis{2}\n\nCalculate basis vectors mathbfR_1, mathbfR_2 in a 2D Cartesian basis for a right-handed coordinate system with specified basis vector lengths a, b (associated with mathbfR_1 & mathbfR_2, respectively) and specified interaxial angle γ = (mathbfR_1mathbfR_2).\n\nFor definiteness, the mathbfR_1 basis vector is oriented along the x-axis of the Cartesian coordinate system.\n\n\n\n\n\ncrystal(a) --> DirectBasis{1}\n\nReturn a one-dimensional crystal with lattice period a.\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.directbasis","page":"Bravais types & bases","title":"Bravais.directbasis","text":"directbasis(sgnum, D=3; abclims, αβγlims)\ndirectbasis(sgnum, Val(D); abclims, αβγlims) --> DirectBasis{D}\n\nReturn 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.\n\nLimits 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).\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.reciprocalbasis","page":"Bravais types & bases","title":"Bravais.reciprocalbasis","text":"reciprocalbasis(Rs) --> ::ReciprocalBasis{D}\n\nReturn 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).\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.nigglibasis","page":"Bravais types & bases","title":"Bravais.nigglibasis","text":"nigglibasis(Rs; rtol=1e-5, max_iterations=200)\n\nGiven a set of primitive basis vectors Rs, return a basis Rs′ for the corresponding Niggli-reduced unit cell, as well as a transformation matrix P, such that Rs′ = transform(Rs, P) (see transform).\n\nDefinition\n\nA Niggli-reduced basis (mathbfa mathbfb mathbfc) represents a unique choice of basis for any given lattice (or, more precisely, a unique choice of the basis vector lengths mathbfa mathbfb mathbfc, and mutual angles between mathbfa mathbfb mathbfc). This uniqueness is one of the main motivations for computing the Niggli reduction procedure, as it enables easy comparison of lattices. Additionally, the associated Niggli-reduced basis vectors (mathbfa mathbfb mathbfc), fulfil several conditions [3]:\n\n\"Main\" conditions:\nThe basis vectors are sorted by increasing length: mathbfa mathbfb mathbfc.\nThe angles between basis vectors are either all acute or all non-acute.\n\"Special\" conditions:\nSeveral special conditions, applied in \"special\" cases, such as mathbfa = mathbfb or \\mathbf{b}\\cdot\\mathbf{c} = \\tfrac{1}{2}|\\mathbf{b}|^2. See Ref. [3] for details.\n\nEquivalently, the Niggli-reduced basis fulfils the following geometric conditions (Section 9.3.1 of Ref. [3]):\n\nThe basis vectors are sorted by increasing length.\nThe basis vectors have least possible total length, i.e., ``|\\mathbf{a}| + |\\mathbf{b}|\n|\\mathbf{c}|`` is minimum. I.e., the associated Niggli cell is a Buerger cell.\nThe associated Buerger cell has maximum deviation among all other Buerger cells, i.e., the basis vector angles α β γ maximize 90 - α + 90 - β + 90 - γ.\n\nKeyword arguments\n\nrtol :: Real: relative tolerance used in the Grosse-Kunstleve approach for floating point comparisons (default: 1e-5).\nmax_iterations :: Int: maximum number of iterations in which to cycle the Krivy-Gruber steps (default: 200).\n\nImplementation\n\nImplementation follows the algorithm originally described by Krivy & Gruber [1], with the stability modificiations proposed by Grosse-Kunstleve et al. [2] (without which the algorithm proposed in [1] simply does not work on floating point hardware).\n\n[1] I. Krivy & B. Gruber. A unified algorithm for determinign the reduced (Niggli) cell, Acta Crystallogr. A 32, 297 (1976). [2] R.W. Grosse-Kunstleve, N.K. Sauter, & P.D. Adams, Numerically stable algorithms for the computation of reduced unit cells, Acta Crystallogr. A 60, 1 (2004) [3] Sections 9.2 & 9.3, International Tables of Crystallography, Volume A, 5th ed. (2005).\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Transformations","page":"Bravais types & bases","title":"Transformations","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"primitivebasismatrix\ntransform\nprimitivize\nconventionalize\ncartesianize\ncartesianize!\nlatticize\nlatticize!","category":"page"},{"location":"bravais/#Bravais.primitivebasismatrix","page":"Bravais types & bases","title":"Bravais.primitivebasismatrix","text":"primitivebasismatrix(cntr::Char, ::Val{D}=Val(3)) --> SMatrix{D,D,Float64}\nprimitivebasismatrix(cntr::Char, ::Val{D}, ::Val{P}) --> SMatrix{D,D,Float64}\n\nReturn the transformation matrix mathbfP that transforms a conventional unit cell with centering cntr to the corresponding primitive unit cell (in dimension D and periodicity P) in CDML setting.\n\nIf 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).\n\nTransformations in direct and reciprocal space\n\nBases\n\nThe returned transformation matrix mathbfP transforms a direct-space conventional basis (mathbfa mathbfb mathbfc) to the direct-space primitive basis\n\n (mathbfa mathbfb mathbfc) =\n (mathbfa mathbfb mathbfc)mathbfP\n\nAnalogously, mathbfP transforms a reciprocal-space conventional basis (mathbfa^* mathbfb^* mathbfc^*) to \n\n(mathbfa^*prime mathbfb^*prime mathbfc^*prime) =\n(mathbfa^* mathbfb^* mathbfc^*)(mathbfP^-1)^textT\n\nsee also transform(::DirectBasis, ::AbstractMatrix{<:Real}) and transform(::ReciprocalBasis, ::AbstractMatrix{<:Real})).\n\nCoordinates\n\nThe coordinates of a point in either direct or reciprocal space, each referred to a basis, also transform under mathbfP. Concretely, direct- and reciprocal-space conventional points mathbfr = (r_1 r_2 r_3)^textT and mathbfk = (k_1 k_2 k_3)^textT, respectively, transform to a primitive setting under mathbfP according to:\n\nmathbfr = mathbfP^-1mathbfr\nmathbfk = mathbfP^textTmathbfk\n\nSee also transform(::DirectPoint, ::AbstractMatrix{<:Real}) and transform(::ReciprocalPoint, ::AbstractMatrix{<:Real})).\n\nSetting conventions\n\nThe setting choice for the primitive cell implied by the returned mathbfP 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]\n\nNote 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.\n\nThe setting choice is usually referred to as the CDML primitive setting, or, less frequently and more ambiguously, as the crystallographic primitive setting.\n\n[CDML]: Cracknell, Davies, Miller, & Love, Kroenecker Product Tables, Vol. 1 (1979).\n\n[BCS]: Bilbao Crystallographic Server, KVEC.\n\n[Aroyo]: Aroyo et al., Acta Cryst. A70, 126 (2014): Table 2 gives (mathbfP^-1)^textT.\n\n[ITB2]: Hahn, International Tables of Crystallography, Vol. B, 2nd edition (2001).\n\n[spglib]: Spglib documentation: Transformation to the primitive setting. Thus, Bravais.jl and Spglib.jl transform to identical primitive settings and are hence mutually compatible.\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.transform","page":"Bravais types & bases","title":"Bravais.transform","text":"transform(v::AbstractVec, P::AbstractMatrix) --> v′::typeof(v)\n\nReturn a transformed coordinate vector v′ from an original coordinate vector v using a basis change matrix P.\n\nNote that a basis change matrix mathbfP transforms direct coordinate vectors (RVec) as mathbfr = mathbfP^-1mathbfr but transforms reciprocal coordinates (KVec) as mathbfk = mathbfP^mathrmTmathbfk [ITA6]\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th edition (2016): Secs. 1.5.1.2 and 1.5.2.1.\n\n\n\n\n\ntransform(op::SymOperation, P::AbstractMatrix{<:Real}, \n p::Union{AbstractVector{<:Real}, Nothing}=nothing,\n modw::Bool=true) --> SymOperation\n\nTransforms a op = mathbfWmathbfw by a rotation matrix P and a translation vector p (can be nothing for zero-translations), producing a new symmetry operation op′ = mathbfWmathbfw (cf. Section 1.5.2.3 of [ITA6])\n\nmathbfWmathbfw = mathbfPmathbfp^-1mathbfWmathbfw\nmathbfPmathbfp\n\nwith\n\nmathbfW = mathbfP^-1mathbfWmathbfP\ntext and \nmathbfw = mathbfP^-1(mathbfw+mathbfWmathbfp-mathbfp)\n\nBy default, the translation part of op′, i.e. mathbfw, is reduced to the range 01), i.e. computed modulo 1. This can be disabled by setting modw = false (default, modw = true).\n\nSee also Bravais.primitivize(::SymOperation, ::Char, ::Bool) and Bravais.conventionalize(::SymOperation, ::Char, ::Bool).\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016).\n\n\n\n\n\ntransform(Rs::DirectBasis, P::AbstractMatrix{<:Real})\n\nTransform a direct basis Rs = (mathbfa mathbfb mathbfc) under the transformation matrix P = mathbfP, returning Rs′ = (mathbfa mathbfb mathbfc) = (mathbfa mathbfb mathbfc) mathbfP.\n\n\n\n\n\ntransform(Gs::ReciprocalBasis, P::AbstractMatrix{<:Real})\n\nTransform a reciprocal basis Gs = (mathbfa^* mathbfb^* mathbfc^*) under the transformation matrix P = mathbfP, returning Gs′ = (mathbfa^*prime mathbfb^*prime mathbfc^*prime) = (mathbfa^* mathbfb^* mathbfc^*)(mathbfP^-1)^textT.\n\n\n\n\n\ntransform(r::DirectPoint, P::AbstractMatrix{<:Real}) --> r′::typeof(r)\n\nTransform a point in direct space r = (r_1 r_2 r_3)^textT under the transformation matrix P = mathbfP, returning r′ = (r_1 r_2 r_3)^textT = mathbfP^-1(r_1 r_2 r_3)^textT.\n\n\n\n\n\ntransform(k::ReciprocalPoint, P::AbstractMatrix{<:Real}) --> k′::typeof(k)\n\nTransform a point in reciprocal space k = (k_1 k_2 k_3)^textT under the transformation matrix P = mathbfP, returning k′ = (k_1 k_2 k_3)^textT = mathbfP^textT(k_1 k_2 k_3)^textT.\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.primitivize","page":"Bravais types & bases","title":"Bravais.primitivize","text":"primitivize(v::AbstractVec, cntr::Char) --> v′::typeof(v)\n\nTransforms a conventional coordinate vector v to a standard primitive basis (specified by the centering type cntr), returning the primitive coordinate vector v′.\n\nNote that a basis change matrix mathbfP (as returned e.g. by Bravais.primitivebasismatrix) transforms direct coordinate vectors (RVec) as mathbfr = mathbfP^-1mathbfr but transforms reciprocal coordinates (KVec) as mathbfk = mathbfP^textTmathbfk [ITA6]. Recall also the distinction between transforming a basis and the coordinates of a vector.\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th edition (2016): Secs. 1.5.1.2 and 1.5.2.1.\n\n\n\n\n\nprimitivize(op::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)\n\nReturn a symmetry operation op′ Ww in a primitive setting, transformed from an input symmetry operation op = Ww in a conventional setting. The operations Ww and Ww are related by a transformation Pp via (cf. Section 1.5.2.3 of [ITA6]):\n\nWw = Pp¹WwPp\n\nwhere P and p are the basis change matrix and origin shifts, respectively. The relevant transformation Pp is inferred from the centering type, as provided by cntr (see also Bravais.centering).\n\nBy default, translation parts of op′, i.e. w are reduced modulo 1 (modw = true); to disable this, set modw = false.\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016).\n\n\n\n\n\nprimitivize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat)\n\nGiven flat referred to a conventional basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated primitive basis. \n\nSpecifically, if flat refers to a direct conventional basis Rs (mathbfa mathbfb mathbfc) [with coordinate vectors mathbfr (r_1 r_2 r_3)^mathrmT] then flat′ refers to a direct primitive basis Rs′ (mathbfa mathbfb mathbfc) (mathbfa mathbfb mathbfc)mathbfP [with coordinate vectors mathbfr (r_1 r_2 r_3)^mathrmT = mathbfP^-1mathbfr], where mathbfP denotes the basis-change matrix obtained from primitivebasismatrix(...).\n\nTo compute the associated primitive basis vectors, see primitivize(::DirectBasis, ::Char) [specifically, Rs′ = primitivize(Rs, cntr)].\n\nExamples\n\nA centered ('c') lattice from plane group 5 in 2D, plotted in its conventional and primitive basis (requires using PyPlot):\n\njulia> sgnum = 5; D = 2; cntr = centering(sgnum, D) # 'c' (body-centered)\n\njulia> Rs = directbasis(sgnum, Val(D)) # conventional basis (rectangular)\njulia> flat = levelsetlattice(sgnum, Val(D)) # Fourier lattice in basis of Rs\njulia> flat = modulate(flat) # modulate the lattice coefficients\njulia> plot(flat, Rs)\n\njulia> Rs′ = primitivize(Rs, cntr) # primitive basis (oblique)\njulia> flat′ = primitivize(flat, cntr) # Fourier lattice in basis of Rs′\n\njulia> using PyPlot\njulia> plot(flat′, Rs′)\n\n\n\n\n\nprimitivize(V::Union{AbstractBasis, AbstractPoint}, \n cntr_or_sgnum::Union{Char, <:Integer}) --> V′::typeof(V)\n\nReturn the primitive basis or point V′ associated with the input conventional AbstractBasis or AbstractPoint V.\n\nThe 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)).\n\n\n\n\n\nprimitivize(Rs::DirectBasis, cntr_or_sgnum::Union{Char, <:Integer}) --> Rs′::typeof(Rs)\n\nReturn the primitive direct basis Rs′ corresponding to the input conventional direct basis Rs.\n\n\n\n\n\nprimitivize(Gs::ReciprocalBasis, cntr_or_sgnum::Union{Char, <:Integer}) --> Gs′::typeof(Gs)\n\nReturn the primitive reciprocal basis Gs′ corresponding to the input conventional reciprocal basis Gs.\n\n\n\n\n\nprimitivize(r::DirectPoint, cntr_or_sgnum::Union{Char, <:Integer}) --> r′::typeof(r)\n\nReturn the direct point r′ with coordinates in a primitive basis, corresponding to the input point r with coordinates in a conventional basis. \n\n\n\n\n\nprimitivize(k::ReciprocalPoint, cntr_or_sgnum::Union{Char, <:Integer}) --> k′::typeof(k)\n\nReturn the reciprocal point k′ with coordinates in a primitive basis, corresponding to the input point k with coordinates in a conventional basis. \n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.conventionalize","page":"Bravais types & bases","title":"Bravais.conventionalize","text":"conventionalize(v′::AbstractVec, cntr::Char) --> v::typeof(v′)\n\nTransforms a primitive coordinate vector v′ back to a standard conventional basis (specified by the centering type cntr), returning the conventional coordinate vector v.\n\nSee also primitivize and transform.\n\n\n\n\n\nconventionalize(op′::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)\n\nReturn a symmetry operation op = Ww in a conventional setting, transformed from an input symmetry operation op′ Ww in a primitive setting.\n\nSee primitivize(::SymOperation, ::Char, ::Bool) for description of the centering argument cntr and optional argument modw.\n\n\n\n\n\nconventionalize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat′)\n\nGiven flat referred to a primitive basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated conventional basis. \n\nSee also the complementary method primitivize(::AbstractFourierLattice, ::Char) for additional details.\n\n\n\n\n\nconventionalize(V′::Union{AbstractBasis, AbstractPoint}, \n cntr_or_sgnum::Union{Char, <:Integer}) --> V::typeof(V′)\n\nReturn the conventional basis or point V associated with the input primitive AbstractBasis or AbstractPoint V′.\n\nThe 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)).\n\n\n\n\n\nconventionalize(Rs′::DirectBasis, cntr_or_sgnum::Union{Char, <:Integer}) --> Rs::typeof(Rs′)\n\nReturn the conventional direct basis Rs corresponding to the input primitive direct basis Rs′.\n\n\n\n\n\nconventionalize(Gs′::ReciprocalBasis, cntr_or_sgnum::Union{Char, <:Integer}) --> Gs::typeof(Gs′)\n\nReturn the conventional reciprocal basis Gs corresponding to the input primitive reciprocal basis Gs′.\n\n\n\n\n\nconventionalize(r′::DirectPoint, cntr_or_sgnum::Union{Char, <:Integer}) --> r::typeof(r′)\n\nReturn the direct point r with coordinates in a conventional basis, corresponding to the input point r′ with coordinates in a primitive basis.\n\n\n\n\n\nconventionalize(k′::ReciprocalPoint, cntr_or_sgnum::Union{Char, <:Integer}) --> k::typeof(k′)\n\nReturn the reciprocal point k with coordinates in a conventional basis, corresponding to the input point k′ with coordinates in a primitive basis. \n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.cartesianize","page":"Bravais types & bases","title":"Bravais.cartesianize","text":"cartesianize\n\nTransform an object with coordinates in an lattice basis to an object with coordinates in a Cartesian basis.\n\nDepending on the object, the basis may be inferrable directly from the object; if not, it must be supplied explicitly. @doc \n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.cartesianize!","page":"Bravais types & bases","title":"Bravais.cartesianize!","text":"cartesianize!\n\nIn-place transform an object with coordinates in an lattice basis to an object with coordinates in a Cartesian basis.\n\nDepending on the object, the basis may be inferrable directly from the object; if not, it must be supplied explicitly.\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.latticize","page":"Bravais types & bases","title":"Bravais.latticize","text":"latticize\n\nTransform an object with coordinates in a Cartesian basis to an object with coordinates in a lattice basis.\n\nDepending on the object, the basis may be inferrable directly from the object; if not, it must be supplied explicitly.\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.latticize!","page":"Bravais types & bases","title":"Bravais.latticize!","text":"latticize!\n\nIn-place transform object with coordinates in a Cartesian basis to an object with coordinates in a lattice basis.\n\nDepending on the object, the basis may be inferrable directly from the object; if not, it must be supplied explicitly.\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Miscellaneous","page":"Bravais types & bases","title":"Miscellaneous","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"volume\nmetricmatrix","category":"page"},{"location":"bravais/#Bravais.volume","page":"Bravais types & bases","title":"Bravais.volume","text":"volume(Vs::AbstractBasis)\n\nReturn the volume V of the unit cell associated with the basis Vs::AbstractBasis{D}.\n\nThe volume is computed as V = sqrtmathrmdetmathbfG with with mathbfG denoting the metric matrix of Vs (cf. the International Tables of Crystallography, Volume A, Section 5.2.2.3).\n\nSee also metricmatrix.\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.metricmatrix","page":"Bravais types & bases","title":"Bravais.metricmatrix","text":"metricmatrix(Vs::AbstractBasis)\n\nReturn 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.\n\nEquivalently, 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.\n\nSee also volume.\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Crystalline.jl-extensions-of-Bravais.jl-functions","page":"Bravais types & bases","title":"Crystalline.jl extensions of Bravais.jl functions","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"CurrentModule = Crystalline","category":"page"},{"location":"bravais/#SymOperation","page":"Bravais types & bases","title":"SymOperation","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"transform(::SymOperation, ::AbstractMatrix{<:Real}, ::Union{AbstractVector{<:Real}, Nothing}, ::Bool=true)\nprimitivize(::SymOperation, ::Char, ::Bool)\nconventionalize(::SymOperation, ::Char, ::Bool)","category":"page"},{"location":"bravais/#Bravais.transform-2","page":"Bravais types & bases","title":"Bravais.transform","text":"transform(op::SymOperation, P::AbstractMatrix{<:Real}, \n p::Union{AbstractVector{<:Real}, Nothing}=nothing,\n modw::Bool=true) --> SymOperation\n\nTransforms a op = mathbfWmathbfw by a rotation matrix P and a translation vector p (can be nothing for zero-translations), producing a new symmetry operation op′ = mathbfWmathbfw (cf. Section 1.5.2.3 of [ITA6])\n\nmathbfWmathbfw = mathbfPmathbfp^-1mathbfWmathbfw\nmathbfPmathbfp\n\nwith\n\nmathbfW = mathbfP^-1mathbfWmathbfP\ntext and \nmathbfw = mathbfP^-1(mathbfw+mathbfWmathbfp-mathbfp)\n\nBy default, the translation part of op′, i.e. mathbfw, is reduced to the range 01), i.e. computed modulo 1. This can be disabled by setting modw = false (default, modw = true).\n\nSee also Bravais.primitivize(::SymOperation, ::Char, ::Bool) and Bravais.conventionalize(::SymOperation, ::Char, ::Bool).\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016).\n\n\n\n\n\n","category":"function"},{"location":"bravais/#Bravais.primitivize-Tuple{SymOperation, Char, Bool}","page":"Bravais types & bases","title":"Bravais.primitivize","text":"primitivize(op::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)\n\nReturn a symmetry operation op′ Ww in a primitive setting, transformed from an input symmetry operation op = Ww in a conventional setting. The operations Ww and Ww are related by a transformation Pp via (cf. Section 1.5.2.3 of [ITA6]):\n\nWw = Pp¹WwPp\n\nwhere P and p are the basis change matrix and origin shifts, respectively. The relevant transformation Pp is inferred from the centering type, as provided by cntr (see also Bravais.centering).\n\nBy default, translation parts of op′, i.e. w are reduced modulo 1 (modw = true); to disable this, set modw = false.\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th ed. (2016).\n\n\n\n\n\n","category":"method"},{"location":"bravais/#Bravais.conventionalize-Tuple{SymOperation, Char, Bool}","page":"Bravais types & bases","title":"Bravais.conventionalize","text":"conventionalize(op′::SymOperation, cntr::Char, modw::Bool=true) --> typeof(op)\n\nReturn a symmetry operation op = Ww in a conventional setting, transformed from an input symmetry operation op′ Ww in a primitive setting.\n\nSee primitivize(::SymOperation, ::Char, ::Bool) for description of the centering argument cntr and optional argument modw.\n\n\n\n\n\n","category":"method"},{"location":"bravais/#AbstractVec","page":"Bravais types & bases","title":"AbstractVec","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"transform(::Crystalline.AbstractVec, ::AbstractMatrix{<:Real})\nprimitivize(::Crystalline.AbstractVec, ::Char)\nconventionalize(::Crystalline.AbstractVec, ::Char)","category":"page"},{"location":"bravais/#Bravais.transform-Tuple{Crystalline.AbstractVec, AbstractMatrix{<:Real}}","page":"Bravais types & bases","title":"Bravais.transform","text":"transform(v::AbstractVec, P::AbstractMatrix) --> v′::typeof(v)\n\nReturn a transformed coordinate vector v′ from an original coordinate vector v using a basis change matrix P.\n\nNote that a basis change matrix mathbfP transforms direct coordinate vectors (RVec) as mathbfr = mathbfP^-1mathbfr but transforms reciprocal coordinates (KVec) as mathbfk = mathbfP^mathrmTmathbfk [ITA6]\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th edition (2016): Secs. 1.5.1.2 and 1.5.2.1.\n\n\n\n\n\n","category":"method"},{"location":"bravais/#Bravais.primitivize-Tuple{Crystalline.AbstractVec, Char}","page":"Bravais types & bases","title":"Bravais.primitivize","text":"primitivize(v::AbstractVec, cntr::Char) --> v′::typeof(v)\n\nTransforms a conventional coordinate vector v to a standard primitive basis (specified by the centering type cntr), returning the primitive coordinate vector v′.\n\nNote that a basis change matrix mathbfP (as returned e.g. by Bravais.primitivebasismatrix) transforms direct coordinate vectors (RVec) as mathbfr = mathbfP^-1mathbfr but transforms reciprocal coordinates (KVec) as mathbfk = mathbfP^textTmathbfk [ITA6]. Recall also the distinction between transforming a basis and the coordinates of a vector.\n\n[ITA6]: M.I. Aroyo, International Tables of Crystallography, Vol. A, 6th edition (2016): Secs. 1.5.1.2 and 1.5.2.1.\n\n\n\n\n\n","category":"method"},{"location":"bravais/#Bravais.conventionalize-Tuple{Crystalline.AbstractVec, Char}","page":"Bravais types & bases","title":"Bravais.conventionalize","text":"conventionalize(v′::AbstractVec, cntr::Char) --> v::typeof(v′)\n\nTransforms a primitive coordinate vector v′ back to a standard conventional basis (specified by the centering type cntr), returning the conventional coordinate vector v.\n\nSee also primitivize and transform.\n\n\n\n\n\n","category":"method"},{"location":"bravais/#AbstractFourierLattice","page":"Bravais types & bases","title":"AbstractFourierLattice","text":"","category":"section"},{"location":"bravais/","page":"Bravais types & bases","title":"Bravais types & bases","text":"primitivize(::AbstractFourierLattice, ::Char)\nconventionalize(::AbstractFourierLattice, ::Char)","category":"page"},{"location":"bravais/#Bravais.primitivize-Tuple{Crystalline.AbstractFourierLattice, Char}","page":"Bravais types & bases","title":"Bravais.primitivize","text":"primitivize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat)\n\nGiven flat referred to a conventional basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated primitive basis. \n\nSpecifically, if flat refers to a direct conventional basis Rs (mathbfa mathbfb mathbfc) [with coordinate vectors mathbfr (r_1 r_2 r_3)^mathrmT] then flat′ refers to a direct primitive basis Rs′ (mathbfa mathbfb mathbfc) (mathbfa mathbfb mathbfc)mathbfP [with coordinate vectors mathbfr (r_1 r_2 r_3)^mathrmT = mathbfP^-1mathbfr], where mathbfP denotes the basis-change matrix obtained from primitivebasismatrix(...).\n\nTo compute the associated primitive basis vectors, see primitivize(::DirectBasis, ::Char) [specifically, Rs′ = primitivize(Rs, cntr)].\n\nExamples\n\nA centered ('c') lattice from plane group 5 in 2D, plotted in its conventional and primitive basis (requires using PyPlot):\n\njulia> sgnum = 5; D = 2; cntr = centering(sgnum, D) # 'c' (body-centered)\n\njulia> Rs = directbasis(sgnum, Val(D)) # conventional basis (rectangular)\njulia> flat = levelsetlattice(sgnum, Val(D)) # Fourier lattice in basis of Rs\njulia> flat = modulate(flat) # modulate the lattice coefficients\njulia> plot(flat, Rs)\n\njulia> Rs′ = primitivize(Rs, cntr) # primitive basis (oblique)\njulia> flat′ = primitivize(flat, cntr) # Fourier lattice in basis of Rs′\n\njulia> using PyPlot\njulia> plot(flat′, Rs′)\n\n\n\n\n\n","category":"method"},{"location":"bravais/#Bravais.conventionalize-Tuple{Crystalline.AbstractFourierLattice, Char}","page":"Bravais types & bases","title":"Bravais.conventionalize","text":"conventionalize(flat::AbstractFourierLattice, cntr::Char) --> ::typeof(flat′)\n\nGiven flat referred to a primitive basis with centering cntr, compute the derived (but physically equivalent) lattice flat′ referred to the associated conventional basis. \n\nSee also the complementary method primitivize(::AbstractFourierLattice, ::Char) for additional details.\n\n\n\n\n\n","category":"method"},{"location":"#Crystalline.jl","page":"Home","title":"Crystalline.jl","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"","category":"page"},{"location":"","page":"Home","title":"Home","text":"Documentation for Crystalline.jl and Bravais.jl.","category":"page"},{"location":"","page":"Home","title":"Home","text":"note: Note\nCrystalline.jl remains a work-in-progress research package. Breaking changes are likely (but will respect semver conventions).","category":"page"},{"location":"","page":"Home","title":"Home","text":"Pages = [\"operations.md\",\n \"groups.md\",\n \"irreps.md\",\n \"bravais.md\",\n \"bandreps.md\",\n \"lattices.md\",\n \"api.md\",\n \"internal-api.md\"]","category":"page"},{"location":"irreps/#Irreducible-representations","page":"Irreps","title":"Irreducible representations","text":"","category":"section"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"Crystalline.jl provides easy access to crystallographic point group irreps, site symmetry group irreps, and the little group irreps of space groups. Currently, we only provide access to spinless (or \"single-valued\") irreps.","category":"page"},{"location":"irreps/#Point-group-irreps","page":"Irreps","title":"Point group irreps","text":"","category":"section"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"Irreps for the crystallographic point groups are accessible via pgirreps, with the point group specified either by IUC label and dimensionality. As an example, we may load the irreps of the 6mm (C₆ᵥ in Schoenflies notation; see also schoenflies(::PointGroup)) point group in 3D.","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"using Crystalline\n\npgirs = pgirreps(\"6mm\", Val(3))","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"Frequently, the character table of the associated irreps is more informative than the irrep matrices themselves. We can construct this table using characters, which returns a CharacterTable:","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"characters(pgirs)","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"The characters are functions of the conjugacy class (i.e., the characters of operations in the same conjugacy class are equal). Thus, a more compact representation of the character table can be achieved by a class-resolved table, achievable via classcharacters:","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"classcharacters(pgirs)","category":"page"},{"location":"irreps/#Notation","page":"Irreps","title":"Notation","text":"","category":"section"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"The default point group irrep labeling follows the Bilbao Crystallographic Server's labeling, which in turn follows the 1963 labelling of Koster, Dimmock, Wheeler, & Statz [2] (which is also followed e.g. by CDML [1] labeling as well as Bradley and Cracknell's book). Associated Muliken (or \"spectroscopist's\") notation can be obtained via mulliken.","category":"page"},{"location":"irreps/#Little-group-irreps","page":"Irreps","title":"Little group irreps","text":"","category":"section"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"Little group irreps, sometimes called ''small'' irreps, are accessible via lgirreps and provided with CDML [1] labels (courtesy of ISOTROPY). As an example, we can obtain the irreps of space group 183 (P6mm; the trivial 3D extension of plane group 17, which in turn is the space group extension of point group 6mm from above) by:","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"using Crystalline\n\nlgirsd = lgirreps(183, Val(3))","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"which returns a dictionary of LGIrreps, indexed by k-labels given as Strings, corresponding to different little groups. In general, we include all the little groups included in ISOTROPY; unfortunately, there is no strict guarantee that this includes a full listing of all inequivalent irreps (although it is typically true). The listing typically contains both special points, lines, and planes (and also always the general point).","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"We can inspect the little group irreps of any particular k-point, accessing it via its canonical label. As before, we can inspect the associated character tables to get an overview of the irreps:","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"lgirs = lgirsd[\"Γ\"] # little group irreps at the Γ point\ncharacters(lgirs)","category":"page"},{"location":"irreps/#Space-group-irreps","page":"Irreps","title":"Space group irreps","text":"","category":"section"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"We currently do not provide access to \"full\" space group irreps. They can, however, be readily built by induction from little group irreps. Specifically, every little group irrep D_mathbfk^alpha associated with the little group G_mathbfk, induces a space group irrep, sometimes denoted ^*D_mathbfk^alpha or D^alpha_mathbfkuparrow G, in the full space group G:[Inui]","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":" ^*D_mathbfk^alpha(g)_ij\n =\n begincases\n D_mathbfk^alpha(h_i^-1gh_j) textif h_i^-1gh_j in G_mathbfk\n boldsymbol0_d_mathbfk^alphatimes d_mathbfk^alpha textotherwise\n endcases","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"where d_mathbfk^alpha is the dimension of the little group irrep D^alpha_mathbfk, boldsymbol0_d_mathbfk^alphatimes d_mathbfk^alpha is a d_mathbfk^alphatimes d_mathbfk^alpha zero matrix, and h_i and h_j iterate over the (left) coset representatives of G_mathbfk in G (of which there are mathrmstarmathbfk, i.e., the order of the star of mathbfk). The induced irrep ^*D_mathbfk^alpha is consequently a d_mathbfk^alphamathrmstarmathbfktimes d_mathbfk^alphamathrmstarmathbfk matrix.","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"[Inui]: Inui, Tanabe, & Onodera, Group Theory and its Applications in Physics, Springer (1990). Section 11.9.","category":"page"},{"location":"irreps/#Site-symmetry-irreps","page":"Irreps","title":"Site symmetry irreps","text":"","category":"section"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"To obtain irreps associated with a given site symmetry group (see SiteGroup), use siteirreps which obtains the irreps associated with the site symmetry group by identifying a \"parent\" point group which is isomorphic to the provided site symmetry group, and then returning a suitable permutation of the point group's irreps.","category":"page"},{"location":"irreps/#Time-reversal-symmetry-and-\"physically-real\"-irreps","page":"Irreps","title":"Time-reversal symmetry & \"physically real\" irreps","text":"","category":"section"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"Irreps returned in Crystalline.jl do not assume time-reversal symmetry by default. To incorporate time-reversal symmetry (or, equivalently, to obtain associated \"physically real\" irreps - or, more technically, co-representations), which may cause irreps to \"stick together\", see realify (which takes a vector of PGIrreps or LGIrreps).","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"As an example, the Γ₃, Γ₄, Γ₅, and Γ₆ irreps of point group 6 (C₆) are intrinsically complex in the absence of time-reversal symmetry:","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"using Crystalline\n\npgirs = pgirreps(\"6\", Val(3))\ncharacters(pgirs)","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"When time-reversal symmetry is incorporated, the irreps stick together pairwise and have real characters:","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"pgirs′ = realify(pgirs)\ncharacters(pgirs′)","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"To inspect the reality type of a given irrep, see reality. Possible types are REAL, COMPLEX, and PSEUDOREAL (the latter does not arise for point groups):","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"label.(pgirs) .=> reality.(pgirs)","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"The reality type can be computed ab initio via calc_reality, using the Frobenius criterion for PGIrreps and SiteIrreps and the Herring criterion for LGIrreps.","category":"page"},{"location":"irreps/#Data-sources","page":"Irreps","title":"Data sources","text":"","category":"section"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"Point group irreps are obtained from the Bilbao Crystallographic Server's Representations PG program and little group irreps of space groups are obtained from ISOTROPY's 2011 ISO-IR dataset.","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"If these functionalities are used in published research, please cite the original publications (listed in associated function docstrings).","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"[1]: Cracknell, A.P., Davies, B.L., Miller, S.C., & Love, W.F., Kronecker Product Tables, Vol. 1. General Introduction and Tables of Irreducible Representations of Space Groups, New York: IFI/Plenum (1979).","category":"page"},{"location":"irreps/","page":"Irreps","title":"Irreps","text":"[2]: Koster, G.F., Dimmock, J.O., Wheeler, R.G., & Statz, H., Properties of the Thirty-two Point Groups, Cambridge: MIT Press (1963).","category":"page"}] }