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 name as max 4 characters.

The name variable can be used as atom name in PDB format or some other way to mark same kind of atoms from one another.

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)

Constructors for names

ChemicalSpecies(:C; atom_name=:MyC)
ChemicalSpecies(:C13; atom_name=:MyC)

Comparisons with different isotopes and names

# true
ChemicalSpecies(:C13) == ChemicalSpecies(:C)

# false
ChemicalSpecies(:C12) == ChemicalSpecies(:C13)

# true
ChemicalSpecies(:C; atom_name=:MyC) == ChemicalSpecies(:C)

# true
ChemicalSpecies(:C12; atom_name=:MyC) == ChemicalSpecies(:C12)

# false
ChemicalSpecies(:C; atom_name=:MyC) == ChemicalSpecies(:C12)

# true
ChemicalSpecies(:C12; atom_name=:MyC) == ChemicalSpecies(:C)

# true
ChemicalSpecies(:C; atom_name=:MyC) == ChemicalSpecies(:C12; atom_name=:MyC)

cell_vectors(sys::AbstractSystem{D})

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

set_cell_vectors!(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 cell_vectors.

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.

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

Return atomic name (Symbol) for species or vector of names for sys.

Defaults to atomic_symbol, if name field is zero or not defined.

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, cell_vectors, periodicity; kwargs...)
FlexibleSystem(particles; cell_vectors, 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, cell_vectors, 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> cell_vectors = [[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"],
                                  cell_vectors, pbcs)

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, box; fractional=false, kwargs...)

Construct a FlexibleSystem with all boundaries of the 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> cell_vectors = ([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"],
                                  cell_vectors)

Setup a silicon unit cell using fractional positions

julia> 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],
                                 box, fractional=true)