Internal API

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

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.

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.

AbstractSymmetryVector{D, IR<:AbstractLGIrrep{D}} <: AbstractVector{Int}

Abstract supertype for symmetry vectors in dimension D, over little group irreps of type IR (LGIrrep{D} for spinless and DLGIrrep{D} for spinful symmetry vectors).

struct GenericGroup{D, O<:Crystalline.AbstractOperation{D}} <: Crystalline.AbstractGroup{D, O<:Crystalline.AbstractOperation{D}}

• operations::Vector{O} where {D, O<:Crystalline.AbstractOperation{D}}

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

parse(::Type{<:SymmetryVector},
      s::AbstractString,
      lgirsv::Vector{<:Collection{<:AbstractLGIrrep}})  ->  SymmetryVector

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 = bandreps(220);

julia> lgirsv = irreps(brs); # irreps at Γ, H, P, PA, & N

julia> s = "[Γ₁+Γ₂+Γ₄+Γ₅, H₁H₂+H₄H₅, 2P₃, 2PA₃, 4N₁]";

julia> parse(SymmetryVector, s, lgirsv)
15-irrep SymmetryVector{3} (spinless):
 [Γ₁+Γ₂+Γ₄+Γ₅, H₁H₂+H₄H₅, 2P₃, 2PA₃, 4N₁] (8 bands)

(⊚)(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]

CompositeBandRep_from_indices(idxs::Vector{Int}, brs::Collection{<:BandRep})

Return a CompositeBandRep whose symmetry content is equal to the sum of the band representations in 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 = bandreps(2);

julia> cbr = CompositeBandRep_from_indices([1, 1, 2, 6], brs)
16-irrep CompositeBandRep{3} (spinless):
 (1f|Aᵤ) + (1h|Aᵤ) + 2(1h|Ag) (4 bands)

julia> cbr == brs[1] + brs[1] + brs[2] + brs[6]
true

julia> SymmetryVector(cbr)
16-irrep SymmetryVector{3} (spinless):
 [2Γ₁⁺+2Γ₁⁻, R₁⁺+3R₁⁻, 3T₁⁺+T₁⁻, 2U₁⁺+2U₁⁻, 3V₁⁺+V₁⁻, 2X₁⁺+2X₁⁻, Y₁⁺+3Y₁⁻, 2Z₁⁺+2Z₁⁻] (4 bands)

_binary_axis(u::SU2) --> SVector{3,Float64}

Return the oriented rotation axis 𝐧 of a two-fold rotation or mirror whose SU(2) element is u = -i(𝐧⋅𝛔). Since -𝐧 gives -u, the orientation of the axis picks out one of the two SU(2) elements of the operation. Altmann calls 𝐧 the operation's pole.

_collect_lgirsd_sorted(lgirsd::AbstractDict{String, <:AbstractVector})
                                            --> Vector{<:AbstractVector}

Collect the values of lgirsd (e.g., as returned by lgirreps) into a vector, sorted deterministically, i.e., independently of the iteration order of lgirsd: k-points with larger little groups come first; ties are broken alphabetically by k-label, with Greek letters sorted before Latin ones (e.g., Γ before M).

_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]

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

_lift_signs(
    ops::AbstractVector{<:DSymOperation},
    ops′::AbstractVector{<:DSymOperation}
) -->  Vector{Int}

Given the unbarred operations ops and ops′ of two double groups whose spatial parts correspond one-to-one (ops[i] ↔ ops′[i], as a group isomorphism), return signs s such that mapping ops[i] to ops′[i] if s[i] = 1, or to its barred partner if s[i] = -1, is an isomorphism of the double groups. The two sets of operations may refer to different DSymOperations of different dimension, e.g., a plane group and the space group it is embedded in.

Matching the spatial parts does not settle the signs: for two-fold rotations and mirrors, which of the two SU(2) elements is unbarred is a convention (see isbarred), and a change of setting need not respect it. Several choices of signs are valid in general; they differ by a one-dimensional ±1 representation of the group. We return the valid choice with the fewest -1s, i.e., the one that maps unbarred operations to unbarred operations as often as possible (on ties, the first found).

For all site symmetry groups of the 230 space groups, the tied choices give the same irrep characters.

_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]

_to_val(x)

If x is a Val{T} type, returns x; otherwise returns Val(x).

_to_value(x)

If x is a Val{T} type, returns T; otherwise returns x itself.

build_candidate_symmetryvectors(
    bandirsv::Vector{Vector{Pair{UnitRange{Int64}, Vector{Int64}}}},
    lgirsv::AbstractArray{Collection{IR<:AbstractLGIrrep{D}}, 1};
    latestarts
) -> Vector

Return ns with ns denoting symmetry vectors associated with a vector of symmetry data bandirsv (see build_candidate_symmetryvectors), in the rrep-sorting of lgirsv. The returned vectors are sorted according to iteration through symeigsv[…][bandidx][…] (i.e., low-lying bands first).

The returned symmetry vectors are potentially separable, in the sense that they have integer symmetry data and a consistent occupation number across k-points. Aside from this, no account of compatibility relations is made. To test whether a returned symmetry vector in fact fulfills compatibility relations, see iscompatible.

If no potentially separable groupings can be found, an empty pair of vectors are returned.

Input

The required irrep data bandirsv can be obtained from build_candidate_symmetryvectors.

Keyword arguments

• latestarts (default, nothing): a dictionary of k-point labels and a late-start band index. Bands below this index at the corresponding k-label are not included In the tallying of symmetry vectors. This is useful for skipping bands whose symmetry data may be known to be incorrect (such as the zero-frequency data of photonic crystals).

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 where L is an integer-valued lattice vector. If bool == false, they are incompatible (and zero-valued sentinel vectors are returned for αβγ, αβγ′, and L).

Extended help and notes

• 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 require abs(L[i]) > 1, the current implementation will not identify the equivalence.
• This operation is usually only meaningful if the bases of kv and kv′ agree and are primitive.

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.

corep_orthogonality_factor(
    ir::Crystalline.AbstractIrrep
) -> Int64

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. For double-valued irreps, the roles of REAL and PSEUDOREAL are interchanged. 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).

doubled_operations(g::Union{SpaceGroup{D}, LittleGroup{D}, PointGroup{D}, SiteGroup{D}})
                                                        --> Vector{DSymOperation{D}}

Attach the SU(2) element (see SU2) to each operation of g, returning the 2|G| operations of the associated double group: the operations themselves first, then their $\bar{E}$-barred partners, in the same order.

find_compatible(
    kv::KVec{D},
    kvs′::AbstractArray{KVec{D}, 1}
) -> Vector{Int64}

find_multiplicities(
    symeigs::AbstractVector{<:AbstractVector{<:Number}},
    lgirs::Collection{<:AbstractLGIrrep};
    atol,
    αβγ,
    latestarts,
    maxresnorm
) -> Vector{Pair{UnitRange{Int64}, Vector{Int64}}}

Return a Vector{Pair{UnitRange{Int}, Vector{Int}}} of band-position indices (UnitRange) and associated irrep multiplicities (Vector{Int}) at a single k-point associated with the provided symmetry eigenvalues symeigs and little group irreps lgirs. Each element of the vector contains as few bands as needed to obtain integer multiplicities (and iterates from lowest to highest bands in symeigs).

Indexing into symeigs is assumed to be such that symeigs[bandidx][opidx] returns the symmetry eigenvalue of bandidxth energy band and the opidxth little group operation, corresponding to group(lgirs)[opidx].

Keyword arguments

• atol (default, 0.02): absolute tolerance used in computing the irrep multiplicities. Passed to find_representation and also used as a maximum allowable deviation from computed floating point multiplicities to the associated nearest integer values.
• αβγ (default, [0.123123123, 0.456456456, 0.789789789]): fractional parameters provided to any little group irreps with nonspecial k-points.
• latestarts (default, nothing): see description in build_candidate_symmetryvectors.
• maxresnorm (default, 0.01): passsed to find_representation. Denotes the maximum allowable residual norm-difference between provided symmetry eigenvalues and the symmetry eigenvalues associated with the computed floating point multiplicities.

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.

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′]

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

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.

induce_bandrep(siteir::AbstractSiteIrrep, h::AbstractOperation, kv::KVec)

Return the band representation induced by the provided site symmetry irrep evaluated at kv and for an operation h (a DSymOperation for a double-valued DSiteIrrep).

It is assumed that group(siteir) is not centering-reduced: i.e., a centering-reduction attempt is always made; if the group cosets are already reduced in the sense of reduce_orbits_and_cosets, this makes no difference.

isapproxin(x, itr, optargs...; kwargs...) --> Bool

Determine whether x ∈ itr with approximate equality.

iscorep(ir::Crystalline.AbstractIrrep) -> Any

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.

nfreeparams(v::Crystalline.AbstractVec) -> Int64

Return total number of free parameters occurring in v.

parsefraction(str::AbstractString, T::Type=Float64)

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

permute_multtable(mt::Matrix{Int}, P::AbstractVector{Int}) -> Matrix{Int}

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

Example

julia> pg  = pointgroup("-4m2", Val(3))
julia> mt  = MultTable(pg)
julia> P   = [2,3,1,4,5,8,6,7] # permutation of operator indices
julia> mt′ = permute_multtable(mt.table, P)
julia> mt′ == MultTable(pg[P]).table

reduce_orbits_and_cosets(siteg::AbstractSiteGroup{D})

For an input site group, provided in conventional coordinates, reduce its cosets such that the resulting orbit only contains Wyckoff positions that are not equivalent when viewed in the primitive basis (as determined by the centering type cntr). Additionally, the associated orbit will only contain positions whose primitive coefficients lie in [0,1). I.e., the associated orbit lies in the canonical [0,1)ᴰ primitive unit cell. The coset operations are adjusted accordingly.^[1]

The reduced site group is returned in a conventional basis, along with the reduced orbits, also in a conventional basis.

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.

reverse_free(v::Crystalline.AbstractVec) -> Any

Return v with its free part negated, i.e. the same set of points, traversed in the opposite direction (e.g., [α, 1/2+β, 1-γ] ↦ [-α, 1/2-β, 1+γ]).

Two AbstractVecs that differ only in this way parametrize the same line, plane, or volume; see also the modrev keyword argument of orbit.

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.

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.

smith_column_bases(brs::Collection{<:BandRep})   --> @NamedTuple{S̃, Λ, S̃⁻¹}
smith_column_bases(B::AbstractMatrix{<:Integer}) --> @NamedTuple{S̃, Λ, S̃⁻¹}
smith_column_bases(F::Smith)                     --> @NamedTuple{S̃, Λ, S̃⁻¹}

Return the parts of the Smith normal decomposition of a set of band representations brs (or of its matrix B, or of a Smith decomposition F thereof) that pertain to the column space of the band representation matrix, i.e. the parts associated with the $d^{\text{bs}} =$ basisdim(brs) nonzero elementary factors of $\boldsymbol{\Lambda}$:

• S̃: the first $d^{\text{bs}}$ columns of $\mathbf{S}$; an integer-coefficient basis for all gapped band structures {BS}.
• Λ: the first $d^{\text{bs}}$ elements of $\boldsymbol{\Lambda}$, i.e. its nonzero elementary factors $\lambda_1, \ldots, \lambda_{d^{\text{bs}}}$.
• S̃⁻¹: the first $d^{\text{bs}}$ rows of $\mathbf{S}^{-1}$; these take a symmetry vector n to its coefficients in S̃, i.e. S̃⁻¹*n.

Note that S̃⁻¹ is a slice of $\mathbf{S}^{-1}$, not the inverse of the (generally nonsquare) S̃; the two nevertheless satisfy S̃⁻¹*S̃ == I. All three returned quantities are views into F, so nothing is allocated.

A basis for the atomic insulators {AI} — the bands induced by localized orbitals at the Wyckoff positions — is S̃*Diagonal(Λ). A symmetry vector that can be expanded on that basis with positive integer coefficients is a trivial insulator (i.e., deformable to an atomic limit); one that cannot is topological, either fragilely (some negative coefficients) or strongly (fractional coefficients). calc_topology distinguishes the strong case from Λ and S̃⁻¹ alone.

Implementation

For an n×m integer matrix $\mathbf{B}$, the Smith normal form gives integer matrices $\mathbf{S}$, $\mathrm{diagm}(\boldsymbol{\Lambda})$ and $\mathbf{T}$ (of size n×n, n×m and m×m, respectively) with $\mathbf{B} = \mathbf{S}\mathrm{diagm}(\boldsymbol{\Lambda})\mathbf{T}$, where $\boldsymbol{\Lambda} = [\lambda_1, \ldots, \lambda_r, 0, \ldots, 0]$ with $\lambda_{j+1}$ divisible by $\lambda_j$ and $r = d^{\text{bs}} \leq \min(n,m)$; $\mathbf{S}$ and $\mathbf{T}$ have integer-valued inverses.

Applying S̃⁻¹ to integer symmetry data $\mathbf{n}$ gives the integer factors $q_i C_i$ ($C_i = \lambda_i$ here) of Tang, Po, Vishwanath, & Wan, Nature Physics 15, 470 (2019).

uniquetol(A, optargs...; kwargs...)

Computes approximate-equality unique in O(n²) runtime, with any positional arguments optargs and keyword arguments kwargs forwarded to isapprox.

Originally based on https://github.com/JuliaLang/julia/issues/19147#issuecomment-256981994