AbstractSystem{D}

A D-dimensional system.

AbstractSystem(system::AbstractSystem; kwargs...)

Update constructor. Construct a new system where one or more properties are changed, which are given as kwargs. A subtype of AbstractSystem is returned, by default a FlexibleSystem, but depending on the type of the passed system this might differ.

Supported kwargs include particles, atoms, bounding_box and boundary_conditions as well as user-specific custom properties.

Examples

Change the bounding box and the atoms of the passed system

julia> AbstractSystem(system; bounding_box= ..., atoms = ... )

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

Update constructor. Construct a new Atom, by amending the data contained in the passed atom object. Supported kwargs include atomic_symbol, atomic_number, atomic_mass, charge, multiplicity 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; atomic_mass=1.0u"u", charge=-1.0u"e_au")

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}.

Supported kwargs include atomic_symbol, atomic_number, atomic_mass, charge, multiplicity as well as user-specific custom properties.

AtomView{S<:AbstractSystem}

Species type for atoms of systems implemented as struct-of-arrays. Can be queried with the same API than for other species, like Atom.

See FastSystem for an example of system using AtomView as its species type.

Example

julia> system = FastSystem(atoms, box, boundary_conditions);

julia> atom = system[2]
AtomView(C, atomic_number = 6, atomic_mass = 12.011 u):
    position          : [0.75,0.75,0.75]u"Å"

julia> atom isa AtomView{typeof(system)}
true

julia> atomic_symbol(atom)
:C

FlexibleSystem(system; kwargs...)

Update constructor. See AbstractSystem for details.

FlexibleSystem(particles, bounding_box, boundary_conditions; kwargs...)
FlexibleSystem(particles; bounding_box, boundary_conditions, kwargs...)

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

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

Vector of atomic masses in the system sys or the atomic mass of a particular species / the ith species in sys. The elements are <: Unitful.Mass.

atomic_number(sys::AbstractSystem)
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)
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.

atomic_system(atoms::AbstractVector, bounding_box, boundary_conditions; 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> boundary_conditions = [Periodic(), Periodic(), DirichletZero()]
julia> hydrogen = atomic_system([:H => [0, 0, 1.]u"bohr",
                                 :H => [0, 0, 3.]u"bohr"],
                                  bounding_box, boundary_conditions)

atomkeys(sys::AbstractSystem)

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

boundary_conditions(sys::AbstractSystem{D})

Return a vector of length D of BoundaryCondition objects, one for each direction described by bounding_box(sys).

bounding_box(sys::AbstractSystem{D})

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

Returns the chemical formula of an AbstractSystem as a string.

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

element_symbol(system)
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).

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

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

Returns true if the given system is infinite

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"])

n_dimensions(::AbstractSystem)
n_dimensions(atom)

Return number of dimensions.

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], [0.0, 10.0, 0.0], [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)

Return vector indicating whether the system is periodic along a dimension.

Suggested function to print AbstractSystem objects to screen

species_type(::AbstractSystem)

Return the type used to represent a species or atom.

velocity(sys::AbstractSystem{D})
velocity(sys::AbstractSystem, index)
velocity(species)

Return a vector of velocities of every particle in the system sys. Return type should be a vector of vectors each containing D elements that are <:Unitful.Velocity. If an index is passed or the action is on a species, return only the velocity of the referenced species. Returned value of the function may be missing.

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{D})
position(sys::AbstractSystem, index)
position(species)

Return a vector of positions of every particle in the system sys. Return type should be a vector of vectors each containing D elements that are <:Unitful.Length. If an index is passed or the action is on a species, return only the position of the referenced species / species on that index.