Functions

is_bravais_lattice(lattice_system::LatticeSystem, centering::Centering) -> Bool

is_bravais_lattice(unit_cell::UnitCell) -> Bool

Determine if the unit cell defined by unit_cell or lattice_system and centering is a valid Bravais lattice type.

Return values

• true if lattice_system and centering define a valid Bravais lattice type; false otherwise

Examples

julia> is_bravais_lattice(cubic, body_centered)
true

julia> is_bravais_lattice(cubic, base_centered)
false

julia> is_bravais_lattice(UnitCell(TetragonalLatticeConstants(2, 3), primitive))
true

julia> is_bravais_lattice(UnitCell(TetragonalLatticeConstants(2, 3), face_centered))
false

basis(unit_cell::UnitCell) -> (Vector{Float64}, Vector{Float64}, Vector{Float64})

basis(
    lattice_constants::LatticeConstants
) -> (Vector{Float64}, Vector{Float64}, Vector{Float64})

Return a set of basis vectors $\vec{a}, \vec{b}, \vec{c}$ for the unit cell defined by unit_cell or lattice_constants.

Return values

• basis vectors $\vec{a}$, $\vec{b}$, $\vec{c}$

Examples

julia> B = basis(UnitCell(LatticeConstants([1, 0, 0], [1, 1, 0], [1, 0, 2]), primitive));

julia> B[1] ≈ [1.0, 0.0, 0.0]
true
julia> B[2] ≈ [1.0, 1.0, 0.0]
true
julia> B[3] ≈ [1.0, 0.0, 2.0]
true

julia> B = basis(LatticeConstants([1, 0, 0], [1, 1, 0], [1, 0, 2]));

julia> B[1] ≈ [1.0, 0.0, 0.0]
true
julia> B[2] ≈ [1.0, 1.0, 0.0]
true
julia> B[3] ≈ [1.0, 0.0, 2.0]
true

surface_area(unit_cell::UnitCell) -> Float64

surface_area(lattice_constants::LatticeConstants) -> Float64

Compute the surface area of the unit cell defined by unit_cell or lattice_constants.

Return values

• surface area of the unit cell

Examples

julia> surface_area(UnitCell(LatticeConstants([1, 0, 0], [1, 1, 0], [1, 0, 1]), primitive))
7.464101615137754

julia> surface_area(LatticeConstants([1, 0, 0], [1, 1, 0], [1, 0, 1]))
7.464101615137754

volume(unit_cell::UnitCell) -> Float64

volume(lattice_constants::LatticeConstants) -> Float64

Compute the volume of the unit cell defined by unit_cell or lattice_constants.

Return values

• volume of the unit cell

Examples

julia> volume(UnitCell(LatticeConstants([1, 0, 0], [1, 1, 0], [1, 0, 2]), primitive))
2.0

julia> volume(LatticeConstants([1, 0, 0], [1, 1, 0], [1, 0, 2]))
2.0

isapprox(x::LatticeConstants, y::LatticeConstants;
         atol::Real=0, rtol::Real=atol>0 ? 0 : √eps)

Inexact equality comparison between LatticeConstants. Two sets of lattice constants compare equal if all lattice constant values are within the tolerance bounds. For instance, isapprox returns true for TetragonalLatticeConstants if isapprox(x.a - y.a; atol=atol, rtol=rtol) and isapprox(x.b - y.b; atol=atol, rtol=rtol). Returns false if x and y have different types.

conventional_cell(unit_cell::UnitCell) -> UnitCell

Return the IUCr conventional cell that is equivalent to unit_cell.

Return values

• IUCr conventional cell for unit_cell

Examples

julia> unit_cell = UnitCell(LatticeConstants([1, 1, 0], [1, -1, 0], [0, 1, 1]), primitive);

julia> lattice_system(unit_cell.lattice_constants)
Triclinic()

julia> conventional_cell(unit_cell) ≈ UnitCell(CubicLatticeConstants(2.0), FaceCentered())
true

is_equivalent_unit_cell(
    unit_cell_test::UnitCell,
    unit_cell_ref::UnitCell;
    atol::Real=1e-3,
    rtol::Real=atol > 0 ? 0 : 1e-3,
    p::Real=2,
) -> Bool

Check if the unit cell defined by unit_cell_test is equivalent to the unit cell defined by unit_cell_ref.

Keyword Arguments

• atol: tolerance of the absolute difference between the reduced unit cells defined by unit_cell_test and unit_cell_ref.

• rtol: tolerance of the relative difference between the reduced unit cells defined by unit_cell_test and unit_cell_ref.

Return values

• true if the test unit cell is equivalent to the reference unit cell; false otherwise

Examples

julia> lattice_constants_ref = LatticeConstants([1, 0, 0], [1, 1, 0], [0, 0, 2]);

julia> unit_cell_ref = UnitCell(lattice_constants_ref, body_centered);

julia> lattice_constants_test = TetragonalLatticeConstants(1.0, 2.0);

julia> unit_cell_test = UnitCell(lattice_constants_test, body_centered);

julia> is_equivalent_unit_cell(unit_cell_test, unit_cell_ref)
true

is_equivalent_unit_cell(
    lattice_constants_test::LatticeConstants,
    lattice_constants_ref::LatticeConstants;
    atol::Real=1e-3,
    rtol::Real=atol > 0 ? 0 : 1e-3,
) -> Bool

Check if the primitive unit cell defined by lattice_constants_test is equivalent to the unit cell defined by lattice_constants_ref.

Keyword Arguments

• tol: absolute tolerance of the deviation between the reduced unit cells defined by lattice_constants_test and lattice_constants_ref.

Return values

• true if the test unit cell is equivalent to the reference unit cell; false otherwise

Examples

julia> lattice_constants_ref = LatticeConstants([1, 0, 0], [1, 1, 0], [0, 0, 2]);

julia> is_equivalent_unit_cell(TetragonalLatticeConstants(1.0, 2.0), lattice_constants_ref)
true

is_supercell(
    lattice_constants_test::LatticeConstants,
    lattice_constants_ref::LatticeConstants;
    tol::Real=1e-3,
    max_index::Integer=3
) -> Bool

Check if the unit cell defined by lattice_constants_test is a supercell of the unit cell defined by lattice_constants_ref.

Keyword Arguments

• tol: absolute tolerance of the deviation between test unit cell and supercells of the reference unit cell

• max_index: maximum multiple of the basis vectors of the reference unit cell to include when checking whether the test unit cell is a supercell of the reference unit cell

  Note

  max_index is ignored for Cubic lattice systems.

Return values

• true if the test unit cell is a supercell of the reference unit cell; false otherwise

Examples

julia> lattice_constants_ref = LatticeConstants([1, 0, 0], [0, 1, 0], [0, 0, 1]);

julia> is_supercell(CubicLatticeConstants(2), lattice_constants_ref)
true

julia> is_supercell(CubicLatticeConstants(2.5), lattice_constants_ref)
false

julia> is_supercell(LatticeConstants([1, 0, 0], [0, 2, 0], [0, 0, 3]),
                    lattice_constants_ref)
false

reduced_cell(unit_cell::UnitCell) -> UnitCell

Compute the primitive reduced cell for the lattice defined by unit_cell. The Selling-Delaunay reduction algorithm is used to compute the reduced basis.

Return values

• primitive reduced cell

Examples

julia> reduced_cell(UnitCell(LatticeConstants([1, 0, 0], [1, 1, 0], [0, 0, 2]), primitive))
UnitCell(TetragonalLatticeConstants(1.0, 2.0), Primitive())

standardize(unit_cell::UnitCell) -> LatticeConstants

Standardize the lattice constants and centering for unit_cell.

Return values

• unit cell with standardized lattice constants and centering

Examples

julia> unit_cell = UnitCell(OrthorhombicLatticeConstants(3, 2, 1), primitive)
UnitCell(OrthorhombicLatticeConstants(3.0, 2.0, 1.0), Primitive())
julia> standardize(unit_cell)
UnitCell(OrthorhombicLatticeConstants(1.0, 2.0, 3.0), Primitive())

julia> unit_cell = UnitCell(OrthorhombicLatticeConstants(3, 2, 1), base_centered)
UnitCell(OrthorhombicLatticeConstants(3.0, 2.0, 1.0), BaseCentered())
julia> standardize(unit_cell)
UnitCell(OrthorhombicLatticeConstants(2.0, 3.0, 1.0), BaseCentered())

standardize(
    lattice_constants::LatticeConstants, centering::Centering
) -> (LatticeConstants, Centering)

Standardize the lattice constants and centering for the unit cell defined by lattice_constants and centering.

Return values

• standardized lattice constants and centering

Examples

julia> standardize(OrthorhombicLatticeConstants(3, 2, 1), primitive)
(OrthorhombicLatticeConstants(1.0, 2.0, 3.0), Primitive())

julia> standardize(OrthorhombicLatticeConstants(3, 2, 1), base_centered)
(OrthorhombicLatticeConstants(2.0, 3.0, 1.0), BaseCentered())

standardize(lattice_constants::LatticeConstants) -> LatticeConstants

Standardize the lattice constants the primitive unit cell defined by lattice_constants.

Return values

• standardized lattice constants for primitive unit cell

Examples

julia> standardize(OrthorhombicLatticeConstants(3, 2, 1))
OrthorhombicLatticeConstants(1.0, 2.0, 3.0)

lattice_system(lattice_constants::LatticeConstants) -> LatticeSystem

lattice_system(Δlattice_constants::LatticeConstantDeltas) -> LatticeSystem

lattice_system(unit_cell::UnitCell) -> LatticeSystem

Return the lattice system for a set of lattice_constants, Δlattice_constants or unit_cell.

Return values

• lattice system

Examples

```jldoctest julia> lattice_system(HexagonalLatticeConstants(2, 4)) Hexagonal()

julia> lattice_system(CubicLatticeConstants(2)) Cubic()

julia> latticesystem(UnitCell(OrthorhombicLatticeConstants(2, 3, 4), facecentered)) Orthorhombic()

isapprox(Δx::LatticeConstantDeltas, Δy::LatticeConstantDeltas;
         atol::Real=0, rtol::Real=atol>0 ? 0 : √eps)

Inexact equality comparison between LatticeConstantDeltas. Two sets of lattice constant deltas compare equal if all lattice constant values are within the tolerance bounds. For instance, isapprox returns true for TetragonalLatticeConstantDeltas if isapprox(Δx.a - Δy.a; atol=atol, rtol=rtol) and isapprox(Δx.b - Δy.b; atol=atol, rtol=rtol). Returns false if Δx and Δy have different types.

convert(::Type{<:Array}, lattice_constants::LatticeConstants)

Convert lattice_constants to an Array. For each lattice system, the order of lattice constants in the array are in the conventional order:

• triclinic: [a, b, c, α, β, γ]
• monoclinic: [a, b, c, β]
• orthorhombic: [a, b, c]
• tetragonal: [a, c]
• rhombohedral: [a, α]
• hexagonal: [a, c]
• cubic: [a]

convert(::Type{<:Array}, Δlattice_constants::LatticeConstantDeltas)

Convert Δlattice_constants to an Array. For each lattice system, the order of lattice constant deltas in the array are in the conventional order:

• triclinic: [Δa, Δb, Δc, Δα, Δβ, Δγ]
• monoclinic: [Δa, Δb, Δc, Δβ]
• orthorhombic: [Δa, Δb, Δc]
• tetragonal: [Δa, Δc]
• rhombohedral: [Δa, Δα]
• hexagonal: [Δa, Δc]
• cubic: [Δa]

convert_to_mP(
    lattice_constants::TriclinicLatticeConstants
) -> MonoclinicLatticeConstants

Attempt to convert the triclinic unit cell defined by lattice_constants to an equivalent primitive monoclinic unit cell.

Return values

• lattice constants for the equivalent primitive monoclinic unit cell if one exists

Exceptions

Throws an ErrorException if the triclinic unit cell defined by lattice_constants is not equivalent to a primitive monoclinic unit cell.

convert_to_mI(
    lattice_constants::TriclinicLatticeConstants
) -> MonoclinicLatticeConstants

Attempt to convert the triclinic unit cell defined by lattice_constants to an equivalent body-centered monoclinic unit cell.

Return values

• lattice constants for the equivalent body-centered monoclinic unit cell if one exists; nothing otherwise

Exceptions

Throws an ErrorException if the triclinic unit cell defined by lattice_constants is not equivalent to a body-centered monoclinic unit cell.

convert_to_mC(
    lattice_constants::TriclinicLatticeConstants
) -> MonoclinicLatticeConstants

Attempt to convert the triclinic unit cell defined by lattice_constants to an equivalent base-centered monoclinic unit cell.

Return values

• lattice constants for the equivalent base-centered monoclinic unit cell if one exists; nothing otherwise

  Warn

  Returned lattice constants are not guaranteed to be standardized.

Exceptions

Throws an ErrorException if the triclinic unit cell defined by lattice_constants is not equivalent to a base-centered monoclinic unit cell.

is_triclinic_type_I_cell(lattice_constants::TriclinicLatticeConstants) -> Bool

Determine whether the unit cell defined by lattice_constants is a Type I or Type II cell.

A triclinic unit cell is Type I if the product of the dot products of all pairs of basis vectors for unit cell is positive:

\[(\vec{a} \cdot \vec{b})(\vec{b} \cdot \vec{c})(\vec{c} \cdot \vec{a}) > 0.\]

Otherwise, the triclinic unit cell is Type II.

Return values

• true if lattice_constants defines a Type I cell; false if lattice_constants defines a Type II cell.

satisfies_triclinic_angle_constraints(α::Real, β::Real, γ::Real) -> Bool

Determine whether α, β, and γ satisfy the angle constraints for triclinic lattices:

• $0 < α + β + γ < 2π$
• $0 < α + β - γ < 2π$
• $0 < α - β + γ < 2π$
• $0 < -α + β + γ < 2π$

Return values

• true if (α, β, γ) form a valid triple of angles for a triclinic unit cell; false otherwise

Examples

julia> satisfies_triclinic_angle_constraints(π/4, π/5, π/6)
true
julia> satisfies_triclinic_angle_constraints(3π/4, 4π/5, 5π/6)
false

convert_to_base_centering(
    lattice_constants::MonoclinicLatticeConstants
) -> MonoclinicLatticeConstants

Convert a body-centered monoclinic unit cell to base-centered monoclinic unit cell.

Return values

• lattice constants for equivalent base-centered unit cell

Examples

julia> lattice_constants = MonoclinicLatticeConstants(1.0, 2.0, 3.0, 3π / 5);

julia> base_centered_lattice_constants = convert_to_base_centering(lattice_constants);

julia> base_centered_lattice_constants.a ≈ 2.8541019662496847
true

julia> base_centered_lattice_constants.b ≈ 2
true

julia> base_centered_lattice_constants.c ≈ 1
true

julia> base_centered_lattice_constants.β ≈ 1.5963584695539381
true

convert_to_body_centering(
    lattice_constants::MonoclinicLatticeConstants
) -> MonoclinicLatticeConstants

Convert a base-centered monoclinic unit cell to body-centered monoclinic unit cell.

Return values

• lattice constants for equivalent body-centered unit cell

Examples

julia> lattice_constants = MonoclinicLatticeConstants(1.0, 2.0, 3.0, 3π / 5);

julia> body_centered_lattice_constants = convert_to_body_centering(lattice_constants);

julia> body_centered_lattice_constants.a ≈ 2.8541019662496847
true

julia> body_centered_lattice_constants.b ≈ 2
true

julia> body_centered_lattice_constants.c ≈ 3
true

julia> body_centered_lattice_constants.β ≈ 2.8018712454717734
true

asin_(x::Real; atol::Real=√eps(1.0)) -> Float64

Compute the arcsin of x with a tolerance for values of x that are slightly outside of the mathematical domain [-1, 1].

When the value of x is approximately equal to 1, asin_(x) returns π / 2; when the value of x is approximately equal to -1, asin_(x) returns -π / 2.

Return values

• arcsin of x

Examples

julia> asin_(0.5) ≈ π / 6
true
julia> asin_(1 + eps(1.0)) == π / 2
true
julia> asin_(-1 - eps(1.0)) == -π / 2
true

acos_(x::Real; atol::Real=√eps(1.0)) -> Float64

Compute the arccos of x with a tolerance for values of x that are slightly outside of the mathematical domain [-1, 1].

When the value of x is approximately equal to 1, acos_(x) returns 0; when the value of x is approximately equal to -1, acos_(x) returns π.

Return values

• arccos of x

Examples

julia> acos_(0.5) ≈ π / 3
true
julia> acos_(1 + eps(1.0)) == 0
true
julia> acos_(-1 - eps(1.0)) == π
true

is_basis(v1::Vector{Real}, v2::Vector{Real}, v3::Vector{Real}) -> Bool

Determine if the vectors v1, v2, and v3 are a basis for a three-dimensional lattice (i.e., v1, v2, and v3 are linearly independent).

Return values

• true if v1, v2, and v3 are a basis; false otherwise

Examples

julia> is_basis([1, 0, 0], [1, 1, 0], [1, 0, 1])
true

julia> is_basis([1, 0, 0], [1, 1, 0], [1, -1, 0])
false

surface_area(v1::Vector{Real}, v2::Vector{Real}, v3::Vector{Real}) -> Float64

Compute the surface area of the parallelipiped defined by the vectors v1, v2, and v3.

Return values

• surface area of the parallelipiped defined by v1, v2, and v3

Examples

julia> surface_area([1, 0, 0], [1, 1, 0], [1, 0, 1])
7.464101615137754

volume(v1::Vector{Real}, v2::Vector{Real}, v3::Vector{Real}) -> Float64

Compute the volume of the parallelipiped defined by the vectors v1, v2, and v3.

Return values

• volume of the parallelipiped defined by v1, v2, and v3

Examples

julia> volume([1, 0, 0], [1, 1, 0], [1, 0, 2])
2.0