API reference

AbstractSystem{D}

A D-dimensional particle system.

  IsolatedCell{D, T}

Defines a computational domain / cell describing an open system.

Implementation of a computational cell for particle systems within AtomsBase.jl. PeriodicCell specifies a parallepiped shaped cell with choice of open or periodic boundary condition in each cell vector direction.

TODO: reintroduce the original docs (failing docstest...)

Encodes a chemical species by wrapping an integer that represents the atomic number, the number of protons, and additional unspecified information as a UInt32.

Constructors for standard chemical elements

ChemicalSpecies(Z::Integer)
ChemicalSpecies(sym::Symbol) 
# for example 
ChemicalSpecies(:C)
ChemicalSpecies(6)

Constructors for isotopes

# standard carbon = C-12
ChemicalSpecies(:C)
ChemicalSpecies(:C; n_neutrons = 6)

# three equivalent constructors for C-13
ChemicalSpecies(:C; n_neutrons = 7)
ChemicalSpecies(6; n_neutrons = 7)
ChemicalSpecies(:C13)
# deuterium
ChemicalSpecies(:D) 

bounding_box(sys::AbstractSystem{D})

Return a tuple of length D of vectors of length D that describe the "box" in which the system sys is defined.

set_bounding_box!(sys::AbstractSystem{D}, bb::NTuple{D, SVector{D, L}})

periodicity(sys::AbstractSystem{D})

Return a NTuple{D, Bool} indicating whether the system is periodic along a cell vector as specified by bounding_box.

set_periodicity!(sys::AbstractSystem{D}, pbc::NTuple{D, Bool})

cell(sys::AbstractSystem)

Returns the computational cell (domain). See e.g. PeriodicCell and IsolatedCell.

set_cell!(sys, cell)

n_dimensions(::AbstractSystem)

Return number of dimensions.

atomkeys(sys::AbstractSystem)

Return the atomic properties, which are available in all atoms of the system.

hasatomkey(system::AbstractSystem, x::Symbol)

Returns true whether the passed property available in all atoms of the passed system.

Returns the chemical formula of an AbstractSystem as a string.

Build an ASCII representation of the passed atomistic structure. The string may be empty if the passed structure could not be represented (structure not supported or invalid).

position(sys::AbstractSystem, i)

Return the position of the ith particle if i is an Integer, a vector of positions if i is a vector of integers, or a vector of all positions if i == :.

The return type should be a vector of vectors each containing D elements that are <:Unitful.Length.

set_position!(sys::AbstractSystem{D}, i, x)

• If i is an integer then x is an SVector{D, L} with L <: Unitful.Length
• If i is an AbstractVector{<: Integer} or : then x is an AbstractVector{SVector{D, L}}

mass(sys::AbstractSystem, i)

Mass of a particle if i::Integer, vector of masses if i is a vector of integers or :. The elements are <: Unitful.Mass.

set_mass!(sys::AbstractSystem, i, m)

• If i is an integer then m is a Unitful.Mass
• If i is an AbstractVector{<: Integer} or : then x is an AbstractVector{<: Unitful.Mass}

species(::AbstractSystem, i)

Return the species (type, category, ...) of a particle or particles.

set_species!(sys::AbstractSystem, i, s)

• If i is an integer then s is an object describing the particle species, e.g., ChemicalSpecies
• If i is an AbstractVector{<: Integer} or : then x is an AbstractVector of species objects.

velocity(sys::AbstractSystem, i)

Return a velocity vector if i::Integer, a vector of velocities if i is a vector of integers or :. Return type should be a vector of vectors each containing D elements that are <:Unitful.Velocity. Returned value of the function may be missing.

set_velocity!(sys::AbstractSystem, i, v)

atomic_number(sys::AbstractSystem, i)
atomic_number(species)

Vector of atomic numbers in the system sys or the atomic number of a particular species / the ith species in sys.

The intention is that atomic_number carries the meaning of identifying the type of a species (e.g. the element for the case of an atom), whereas atomic_symbol may return a more unique identifier. For example for a deuterium atom this may be :D while atomic_number is still 1.

atomic_symbol(sys::AbstractSystem, i)
atomic_symbol(species)

Vector of atomic symbols in the system sys or the atomic symbol of a particular species / the ith species in sys.

The intention is that atomic_number carries the meaning of identifying the type of a species (e.g. the element for the case of an atom), whereas atomic_symbol may return a more unique identifier. For example for a deuterium atom this may be :D while atomic_number is still 1.

element_symbol(system, index)
element_symbol(species)

Return the symbols corresponding to the elements of the atoms. Note that this may be different than atomic_symbol for cases where atomic_symbol is chosen to be more specific (i.e. designate a special atom).

The element corresponding to a species/atom (or missing).

Atom(identifier::AtomId, position::AbstractVector; kwargs...)
Atom(identifier::AtomId, position::AbstractVector, velocity::AbstractVector; kwargs...)
Atom(; atomic_number, position, velocity=zeros(D)u"bohr/s", kwargs...)

Construct an atomic located at the cartesian coordinates position with (optionally) the given cartesian velocity. Note that AtomId = Union{Symbol,AbstractString,Integer,ChemicalSymbol}.

Supported kwargs include species, mass, as well as user-specific custom properties.

Atom(atom::Atom; kwargs...)

Update constructor. Construct a new Atom, by amending the data contained in the passed atom object. Supported kwargs include species, mass, as well as user-specific custom properties.

Examples

Construct a standard hydrogen atom located at the origin

julia> hydrogen = Atom(:H, zeros(3)u"Å")

and now amend its charge and atomic mass

julia> Atom(atom; mass=1.0u"u", charge=-1.0u"e_au")

FlexibleSystem(particles, bounding_box, periodicity; kwargs...)
FlexibleSystem(particles; bounding_box, periodicity, kwargs...)
FlexibleSystem(particles, cell; kwargs...)

Construct a flexible system, a versatile data structure for atomistic systems, which puts an emphasis on flexibility rather than speed.

FlexibleSystem(system; kwargs...)

Update constructor. See AbstractSystem for details.

FastSystem

A struct of arrays style prototype implementation of the AtomsBase interface.

atomic_system(atoms::AbstractVector, bounding_box, periodicity; kwargs...)

Construct a FlexibleSystem using the passed atoms and boundary box and conditions. Extra kwargs are stored as custom system properties.

Examples

Construct a hydrogen molecule in a box, which is periodic only in the first two dimensions

julia> bounding_box = [[10.0, 0.0, 0.0], [0.0, 10.0, 0.0], [0.0, 0.0, 10.0]]u"Å"
julia> pbcs = (true, true, false)
julia> hydrogen = atomic_system([:H => [0, 0, 1.]u"bohr",
                                 :H => [0, 0, 3.]u"bohr"],
                                  bounding_box, pubcs)

isolated_system(atoms::AbstractVector; kwargs...)

Construct a FlexibleSystem by placing the passed atoms into an infinite vacuum (standard setup for modelling molecular systems). Extra kwargs are stored as custom system properties.

Examples

Construct a hydrogen molecule

julia> hydrogen = isolated_system([:H => [0, 0, 1.]u"bohr", :H => [0, 0, 3.]u"bohr"])

periodic_system(atoms::AbstractVector, bounding_box; fractional=false, kwargs...)

Construct a FlexibleSystem with all boundaries of the bounding_box periodic (standard setup for modelling solid-state systems). If fractional is true, atom coordinates are given in fractional (and not in Cartesian) coordinates. Extra kwargs are stored as custom system properties.

Examples

Setup a hydrogen molecule inside periodic BCs:

julia> bounding_box = ([10.0, 0.0, 0.0]u"Å", [0.0, 10.0, 0.0]u"Å", [0.0, 0.0, 10.0]u"Å")
julia> hydrogen = periodic_system([:H => [0, 0, 1.]u"bohr",
                                   :H => [0, 0, 3.]u"bohr"],
                                  bounding_box)

Setup a silicon unit cell using fractional positions

julia> bounding_box = 10.26 / 2 * [[0, 0, 1], [1, 0, 1], [1, 1, 0]]u"bohr"
julia> silicon = periodic_system([:Si =>  ones(3)/8,
                                  :Si => -ones(3)/8],
                                 bounding_box, fractional=true)