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.

struct GenericGroup{D} <: Crystalline.AbstractGroup{D, SymOperation{D}}

• operations::Array{SymOperation{D}, 1} where 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{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);

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

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

julia> parse(SymmetryVector, s, lgirsv)
15-irrep SymmetryVector{3}:
 [2P₃, 4N₁, H₁H₂+H₄H₅, Γ₁+Γ₂+Γ₄+Γ₅, 2PA₃] (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{<: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}:
 (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}:
 [2Z₁⁺+2Z₁⁻, Y₁⁺+3Y₁⁻, 2U₁⁺+2U₁⁻, 2X₁⁺+2X₁⁻, 3T₁⁺+T₁⁻, 2Γ₁⁺+2Γ₁⁻, 3V₁⁺+V₁⁻, R₁⁺+3R₁⁻] (4 bands)

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

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

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.

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

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

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

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::SiteIrrep, h::SymOperation, kv::KVec)

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

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

Determine whether x ∈ itr with approximate equality.

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.

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.

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

Return total number of free parameters occuring in v.

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

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

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

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

pg  = pointgroup("-4m2", Val(3))
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

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.

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.

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.

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.

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

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