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

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.

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

_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′)  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 opsᴳ[idxs] == opsᴴ.

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

compact_print_matrix(io, X::Matrix, prerow)
compact_print_matrix(io, X::Matrix, prerow, elformat)
compact_print_matrix(io, X::Matrix, prerow, elformat, sep)

Canibalized and adapted from Base.print_matrix, specifically to allow a prerow input.

Should never be used for printing very large matrices, as it will not wrap or abbreviate rows/columns.

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′::Array{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.

is_compatible(kv::KVec{D}, kv′::KVec{D}) -> Bool

Check whether a special k-point kv is compatible with a non-special k-point kv′. Note that, in general, this is only meaningful if the basis of kv and kv′ is primitive.

TODO: This method should eventually be merged with the equivalently named method in PhotonicBandConnectivity/src/connectivity.jl, which handles everything more correctly, but currently has a slightly incompatible API.

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

Return total number of free parameters occuring in v.

parsefraction(str::AbstractString)

Parse a string str, allowing fraction inputs (e.g. "1/2"), return as 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_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).