The Spatial Box

Within Xtals.jl, the 3D space in which all Coords are located is the Box. Each Crystal has its own Box, equivalent to the unit cell of a material, containing as attributes the unit cell edge lengths (a b c), crystallographic dihedral angles (α β γ), volume, conversion factors for translating between Fractional and Cartesian coordinates, and the reciprocal (Fourier transform) vectors for the Bravais lattice.

defining a box

A Box is most conveniently constructed from its basic spatial data (a b c α β γ). For example, given the unit cell of Co-MOF-74, we can define its Box:

a = 26.13173 # Å
b = 26.13173
c = 6.722028
α = π/2 # radians
β = π/2
γ = 2*π/3
box = Box(a, b, c, α, β, γ)

A Box may also be defined by providing only the Fractional-to-Cartesian conversion matrix:

box = Box([26.1317 -13.0659 0; 0 22.6307 0; 0 0 6.72203])

To quickly get a simple unit-cubic Box, use the unit_cube function.

@info unit_cube()
#┌ Info: Bravais unit cell of a crystal.
#│       Unit cell angles α = 90.000000 deg. β = 90.000000 deg. γ = 90.000000 deg.
#│       Unit cell dimensions a = 1.000000 Å. b = 1.000000 Å, c = 1.000000 Å
#└       Volume of unit cell: 1.000000 Å³

transforming coordinates

Conversions are provided for switching between Fractional and Cartesian Coords using the Box (works for Atoms and Charges, too)

xtal = Crystal("Co-MOF-74.cif")
Cart(xtal.atoms.coords, xtal.box)
#Cart([-5.496156112249995 7.181391379950001 … 15.131970232450003 2.4686645331000063;
# 22.270234304380295 2.8331425940892103 … 0.7607701110682343 22.13256395706254;
# 1.231811631 0.32198514120000005 … 6.2082409932000004 2.2119953472])

replicating a box

For simulations in larger volumes than a single crystallograhic unit cell, the Box may be replicated along each or any of the three crystallographic axes.

replicated_box = replicate(box, (2,2,2))

exporting a box

For visualization of the unit cell boundaries, the Box may be written out to a .vtk file for use in Visit

write_vtk(box, "box.vtk")

detailed docs

Xtals.Box — Type

box = Box(a, b, c, α, β, γ, volume, f_to_c, c_to_f, reciprocal_lattice)
box = Box(a, b, c, α, β, γ)
box = Box(a, b, c) # α=β=γ=π/2 assumed.
box = Box(f_to_c)

Data structure to describe a unit cell box (Bravais lattice) and convert between fractional and Cartesian coordinates.

Attributes

a,b,c::Float64: unit cell dimensions (units: Angstroms)
α,β,γ::Float64: unit cell angles (units: radians)
Ω::Float64: volume of the unit cell (units: cubic Angtroms)
f_to_c::Array{Float64,2}: the 3x3 transformation matrix used to map fractional

coordinates to cartesian coordinates. The columns of this matrix define the unit cell axes. Columns are the vectors defining the unit cell box. units: Angstrom

c_to_f::Array{Float64,2}: the 3x3 transformation matrix used to map Cartesian

coordinates to fractional coordinates. units: inverse Angstrom

reciprocal_lattice::Array{Float64, 2}: the rows are the reciprocal lattice vectors.

This choice was made (instead of columns) for speed of Ewald Sums.

source

Xtals.unit_cube — Function

uc = unit_cube()

This function generates a unit cube, each side is 1.0 Angstrom long, and all the corners are right angles.

source

Xtals.replicate — Function

new_box = replicate(original_box, repfactors)

Replicates a Box in positive directions to construct a new Box representing a supercell. The original_box is replicated according to the factors in repfactors. Note replicate(original_box, repfactors=(1, 1, 1)) returns same Box. The new fractional coordinates as described by f_to_c and c_to_f still ∈ [0, 1].

Arguments

original_box::Box: The box that you want to replicate
repfactors::Tuple{Int, Int, Int}: The factor you want to replicate the box by

Returns

box::Box: Fully formed Box object

source

replicated_crystal = replicate(crystal, repfactors)

replicate the atoms and charges in a Crystal in positive directions to construct a new Crystal. Note replicate(crystal, (1, 1, 1)) returns the same Crystal. the fractional coordinates will be rescaled to be in [0, 1].

arguments

crystal::Crystal: The crystal to replicate
repfactors::Tuple{Int, Int, Int}: The factors by which to replicate the crystal structure in each crystallographic direction (a, b, c).

returns

replicated_frame::Crystal: replicated crystal

source

Xtals.write_vtk — Function

write_vtk(box, filename; verbose=true, center_at_origin=false)
write_vtk(framework)

Write a Box to a .vtk file for visualizing e.g. the unit cell boundary of a crystal. If a Framework is passed, the Box of that framework is written to a file that is the same as the crystal structure filename but with a .vtk extension.

Appends ".vtk" extension to filename automatically if not passed.

Arguments

box::Box: a Bravais lattice
filename::AbstractString: filename of the .vtk file output (absolute path)
framework::Framework: A framework containing the crystal structure information
center_at_origin::Bool: center box at origin if true. if false, the origin is the corner of the box.

source

Xtals.Frac — Type

fractional coordinates, a subtype of Coords.

construct by passing an Array{Float64, 2} whose columns are the coordinates.

generally, fractional coordinates should be in [0, 1] and are implicitly associated with a Box to represent a periodic coordinate system.

e.g.

f_coords = Frac(rand(3, 2))  # 2 particles
f_coords.xf                  # retreive fractional coords

source