Public API

SpaceGroupElement{N,T<:Integer}

An element of a space group in N dimensions.

Type Parameters

• N: The dimension of the space.
• T<:Integer: The type of the elements in the transformation matrix and translation vector.

Fields

• a::StaticArrays.SMatrix{N,N,T}: The linear transformation matrix.
• b::StaticArrays.SVector{N, Rational{T}}: The translation vector.

The group action is given by the formula x ↦ a*x+b.

Constructors

• SpaceGroupElement{N,T}(): The identity element of the space group.
• SpaceGroupElement{N,T}(t::SVector{N,T}): A pure lattice translation.
• SpaceGroupElement{N,T}(m::SMatrix{N,N,T}): A pure linear transformation.

Example

julia> SpaceGroupElement{2, Int}()
SpaceGroupElement(
  a = [1 0; 0 1],
  b = [0//1, 0//1]
)

julia> SpaceGroupElement(SMatrix{2,2,Int}([0 1; -1 0]))
SpaceGroupElement(
  a = [0 1; -1 0],
  b = [0//1, 0//1]
)

julia> SpaceGroupElement(SVector{2,Int}([1, 1]))
SpaceGroupElement(
  a = [1 0; 0 1],
  b = [1//1, 1//1]
)

SpaceGroupQuotient{N,T} = FiniteGroup{SpaceGroupElement{N,T}}

The factor group of the space group with respect to the subgroup of pure translations. This group is isomorphic to the point group of the space group, but the representation of its elements contains enough information to reconstruct the original space group. In particular, the representation of symmorphic and non-symmorphic space groups is different.

Type Parameters

• N: The dimension of the space.
• T<:Integer: The type of the elements in the transformation matrix and translation vector.

Constructors

• SpaceGroupQuotient{N,T}(): Construct the trivial space group (P1) of dimension N
• SpaceGroupQuotient{N,T}(gen): Constructs the space group using the generating set gen (which should be an iterable of SpaceGroupElement{N, T})

Examples

julia> SpaceGroupQuotient{2, Int}()
SpaceGroupQuotient (dimension 2, order 1)

julia> g1=@SGE([-1 0; 0 -1])
SpaceGroupElement(
  a = [-1 0; 0 -1],
  b = [0//1, 0//1]
)

julia> g2=@SGE([-1 0; 0 1], [1//2, 0//1])
SpaceGroupElement(
  a = [-1 0; 0 1],
  b = [1//2, 0//1]
)

julia> p2mg=SpaceGroupQuotient([g1, g2])
SpaceGroupQuotient (dimension 2, order 4)

@SGE(args...)

A macro for creating SpaceGroupElement objects. It can take either one or two arguments:

• If two arguments are provided, the first should be a matrix and the second a vector. The macro will create a SpaceGroupElement with the given matrix and vector.
• If one argument is provided, it can be either a matrix or a vector. If it's a matrix, the macro will create a SpaceGroupElement with the identity matrix and a zero vector. If it's a vector, the macro will create a SpaceGroupElement with the identity matrix and the given vector.

The macro will check the dimensions and types of the inputs to ensure they are valid.

Arguments

• args...: The arguments to be passed to the macro. It can be either one or two arguments.

Returns

• A SpaceGroupElement object created from the provided arguments.

Example

julia> @SGE([1 0; 0 -1], [1//3, 2//3])
SpaceGroupElement(
    a = [1 0; 0 -1],
    b = [1//3, 2//3]
)

julia> @SGE([1 0; 0 -1])
SpaceGroupElement(
    a = [1 0; 0 -1],
    b = [0//1, 0//1]
)

julia> @SGE([1//3, 2//3])
SpaceGroupElement(
    a = [1 0; 0 1],
    b = [1//3, 2//3]
)

*(e1::SpaceGroupElement{N,T}, e2::SpaceGroupElement{N,T}) where {N,T<:Integer}

Composition of two space group elements.

Arguments

• e1::SpaceGroupElement{N,T}: The first space group element.
• e2::SpaceGroupElement{N,T}: The second space group element.

Returns

• The composition of the two space group elements.

Example

julia> e1 = @SGE([0 1; -1 0]);
       e2 = @SGE([1//1, 1//1]);
       e1*e2
SpaceGroupElement(
  a = [0 1; -1 0],
  b = [1//1, -1//1]
)

∘(e1::SpaceGroupElement{N,T}, e2::SpaceGroupElement{N,T}) where {N,T<:Integer}

Reduced composition of two space group elements. The translation vector of the result is brought inside the standard unit cell.

Arguments

• e1::SpaceGroupElement{N,T}: The first space group element.
• e2::SpaceGroupElement{N,T}: The second space group element.

Returns

• The reduced composition of the two space group elements.

Example

julia> e1 = @SGE([0 1; -1 0]);
       e2 = @SGE([1//1, 1//1]);
       e1∘e2
SpaceGroupElement(
  a = [0 1; -1 0],
  b = [0//1, 0//1]
)

reduce(g::SpaceGroupElement{N,T}) where {N, T<:Integer}

Brings the translation vector of a space group element inside the standard unit cell.

Arguments

• g::SpaceGroupElement{N,T}: The space group element to be reduced.

Returns

• A new SpaceGroupElement with the same linear transformation matrix and a reduced translation vector.

AffinePhase{N, T<:Integer}

Represents the phase of a plane wave x ↦ exp(2π i (k ⋅ x + ϕ)).

The wave is characterized by a wave vector k and a phase offset ϕ.

Type Parameters

• N: The dimensionality of the space.
• T<:Integer: The numeric type for the elements of the wave vector.

Fields

• k::SVector{N, T}: The wave vector.
• ϕ::Rational{T}: The phase offset, always maintained within the interval [0, 1).

Constructors

• AffinePhase(k::SVector{N,T}, ϕ::Rational{T}): Creates a new AffinePhase instance.

The phase ϕ is automatically normalized to its fractional part.

*(g::SpaceGroupElement, ap::AffinePhase) -> AffinePhase

Applies a symmetry operation g to an AffinePhase ap.

The action of a space group element g = (a, b) on an AffinePhase with wave vector k and phase ϕ. This results in a new AffinePhase with a transformed wave vector k' = aᵀk and a new phase ϕ' = ϕ + b ⋅ k.

Arguments

• g::SpaceGroupElement{N,T}: The symmetry operation to apply.
• ap::AffinePhase{N,T}: The affine phase to be transformed.

Returns

• AffinePhase{N,T}: A new AffinePhase instance after the transformation.

ComplexOrbit{N, T<:Integer}

Represents an orbit of plane waves where the phase is unconstrained.

In a ComplexOrbit, for any wave vector k in the orbit, its antipode -k is not present.

Type Parameters

• N: The dimensionality of the space.
• T<:Integer: The numeric type for the elements of the affine phase.

Fields

• aps::Vector{AffinePhase{N,T}}: A vector of AffinePhase objects that constitute the orbit.

RealOrbit{N, T<:Integer}

Represents an orbit of plane waves where the phase is fixed modulo π.

In a RealOrbit, for every wave vector k in the orbit, its antipode -k is also present. The phase is specifically determined to ensure that the superposition of two antipodal waves results in a real-valued function.

Type Parameters

• N: The dimensionality of the space.
• T<:Integer: The numeric type for the elements of the affine phase.

Fields

• aps::Vector{AffinePhase{N,T}}: A vector of AffinePhase objects forming the orbit.

ExtinctOrbit{N, T<:Integer}

Represents an orbit of wave vectors that corresponds to a systematic extinction.

Systematic extinctions arise in the case of non-symmorphic space groups when a symmetry operation preserves the direction of a wave vector but alters the phase of the corresponding plane wave, leading to destructive interference.

Type Parameters

• N: The dimensionality of the space.
• T<:Integer: The numeric type for the elements of the affine phase.

Fields

• k::Vector{SVector{N,T}}: A vector of wave vectors k that are subject to extinction.

FormalOrbit{N, T<:Integer}

A type alias representing the union of ComplexOrbit, RealOrbit, and ExtinctOrbit.

This union type encompasses all possible outcomes of generating an orbit from a wave vector and a space group, including orbits that may be physically unobservable due to extinction.

PhysicalOrbit{N, T<:Integer}

A type alias for the union of ComplexOrbit and RealOrbit.

This type represents orbits corresponding to actual Bragg peaks.

make_orbit(k::SVector{N,T}, G::SpaceGroupQuotient{N,T}) -> FormalOrbit{N,T}

Generates an orbit of affine phases from an initial wave vector k for a given space group (quotient) G.

The function determines the type of orbit (Complex, Real, or Extinct) by analyzing the action of the symmetry operations in G on the initial wave vector.

Arguments

• k::SVector{N,T}: The starting wave vector.
• G::SpaceGroupQuotient{N,T}: The quotient of the space group.

Returns

• FormalOrbit{N,T}: The generated orbit, which can be a ComplexOrbit, RealOrbit, or ExtinctOrbit.

Logic

1. Extinction Check: If any symmetry operation maps k to itself but shifts its phase, the orbit is ExtinctOrbit.
2. Real Orbit Check: If the orbit contains the antipode -k for any k in the orbit, it is a RealOrbit. In this case, for the corresponding affine phases, ϕ is shifted to have opposite sign for the antipodes to insure that their superposition is a real function.
3. Complex Orbit: If neither of the above conditions is met, the orbit is ComplexOrbit.

Example

julia> g=@SGE([-1 0; 0 1], [0//1, 1//2]);

julia> p1g1=SpaceGroupQuotient([g])
SpaceGroupQuotient (dimension 2, order 2)

julia> make_orbit([1, -1], p1g1)
ComplexOrbit with 2 elements

julia> make_orbit([1, 0], p1g1)
RealOrbit with 2 elements

julia> make_orbit([0, 1], p1g1)
ExtinctOrbit with 2 elements

WyckoffPosition{N,T<:Integer}

A Wyckoff position in N dimensions.

Type Parameters

• N: The dimension of the space.
• T<:Integer: The type of the elements in the transformation matrix and translation vector.

Fields

• anchor::StaticArrays.SVector{N, Rational{T}}: The anchor point of the Wyckoff position.
• directions::StaticArrays.SMatrix{N,M,T}: The directions of the Wyckoff position.

Constructors

• WyckoffPosition(anchor::SVector{N,Rational{T}}, directions::SMatrix{N,M,T}): A Wyckoff position with free parameters. The constructore checks that the directions are linearly independent.
• WyckoffPosition{N,T}(): A general Wyckoff position, the number of free parameters equals the dimension of the space.
• WyckoffPosition(anchor::SVector{N,Rational{T}}): A Wyckoff position with zero free parameters (the most special type of Wyckoff position).

@WP(anchor_expr, dirs_expr=nothing)

Construct a Wyckoff position using a convenient macro interface.

• anchor_expr: An expression that evaluates to a vector of rationals, specifying the anchor point.
• dirs_expr: (Optional) An expression that evaluates to a matrix of integers, specifying the directions. If omitted or nothing, the Wyckoff position will have zero free parameters.

Examples

julia> @WP([0//1, 1//2, 1//2], [1; 1; 1;;])
WyckoffPosition(anchor=[0//1, 1//2, 1//2]), directions=[1; 1; 1;;])

julia> @WP([0//1, 1//2, 1//2])
WyckoffPosition(anchor=[0//1, 1//2, 1//2]), no parameters)

*(e::SpaceGroupElement{N,T}, w::WyckoffPosition{N, T}) -> WyckoffPosition{N, T}

Action of a space group element on a Wyckoff position.

Example

julia> g=@SGE([0 1; -1 0])
SpaceGroupElement(
  a = [0 1; -1 0],
  b = [0//1, 0//1]
)

julia> w=@WP([1//2, 0//1])
WyckoffPosition(anchor=[1//2, 0//1]), no parameters)

julia> g*w
WyckoffPosition(anchor=[0//1, -1//2]), no parameters)

stabilizer_quotient(w::WyckoffPosition{N, T}, G::SpaceGroupQuotient{N, T}) where {N, T<:Integer}

Compute the quotient of the stabilizer group (the site symmetry group) of a Wyckoff position (with respect to translations).

Arguments

• w::WyckoffPosition{N, T}: The Wyckoff position.
• G::SpaceGroupQuotient{N, T}: The space group quotient.

Returns

• The stabilizer subgroup of G for the Wyckoff position w.

Example

julia> g1=@SGE([-1 0; 0 -1]);

julia> g2=@SGE([-1 0; 0 1], [1//2, 0//1]);

julia> p2mg=SpaceGroupQuotient([g1, g2]);

julia> w1=@WP([1//4, 0], [0; 1;;]);

julia> G=stabilizer_quotient(w1, p2mg)
SpaceGroupQuotient (dimension 2, order 2)

julia> G.e
Set{SpaceGroupElement{2, Int64}} with 2 elements:
  SGE([1 0; 0 1], [0//1, 0//1])
  SGE([-1 0; 0 1], [1//2, 0//1])

is_valid(w::WyckoffPosition{N, T}, G::SpaceGroupQuotient{N, T})::Bool where {N, T<:Integer}

Check if w is a valid special Wyckoff position for the space group quotient G. Namely, check if the stabilizer group of w does not conserve more directions than the number of free parameters of w.

Arguments

• w::WyckoffPosition{N, T}: The Wyckoff position.
• G::SpaceGroupQuotient{N, T}: The space group quotient.

Returns

• true if w is a valid special Wyckoff position for the space group quotient G, false otherwise.

Example

julia> g1=@SGE([-1 0; 0 -1]);

julia> g2=@SGE([-1 0; 0 1], [1//2, 0//1]);

julia> p2mg=SpaceGroupQuotient([g1, g2]);)

julia> w1=@WP([1//4, 0], [0; 1;;])
WyckoffPosition(anchor=[1//4, 0//1]), directions=[0; 1;;])

julia> is_valid_wyckoff(w1, p2mg)
true

julia> w2=@WP([1//3, 0], [0; 1;;])
WyckoffPosition(anchor=[1//3, 0//1]), directions=[0; 1;;])

julia> is_valid_wyckoff(w2, p2mg)
false

normalize(w::WyckoffPosition{N, T}) -> Tuple{WyckoffPosition{N, T}, StaticArrays.SVector{N, T}}

Normalize a Wyckoff position to the standard unit cell.

Example

julia> w=@WP([1//1, 1//1])
WyckoffPosition(anchor=[1//1, 1//1]), no parameters)

julia> normalize(w)
(WP{2,0}, [1, 1])