GitHub

Unit Cells

Types and functions related to unit cells.

Unit Cells

Xtallography.basis — Function
basis(unit_cell::UnitCell) -> (Vector{Float64}, Vector{Float64}, Vector{Float64})

Return a set of basis vectors $\vec{a}, \vec{b}, \vec{c}$ for unit_ cell.

Return values

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

Examples

julia> B = basis(UnitCell([1, 0, 0], [1, 1, 0], [1, 0, 2]; centering=P_centering));

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
source
Xtallography.conventional_cell — Function
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([1, 1, 0], [1, -1, 0], [0, 1, 1]; centering=P_centering);

julia> lattice_system(unit_cell)
Triclinic()

julia> conventional_cell(unit_cell) ≈ CubicUnitCell(2.0; centering=F_centering)
true
source
Base.isapprox — Method
isapprox(x::UnitCell, y::UnitCell;
         atol::Real=0, rtol::Real=atol>0 ? 0 : √eps)

Inexact equality comparison between UnitCell. Two unit cells are approximately equal if (1) their lattice constant values are equal to within the tolerance bounds and (2) they have the same symmetry. For instance, isapprox returns true for TetragonalUnitCell if isapprox(lattice_constants(x).a - lattice_constants(y).a; atol=atol, rtol=rtol) and isapprox(lattice_constants(x).b - lattice_constants(y).b; atol=atol, rtol=rtol) and symmetry(x) == symmetry(y). Returns false if x and y have different types.

source
Xtallography.is_equivalent — Function
is_equivalent(
    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> unit_cell_ref = UnitCell([1, 0, 0], [1, 1, 0], [0, 0, 2]);

julia> unit_cell_test = TetragonalUnitCell(1.0, 2.0);

julia> is_equivalent(unit_cell_test, unit_cell_ref)
true
source
Xtallography.is_supercell — Function
is_supercell(
    unit_cell_test::UnitCell,
    unit_cell_ref::UnitCell;
    tol::Real=1e-3,
    max_index::Integer=3
) -> Bool

Check if the unit cell defined by unit_cell_test is a supercell of the unit cell defined by unit_cell_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 unit cells.

Return values

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

Examples

julia> unit_cell_ref = UnitCell([1, 0, 0], [0, 1, 0], [0, 0, 1]);

julia> is_supercell(CubicUnitCell(2), unit_cell_ref)
true

julia> is_supercell(CubicUnitCell(2.5), unit_cell_ref)
false

julia> is_supercell(UnitCell([1, 0, 0], [0, 2, 0], [0, 0, 3]), unit_cell_ref)
false
source
Xtallography.reduced_cell — Function
reduced_cell(unit_cell::UnitCell) -> UnitCell

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

Return values

primitive reduced cell

Examples

julia> reduced_cell(UnitCell([1, 0, 0], [1, 1, 0], [0, 0, 2]; centering=P_centering))
TetragonalUnitCell((a = 1.0, c = 2.0), UnitCellSymmetry(PrimitiveCentering(), Set{SymmetryElement}()))
source
Xtallography.standardize — Function
standardize(unit_cell::UnitCell) -> UnitCell

Standardize the lattice constants and centering for unit_cell.

Note

This function only enforces lattice constant constraints. It does not modify the Bravais lattice type. To find an equivalent Bravais lattice with higher symmetry (if one exists), use conventional_cell().

Note

Lattice constant standardizations are based on the conventions provided in the Table 3.1.4.1. of the International Tables for Crystallography (2016).

  • For triclinic lattices, the lattice constants are standardized using the following conventions:

    • a ≤ b ≤ c

    • all three angles are acute (Type I cell) or all three angles are non-acute (Type II cell)

    • angles sorted in increasing order when edge lengths are equal

      • α ≤ β when a = b
      • β ≤ γ when b = c
      • α ≤ β ≤ γ when a = b = c

  • For monoclinic lattices, the lattice constants are standardized using the following conventions:

    • a ≤ c

    • π/2 ≤ β ≤ π

  • For orthorhombic lattices, the lattice constants are standardized using the following conventions:

    • Primitive, body-centered, and face-centered unit cells: a ≤ b ≤ c

    • Base-C centered unit cells: a ≤ b, no constraints on c

Note

Except for monoclinic lattices, standardize() does not modify the unit cell.

For monoclinic lattices, the unit cell may be potentially modified in two ways:

  • the 2D unit cell in the plane normal to the b-axis may be reduced in order to satisfy the IUCr conventions for a, c, and β;

  • base-centered unit cells are transformed to equivalent body-centered unit cells.

Return values

unit cell with standardized lattice constants and centering

Examples

julia> unit_cell = OrthorhombicUnitCell(3, 2, 1; centering=P_centering)
OrthorhombicUnitCell((a = 3, b = 2, c = 1), UnitCellSymmetry(PrimitiveCentering(), Set{SymmetryElement}()))
julia> standardize(unit_cell)
OrthorhombicUnitCell((a = 1, b = 2, c = 3), UnitCellSymmetry(PrimitiveCentering(), Set{SymmetryElement}()))

julia> unit_cell = OrthorhombicUnitCell(3, 2, 1; centering=base_centering)
OrthorhombicUnitCell((a = 3, b = 2, c = 1), UnitCellSymmetry(BaseCentering(), Set{SymmetryElement}()))
julia> standardize(unit_cell)
OrthorhombicUnitCell((a = 2, b = 3, c = 1), UnitCellSymmetry(BaseCentering(), Set{SymmetryElement}()))
source
standardize(a::Real, b::Real, c::Real, α::Real, β::Real, γ::Real) ->
    (Real, Real, Real, Real, Real, Real)

Standardize the triclinic lattice constants for the unit cell defined by a, b, c, α, β, γ.

Note

Lattice constant standardizations are based on the conventions provided in the Table 3.1.4.1. of the International Tables for Crystallography (2016).

The lattice constants are standardized using the following conventions:

  • a ≤ b ≤ c

  • all three angles are acute (Type I cell) or all three angles are non-acute (Type II cell)

  • angles sorted in increasing order when edge lengths are equal

    • α ≤ β when a = b
    • β ≤ γ when b = c
    • α ≤ β ≤ γ when a = b = c
source
Xtallography.surface_area — Function
surface_area(unit_cell::UnitCell) -> Float64

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

Return values

surface area of the unit cell

Examples

julia> surface_area(UnitCell([1, 0, 0], [1, 1, 0], [1, 0, 1]; centering=P_centering))
7.464101615137754
source
Xtallography.symmetry — Function
symmetry(unit_cell::UnitCell) -> UnitCellSymmetry

Return the symmetry for unit_cell.

Return values

symmetry

source
Xtallography.volume — Function
volume(unit_cell::UnitCell) -> Float64

Compute the volume of the unit cell defined by unit_cell.

Return values

volume of the unit cell

Examples

julia> volume(UnitCell([1, 0, 0], [1, 1, 0], [1, 0, 2]; centering=P_centering))
2.0
source

Concrete Types

Xtallography.CubicUnitCell — Type
CubicUnitCell

Lattice constant and symmetry for a cubic unit cell

Fields

  • a: length of the edge of the unit cell

  • symmetry: unit cell symmetry

source
Xtallography.CubicUnitCell — Method
CubicUnitCell(
    a::Real;
    centering::Centering=primitive_centering,
    symmetry_elements::Union{Set,Vector,Nothing}=nothing
)

Construct a CubicUnitCell object from a set of lattice constants.

Note

No constraints are imposed on centering. The unit cell does not to be a valid Bravais lattice.

Keyword Arguments

  • centering: centering of unit cell

  • symmetry_elements: symmetry elements of crystal

source
Xtallography.HexagonalUnitCell — Type
HexagonalUnitCell

Lattice constants and symmetry for a hexagonal unit cell

Fields

  • a, c: lengths of the edges of the unit cell

  • symmetry: unit cell symmetry

source
Xtallography.HexagonalUnitCell — Method
HexagonalUnitCell(
    a::Real, c::Real;
    centering::Centering=primitive_centering,
    symmetry_elements::Union{Set,Vector,Nothing}=nothing
)

Construct a HexagonalUnitCell object from a set of lattice constants.

Note

No constraints are imposed on centering. The unit cell does not to be a valid Bravais lattice.

Keyword Arguments

  • centering: centering of unit cell

  • symmetry_elements: symmetry elements of crystal

source
Xtallography.OrthorhombicUnitCell — Type
OrthorhombicUnitCell

Lattice constants and symmetry for an orthorhombic unit cell

Fields

  • a, b, c: lengths of the edges of the unit cell

  • symmetry: unit cell symmetry

source
Xtallography.OrthorhombicUnitCell — Method
OrthorhombicUnitCell(
    a::Real, b::Real, c::Real;
    centering::Centering=primitive_centering,
    symmetry_elements::Union{Set,Vector,Nothing}=nothing
)

Construct a OrthorhombicUnitCell object from a set of lattice constants.

Keyword Arguments

  • centering: centering of unit cell

  • symmetry_elements: symmetry elements of crystal

source
Xtallography.MonoclinicUnitCell — Type
MonoclinicUnitCell

Lattice constants for a monoclinic unit cell

Fields

  • a, b, c: lengths of the edges of the unit cell

  • β: angle between edges of the unit cell in the plane of the face of the unit cell where the edges are not orthogonal

  • symmetry: unit cell symmetry

source
Xtallography.MonoclinicUnitCell — Method
MonoclinicUnitCell(
    a::Real, b::Real, c::Real, β::Real;
    centering::Centering=primitive_centering,
    symmetry_elements::Union{Set,Vector,Nothing}=nothing
)

Construct a MonoclinicUnitCell object from a set of lattice constants.

Note

No constraints are imposed on centering. The unit cell does not to be a valid Bravais lattice.

Keyword Arguments

  • centering: centering of unit cell

  • symmetry_elements: symmetry elements of crystal

source
Xtallography.RhombohedralUnitCell — Type
RhombohedralUnitCell

Lattice constants for a rhombohedral unit cell

Fields

  • a: length of the edge of the unit cell

  • α: angle between edges of the unit cell

  • symmetry: unit cell symmetry

source
Xtallography.RhombohedralUnitCell — Method
RhombohedralUnitCell(
    a::Real, α::Real;
    centering::Centering=primitive_centering,
    symmetry_elements::Union{Set,Vector,Nothing}=nothing
)

Construct a RhombohedralUnitCell object from a set of lattice constants.

Note

No constraints are imposed on centering. The unit cell does not to be a valid Bravais lattice.

Keyword Arguments

  • centering: centering of unit cell

  • symmetry_elements: symmetry elements of crystal

source
Xtallography.TetragonalUnitCell — Type
TetragonalUnitCell

Lattice constants and symmetry for a tetragonal unit cell

Fields

  • a, c: lengths of the edges of the unit cell

  • symmetry: unit cell symmetry

source
Xtallography.TetragonalUnitCell — Method
TetragonalUnitCell(
    a::Real, c::Real;
    centering::Centering=primitive_centering,
    symmetry_elements::Union{Set,Vector,Nothing}=nothing
)

Construct a TetragonalUnitCell object from a set of lattice constants.

Note

No constraints are imposed on centering. The unit cell does not to be a valid Bravais lattice.

Keyword Arguments

  • centering: centering of unit cell

  • symmetry_elements: symmetry elements of crystal

source
Xtallography.TriclinicUnitCell — Type
TriclinicUnitCell

Lattice constants and symmetry for a triclinic unit cell

Fields

  • a, b, c: lengths of the edges of the unit cell

  • α, β, γ: angles between edges of the unit cell unit cell

  • symmetry: unit cell symmetry

source
Xtallography.TriclinicUnitCell — Method
TriclinicUnitCell(
    a::Real, b::Real, c::Real, α::Real, β::Real, γ::Real;
    centering::Centering=primitive_centering,
    symmetry_elements::Union{Set,Vector,Nothing}=nothing,
    check_angle_constraints::Bool=true
)

Construct a TriclinicUnitCell object from a set of lattice constants.

Note

No constraints are imposed on centering. The unit cell does not to be a valid Bravais lattice.

Keyword Arguments

  • centering: centering of unit cell

  • symmetry_elements: symmetry elements of crystal

  • check_angle_constraints: if true, throw an error if α, β, and γ do not satisfy the angle constraints for a valid triclinic unit cell. Otherwise, ignore angle constraints.

source

Lattice-Specific Functions

Triclinic Unit Cell Functions

Xtallography.convert_to_mC — Function
convert_to_mC(
    unit_cell::TriclinicUnitCell
) -> MonoclinicUnitCell

Attempt to convert the triclinic unit cell defined by unit_cell 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 unit_cell is not equivalent to a base-centered monoclinic unit cell.

source
Xtallography.convert_to_mI — Function
convert_to_mI(unit_cell::TriclinicUnitCell) -> MonoclinicUnitCell

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

Return values

unit cell for the equivalent body-centered monoclinic unit cell if one exists

Exceptions

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

source
Xtallography.convert_to_mP — Function
convert_to_mP(unit_cell::TriclinicUnitCell) -> MonoclinicUnitCell

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

Return values

unit cell for the equivalent primitive monoclinic unit cell if one exists

Exceptions

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

source
Xtallography.is_triclinic_type_I_cell — Function
is_triclinic_type_I_cell(α::Real, β::Real, γ::Real) -> Bool

Determine whether the unit cell having lattice angles α, β, and γ is a Type I or Type II cell.

A triclinic unit cell is Type I if the product of the cosines of its lattice angles is positive:

\[\cos{α} \cos{β} \cos{γ} > 0.\]

Otherwise, the triclinic unit cell is Type II.

Return values

true if α, β, γ are lattice angles for a Type I cell; false if α, β, γ are lattice angles for a Type II cell

source
is_triclinic_type_I_cell(unit_cell::TriclinicUnitCell) -> Bool

Determine whether the unit cell defined by unit_cell 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 unit_cell defines a Type I cell; false if unit_cell defines a Type II cell

source
Xtallography.satisfies_triclinic_angle_constraints — Function
satisfies_triclinic_angle_constraints(α::Real, β::Real, γ::Real) -> Bool

Determine whether α, β, and γ satisfy the angle constraints for a triclinic unit cell:

  • $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
source

Monoclinic Unit Cell Functions

Xtallography.convert_to_base_centering — Function
convert_to_base_centering(unit_cell::MonoclinicUnitCell) -> MonoclinicUnitCell

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> unit_cell = MonoclinicUnitCell(1.0, 2.0, 3.0, 3π / 5);

julia> base_centered_unit_cell = convert_to_base_centering(unit_cell);

julia> lattice_constants_ = lattice_constants(base_centered_unit_cell);

julia> lattice_constants_.a ≈ 2.8541019662496847
true

julia> lattice_constants_.b ≈ 2
true

julia> lattice_constants_.c ≈ 1
true

julia> lattice_constants_.β ≈ 1.5963584695539381
true
source
Xtallography.convert_to_body_centering — Function
convert_to_body_centering(unit_cell::MonoclinicUnitCell) -> MonoclinicUnitCell

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

Return values

unit cell of equivalent body-centered unit cell

Examples

julia> unit_cell = MonoclinicUnitCell(1.0, 2.0, 3.0, 3π / 5);

julia> body_centered_unit_cell = convert_to_body_centering(unit_cell);

julia> lattice_constants_ = lattice_constants(body_centered_unit_cell);

julia> lattice_constants_.a ≈ 2.8541019662496847
true

julia> lattice_constants_.b ≈ 2
true

julia> lattice_constants_.c ≈ 3
true

julia> lattice_constants_.β ≈ 2.8018712454717734
true
source

Unit Cell Deltas

Xtallography.Δlattice_constants — Function
Δlattice_constants(unit_cell::UnitCell) -> NamedTuple

lattice_constant_deltas(unit_cell::UnitCell) -> NamedTuple

Return the lattice constant deltas for unit_cell.

Return values

lattice constant deltas

source
Base.isapprox — Method
isapprox(Δx::UnitCellDelta, Δy::UnitCellDelta;
         atol::Real=0, rtol::Real=atol>0 ? 0 : √eps)

Inexact equality comparison between UnitCellDelta. Two unit cell deltas are approximately equal if all lattice constant values are within the tolerance bounds. For instance, isapprox returns true for TetragonalUnitCellDelta if isapprox(Δlattice_constants(Δx).Δa - Δlattice_constants(Δy).Δa; atol=atol, rtol=rtol) and isapprox(Δlattice_constants(Δx).Δb - Δlattice_constants(Δy).Δb; atol=atol, rtol=rtol). Returns false if Δx and Δy have different types.

source

Concrete Types

Xtallography.MonoclinicUnitCellDelta — Type
MonoclinicUnitCellDelta

Lattice constant deltas for a monoclinic unit cell

Fields

  • Δa, Δb, Δc: deltas of the lengths of the edges of the unit cell

  • Δβ: delta of the angle between edges of the unit cell in the plane of the face of the unit cell where the edges are not orthogonal

source
Xtallography.RhombohedralUnitCellDelta — Type
RhombohedralUnitCellDelta

Lattice constant deltas for a rhombohedral unit cell

Fields

  • Δa: delta of the length of the edge of the unit cell

  • Δα: delta of angle between edges of the unit cell

source
Xtallography.TriclinicUnitCellDelta — Type
TriclinicUnitCellDelta

Lattice constant deltas for a triclinic unit cell

Fields

  • Δa, Δb, Δc: deltas of the lengths of the edges of the unit cell

  • Δα, Δβ, Δγ: deltas of the angles between edges of the unit cell

source
Xtallography.TriclinicUnitCellDelta — Method
TriclinicUnitCellDelta(Δa::Real, Δb::Real, Δc::Real, Δα::Real, Δβ::Real, Δγ::Real)

Construct a TriclinicUnitCellDelta object from a set of lattice constant deltas.

source

Unit Cell Symmetry

Xtallography.centering — Method
centering(symmetry::UnitCellSymmetry) -> Centering

Return the centering of symmetry.

Return values

centering

source
Xtallography.symmetry_elements — Function
symmetry_elements(symmetry::UnitCellSymmetry) -> Set{SymmetryElement}

Return the symmetry elements of symmetry.

Return values

symmetry elements

source
symmetry_elements(unit_cell::UnitCell) -> Vector{SymmetryElement}

Return the symmetry elements of unit_cell.

Return values

symmetry elements

source