From 70b9a393db8b06ee5311fd983b5cc8ef611b56bf Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Thu, 21 Nov 2024 05:53:47 +0000 Subject: [PATCH] build based on f2d862d --- dev/.documenter-siteinfo.json | 2 +- dev/apireference/index.html | 39 +++++++++++++++++++++++++-------- dev/implementations/index.html | 2 +- dev/index.html | 2 +- dev/interface/index.html | 2 +- dev/objects.inv | Bin 1030 -> 1035 bytes dev/search_index.js | 2 +- dev/tutorial/index.html | 6 ++--- dev/utilities/index.html | 2 +- 9 files changed, 39 insertions(+), 18 deletions(-) diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index ad3ad34..33f2c07 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-11-21T05:50:31","documenter_version":"1.8.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-11-21T05:53:43","documenter_version":"1.8.0"}} \ No newline at end of file diff --git a/dev/apireference/index.html b/dev/apireference/index.html index 65dab1e..dc5aa55 100644 --- a/dev/apireference/index.html +++ b/dev/apireference/index.html @@ -1,5 +1,5 @@ -Reference · AtomsBase.jl
GitHub

API reference

Index

Types

AtomsBase.PeriodicCell — Type

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.

source
AtomsBase.ChemicalSpecies — Type

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)
+Reference · AtomsBase.jl
GitHub
API reference
Index
Types
AtomsBase.PeriodicCell — Type
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.
source
AtomsBase.ChemicalSpecies — Type
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)
@@ -12,21 +12,42 @@
 ChemicalSpecies(6; n_neutrons = 7)
 ChemicalSpecies(:C13)
 # deuterium
-ChemicalSpecies(:D) 
source
System properties
AtomsBase.cell_vectors — Function
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.
source
AtomsBase.periodicity — Function
periodicity(sys::AbstractSystem{D})
Return a NTuple{D, Bool} indicating whether the system is periodic along a cell vector as specified by cell_vectors.
source
AtomsBase.cell — Function
cell(sys::AbstractSystem)
Returns the computational cell (domain).  See e.g. PeriodicCell and IsolatedCell.
source
AtomsBase.atomkeys — Function
atomkeys(sys::AbstractSystem)
Return the atomic properties, which are available in all atoms of the system.
source
AtomsBase.hasatomkey — Function
hasatomkey(system::AbstractSystem, x::Symbol)
Returns true whether the passed property available in all atoms of the passed system.
source
AtomsBase.visualize_ascii — Function
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).
source
Species / atom properties
Base.position — Function
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.
source
AtomsBase.set_position! — Function
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}}
source
AtomsBase.mass — Function
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.
source
AtomsBase.set_mass! — Function
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}
source
AtomsBase.species — Function
species(::AbstractSystem, i)
Return the species (type, category, ...) of a particle or particles.
source
AtomsBase.set_species! — Function
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.
source
AtomsBase.velocity — Function
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.
source
AtomsBase.atomic_number — Function
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.
source
AtomsBase.atomic_symbol — Function
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.
source
AtomsBase.element_symbol — Function
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).
source
Prototype Implementation
AtomsBase.Atom — Type
Atom(identifier::AtomId, position::AbstractVector; kwargs...)
+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)
source
System properties
AtomsBase.cell_vectors — Function
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.
source
AtomsBase.periodicity — Function
periodicity(sys::AbstractSystem{D})
Return a NTuple{D, Bool} indicating whether the system is periodic along a cell vector as specified by cell_vectors.
source
AtomsBase.cell — Function
cell(sys::AbstractSystem)
Returns the computational cell (domain).  See e.g. PeriodicCell and IsolatedCell.
source
AtomsBase.atomkeys — Function
atomkeys(sys::AbstractSystem)
Return the atomic properties, which are available in all atoms of the system.
source
AtomsBase.hasatomkey — Function
hasatomkey(system::AbstractSystem, x::Symbol)
Returns true whether the passed property available in all atoms of the passed system.
source
AtomsBase.visualize_ascii — Function
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).
source
Species / atom properties
Base.position — Function
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.
source
AtomsBase.set_position! — Function
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}}
source
AtomsBase.mass — Function
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.
source
AtomsBase.set_mass! — Function
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}
source
AtomsBase.species — Function
species(::AbstractSystem, i)
Return the species (type, category, ...) of a particle or particles.
source
AtomsBase.set_species! — Function
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.
source
AtomsBase.velocity — Function
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.
source
AtomsBase.atomic_number — Function
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.
source
AtomsBase.atomic_symbol — Function
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.
source
AtomsBase.atom_name — Function
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.
source
AtomsBase.element_symbol — Function
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).
source
Prototype Implementation
AtomsBase.Atom — Type
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.
source
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")
source
AtomsBase.FlexibleSystem — Type
FlexibleSystem(particles, cell_vectors, periodicity; 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.
source
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")
source
AtomsBase.FlexibleSystem — Type
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.
source
FlexibleSystem(system; kwargs...)
Update constructor. See AbstractSystem for details.
source
AtomsBase.atomic_system — Function
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"Å"
+FlexibleSystem(particles, cell; kwargs...)
Construct a flexible system, a versatile data structure for atomistic systems, which puts an emphasis on flexibility rather than speed.
source
FlexibleSystem(system; kwargs...)
Update constructor. See AbstractSystem for details.
source
AtomsBase.atomic_system — Function
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)
source
AtomsBase.isolated_system — Function
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"])
source
AtomsBase.periodic_system — Function
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"Å")
+                                  cell_vectors, pbcs)
source
AtomsBase.isolated_system — Function
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"])
source
AtomsBase.periodic_system — Function
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)
source

+                                 box, fractional=true)
source
diff --git a/dev/implementations/index.html b/dev/implementations/index.html index 0af7dc4..c10765d 100644 --- a/dev/implementations/index.html +++ b/dev/implementations/index.html @@ -1,2 +1,2 @@ -Implementations · AtomsBase.jl
GitHub

Prototype Implementations

AtomsBase provides two prototype implementations of AbstractSystem{D} that are exported:

and are briefly discussed in more detail in the remainder of this page.

Struct-of-Arrays vs. Array-of-Structs

The "struct-of-arrays" (SoA) vs. "array-of-structs" (AoS) is a common design dilemma in representations of systems of particles. AtomsBase is deliberately designed to be agnostic to how a concrete implementation chooses to structure its data. Some specific notes regarding how implementations might differ for these two paradigms are included below.

A way to think about this broadly is that the difference amounts to the ordering of function calls. For example, to get the position of a single particle in an AoS implementation, the explicit function chaining would be position(getindex(sys)) (i.e. extract the single struct representing the particle of interest and query its position), while for SoA, one should prefer an implementation like getindex(position(sys)) (extract the array of positions, then index into it for a single particle). The beauty of an abstract interface in Julia is that these details can be, in large part, abstracted away through method dispatch such that the end user sees the same expected behavior irrespective of how things are implemented "under the hood".

Struct of Arrays / FastSystem

The file fast_system.jl contains an implementation of AtomsBase based on the struct-of-arrays approach. All species data is stored as plain arrays, but for convenience indexing of individual atoms is supported by a light-weight AtomView. See the implementation files as well as the tests for how these can be used.

Atoms and FlexibleSystem

A flexible implementation of the interface is provided by the FlexibleSystem and the Atom structs for representing atomic systems.These are discussed in detail in the tutorial.

+Implementations · AtomsBase.jl
GitHub

Prototype Implementations

AtomsBase provides two prototype implementations of AbstractSystem{D} that are exported:

and are briefly discussed in more detail in the remainder of this page.

Struct-of-Arrays vs. Array-of-Structs

The "struct-of-arrays" (SoA) vs. "array-of-structs" (AoS) is a common design dilemma in representations of systems of particles. AtomsBase is deliberately designed to be agnostic to how a concrete implementation chooses to structure its data. Some specific notes regarding how implementations might differ for these two paradigms are included below.

A way to think about this broadly is that the difference amounts to the ordering of function calls. For example, to get the position of a single particle in an AoS implementation, the explicit function chaining would be position(getindex(sys)) (i.e. extract the single struct representing the particle of interest and query its position), while for SoA, one should prefer an implementation like getindex(position(sys)) (extract the array of positions, then index into it for a single particle). The beauty of an abstract interface in Julia is that these details can be, in large part, abstracted away through method dispatch such that the end user sees the same expected behavior irrespective of how things are implemented "under the hood".

Struct of Arrays / FastSystem

The file fast_system.jl contains an implementation of AtomsBase based on the struct-of-arrays approach. All species data is stored as plain arrays, but for convenience indexing of individual atoms is supported by a light-weight AtomView. See the implementation files as well as the tests for how these can be used.

Atoms and FlexibleSystem

A flexible implementation of the interface is provided by the FlexibleSystem and the Atom structs for representing atomic systems.These are discussed in detail in the tutorial.

diff --git a/dev/index.html b/dev/index.html index b468993..138f90f 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Home · AtomsBase.jl
GitHub

AtomsBase

A Julian abstract interface for atomic structures.

Stable Dev Build Status Coverage

AtomsBase is an abstract interface for representation of atomic geometries in Julia. It aims to be a lightweight means of facilitating interoperability between various tools including, e.g.,

  • Simulation engines, e.g. molecular dynamics, geometry optimization, etc
  • Computing chemical or mechanical properties, e.g., via DFT, or interatomic potentials,
  • Integration with third party-libraries
  • I/O with standard file formats (.cif, .xyz, ...)
  • automatic differentiation and machine learning systems
  • numerical tools: sampling, integration schemes, etc.
  • visualization (e.g. plot recipes)

While AtomsBase focusses on representation of atomic systems, the sister package AtomsCalculators provides a general interface to compute properties of such systems.

Currently, the design philosophy is to be as lightweight as possible with a small set of required function dispatches to make adopting the interface easy. We also provide prototype implementations that we envision to be broadly applicable. If features beyond these are required we encourage developers to open PRs or provide their own implementations. For more on how to use the package, see the documentation.

Packages using AtomsBase

The following (not all yet-registered) packages currently make use of AtomsBase:

+Home · AtomsBase.jl
GitHub

AtomsBase

A Julian abstract interface for atomic structures.

Stable Dev Build Status Coverage

AtomsBase is an abstract interface for representation of atomic geometries in Julia. It aims to be a lightweight means of facilitating interoperability between various tools including, e.g.,

  • Simulation engines, e.g. molecular dynamics, geometry optimization, etc
  • Computing chemical or mechanical properties, e.g., via DFT, or interatomic potentials,
  • Integration with third party-libraries
  • I/O with standard file formats (.cif, .xyz, ...)
  • automatic differentiation and machine learning systems
  • numerical tools: sampling, integration schemes, etc.
  • visualization (e.g. plot recipes)

While AtomsBase focusses on representation of atomic systems, the sister package AtomsCalculators provides a general interface to compute properties of such systems.

Currently, the design philosophy is to be as lightweight as possible with a small set of required function dispatches to make adopting the interface easy. We also provide prototype implementations that we envision to be broadly applicable. If features beyond these are required we encourage developers to open PRs or provide their own implementations. For more on how to use the package, see the documentation.

Packages using AtomsBase

The following (not all yet-registered) packages currently make use of AtomsBase:

diff --git a/dev/interface/index.html b/dev/interface/index.html index cff4e68..64bea60 100644 --- a/dev/interface/index.html +++ b/dev/interface/index.html @@ -2,4 +2,4 @@ Interface · AtomsBase.jl
GitHub

Interface

This page formally defines the AtomsBase interface for particle systems. The main use-case for which the interface is designed is for systems of atoms. For this case some additional functionality is provided. The main abstract type introduced in AtomsBase is

An implementation of AbstractSystem{D}, 

struct ConcreteSystem{D} <: AbstractSystem{D}
    # ... 
 end

specifies a system of particles that have a position in D dimensional Euclidean space. That is, the parameter D indicates the number of spatial dimensions into which each particle is embedded. A particle will normally also have additional properties such as mass, charge, chemical species, etc, but those are ignored in the interpretation of D.

The interface aims to achieve predictable behavior of several core functions to access information about a particle system.

  • Core Interface : this is a minimal read-only core of the AtomsBase interface and must be implemented by a subtype of AtomsBase.AbstractSystem to enable the implementation to be used across the AtomsBase ecosystem.
  • Setter Interface : (optional) It is strongly recommended that implementations requiring mutation follow this interface.
  • Optional properties interface : (optional) For some use-cases (e.g. managing datasets) it can be useful to allow a system to store more general properties about a particle system (or the individual particles themselves). The optional properties interface specifies the recommended interface for such as scenario.

Core Interface

A minimal implementation of the AtomsBase interface is read-only and must implement methods for the functions listed as follows.

System Properties and Cell Interface

A system is specified by a computational cell and particles within that cell (or, domain). System properties are properties of the entire particle system, as opposed to properties of individual particles.

  • Base.length(system) : return an Integer, the number of particles in the system; if the system describes a periodic cell, then the number of particles in one period of the cell is returned.
  • `AtomsBase.cell(system) : returns an object cell that specifies the computational cell. Two reference implementations, PeriodicCell and IsolatedCell that should serve most purposes are provided.

A cell object must implement methods for the following functions:

  • AtomsBase.cell_vectors(cell) : returns NTuple{D, SVector{D, T}} the cell vectors that specify the computational domain if it is finite. For isolated systems, the return values are unspecified.
  • AtomsBase.periodicity(cell) : returns NTuple{D, Bool}, booleans that specify whether the system is periodic in the direction of the D cell vectors provided by cell_vectors. For isolated systems periodicity must return (false, ..., false).
  • AtomsBase.n_dimensions(cell) : returns the dimensionality of the computational cell, it must match the dimensionality of the system.

AtomsBase provides cell_vectors and periodicity methods so that they can be called with a system as argument, i.e., 

cell_vectors(system) = cell_vectors(cell(system))
-periodicity(system)  =  periodicity(cell(system))

Two recommended general purpose implementations of computational cells are provided as part of AtomsBase:

  • PeriodicCell : implementation of a periodic parallelepiped shaped cell
  • IsolatedCell : implementation of a cell describing an isolated system within an infinite domain.

Particle properties

  • position(system, i::Integer) : return an SVector{D, <: Unitful.Length} enconding the position of the ith particle
  • mass(system, i::Integer) : return a <: Unitful.Mass, the mass of the ith particle
  • species(system, i::Integer) : return an object that defines the particle species (kind, type, ...). In most cases this should be a categorical variable on which no arithmetic is defined. In atomistic simulation this is normally the chemical element (cf. AtomsBase.ChemicalSpecies), possibly augmented with additional information about the atom. But the interface does not require use of any specific type to define the particle species.

For each of property in [position, mass, species] there must also be defined

  • property(system, inds::AbstractVector{<: Integer}) : return a list (e.g. AbstractVector) of the requested property of the particles indexed by inds;
  • property(system, :) : return a list of the requested property for all particles in the system.

AtomsBase provides default fallbacks for these methods but they will normally be inefficient. The caller cannot assume whether a view or a copy are returned.

Iteration and Indexing over systems

There is a presumption of the ability to somehow extract an individual component (e.g. a single atom or molecule) of this system, though there are no constraints on the type of this component. To achieve this, an AbstractSystem object is expected to implement the Julia interfaces for iteration and indexing in order to access representations of individual components of the system. Some default dispatches of parts of these interfaces are already included, so the minimal set of functions to dispatch in a concrete implementation is Base.getindex and Base.length, though it may be desirable to customize additional behavior depending on context.

Setter Interface

The optional setter / mutation interface consists of the following functions to be overloaded.

For each of the particle property setters, i may be an Integer, an AbstractVector{<: Integer} or :.

Optional properties interface

For some use-cases (e.g. managing datasets) it can be useful to allow a system to store more general properties about a particle system or even the individual particles themselves. The optional properties interface specifies the recommended interface for such as scenario. The Tutorial provides a more detailed discussion and exmaples how these can be used. The prototype implementations also provide further details.

An implementation that wants to support the AtomsBase optional properties interface should implement the following methods:

System properties:

  • getindex
  • haskey
  • get
  • keys
  • pairs

Particle properties

  • atomkeys
  • hasatomkey

Future Interface Extensions

The AtomsBase developers are considering extending the AtomsBase interface with additional functions. Developers may keep this in mind during development. Issues or discussions related to this are welcome.

Here we maintain a list of possibly future interface functions:

  • charge
  • charge_dipole
  • velocity
  • momentum
  • spin
  • magnetic_moment
  • multiplicity
+periodicity(system) = periodicity(cell(system))

Two recommended general purpose implementations of computational cells are provided as part of AtomsBase:

Particle properties

For each of property in [position, mass, species] there must also be defined

AtomsBase provides default fallbacks for these methods but they will normally be inefficient. The caller cannot assume whether a view or a copy are returned.

Iteration and Indexing over systems

There is a presumption of the ability to somehow extract an individual component (e.g. a single atom or molecule) of this system, though there are no constraints on the type of this component. To achieve this, an AbstractSystem object is expected to implement the Julia interfaces for iteration and indexing in order to access representations of individual components of the system. Some default dispatches of parts of these interfaces are already included, so the minimal set of functions to dispatch in a concrete implementation is Base.getindex and Base.length, though it may be desirable to customize additional behavior depending on context.

Setter Interface

The optional setter / mutation interface consists of the following functions to be overloaded.

For each of the particle property setters, i may be an Integer, an AbstractVector{<: Integer} or :.

Optional properties interface

For some use-cases (e.g. managing datasets) it can be useful to allow a system to store more general properties about a particle system or even the individual particles themselves. The optional properties interface specifies the recommended interface for such as scenario. The Tutorial provides a more detailed discussion and exmaples how these can be used. The prototype implementations also provide further details.

An implementation that wants to support the AtomsBase optional properties interface should implement the following methods:

System properties:

Particle properties

Future Interface Extensions

The AtomsBase developers are considering extending the AtomsBase interface with additional functions. Developers may keep this in mind during development. Issues or discussions related to this are welcome.

Here we maintain a list of possibly future interface functions:

diff --git a/dev/objects.inv b/dev/objects.inv index d2587d907255ec78ff2d140825a30ee55dc3f6bf..48e314f54161d94c5156f00a2ba00e1a5acb5f13 100644 GIT binary patch delta 200 zcmV;(05|`J2#W}?Oap(iD`^3l9L{#CyUCe66|WCG2x;*_nyjrk|6f z#Sas-^WhqEVg=4HUh+vk@1A(ukn;@z{_`iFk>A4JsA}7Ju9u<pV#y5iMP!)-w@zGW%3#ME$oe|wl(K^DY`JrPLbvX{tGiW92XKCVVVE{ diff --git a/dev/search_index.js b/dev/search_index.js index 04e4002..69f9d75 100644 --- a/dev/search_index.js +++ b/dev/search_index.js @@ -1,3 +1,3 @@ var documenterSearchIndex = {"docs": -[{"location":"interface/","page":"Interface","title":"Interface","text":"CurrentModule = AtomsBase","category":"page"},{"location":"interface/#Interface","page":"Interface","title":"Interface","text":"","category":"section"},{"location":"interface/","page":"Interface","title":"Interface","text":"This page formally defines the AtomsBase interface for particle systems. The main use-case for which the interface is designed is for systems of atoms. For this case some additional functionality is provided. The main abstract type introduced in AtomsBase is ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"AbstractSystem.","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"An implementation of AbstractSystem{D}, ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"struct ConcreteSystem{D} <: AbstractSystem{D}\n # ... \nend","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"specifies a system of particles that have a position in D dimensional Euclidean space. That is, the parameter D indicates the number of spatial dimensions into which each particle is embedded. A particle will normally also have additional properties such as mass, charge, chemical species, etc, but those are ignored in the interpretation of D.","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"The interface aims to achieve predictable behavior of several core functions to access information about a particle system. ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"Core Interface : this is a minimal read-only core of the AtomsBase interface and must be implemented by a subtype of AtomsBase.AbstractSystem to enable the implementation to be used across the AtomsBase ecosystem. \nSetter Interface : (optional) It is strongly recommended that implementations requiring mutation follow this interface. \nOptional properties interface : (optional) For some use-cases (e.g. managing datasets) it can be useful to allow a system to store more general properties about a particle system (or the individual particles themselves). The optional properties interface specifies the recommended interface for such as scenario. ","category":"page"},{"location":"interface/#Core-Interface","page":"Interface","title":"Core Interface","text":"","category":"section"},{"location":"interface/","page":"Interface","title":"Interface","text":"A minimal implementation of the AtomsBase interface is read-only and must implement methods for the functions listed as follows. ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"Base.length(system)\nBase.getindex(system, i) \n`AtomsBase.cell(system)\nAtomsBase.position(system, i)\nAtomsBase.mass(system, i)\nAtomsBase.species(system, i)","category":"page"},{"location":"interface/#System-Properties-and-Cell-Interface","page":"Interface","title":"System Properties and Cell Interface","text":"","category":"section"},{"location":"interface/","page":"Interface","title":"Interface","text":"A system is specified by a computational cell and particles within that cell (or, domain). System properties are properties of the entire particle system, as opposed to properties of individual particles. ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"Base.length(system) : return an Integer, the number of particles in the system; if the system describes a periodic cell, then the number of particles in one period of the cell is returned.\n`AtomsBase.cell(system) : returns an object cell that specifies the computational cell. Two reference implementations, PeriodicCell and IsolatedCell that should serve most purposes are provided. ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"A cell object must implement methods for the following functions: ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"AtomsBase.cell_vectors(cell) : returns NTuple{D, SVector{D, T}} the cell vectors that specify the computational domain if it is finite. For isolated systems, the return values are unspecified.\nAtomsBase.periodicity(cell) : returns NTuple{D, Bool}, booleans that specify whether the system is periodic in the direction of the D cell vectors provided by cell_vectors. For isolated systems periodicity must return (false, ..., false).\nAtomsBase.n_dimensions(cell) : returns the dimensionality of the computational cell, it must match the dimensionality of the system. ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"AtomsBase provides cell_vectors and periodicity methods so that they can be called with a system as argument, i.e., ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"cell_vectors(system) = cell_vectors(cell(system))\nperiodicity(system) = periodicity(cell(system))","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"Two recommended general purpose implementations of computational cells are provided as part of AtomsBase: ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"PeriodicCell : implementation of a periodic parallelepiped shaped cell\nIsolatedCell : implementation of a cell describing an isolated system within an infinite domain. ","category":"page"},{"location":"interface/#Particle-properties","page":"Interface","title":"Particle properties","text":"","category":"section"},{"location":"interface/","page":"Interface","title":"Interface","text":"position(system, i::Integer) : return an SVector{D, <: Unitful.Length} enconding the position of the ith particle\nmass(system, i::Integer) : return a <: Unitful.Mass, the mass of the ith particle\nspecies(system, i::Integer) : return an object that defines the particle species (kind, type, ...). In most cases this should be a categorical variable on which no arithmetic is defined. In atomistic simulation this is normally the chemical element (cf. AtomsBase.ChemicalSpecies), possibly augmented with additional information about the atom. But the interface does not require use of any specific type to define the particle species.","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"For each of property in [position, mass, species] there must also be defined ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"property(system, inds::AbstractVector{<: Integer}) : return a list (e.g. AbstractVector) of the requested property of the particles indexed by inds; \nproperty(system, :) : return a list of the requested property for all particles in the system.","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"AtomsBase provides default fallbacks for these methods but they will normally be inefficient. The caller cannot assume whether a view or a copy are returned. ","category":"page"},{"location":"interface/#Iteration-and-Indexing-over-systems","page":"Interface","title":"Iteration and Indexing over systems","text":"","category":"section"},{"location":"interface/","page":"Interface","title":"Interface","text":"There is a presumption of the ability to somehow extract an individual component (e.g. a single atom or molecule) of this system, though there are no constraints on the type of this component. To achieve this, an AbstractSystem object is expected to implement the Julia interfaces for iteration and indexing in order to access representations of individual components of the system. Some default dispatches of parts of these interfaces are already included, so the minimal set of functions to dispatch in a concrete implementation is Base.getindex and Base.length, though it may be desirable to customize additional behavior depending on context.","category":"page"},{"location":"interface/#Setter-Interface","page":"Interface","title":"Setter Interface","text":"","category":"section"},{"location":"interface/","page":"Interface","title":"Interface","text":"The optional setter / mutation interface consists of the following functions to be overloaded. ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"set_cell!(system, cell) \nset_position!(system, i, x) \nset_mass!(system, i, x)\nset_species!(system, i, x) \nset_cell_vectors!(cell, bb) \nset_periodicity!(cell, pbc) \ndeleteat!(system, i) : delete atoms i (or atoms i if a list of \":)\nappend!(system1, system2) : append system 2 to system 1, provided they are \"compatible\". ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"For each of the particle property setters, i may be an Integer, an AbstractVector{<: Integer} or :.","category":"page"},{"location":"interface/#Optional-properties-interface","page":"Interface","title":"Optional properties interface","text":"","category":"section"},{"location":"interface/","page":"Interface","title":"Interface","text":"For some use-cases (e.g. managing datasets) it can be useful to allow a system to store more general properties about a particle system or even the individual particles themselves. The optional properties interface specifies the recommended interface for such as scenario. The Tutorial provides a more detailed discussion and exmaples how these can be used. The prototype implementations also provide further details.","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"An implementation that wants to support the AtomsBase optional properties interface should implement the following methods: ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"System properties:","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"getindex\nhaskey\nget\nkeys\npairs","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"Particle properties","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"atomkeys \nhasatomkey ","category":"page"},{"location":"interface/#Future-Interface-Extensions","page":"Interface","title":"Future Interface Extensions","text":"","category":"section"},{"location":"interface/","page":"Interface","title":"Interface","text":"The AtomsBase developers are considering extending the AtomsBase interface with additional functions. Developers may keep this in mind during development. Issues or discussions related to this are welcome. ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"Here we maintain a list of possibly future interface functions:","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"charge \ncharge_dipole \nvelocity\nmomentum \nspin\nmagnetic_moment\nmultiplicity ","category":"page"},{"location":"implementations/","page":"Implementations","title":"Implementations","text":"CurrentModule = AtomsBase","category":"page"},{"location":"implementations/#Prototype-Implementations","page":"Implementations","title":"Prototype Implementations","text":"","category":"section"},{"location":"implementations/","page":"Implementations","title":"Implementations","text":"AtomsBase provides two prototype implementations of AbstractSystem{D} that are exported: ","category":"page"},{"location":"implementations/","page":"Implementations","title":"Implementations","text":"FlexibleSystem\nFastSystem","category":"page"},{"location":"implementations/","page":"Implementations","title":"Implementations","text":"and are briefly discussed in more detail in the remainder of this page. ","category":"page"},{"location":"implementations/#Struct-of-Arrays-vs.-Array-of-Structs","page":"Implementations","title":"Struct-of-Arrays vs. Array-of-Structs","text":"","category":"section"},{"location":"implementations/","page":"Implementations","title":"Implementations","text":"The \"struct-of-arrays\" (SoA) vs. \"array-of-structs\" (AoS) is a common design dilemma in representations of systems of particles. AtomsBase is deliberately designed to be agnostic to how a concrete implementation chooses to structure its data. Some specific notes regarding how implementations might differ for these two paradigms are included below.","category":"page"},{"location":"implementations/","page":"Implementations","title":"Implementations","text":"A way to think about this broadly is that the difference amounts to the ordering of function calls. For example, to get the position of a single particle in an AoS implementation, the explicit function chaining would be position(getindex(sys)) (i.e. extract the single struct representing the particle of interest and query its position), while for SoA, one should prefer an implementation like getindex(position(sys)) (extract the array of positions, then index into it for a single particle). The beauty of an abstract interface in Julia is that these details can be, in large part, abstracted away through method dispatch such that the end user sees the same expected behavior irrespective of how things are implemented \"under the hood\".","category":"page"},{"location":"implementations/#Struct-of-Arrays-/-FastSystem","page":"Implementations","title":"Struct of Arrays / FastSystem","text":"","category":"section"},{"location":"implementations/","page":"Implementations","title":"Implementations","text":"The file fast_system.jl contains an implementation of AtomsBase based on the struct-of-arrays approach. All species data is stored as plain arrays, but for convenience indexing of individual atoms is supported by a light-weight AtomView. See the implementation files as well as the tests for how these can be used.","category":"page"},{"location":"implementations/#Atoms-and-FlexibleSystem","page":"Implementations","title":"Atoms and FlexibleSystem","text":"","category":"section"},{"location":"implementations/","page":"Implementations","title":"Implementations","text":"A flexible implementation of the interface is provided by the FlexibleSystem and the Atom structs for representing atomic systems.These are discussed in detail in the tutorial. ","category":"page"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"CurrentModule = AtomsBase","category":"page"},{"location":"utilities/#Utilities","page":"Utilities","title":"Utilities","text":"","category":"section"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"This page documents some utilities that AtomsBase provides in addition to the interface. This documentation is preliminary. PRs to improve it are welcome. ","category":"page"},{"location":"utilities/#Cell-Types","page":"Utilities","title":"Cell Types","text":"","category":"section"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"As of AtomsBase 0.4 we recommend that implementations of the interface specify a computational cell type. To simplify this, AtomsBase provides two prototype implementations: ","category":"page"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"PeriodicCell : implements the standard parallepiped shaped cell defined through three cell vectors and periodicity (true or false) along each cell vector.\nIsolatedCell : implements a computational cell that is open (infinite) in all directions, i.e. the entire space.","category":"page"},{"location":"utilities/#Chemical-Species","page":"Utilities","title":"Chemical Species","text":"","category":"section"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"The function AtomsBase.species(sys, i) return the particle species of a particle (or multiple particles). AtomsBase does not enforce any specific type to be returned. However, it is recommended that systems describing atomic structures use - whenever possible - the ChemicalSpecies type that is implemented as part of AtomsBase.","category":"page"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"ChemicalSpecies : a prototype implementation and recommended default for the species of an atom.","category":"page"},{"location":"utilities/#Convenience-functions","page":"Utilities","title":"Convenience functions","text":"","category":"section"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"AtomsBase provides a number of convenience utilities that should work for any system that implements the AtomsBase interface. If they not work as expected this is likely a bug and should be reported as an issue. ","category":"page"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"atomic_mass = mass : deprecated \nn_dimensions \natomic_symbol\natomic_number\nelement_symbol\nchemical_formula\nelement\nvisualize_ascii","category":"page"},{"location":"utilities/#Testing-Utilities","page":"Utilities","title":"Testing Utilities","text":"","category":"section"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"The AtomsBaseTesting package provides a few utility functions to test downstream packages for having properly implemented the AtomsBase interface. The tests are probably not complete, but they should be a good start ... and as always PRs are welcome.","category":"page"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"Two functions are provided, namely make_test_system to generate standard FlexibleSystem test systems and test_approx_eq for testing approximate equality between AtomsBase systems (of not necessarily the same type). The basic idea of the functions is to use make_test_system to obtain a test system, construct an identical system in a downstream library and then use test_approx_eq to check they are actually equal.","category":"page"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"For usage examples see the tests of ExtXYZ, AtomsIO, Chemfiles and ASEconnect.","category":"page"},{"location":"apireference/","page":"Reference","title":"Reference","text":"CurrentModule = AtomsBase","category":"page"},{"location":"apireference/#API-reference","page":"Reference","title":"API reference","text":"","category":"section"},{"location":"apireference/#Index","page":"Reference","title":"Index","text":"","category":"section"},{"location":"apireference/","page":"Reference","title":"Reference","text":"Pages = [\"apireference.md\"]","category":"page"},{"location":"apireference/#Types","page":"Reference","title":"Types","text":"","category":"section"},{"location":"apireference/","page":"Reference","title":"Reference","text":"AbstractSystem\nIsolatedCell\nPeriodicCell \nAtomView\nChemicalSpecies ","category":"page"},{"location":"apireference/#AtomsBase.AbstractSystem","page":"Reference","title":"AtomsBase.AbstractSystem","text":"AbstractSystem{D}\n\nA D-dimensional particle system.\n\n\n\n\n\n","category":"type"},{"location":"apireference/#AtomsBase.IsolatedCell","page":"Reference","title":"AtomsBase.IsolatedCell","text":" IsolatedCell{D, T}\n\nDefines a computational domain / cell describing an open system.\n\n\n\n\n\n","category":"type"},{"location":"apireference/#AtomsBase.PeriodicCell","page":"Reference","title":"AtomsBase.PeriodicCell","text":"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.\n\n\n\n\n\n","category":"type"},{"location":"apireference/#AtomsBase.AtomView","page":"Reference","title":"AtomsBase.AtomView","text":"TODO: reintroduce the original docs (failing docstest...)\n\n\n\n\n\n","category":"type"},{"location":"apireference/#AtomsBase.ChemicalSpecies","page":"Reference","title":"AtomsBase.ChemicalSpecies","text":"Encodes a chemical species by wrapping an integer that represents the atomic number, the number of protons, and additional unspecified information as a UInt32. \n\nConstructors for standard chemical elements\n\nChemicalSpecies(Z::Integer)\nChemicalSpecies(sym::Symbol) \n# for example \nChemicalSpecies(:C)\nChemicalSpecies(6)\n\nConstructors for isotopes \n\n# standard carbon = C-12\nChemicalSpecies(:C)\nChemicalSpecies(:C; n_neutrons = 6)\n\n# three equivalent constructors for C-13\nChemicalSpecies(:C; n_neutrons = 7)\nChemicalSpecies(6; n_neutrons = 7)\nChemicalSpecies(:C13)\n# deuterium\nChemicalSpecies(:D) \n\n\n\n\n\n","category":"type"},{"location":"apireference/#System-properties","page":"Reference","title":"System properties","text":"","category":"section"},{"location":"apireference/","page":"Reference","title":"Reference","text":"cell_vectors\nset_cell_vectors!\nperiodicity\nset_periodicity!\ncell \nset_cell! \nn_dimensions\natomkeys\nhasatomkey\nchemical_formula\nvisualize_ascii","category":"page"},{"location":"apireference/#AtomsBase.cell_vectors","page":"Reference","title":"AtomsBase.cell_vectors","text":"cell_vectors(sys::AbstractSystem{D})\n\nReturn a tuple of length D of vectors of length D that describe the cell in which the system sys is defined.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.set_cell_vectors!","page":"Reference","title":"AtomsBase.set_cell_vectors!","text":"set_cell_vectors!(sys::AbstractSystem{D}, bb::NTuple{D, SVector{D, L}})\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.periodicity","page":"Reference","title":"AtomsBase.periodicity","text":"periodicity(sys::AbstractSystem{D})\n\nReturn a NTuple{D, Bool} indicating whether the system is periodic along a cell vector as specified by cell_vectors.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.set_periodicity!","page":"Reference","title":"AtomsBase.set_periodicity!","text":"set_periodicity!(sys::AbstractSystem{D}, pbc::NTuple{D, Bool})\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.cell","page":"Reference","title":"AtomsBase.cell","text":"cell(sys::AbstractSystem)\n\nReturns the computational cell (domain). See e.g. PeriodicCell and IsolatedCell.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.set_cell!","page":"Reference","title":"AtomsBase.set_cell!","text":"set_cell!(sys, cell)\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.n_dimensions","page":"Reference","title":"AtomsBase.n_dimensions","text":"n_dimensions(::AbstractSystem)\n\nReturn number of dimensions.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.atomkeys","page":"Reference","title":"AtomsBase.atomkeys","text":"atomkeys(sys::AbstractSystem)\n\nReturn the atomic properties, which are available in all atoms of the system.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.hasatomkey","page":"Reference","title":"AtomsBase.hasatomkey","text":"hasatomkey(system::AbstractSystem, x::Symbol)\n\nReturns true whether the passed property available in all atoms of the passed system.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.chemical_formula","page":"Reference","title":"AtomsBase.chemical_formula","text":"Returns the chemical formula of an AbstractSystem as a string.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.visualize_ascii","page":"Reference","title":"AtomsBase.visualize_ascii","text":"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).\n\n\n\n\n\n","category":"function"},{"location":"apireference/#Species-/-atom-properties","page":"Reference","title":"Species / atom properties","text":"","category":"section"},{"location":"apireference/","page":"Reference","title":"Reference","text":"position\nset_position!\nmass\nset_mass!\nspecies\nset_species!\nvelocity\nset_velocity!\natomic_number\natomic_symbol\nelement_symbol\nelement ","category":"page"},{"location":"apireference/#Base.position","page":"Reference","title":"Base.position","text":"position(sys::AbstractSystem, i)\n\nReturn 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 == :.\n\nThe return type should be a vector of vectors each containing D elements that are <:Unitful.Length.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.set_position!","page":"Reference","title":"AtomsBase.set_position!","text":"set_position!(sys::AbstractSystem{D}, i, x)\n\nIf i is an integer then x is an SVector{D, L} with L <: Unitful.Length\nIf i is an AbstractVector{<: Integer} or : then x is an AbstractVector{SVector{D, L}}\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.mass","page":"Reference","title":"AtomsBase.mass","text":"mass(sys::AbstractSystem, i)\n\nMass of a particle if i::Integer, vector of masses if i is a vector of integers or :. The elements are <: Unitful.Mass.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.set_mass!","page":"Reference","title":"AtomsBase.set_mass!","text":"set_mass!(sys::AbstractSystem, i, m)\n\nIf i is an integer then m is a Unitful.Mass\nIf i is an AbstractVector{<: Integer} or : then x is an AbstractVector{<: Unitful.Mass}\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.species","page":"Reference","title":"AtomsBase.species","text":"species(::AbstractSystem, i)\n\nReturn the species (type, category, ...) of a particle or particles.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.set_species!","page":"Reference","title":"AtomsBase.set_species!","text":"set_species!(sys::AbstractSystem, i, s)\n\nIf i is an integer then s is an object describing the particle species, e.g., ChemicalSpecies\nIf i is an AbstractVector{<: Integer} or : then x is an AbstractVector of species objects.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.velocity","page":"Reference","title":"AtomsBase.velocity","text":"velocity(sys::AbstractSystem, i)\n\nReturn 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.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.set_velocity!","page":"Reference","title":"AtomsBase.set_velocity!","text":"set_velocity!(sys::AbstractSystem, i, v)\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.atomic_number","page":"Reference","title":"AtomsBase.atomic_number","text":"atomic_number(sys::AbstractSystem, i)\natomic_number(species)\n\nVector of atomic numbers in the system sys or the atomic number of a particular species / the ith species in sys.\n\nThe 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.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.atomic_symbol","page":"Reference","title":"AtomsBase.atomic_symbol","text":"atomic_symbol(sys::AbstractSystem, i)\natomic_symbol(species)\n\nVector of atomic symbols in the system sys or the atomic symbol of a particular species / the ith species in sys.\n\nThe 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.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.element_symbol","page":"Reference","title":"AtomsBase.element_symbol","text":"element_symbol(system, index)\nelement_symbol(species)\n\nReturn 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).\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.element","page":"Reference","title":"AtomsBase.element","text":"The element corresponding to a species/atom (or missing).\n\n\n\n\n\n","category":"function"},{"location":"apireference/#Prototype-Implementation","page":"Reference","title":"Prototype Implementation","text":"","category":"section"},{"location":"apireference/","page":"Reference","title":"Reference","text":"Atom\nFlexibleSystem\nFastSystem\natomic_system\nisolated_system\nperiodic_system ","category":"page"},{"location":"apireference/#AtomsBase.Atom","page":"Reference","title":"AtomsBase.Atom","text":"Atom(identifier::AtomId, position::AbstractVector; kwargs...)\nAtom(identifier::AtomId, position::AbstractVector, velocity::AbstractVector; kwargs...)\nAtom(; atomic_number, position, velocity=zeros(D)u\"bohr/s\", kwargs...)\n\nConstruct an atomic located at the cartesian coordinates position with (optionally) the given cartesian velocity. Note that AtomId = Union{Symbol,AbstractString,Integer,ChemicalSymbol}.\n\nSupported kwargs include species, mass, as well as user-specific custom properties.\n\n\n\n\n\nAtom(atom::Atom; kwargs...)\n\nUpdate 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.\n\nExamples\n\nConstruct a standard hydrogen atom located at the origin\n\njulia> hydrogen = Atom(:H, zeros(3)u\"Å\")\n\nand now amend its charge and atomic mass\n\njulia> Atom(atom; mass=1.0u\"u\", charge=-1.0u\"e_au\")\n\n\n\n\n\n","category":"type"},{"location":"apireference/#AtomsBase.FlexibleSystem","page":"Reference","title":"AtomsBase.FlexibleSystem","text":"FlexibleSystem(particles, cell_vectors, periodicity; kwargs...)\nFlexibleSystem(particles; cell_vectors, periodicity, kwargs...)\nFlexibleSystem(particles, cell; kwargs...)\n\nConstruct a flexible system, a versatile data structure for atomistic systems, which puts an emphasis on flexibility rather than speed.\n\n\n\n\n\nFlexibleSystem(system; kwargs...)\n\nUpdate constructor. See AbstractSystem for details.\n\n\n\n\n\n","category":"type"},{"location":"apireference/#AtomsBase.FastSystem","page":"Reference","title":"AtomsBase.FastSystem","text":"FastSystem\n\nA struct of arrays style prototype implementation of the AtomsBase interface. \n\n\n\n\n\n","category":"type"},{"location":"apireference/#AtomsBase.atomic_system","page":"Reference","title":"AtomsBase.atomic_system","text":"atomic_system(atoms::AbstractVector, cell_vectors, periodicity; kwargs...)\n\nConstruct a FlexibleSystem using the passed atoms and boundary box and conditions. Extra kwargs are stored as custom system properties.\n\nExamples\n\nConstruct a hydrogen molecule in a box, which is periodic only in the first two dimensions\n\njulia> cell_vectors = [[10.0, 0.0, 0.0], [0.0, 10.0, 0.0], [0.0, 0.0, 10.0]]u\"Å\"\njulia> pbcs = (true, true, false)\njulia> hydrogen = atomic_system([:H => [0, 0, 1.]u\"bohr\",\n :H => [0, 0, 3.]u\"bohr\"],\n cell_vectors, pbcs)\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.isolated_system","page":"Reference","title":"AtomsBase.isolated_system","text":"isolated_system(atoms::AbstractVector; kwargs...)\n\nConstruct 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.\n\nExamples\n\nConstruct a hydrogen molecule\n\njulia> hydrogen = isolated_system([:H => [0, 0, 1.]u\"bohr\", :H => [0, 0, 3.]u\"bohr\"])\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.periodic_system","page":"Reference","title":"AtomsBase.periodic_system","text":"periodic_system(atoms::AbstractVector, box; fractional=false, kwargs...)\n\nConstruct 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.\n\nExamples\n\nSetup a hydrogen molecule inside periodic BCs:\n\njulia> cell_vectors = ([10.0, 0.0, 0.0]u\"Å\", [0.0, 10.0, 0.0]u\"Å\", [0.0, 0.0, 10.0]u\"Å\")\njulia> hydrogen = periodic_system([:H => [0, 0, 1.]u\"bohr\",\n :H => [0, 0, 3.]u\"bohr\"],\n cell_vectors)\n\nSetup a silicon unit cell using fractional positions\n\njulia> box = 10.26 / 2 * [[0, 0, 1], [1, 0, 1], [1, 1, 0]]u\"bohr\"\njulia> silicon = periodic_system([:Si => ones(3)/8,\n :Si => -ones(3)/8],\n box, fractional=true)\n\n\n\n\n\n","category":"function"},{"location":"#AtomsBase","page":"Home","title":"AtomsBase","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"A Julian abstract interface for atomic structures.","category":"page"},{"location":"","page":"Home","title":"Home","text":"(Image: Stable) (Image: Dev) (Image: Build Status) (Image: Coverage)","category":"page"},{"location":"","page":"Home","title":"Home","text":"AtomsBase is an abstract interface for representation of atomic geometries in Julia. It aims to be a lightweight means of facilitating interoperability between various tools including, e.g., ","category":"page"},{"location":"","page":"Home","title":"Home","text":"Simulation engines, e.g. molecular dynamics, geometry optimization, etc \nComputing chemical or mechanical properties, e.g., via DFT, or interatomic potentials,\nIntegration with third party-libraries\nI/O with standard file formats (.cif, .xyz, ...)\nautomatic differentiation and machine learning systems\nnumerical tools: sampling, integration schemes, etc.\nvisualization (e.g. plot recipes)","category":"page"},{"location":"","page":"Home","title":"Home","text":"While AtomsBase focusses on representation of atomic systems, the sister package AtomsCalculators provides a general interface to compute properties of such systems. ","category":"page"},{"location":"","page":"Home","title":"Home","text":"Currently, the design philosophy is to be as lightweight as possible with a small set of required function dispatches to make adopting the interface easy. We also provide prototype implementations that we envision to be broadly applicable. If features beyond these are required we encourage developers to open PRs or provide their own implementations. For more on how to use the package, see the documentation.","category":"page"},{"location":"#Packages-using-AtomsBase","page":"Home","title":"Packages using AtomsBase","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"The following (not all yet-registered) packages currently make use of AtomsBase:","category":"page"},{"location":"","page":"Home","title":"Home","text":"ACEpotentials\nASEPotential\nASEconvert : integration with the Atomistic Simulation Environment\nAtomIO: I/O for atomic structures, also wraps some ASE functionality\nAtomistic: integrated workflow for MD simulations, part of CESMIX\nAutoBZCore.jl: Brillouin-zone integration\nBFPIS\nChemistryFeaturization: Interface for featurization of atomic structures for input into machine learning models, part of Chemellia\nDFTK: density functional theory simulations\nEmpiricalPotentials\nExtXYZ: Parser for extended XYZ files\nInteratomicPotentials: implementations of a variety of interatomic potentials, also part of CESMIX\nMolly: molecular dynamics simulations\nXtals: I/O and structure representation for crystals","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"CurrentModule = AtomsBase","category":"page"},{"location":"tutorial/#Tutorial","page":"Tutorial","title":"Tutorial","text":"","category":"section"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"This page gives an overview of using AtomsBase in practice and introduces the conventions followed across the AtomsBase ecosystem. It serves as a reference for both users interested in doing something with an AbstractSystem object as well as developers wishing to integrate their code with AtomsBase. See Interface for a precise specification of the AtomsBase interface.","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"For the examples we will mostly draw on the case of atomistic systems using the FlexibleSystem data structure. The Atom and FlexibleSystem data structure we focus on here should provide good defaults for many purposes.","category":"page"},{"location":"tutorial/#High-level-introduction","page":"Tutorial","title":"High-level introduction","text":"","category":"section"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"The main purpose of AtomsBase is to conveniently pass atomistic data between Julia packages. For example the following snippet loads an extxyz file using AtomsIO and returns it as an AtomsBase-compatible system (in data):","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using AtomsIO\ndata = load_system(\"Si.extxyz\")","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Next we use ASEconvert to convert this system to python, such that we can make use of the atomistic simulation environment (ASE) to form a (2, 1, 1) supercell, which is afterwards converted back to Julia (by forming another AtomsBase-compatible system).","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using ASEconvert\nsupercell = pyconvert(AbstractSystem, data * pytuple((2, 1, 1)))","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Finally the supercell is passed to DFTK, where we attach pseudopotentials and run a PBE calculation:","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using DFTK\ncell_with_pseudos = attach_psp(supercell, Si=\"hgh/pbe/si-q4\")\nmodel = model_PBE(cell_with_pseudos)\nbasis = PlaneWaveBasis(model, Ecut=30, kgrid=(5, 5, 5)\nself_consistent_field(basis).energy.total","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"For more high-level examples see also:","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"The DFTK documentation page on AtomsBase.\nThe AtomsIO documentation","category":"page"},{"location":"tutorial/#Atom-interface-and-conventions","page":"Tutorial","title":"Atom interface and conventions","text":"","category":"section"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"An Atom object can be constructed just by passing an identifier (e.g. symbol like :C, atomic number like 6) and a vector of positions as","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using Unitful, UnitfulAtomic, AtomsBase # hide\natom = Atom(:C, [0, 1, 2.]u\"bohr\")","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"This automatically fills the atom with standard data such as the atomic mass. See also the reference of the Atom function for more ways to construct an atom.","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Such data can be accessed using the AtomsBase interface functions, such as:","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"atomic_mass(atom)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"atomic_symbol(atom)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"atomic_number(atom)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"position(atom)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"velocity(atom)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"See atom.jl and the respective API documentation for details. Notice in particular that atomic_number specifies the element whereas species and also atomic_symbol may be more specific and may e.g. specify isotopes such as deuterium","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using Unitful, UnitfulAtomic, AtomsBase # hide\ndeuterium = Atom(:D, [0, 1, 2.]u\"bohr\")\natomic_number(deuterium) == 1\natomic_symbol(deuterium) == :D","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"An equivalent dict-like interface based on keys, haskey, get and pairs is also available. For example","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"keys(atom)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"atom[:species]","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"pairs(atom)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"This interface seamlessly generalises to working with user-specific atomic properties as will be discussed next.","category":"page"},{"location":"tutorial/#Optional-atomic-properties","page":"Tutorial","title":"Optional atomic properties","text":"","category":"section"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Custom properties can be attached to an Atom by supplying arbitrary keyword arguments upon construction. For example to attach a pseudopotential for using the structure with DFTK, construct the atom as","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using Unitful, UnitfulAtomic, AtomsBase # hide\natom = Atom(:C, [0, 1, 2.]u\"bohr\", pseudopotential=\"hgh/lda/c-q4\")","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"which will make the pseudopotential identifier available as","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"atom[:pseudopotential]","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Notice that such custom properties are fully integrated with the standard atomic properties, e.g. automatically available from the keys, haskey and pairs functions, e.g.:","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"@show haskey(atom, :pseudopotential)\npairs(atom)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Updating an atomic property proceeds similarly. E.g.","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using Unitful, UnitfulAtomic, AtomsBase # hide\nnewatom = Atom(atom; atomic_mass=13u\"u\")","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"makes a new carbon atom with all properties identical to atom (including custom ones), but setting the atomic_mass to 13 units.","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"To simplify interoperability some optional properties are reserved. For these:","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Throughout the AtomsBase ecosystem these property keys carry a well-defined meaning. I.e. if they are supported by a code, the code expects them to hold the data specified below.\nIf a consuming code cannot make use of these properties, it should at least warn the user about it. For example if a library or simulation code does not support such a feature and drops the respective information it should @warn or (even better) interrupt execution with an error.","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Property name Unit / Type Description\n:charge Charge Net charge of the atom\n:covalent_radius Length Covalent radius tabulated for the atom\n:vdw_radius Length VdW radius tabulated for the atom\n:magnetic_moments Union{Float64,Vector{Float64}} Initial magnetic moment\n:pseudopotential String Pseudopotential or PAW keyword or \"\" if Coulomb potential employed","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"A convenient way to iterate over all data stored in an atom offers the pairs function:","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"for (k, v) in pairs(atom)\n println(\"$k = $v\")\nend","category":"page"},{"location":"tutorial/#System-interface-and-conventions","page":"Tutorial","title":"System interface and conventions","text":"","category":"section"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Once the atoms are constructed these can be assembled into a system. For example to place a hydrogen molecule into a cubic box of 10Å and periodic boundary conditions, use:","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using Unitful, UnitfulAtomic, AtomsBase # hide\nbox = ([10.0, 0.0, 0.0]u\"Å\", [0.0, 10.0, 0.0]u\"Å\", [0.0, 0.0, 10.0]u\"Å\")\nhydrogen = periodic_system([Atom(:H, [0, 0, 1.]u\"Å\"),\n Atom(:H, [0, 0, 3.]u\"Å\")],\n box)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"An update constructor for systems is supported as well (see AbstractSystem). For example","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using AtomsBase: AbstractSystem\nAbstractSystem(hydrogen; \n cell_vectors=([5.0, 0.0, 0.0]u\"Å\", \n [0.0, 5.0, 0.0]u\"Å\", \n [0.0, 0.0, 5.0]u\"Å\"))","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"To update the atomic composition of the system, this function supports an atoms (or particles) keyword argument to supply the new set of atoms to be contained in the system.","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Note that in this example FlexibleSystem( ... ) would have worked as well (since we are updating a FlexibleSystem). However, using the AbstractSystem constructor to update the system is more general as it allows for type-specific dispatching when updating other data structures implementing the AbstractSystem interface.","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Similar to the atoms, system objects similarly support a functional-style access to system properties as well as a dict-style access:","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"cell_vectors(hydrogen)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"hydrogen[:periodicity]","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"pairs(hydrogen)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Moreover atomic properties of a specific atom or all atoms can be directly queried using the indexing notation:","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"hydrogen[1, :position] # Position of first atom","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"hydrogen[:, :position] # All atomic symbols","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Finally, supported keys of atomic properties can be directly queried at the system level using atomkeys and hasatomkey. Note that these functions only apply to atomic properties which are supported by all atoms of a system. In other words if a custom atomic property is only set in a few of the contained atoms, these functions will not consider it.","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"atomkeys(hydrogen)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"For constructing atomic systems the functions atomic_system, isolated_system, periodic_system are oftentimes more convenient as they provide specialisations for some standard atomic system setups. For example to setup a hydrogen system with periodic BCs, we can issue","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using Unitful, UnitfulAtomic, AtomsBase # hide\ncell_vectors = ([10.0, 0.0, 0.0]u\"Å\", [0.0, 10.0, 0.0]u\"Å\", [0.0, 0.0, 10.0]u\"Å\")\nhydrogen = periodic_system([:H => [0, 0, 1.]u\"Å\",\n :H => [0, 0, 3.]u\"Å\"],\n cell_vectors)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"To setup a silicon unit cell we can use fractional coordinates (which is common for solid-state simulations):","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using Unitful, UnitfulAtomic, AtomsBase # hide\ncell_vectors = 10.26 / 2 .* ([0, 0, 1]u\"bohr\", [1, 0, 1]u\"bohr\", [1, 1, 0]u\"bohr\")\nsilicon = periodic_system([:Si => ones(3)/8,\n :Si => -ones(3)/8],\n cell_vectors, fractional=true)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Alternatively we can also place an isolated H2 molecule in vacuum, which is the standard setup for molecular simulations:","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using Unitful, UnitfulAtomic, AtomsBase # hide\nhydrogen = isolated_system([:H => [0, 0, 1.]u\"bohr\",\n :H => [0, 0, 3.]u\"bohr\"])","category":"page"},{"location":"tutorial/#Optional-system-properties","page":"Tutorial","title":"Optional system properties","text":"","category":"section"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Similar to atoms, FlexibleSystem and FastSystem also support storing arbitrary data, for example","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using Unitful, UnitfulAtomic, AtomsBase # hide\nsystem = isolated_system([:H => [0, 0, 1.]u\"bohr\", :H => [0, 0, 3.]u\"bohr\"]; extra_data=42)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Again these custom properties are fully integrated with keys, haskey, pairs and get.","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"@show keys(system)","category":"page"}] +[{"location":"interface/","page":"Interface","title":"Interface","text":"CurrentModule = AtomsBase","category":"page"},{"location":"interface/#Interface","page":"Interface","title":"Interface","text":"","category":"section"},{"location":"interface/","page":"Interface","title":"Interface","text":"This page formally defines the AtomsBase interface for particle systems. The main use-case for which the interface is designed is for systems of atoms. For this case some additional functionality is provided. The main abstract type introduced in AtomsBase is ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"AbstractSystem.","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"An implementation of AbstractSystem{D}, ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"struct ConcreteSystem{D} <: AbstractSystem{D}\n # ... \nend","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"specifies a system of particles that have a position in D dimensional Euclidean space. That is, the parameter D indicates the number of spatial dimensions into which each particle is embedded. A particle will normally also have additional properties such as mass, charge, chemical species, etc, but those are ignored in the interpretation of D.","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"The interface aims to achieve predictable behavior of several core functions to access information about a particle system. ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"Core Interface : this is a minimal read-only core of the AtomsBase interface and must be implemented by a subtype of AtomsBase.AbstractSystem to enable the implementation to be used across the AtomsBase ecosystem. \nSetter Interface : (optional) It is strongly recommended that implementations requiring mutation follow this interface. \nOptional properties interface : (optional) For some use-cases (e.g. managing datasets) it can be useful to allow a system to store more general properties about a particle system (or the individual particles themselves). The optional properties interface specifies the recommended interface for such as scenario. ","category":"page"},{"location":"interface/#Core-Interface","page":"Interface","title":"Core Interface","text":"","category":"section"},{"location":"interface/","page":"Interface","title":"Interface","text":"A minimal implementation of the AtomsBase interface is read-only and must implement methods for the functions listed as follows. ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"Base.length(system)\nBase.getindex(system, i) \n`AtomsBase.cell(system)\nAtomsBase.position(system, i)\nAtomsBase.mass(system, i)\nAtomsBase.species(system, i)","category":"page"},{"location":"interface/#System-Properties-and-Cell-Interface","page":"Interface","title":"System Properties and Cell Interface","text":"","category":"section"},{"location":"interface/","page":"Interface","title":"Interface","text":"A system is specified by a computational cell and particles within that cell (or, domain). System properties are properties of the entire particle system, as opposed to properties of individual particles. ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"Base.length(system) : return an Integer, the number of particles in the system; if the system describes a periodic cell, then the number of particles in one period of the cell is returned.\n`AtomsBase.cell(system) : returns an object cell that specifies the computational cell. Two reference implementations, PeriodicCell and IsolatedCell that should serve most purposes are provided. ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"A cell object must implement methods for the following functions: ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"AtomsBase.cell_vectors(cell) : returns NTuple{D, SVector{D, T}} the cell vectors that specify the computational domain if it is finite. For isolated systems, the return values are unspecified.\nAtomsBase.periodicity(cell) : returns NTuple{D, Bool}, booleans that specify whether the system is periodic in the direction of the D cell vectors provided by cell_vectors. For isolated systems periodicity must return (false, ..., false).\nAtomsBase.n_dimensions(cell) : returns the dimensionality of the computational cell, it must match the dimensionality of the system. ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"AtomsBase provides cell_vectors and periodicity methods so that they can be called with a system as argument, i.e., ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"cell_vectors(system) = cell_vectors(cell(system))\nperiodicity(system) = periodicity(cell(system))","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"Two recommended general purpose implementations of computational cells are provided as part of AtomsBase: ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"PeriodicCell : implementation of a periodic parallelepiped shaped cell\nIsolatedCell : implementation of a cell describing an isolated system within an infinite domain. ","category":"page"},{"location":"interface/#Particle-properties","page":"Interface","title":"Particle properties","text":"","category":"section"},{"location":"interface/","page":"Interface","title":"Interface","text":"position(system, i::Integer) : return an SVector{D, <: Unitful.Length} enconding the position of the ith particle\nmass(system, i::Integer) : return a <: Unitful.Mass, the mass of the ith particle\nspecies(system, i::Integer) : return an object that defines the particle species (kind, type, ...). In most cases this should be a categorical variable on which no arithmetic is defined. In atomistic simulation this is normally the chemical element (cf. AtomsBase.ChemicalSpecies), possibly augmented with additional information about the atom. But the interface does not require use of any specific type to define the particle species.","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"For each of property in [position, mass, species] there must also be defined ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"property(system, inds::AbstractVector{<: Integer}) : return a list (e.g. AbstractVector) of the requested property of the particles indexed by inds; \nproperty(system, :) : return a list of the requested property for all particles in the system.","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"AtomsBase provides default fallbacks for these methods but they will normally be inefficient. The caller cannot assume whether a view or a copy are returned. ","category":"page"},{"location":"interface/#Iteration-and-Indexing-over-systems","page":"Interface","title":"Iteration and Indexing over systems","text":"","category":"section"},{"location":"interface/","page":"Interface","title":"Interface","text":"There is a presumption of the ability to somehow extract an individual component (e.g. a single atom or molecule) of this system, though there are no constraints on the type of this component. To achieve this, an AbstractSystem object is expected to implement the Julia interfaces for iteration and indexing in order to access representations of individual components of the system. Some default dispatches of parts of these interfaces are already included, so the minimal set of functions to dispatch in a concrete implementation is Base.getindex and Base.length, though it may be desirable to customize additional behavior depending on context.","category":"page"},{"location":"interface/#Setter-Interface","page":"Interface","title":"Setter Interface","text":"","category":"section"},{"location":"interface/","page":"Interface","title":"Interface","text":"The optional setter / mutation interface consists of the following functions to be overloaded. ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"set_cell!(system, cell) \nset_position!(system, i, x) \nset_mass!(system, i, x)\nset_species!(system, i, x) \nset_cell_vectors!(cell, bb) \nset_periodicity!(cell, pbc) \ndeleteat!(system, i) : delete atoms i (or atoms i if a list of \":)\nappend!(system1, system2) : append system 2 to system 1, provided they are \"compatible\". ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"For each of the particle property setters, i may be an Integer, an AbstractVector{<: Integer} or :.","category":"page"},{"location":"interface/#Optional-properties-interface","page":"Interface","title":"Optional properties interface","text":"","category":"section"},{"location":"interface/","page":"Interface","title":"Interface","text":"For some use-cases (e.g. managing datasets) it can be useful to allow a system to store more general properties about a particle system or even the individual particles themselves. The optional properties interface specifies the recommended interface for such as scenario. The Tutorial provides a more detailed discussion and exmaples how these can be used. The prototype implementations also provide further details.","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"An implementation that wants to support the AtomsBase optional properties interface should implement the following methods: ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"System properties:","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"getindex\nhaskey\nget\nkeys\npairs","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"Particle properties","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"atomkeys \nhasatomkey ","category":"page"},{"location":"interface/#Future-Interface-Extensions","page":"Interface","title":"Future Interface Extensions","text":"","category":"section"},{"location":"interface/","page":"Interface","title":"Interface","text":"The AtomsBase developers are considering extending the AtomsBase interface with additional functions. Developers may keep this in mind during development. Issues or discussions related to this are welcome. ","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"Here we maintain a list of possibly future interface functions:","category":"page"},{"location":"interface/","page":"Interface","title":"Interface","text":"charge \ncharge_dipole \nvelocity\nmomentum \nspin\nmagnetic_moment\nmultiplicity ","category":"page"},{"location":"implementations/","page":"Implementations","title":"Implementations","text":"CurrentModule = AtomsBase","category":"page"},{"location":"implementations/#Prototype-Implementations","page":"Implementations","title":"Prototype Implementations","text":"","category":"section"},{"location":"implementations/","page":"Implementations","title":"Implementations","text":"AtomsBase provides two prototype implementations of AbstractSystem{D} that are exported: ","category":"page"},{"location":"implementations/","page":"Implementations","title":"Implementations","text":"FlexibleSystem\nFastSystem","category":"page"},{"location":"implementations/","page":"Implementations","title":"Implementations","text":"and are briefly discussed in more detail in the remainder of this page. ","category":"page"},{"location":"implementations/#Struct-of-Arrays-vs.-Array-of-Structs","page":"Implementations","title":"Struct-of-Arrays vs. Array-of-Structs","text":"","category":"section"},{"location":"implementations/","page":"Implementations","title":"Implementations","text":"The \"struct-of-arrays\" (SoA) vs. \"array-of-structs\" (AoS) is a common design dilemma in representations of systems of particles. AtomsBase is deliberately designed to be agnostic to how a concrete implementation chooses to structure its data. Some specific notes regarding how implementations might differ for these two paradigms are included below.","category":"page"},{"location":"implementations/","page":"Implementations","title":"Implementations","text":"A way to think about this broadly is that the difference amounts to the ordering of function calls. For example, to get the position of a single particle in an AoS implementation, the explicit function chaining would be position(getindex(sys)) (i.e. extract the single struct representing the particle of interest and query its position), while for SoA, one should prefer an implementation like getindex(position(sys)) (extract the array of positions, then index into it for a single particle). The beauty of an abstract interface in Julia is that these details can be, in large part, abstracted away through method dispatch such that the end user sees the same expected behavior irrespective of how things are implemented \"under the hood\".","category":"page"},{"location":"implementations/#Struct-of-Arrays-/-FastSystem","page":"Implementations","title":"Struct of Arrays / FastSystem","text":"","category":"section"},{"location":"implementations/","page":"Implementations","title":"Implementations","text":"The file fast_system.jl contains an implementation of AtomsBase based on the struct-of-arrays approach. All species data is stored as plain arrays, but for convenience indexing of individual atoms is supported by a light-weight AtomView. See the implementation files as well as the tests for how these can be used.","category":"page"},{"location":"implementations/#Atoms-and-FlexibleSystem","page":"Implementations","title":"Atoms and FlexibleSystem","text":"","category":"section"},{"location":"implementations/","page":"Implementations","title":"Implementations","text":"A flexible implementation of the interface is provided by the FlexibleSystem and the Atom structs for representing atomic systems.These are discussed in detail in the tutorial. ","category":"page"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"CurrentModule = AtomsBase","category":"page"},{"location":"utilities/#Utilities","page":"Utilities","title":"Utilities","text":"","category":"section"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"This page documents some utilities that AtomsBase provides in addition to the interface. This documentation is preliminary. PRs to improve it are welcome. ","category":"page"},{"location":"utilities/#Cell-Types","page":"Utilities","title":"Cell Types","text":"","category":"section"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"As of AtomsBase 0.4 we recommend that implementations of the interface specify a computational cell type. To simplify this, AtomsBase provides two prototype implementations: ","category":"page"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"PeriodicCell : implements the standard parallepiped shaped cell defined through three cell vectors and periodicity (true or false) along each cell vector.\nIsolatedCell : implements a computational cell that is open (infinite) in all directions, i.e. the entire space.","category":"page"},{"location":"utilities/#Chemical-Species","page":"Utilities","title":"Chemical Species","text":"","category":"section"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"The function AtomsBase.species(sys, i) return the particle species of a particle (or multiple particles). AtomsBase does not enforce any specific type to be returned. However, it is recommended that systems describing atomic structures use - whenever possible - the ChemicalSpecies type that is implemented as part of AtomsBase.","category":"page"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"ChemicalSpecies : a prototype implementation and recommended default for the species of an atom.","category":"page"},{"location":"utilities/#Convenience-functions","page":"Utilities","title":"Convenience functions","text":"","category":"section"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"AtomsBase provides a number of convenience utilities that should work for any system that implements the AtomsBase interface. If they not work as expected this is likely a bug and should be reported as an issue. ","category":"page"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"atomic_mass = mass : deprecated \nn_dimensions \natomic_symbol\natomic_number\nelement_symbol\nchemical_formula\nelement\nvisualize_ascii","category":"page"},{"location":"utilities/#Testing-Utilities","page":"Utilities","title":"Testing Utilities","text":"","category":"section"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"The AtomsBaseTesting package provides a few utility functions to test downstream packages for having properly implemented the AtomsBase interface. The tests are probably not complete, but they should be a good start ... and as always PRs are welcome.","category":"page"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"Two functions are provided, namely make_test_system to generate standard FlexibleSystem test systems and test_approx_eq for testing approximate equality between AtomsBase systems (of not necessarily the same type). The basic idea of the functions is to use make_test_system to obtain a test system, construct an identical system in a downstream library and then use test_approx_eq to check they are actually equal.","category":"page"},{"location":"utilities/","page":"Utilities","title":"Utilities","text":"For usage examples see the tests of ExtXYZ, AtomsIO, Chemfiles and ASEconnect.","category":"page"},{"location":"apireference/","page":"Reference","title":"Reference","text":"CurrentModule = AtomsBase","category":"page"},{"location":"apireference/#API-reference","page":"Reference","title":"API reference","text":"","category":"section"},{"location":"apireference/#Index","page":"Reference","title":"Index","text":"","category":"section"},{"location":"apireference/","page":"Reference","title":"Reference","text":"Pages = [\"apireference.md\"]","category":"page"},{"location":"apireference/#Types","page":"Reference","title":"Types","text":"","category":"section"},{"location":"apireference/","page":"Reference","title":"Reference","text":"AbstractSystem\nIsolatedCell\nPeriodicCell \nAtomView\nChemicalSpecies ","category":"page"},{"location":"apireference/#AtomsBase.AbstractSystem","page":"Reference","title":"AtomsBase.AbstractSystem","text":"AbstractSystem{D}\n\nA D-dimensional particle system.\n\n\n\n\n\n","category":"type"},{"location":"apireference/#AtomsBase.IsolatedCell","page":"Reference","title":"AtomsBase.IsolatedCell","text":" IsolatedCell{D, T}\n\nDefines a computational domain / cell describing an open system.\n\n\n\n\n\n","category":"type"},{"location":"apireference/#AtomsBase.PeriodicCell","page":"Reference","title":"AtomsBase.PeriodicCell","text":"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.\n\n\n\n\n\n","category":"type"},{"location":"apireference/#AtomsBase.AtomView","page":"Reference","title":"AtomsBase.AtomView","text":"TODO: reintroduce the original docs (failing docstest...)\n\n\n\n\n\n","category":"type"},{"location":"apireference/#AtomsBase.ChemicalSpecies","page":"Reference","title":"AtomsBase.ChemicalSpecies","text":"Encodes a chemical species by wrapping an integer that represents the atomic number, the number of protons, and additional name as max 4 characters.\n\nThe name variable can be used as atom name in PDB format or some other way to mark same kind of atoms from one another.\n\nConstructors for standard chemical elements\n\nChemicalSpecies(Z::Integer)\nChemicalSpecies(sym::Symbol) \n# for example \nChemicalSpecies(:C)\nChemicalSpecies(6)\n\nConstructors for isotopes \n\n# standard carbon = C-12\nChemicalSpecies(:C)\nChemicalSpecies(:C; n_neutrons = 6)\n\n# three equivalent constructors for C-13\nChemicalSpecies(:C; n_neutrons = 7)\nChemicalSpecies(6; n_neutrons = 7)\nChemicalSpecies(:C13)\n# deuterium\nChemicalSpecies(:D)\n\nConstructors for names\n\nChemicalSpecies(:C; atom_name=:MyC)\nChemicalSpecies(:C13; atom_name=:MyC)\n\nComparisons with different isotopes and names\n\n# true\nChemicalSpecies(:C13) == ChemicalSpecies(:C)\n\n# false\nChemicalSpecies(:C12) == ChemicalSpecies(:C13)\n\n# true\nChemicalSpecies(:C; atom_name=:MyC) == ChemicalSpecies(:C)\n\n# true\nChemicalSpecies(:C12; atom_name=:MyC) == ChemicalSpecies(:C12)\n\n# false\nChemicalSpecies(:C; atom_name=:MyC) == ChemicalSpecies(:C12)\n\n# true\nChemicalSpecies(:C12; atom_name=:MyC) == ChemicalSpecies(:C)\n\n# true\nChemicalSpecies(:C; atom_name=:MyC) == ChemicalSpecies(:C12; atom_name=:MyC)\n\n\n\n\n\n","category":"type"},{"location":"apireference/#System-properties","page":"Reference","title":"System properties","text":"","category":"section"},{"location":"apireference/","page":"Reference","title":"Reference","text":"cell_vectors\nset_cell_vectors!\nperiodicity\nset_periodicity!\ncell \nset_cell! \nn_dimensions\natomkeys\nhasatomkey\nchemical_formula\nvisualize_ascii","category":"page"},{"location":"apireference/#AtomsBase.cell_vectors","page":"Reference","title":"AtomsBase.cell_vectors","text":"cell_vectors(sys::AbstractSystem{D})\n\nReturn a tuple of length D of vectors of length D that describe the cell in which the system sys is defined.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.set_cell_vectors!","page":"Reference","title":"AtomsBase.set_cell_vectors!","text":"set_cell_vectors!(sys::AbstractSystem{D}, bb::NTuple{D, SVector{D, L}})\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.periodicity","page":"Reference","title":"AtomsBase.periodicity","text":"periodicity(sys::AbstractSystem{D})\n\nReturn a NTuple{D, Bool} indicating whether the system is periodic along a cell vector as specified by cell_vectors.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.set_periodicity!","page":"Reference","title":"AtomsBase.set_periodicity!","text":"set_periodicity!(sys::AbstractSystem{D}, pbc::NTuple{D, Bool})\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.cell","page":"Reference","title":"AtomsBase.cell","text":"cell(sys::AbstractSystem)\n\nReturns the computational cell (domain). See e.g. PeriodicCell and IsolatedCell.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.set_cell!","page":"Reference","title":"AtomsBase.set_cell!","text":"set_cell!(sys, cell)\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.n_dimensions","page":"Reference","title":"AtomsBase.n_dimensions","text":"n_dimensions(::AbstractSystem)\n\nReturn number of dimensions.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.atomkeys","page":"Reference","title":"AtomsBase.atomkeys","text":"atomkeys(sys::AbstractSystem)\n\nReturn the atomic properties, which are available in all atoms of the system.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.hasatomkey","page":"Reference","title":"AtomsBase.hasatomkey","text":"hasatomkey(system::AbstractSystem, x::Symbol)\n\nReturns true whether the passed property available in all atoms of the passed system.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.chemical_formula","page":"Reference","title":"AtomsBase.chemical_formula","text":"Returns the chemical formula of an AbstractSystem as a string.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.visualize_ascii","page":"Reference","title":"AtomsBase.visualize_ascii","text":"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).\n\n\n\n\n\n","category":"function"},{"location":"apireference/#Species-/-atom-properties","page":"Reference","title":"Species / atom properties","text":"","category":"section"},{"location":"apireference/","page":"Reference","title":"Reference","text":"position\nset_position!\nmass\nset_mass!\nspecies\nset_species!\nvelocity\nset_velocity!\natomic_number\natomic_symbol\natom_name\nelement_symbol\nelement ","category":"page"},{"location":"apireference/#Base.position","page":"Reference","title":"Base.position","text":"position(sys::AbstractSystem, i)\n\nReturn 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 == :.\n\nThe return type should be a vector of vectors each containing D elements that are <:Unitful.Length.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.set_position!","page":"Reference","title":"AtomsBase.set_position!","text":"set_position!(sys::AbstractSystem{D}, i, x)\n\nIf i is an integer then x is an SVector{D, L} with L <: Unitful.Length\nIf i is an AbstractVector{<: Integer} or : then x is an AbstractVector{SVector{D, L}}\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.mass","page":"Reference","title":"AtomsBase.mass","text":"mass(sys::AbstractSystem, i)\n\nMass of a particle if i::Integer, vector of masses if i is a vector of integers or :. The elements are <: Unitful.Mass.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.set_mass!","page":"Reference","title":"AtomsBase.set_mass!","text":"set_mass!(sys::AbstractSystem, i, m)\n\nIf i is an integer then m is a Unitful.Mass\nIf i is an AbstractVector{<: Integer} or : then x is an AbstractVector{<: Unitful.Mass}\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.species","page":"Reference","title":"AtomsBase.species","text":"species(::AbstractSystem, i)\n\nReturn the species (type, category, ...) of a particle or particles.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.set_species!","page":"Reference","title":"AtomsBase.set_species!","text":"set_species!(sys::AbstractSystem, i, s)\n\nIf i is an integer then s is an object describing the particle species, e.g., ChemicalSpecies\nIf i is an AbstractVector{<: Integer} or : then x is an AbstractVector of species objects.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.velocity","page":"Reference","title":"AtomsBase.velocity","text":"velocity(sys::AbstractSystem, i)\n\nReturn 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.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.set_velocity!","page":"Reference","title":"AtomsBase.set_velocity!","text":"set_velocity!(sys::AbstractSystem, i, v)\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.atomic_number","page":"Reference","title":"AtomsBase.atomic_number","text":"atomic_number(sys::AbstractSystem, i)\natomic_number(species)\n\nVector of atomic numbers in the system sys or the atomic number of a particular species / the ith species in sys.\n\nThe 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.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.atomic_symbol","page":"Reference","title":"AtomsBase.atomic_symbol","text":"atomic_symbol(sys::AbstractSystem, i)\natomic_symbol(species)\n\nVector of atomic symbols in the system sys or the atomic symbol of a particular species / the ith species in sys.\n\nThe 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.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.atom_name","page":"Reference","title":"AtomsBase.atom_name","text":"atom_name(species)\natom_name(sys::AbstractSystem, i)\n\nReturn atomic name (Symbol) for species or vector of names for sys.\n\nDefaults to atomic_symbol, if name field is zero or not defined.\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.element_symbol","page":"Reference","title":"AtomsBase.element_symbol","text":"element_symbol(system, index)\nelement_symbol(species)\n\nReturn 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).\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.element","page":"Reference","title":"AtomsBase.element","text":"The element corresponding to a species/atom (or missing).\n\n\n\n\n\n","category":"function"},{"location":"apireference/#Prototype-Implementation","page":"Reference","title":"Prototype Implementation","text":"","category":"section"},{"location":"apireference/","page":"Reference","title":"Reference","text":"Atom\nFlexibleSystem\nFastSystem\natomic_system\nisolated_system\nperiodic_system ","category":"page"},{"location":"apireference/#AtomsBase.Atom","page":"Reference","title":"AtomsBase.Atom","text":"Atom(identifier::AtomId, position::AbstractVector; kwargs...)\nAtom(identifier::AtomId, position::AbstractVector, velocity::AbstractVector; kwargs...)\nAtom(; atomic_number, position, velocity=zeros(D)u\"bohr/s\", kwargs...)\n\nConstruct an atomic located at the cartesian coordinates position with (optionally) the given cartesian velocity. Note that AtomId = Union{Symbol,AbstractString,Integer,ChemicalSymbol}.\n\nSupported kwargs include species, mass, as well as user-specific custom properties.\n\n\n\n\n\nAtom(atom::Atom; kwargs...)\n\nUpdate 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.\n\nExamples\n\nConstruct a standard hydrogen atom located at the origin\n\njulia> hydrogen = Atom(:H, zeros(3)u\"Å\")\n\nand now amend its charge and atomic mass\n\njulia> Atom(atom; mass=1.0u\"u\", charge=-1.0u\"e_au\")\n\n\n\n\n\n","category":"type"},{"location":"apireference/#AtomsBase.FlexibleSystem","page":"Reference","title":"AtomsBase.FlexibleSystem","text":"FlexibleSystem(particles, cell_vectors, periodicity; kwargs...)\nFlexibleSystem(particles; cell_vectors, periodicity, kwargs...)\nFlexibleSystem(particles, cell; kwargs...)\n\nConstruct a flexible system, a versatile data structure for atomistic systems, which puts an emphasis on flexibility rather than speed.\n\n\n\n\n\nFlexibleSystem(system; kwargs...)\n\nUpdate constructor. See AbstractSystem for details.\n\n\n\n\n\n","category":"type"},{"location":"apireference/#AtomsBase.FastSystem","page":"Reference","title":"AtomsBase.FastSystem","text":"FastSystem\n\nA struct of arrays style prototype implementation of the AtomsBase interface. \n\n\n\n\n\n","category":"type"},{"location":"apireference/#AtomsBase.atomic_system","page":"Reference","title":"AtomsBase.atomic_system","text":"atomic_system(atoms::AbstractVector, cell_vectors, periodicity; kwargs...)\n\nConstruct a FlexibleSystem using the passed atoms and boundary box and conditions. Extra kwargs are stored as custom system properties.\n\nExamples\n\nConstruct a hydrogen molecule in a box, which is periodic only in the first two dimensions\n\njulia> cell_vectors = [[10.0, 0.0, 0.0], [0.0, 10.0, 0.0], [0.0, 0.0, 10.0]]u\"Å\"\njulia> pbcs = (true, true, false)\njulia> hydrogen = atomic_system([:H => [0, 0, 1.]u\"bohr\",\n :H => [0, 0, 3.]u\"bohr\"],\n cell_vectors, pbcs)\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.isolated_system","page":"Reference","title":"AtomsBase.isolated_system","text":"isolated_system(atoms::AbstractVector; kwargs...)\n\nConstruct 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.\n\nExamples\n\nConstruct a hydrogen molecule\n\njulia> hydrogen = isolated_system([:H => [0, 0, 1.]u\"bohr\", :H => [0, 0, 3.]u\"bohr\"])\n\n\n\n\n\n","category":"function"},{"location":"apireference/#AtomsBase.periodic_system","page":"Reference","title":"AtomsBase.periodic_system","text":"periodic_system(atoms::AbstractVector, box; fractional=false, kwargs...)\n\nConstruct 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.\n\nExamples\n\nSetup a hydrogen molecule inside periodic BCs:\n\njulia> cell_vectors = ([10.0, 0.0, 0.0]u\"Å\", [0.0, 10.0, 0.0]u\"Å\", [0.0, 0.0, 10.0]u\"Å\")\njulia> hydrogen = periodic_system([:H => [0, 0, 1.]u\"bohr\",\n :H => [0, 0, 3.]u\"bohr\"],\n cell_vectors)\n\nSetup a silicon unit cell using fractional positions\n\njulia> box = 10.26 / 2 * [[0, 0, 1], [1, 0, 1], [1, 1, 0]]u\"bohr\"\njulia> silicon = periodic_system([:Si => ones(3)/8,\n :Si => -ones(3)/8],\n box, fractional=true)\n\n\n\n\n\n","category":"function"},{"location":"#AtomsBase","page":"Home","title":"AtomsBase","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"A Julian abstract interface for atomic structures.","category":"page"},{"location":"","page":"Home","title":"Home","text":"(Image: Stable) (Image: Dev) (Image: Build Status) (Image: Coverage)","category":"page"},{"location":"","page":"Home","title":"Home","text":"AtomsBase is an abstract interface for representation of atomic geometries in Julia. It aims to be a lightweight means of facilitating interoperability between various tools including, e.g., ","category":"page"},{"location":"","page":"Home","title":"Home","text":"Simulation engines, e.g. molecular dynamics, geometry optimization, etc \nComputing chemical or mechanical properties, e.g., via DFT, or interatomic potentials,\nIntegration with third party-libraries\nI/O with standard file formats (.cif, .xyz, ...)\nautomatic differentiation and machine learning systems\nnumerical tools: sampling, integration schemes, etc.\nvisualization (e.g. plot recipes)","category":"page"},{"location":"","page":"Home","title":"Home","text":"While AtomsBase focusses on representation of atomic systems, the sister package AtomsCalculators provides a general interface to compute properties of such systems. ","category":"page"},{"location":"","page":"Home","title":"Home","text":"Currently, the design philosophy is to be as lightweight as possible with a small set of required function dispatches to make adopting the interface easy. We also provide prototype implementations that we envision to be broadly applicable. If features beyond these are required we encourage developers to open PRs or provide their own implementations. For more on how to use the package, see the documentation.","category":"page"},{"location":"#Packages-using-AtomsBase","page":"Home","title":"Packages using AtomsBase","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"The following (not all yet-registered) packages currently make use of AtomsBase:","category":"page"},{"location":"","page":"Home","title":"Home","text":"ACEpotentials\nASEPotential\nASEconvert : integration with the Atomistic Simulation Environment\nAtomIO: I/O for atomic structures, also wraps some ASE functionality\nAtomistic: integrated workflow for MD simulations, part of CESMIX\nAutoBZCore.jl: Brillouin-zone integration\nBFPIS\nChemistryFeaturization: Interface for featurization of atomic structures for input into machine learning models, part of Chemellia\nDFTK: density functional theory simulations\nEmpiricalPotentials\nExtXYZ: Parser for extended XYZ files\nInteratomicPotentials: implementations of a variety of interatomic potentials, also part of CESMIX\nMolly: molecular dynamics simulations\nXtals: I/O and structure representation for crystals","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"CurrentModule = AtomsBase","category":"page"},{"location":"tutorial/#Tutorial","page":"Tutorial","title":"Tutorial","text":"","category":"section"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"This page gives an overview of using AtomsBase in practice and introduces the conventions followed across the AtomsBase ecosystem. It serves as a reference for both users interested in doing something with an AbstractSystem object as well as developers wishing to integrate their code with AtomsBase. See Interface for a precise specification of the AtomsBase interface.","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"For the examples we will mostly draw on the case of atomistic systems using the FlexibleSystem data structure. The Atom and FlexibleSystem data structure we focus on here should provide good defaults for many purposes.","category":"page"},{"location":"tutorial/#High-level-introduction","page":"Tutorial","title":"High-level introduction","text":"","category":"section"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"The main purpose of AtomsBase is to conveniently pass atomistic data between Julia packages. For example the following snippet loads an extxyz file using AtomsIO and returns it as an AtomsBase-compatible system (in data):","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using AtomsIO\ndata = load_system(\"Si.extxyz\")","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Next we use ASEconvert to convert this system to python, such that we can make use of the atomistic simulation environment (ASE) to form a (2, 1, 1) supercell, which is afterwards converted back to Julia (by forming another AtomsBase-compatible system).","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using ASEconvert\nsupercell = pyconvert(AbstractSystem, data * pytuple((2, 1, 1)))","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Finally the supercell is passed to DFTK, where we attach pseudopotentials and run a PBE calculation:","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using DFTK\ncell_with_pseudos = attach_psp(supercell, Si=\"hgh/pbe/si-q4\")\nmodel = model_PBE(cell_with_pseudos)\nbasis = PlaneWaveBasis(model, Ecut=30, kgrid=(5, 5, 5)\nself_consistent_field(basis).energy.total","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"For more high-level examples see also:","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"The DFTK documentation page on AtomsBase.\nThe AtomsIO documentation","category":"page"},{"location":"tutorial/#Atom-interface-and-conventions","page":"Tutorial","title":"Atom interface and conventions","text":"","category":"section"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"An Atom object can be constructed just by passing an identifier (e.g. symbol like :C, atomic number like 6) and a vector of positions as","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using Unitful, UnitfulAtomic, AtomsBase # hide\natom = Atom(:C, [0, 1, 2.]u\"bohr\")","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"This automatically fills the atom with standard data such as the atomic mass. See also the reference of the Atom function for more ways to construct an atom.","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Such data can be accessed using the AtomsBase interface functions, such as:","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"atomic_mass(atom)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"atomic_symbol(atom)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"atomic_number(atom)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"position(atom)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"velocity(atom)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"See atom.jl and the respective API documentation for details. Notice in particular that atomic_number specifies the element whereas species and also atomic_symbol may be more specific and may e.g. specify isotopes such as deuterium","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using Unitful, UnitfulAtomic, AtomsBase # hide\ndeuterium = Atom(:D, [0, 1, 2.]u\"bohr\")\natomic_number(deuterium) == 1\natomic_symbol(deuterium) == :D","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"An equivalent dict-like interface based on keys, haskey, get and pairs is also available. For example","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"keys(atom)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"atom[:species]","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"pairs(atom)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"This interface seamlessly generalises to working with user-specific atomic properties as will be discussed next.","category":"page"},{"location":"tutorial/#Optional-atomic-properties","page":"Tutorial","title":"Optional atomic properties","text":"","category":"section"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Custom properties can be attached to an Atom by supplying arbitrary keyword arguments upon construction. For example to attach a pseudopotential for using the structure with DFTK, construct the atom as","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using Unitful, UnitfulAtomic, AtomsBase # hide\natom = Atom(:C, [0, 1, 2.]u\"bohr\", pseudopotential=\"hgh/lda/c-q4\")","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"which will make the pseudopotential identifier available as","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"atom[:pseudopotential]","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Notice that such custom properties are fully integrated with the standard atomic properties, e.g. automatically available from the keys, haskey and pairs functions, e.g.:","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"@show haskey(atom, :pseudopotential)\npairs(atom)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Updating an atomic property proceeds similarly. E.g.","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using Unitful, UnitfulAtomic, AtomsBase # hide\nnewatom = Atom(atom; atomic_mass=13u\"u\")","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"makes a new carbon atom with all properties identical to atom (including custom ones), but setting the atomic_mass to 13 units.","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"To simplify interoperability some optional properties are reserved. For these:","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Throughout the AtomsBase ecosystem these property keys carry a well-defined meaning. I.e. if they are supported by a code, the code expects them to hold the data specified below.\nIf a consuming code cannot make use of these properties, it should at least warn the user about it. For example if a library or simulation code does not support such a feature and drops the respective information it should @warn or (even better) interrupt execution with an error.","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Property name Unit / Type Description\n:charge Charge Net charge of the atom\n:covalent_radius Length Covalent radius tabulated for the atom\n:vdw_radius Length VdW radius tabulated for the atom\n:magnetic_moments Union{Float64,Vector{Float64}} Initial magnetic moment\n:pseudopotential String Pseudopotential or PAW keyword or \"\" if Coulomb potential employed","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"A convenient way to iterate over all data stored in an atom offers the pairs function:","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"for (k, v) in pairs(atom)\n println(\"$k = $v\")\nend","category":"page"},{"location":"tutorial/#System-interface-and-conventions","page":"Tutorial","title":"System interface and conventions","text":"","category":"section"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Once the atoms are constructed these can be assembled into a system. For example to place a hydrogen molecule into a cubic box of 10Å and periodic boundary conditions, use:","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using Unitful, UnitfulAtomic, AtomsBase # hide\nbox = ([10.0, 0.0, 0.0]u\"Å\", [0.0, 10.0, 0.0]u\"Å\", [0.0, 0.0, 10.0]u\"Å\")\nhydrogen = periodic_system([Atom(:H, [0, 0, 1.]u\"Å\"),\n Atom(:H, [0, 0, 3.]u\"Å\")],\n box)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"An update constructor for systems is supported as well (see AbstractSystem). For example","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using AtomsBase: AbstractSystem\nAbstractSystem(hydrogen; \n cell_vectors=([5.0, 0.0, 0.0]u\"Å\", \n [0.0, 5.0, 0.0]u\"Å\", \n [0.0, 0.0, 5.0]u\"Å\"))","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"To update the atomic composition of the system, this function supports an atoms (or particles) keyword argument to supply the new set of atoms to be contained in the system.","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Note that in this example FlexibleSystem( ... ) would have worked as well (since we are updating a FlexibleSystem). However, using the AbstractSystem constructor to update the system is more general as it allows for type-specific dispatching when updating other data structures implementing the AbstractSystem interface.","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Similar to the atoms, system objects similarly support a functional-style access to system properties as well as a dict-style access:","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"cell_vectors(hydrogen)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"hydrogen[:periodicity]","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"pairs(hydrogen)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Moreover atomic properties of a specific atom or all atoms can be directly queried using the indexing notation:","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"hydrogen[1, :position] # Position of first atom","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"hydrogen[:, :position] # All atomic symbols","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Finally, supported keys of atomic properties can be directly queried at the system level using atomkeys and hasatomkey. Note that these functions only apply to atomic properties which are supported by all atoms of a system. In other words if a custom atomic property is only set in a few of the contained atoms, these functions will not consider it.","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"atomkeys(hydrogen)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"For constructing atomic systems the functions atomic_system, isolated_system, periodic_system are oftentimes more convenient as they provide specialisations for some standard atomic system setups. For example to setup a hydrogen system with periodic BCs, we can issue","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using Unitful, UnitfulAtomic, AtomsBase # hide\ncell_vectors = ([10.0, 0.0, 0.0]u\"Å\", [0.0, 10.0, 0.0]u\"Å\", [0.0, 0.0, 10.0]u\"Å\")\nhydrogen = periodic_system([:H => [0, 0, 1.]u\"Å\",\n :H => [0, 0, 3.]u\"Å\"],\n cell_vectors)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"To setup a silicon unit cell we can use fractional coordinates (which is common for solid-state simulations):","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using Unitful, UnitfulAtomic, AtomsBase # hide\ncell_vectors = 10.26 / 2 .* ([0, 0, 1]u\"bohr\", [1, 0, 1]u\"bohr\", [1, 1, 0]u\"bohr\")\nsilicon = periodic_system([:Si => ones(3)/8,\n :Si => -ones(3)/8],\n cell_vectors, fractional=true)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Alternatively we can also place an isolated H2 molecule in vacuum, which is the standard setup for molecular simulations:","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using Unitful, UnitfulAtomic, AtomsBase # hide\nhydrogen = isolated_system([:H => [0, 0, 1.]u\"bohr\",\n :H => [0, 0, 3.]u\"bohr\"])","category":"page"},{"location":"tutorial/#Optional-system-properties","page":"Tutorial","title":"Optional system properties","text":"","category":"section"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Similar to atoms, FlexibleSystem and FastSystem also support storing arbitrary data, for example","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"using Unitful, UnitfulAtomic, AtomsBase # hide\nsystem = isolated_system([:H => [0, 0, 1.]u\"bohr\", :H => [0, 0, 3.]u\"bohr\"]; extra_data=42)","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"Again these custom properties are fully integrated with keys, haskey, pairs and get.","category":"page"},{"location":"tutorial/","page":"Tutorial","title":"Tutorial","text":"@show keys(system)","category":"page"}] } diff --git a/dev/tutorial/index.html b/dev/tutorial/index.html index 6b1e943..03bb980 100644 --- a/dev/tutorial/index.html +++ b/dev/tutorial/index.html @@ -16,12 +16,12 @@ 0.0 nm s^-1 0.0 nm s^-1

See atom.jl and the respective API documentation for details. Notice in particular that atomic_number specifies the element whereas species and also atomic_symbol may be more specific and may e.g. specify isotopes such as deuterium

deuterium = Atom(:D, [0, 1, 2.]u"bohr")
 atomic_number(deuterium) == 1
-atomic_symbol(deuterium) == :D
true

An equivalent dict-like interface based on keys, haskey, get and pairs is also available. For example

keys(atom)
(:position, :velocity, :species, :mass)
atom[:species]
C
pairs(atom)
Base.Generator{NTuple{4, Symbol}, AtomsBase.var"#57#58"{Atom{3, Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(a₀,), 𝐋, nothing}}, Unitful.Quantity{Float64, 𝐋 𝐓^-1, Unitful.FreeUnits{(nm, s^-1), 𝐋 𝐓^-1, nothing}}, Unitful.Quantity{Float64, 𝐌, Unitful.FreeUnits{(u,), 𝐌, nothing}}}}}(AtomsBase.var"#57#58"{Atom{3, Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(a₀,), 𝐋, nothing}}, Unitful.Quantity{Float64, 𝐋 𝐓^-1, Unitful.FreeUnits{(nm, s^-1), 𝐋 𝐓^-1, nothing}}, Unitful.Quantity{Float64, 𝐌, Unitful.FreeUnits{(u,), 𝐌, nothing}}}}(Atom(C,  [       0,        1,        2]u"a₀")), (:position, :velocity, :species, :mass))

This interface seamlessly generalises to working with user-specific atomic properties as will be discussed next.

Optional atomic properties

Custom properties can be attached to an Atom by supplying arbitrary keyword arguments upon construction. For example to attach a pseudopotential for using the structure with DFTK, construct the atom as

atom = Atom(:C, [0, 1, 2.]u"bohr", pseudopotential="hgh/lda/c-q4")
Atom(C, Z = 6, m = 12.011 u):
+atomic_symbol(deuterium) == :D
true

An equivalent dict-like interface based on keys, haskey, get and pairs is also available. For example

keys(atom)
(:position, :velocity, :species, :mass)
atom[:species]
C
pairs(atom)
Base.Generator{NTuple{4, Symbol}, AtomsBase.var"#58#59"{Atom{3, Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(a₀,), 𝐋, nothing}}, Unitful.Quantity{Float64, 𝐋 𝐓^-1, Unitful.FreeUnits{(nm, s^-1), 𝐋 𝐓^-1, nothing}}, Unitful.Quantity{Float64, 𝐌, Unitful.FreeUnits{(u,), 𝐌, nothing}}}}}(AtomsBase.var"#58#59"{Atom{3, Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(a₀,), 𝐋, nothing}}, Unitful.Quantity{Float64, 𝐋 𝐓^-1, Unitful.FreeUnits{(nm, s^-1), 𝐋 𝐓^-1, nothing}}, Unitful.Quantity{Float64, 𝐌, Unitful.FreeUnits{(u,), 𝐌, nothing}}}}(Atom(C,  [       0,        1,        2]u"a₀")), (:position, :velocity, :species, :mass))

This interface seamlessly generalises to working with user-specific atomic properties as will be discussed next.

Optional atomic properties

Custom properties can be attached to an Atom by supplying arbitrary keyword arguments upon construction. For example to attach a pseudopotential for using the structure with DFTK, construct the atom as

atom = Atom(:C, [0, 1, 2.]u"bohr", pseudopotential="hgh/lda/c-q4")
Atom(C, Z = 6, m = 12.011 u):
     position          : [0,1,2]u"a₀"
     species           : C
     pseudopotential   : hgh/lda/c-q4

which will make the pseudopotential identifier available as

atom[:pseudopotential]
"hgh/lda/c-q4"

Notice that such custom properties are fully integrated with the standard atomic properties, e.g. automatically available from the keys, haskey and pairs functions, e.g.:

@show haskey(atom, :pseudopotential)
-pairs(atom)
Base.Generator{NTuple{5, Symbol}, AtomsBase.var"#57#58"{Atom{3, Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(a₀,), 𝐋, nothing}}, Unitful.Quantity{Float64, 𝐋 𝐓^-1, Unitful.FreeUnits{(nm, s^-1), 𝐋 𝐓^-1, nothing}}, Unitful.Quantity{Float64, 𝐌, Unitful.FreeUnits{(u,), 𝐌, nothing}}}}}(AtomsBase.var"#57#58"{Atom{3, Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(a₀,), 𝐋, nothing}}, Unitful.Quantity{Float64, 𝐋 𝐓^-1, Unitful.FreeUnits{(nm, s^-1), 𝐋 𝐓^-1, nothing}}, Unitful.Quantity{Float64, 𝐌, Unitful.FreeUnits{(u,), 𝐌, nothing}}}}(Atom(C,  [       0,        1,        2]u"a₀")), (:position, :velocity, :species, :mass, :pseudopotential))

Updating an atomic property proceeds similarly. E.g.

newatom = Atom(atom; atomic_mass=13u"u")
Atom(C, Z = 6, m = 12.011 u):
+pairs(atom)
Base.Generator{NTuple{5, Symbol}, AtomsBase.var"#58#59"{Atom{3, Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(a₀,), 𝐋, nothing}}, Unitful.Quantity{Float64, 𝐋 𝐓^-1, Unitful.FreeUnits{(nm, s^-1), 𝐋 𝐓^-1, nothing}}, Unitful.Quantity{Float64, 𝐌, Unitful.FreeUnits{(u,), 𝐌, nothing}}}}}(AtomsBase.var"#58#59"{Atom{3, Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(a₀,), 𝐋, nothing}}, Unitful.Quantity{Float64, 𝐋 𝐓^-1, Unitful.FreeUnits{(nm, s^-1), 𝐋 𝐓^-1, nothing}}, Unitful.Quantity{Float64, 𝐌, Unitful.FreeUnits{(u,), 𝐌, nothing}}}}(Atom(C,  [       0,        1,        2]u"a₀")), (:position, :velocity, :species, :mass, :pseudopotential))

Updating an atomic property proceeds similarly. E.g.

newatom = Atom(atom; atomic_mass=13u"u")
Atom(C, Z = 6, m = 12.011 u):
     position          : [0,1,2]u"a₀"
     species           : C
     atomic_mass       : 13 u
@@ -87,4 +87,4 @@
 
     Atom(H,  [       0,        0,        1]u"a₀")
     Atom(H,  [       0,        0,        3]u"a₀")
-

Again these custom properties are fully integrated with keys, haskey, pairs and get.

@show keys(system)
(:cell_vectors, :periodicity, :extra_data)
+

Again these custom properties are fully integrated with keys, haskey, pairs and get.

@show keys(system)
(:cell_vectors, :periodicity, :extra_data)
diff --git a/dev/utilities/index.html b/dev/utilities/index.html index 1293153..2959b7e 100644 --- a/dev/utilities/index.html +++ b/dev/utilities/index.html @@ -1,2 +1,2 @@ -Utilities · AtomsBase.jl
GitHub

Utilities

This page documents some utilities that AtomsBase provides in addition to the interface. This documentation is preliminary. PRs to improve it are welcome.

Cell Types

As of AtomsBase 0.4 we recommend that implementations of the interface specify a computational cell type. To simplify this, AtomsBase provides two prototype implementations:

  • PeriodicCell : implements the standard parallepiped shaped cell defined through three cell vectors and periodicity (true or false) along each cell vector.
  • IsolatedCell : implements a computational cell that is open (infinite) in all directions, i.e. the entire space.

Chemical Species

The function AtomsBase.species(sys, i) return the particle species of a particle (or multiple particles). AtomsBase does not enforce any specific type to be returned. However, it is recommended that systems describing atomic structures use - whenever possible - the ChemicalSpecies type that is implemented as part of AtomsBase.

  • ChemicalSpecies : a prototype implementation and recommended default for the species of an atom.

Convenience functions

AtomsBase provides a number of convenience utilities that should work for any system that implements the AtomsBase interface. If they not work as expected this is likely a bug and should be reported as an issue.

Testing Utilities

The AtomsBaseTesting package provides a few utility functions to test downstream packages for having properly implemented the AtomsBase interface. The tests are probably not complete, but they should be a good start ... and as always PRs are welcome.

Two functions are provided, namely make_test_system to generate standard FlexibleSystem test systems and test_approx_eq for testing approximate equality between AtomsBase systems (of not necessarily the same type). The basic idea of the functions is to use make_test_system to obtain a test system, construct an identical system in a downstream library and then use test_approx_eq to check they are actually equal.

For usage examples see the tests of ExtXYZ, AtomsIO, Chemfiles and ASEconnect.

+Utilities · AtomsBase.jl
GitHub

Utilities

This page documents some utilities that AtomsBase provides in addition to the interface. This documentation is preliminary. PRs to improve it are welcome.

Cell Types

As of AtomsBase 0.4 we recommend that implementations of the interface specify a computational cell type. To simplify this, AtomsBase provides two prototype implementations:

  • PeriodicCell : implements the standard parallepiped shaped cell defined through three cell vectors and periodicity (true or false) along each cell vector.
  • IsolatedCell : implements a computational cell that is open (infinite) in all directions, i.e. the entire space.

Chemical Species

The function AtomsBase.species(sys, i) return the particle species of a particle (or multiple particles). AtomsBase does not enforce any specific type to be returned. However, it is recommended that systems describing atomic structures use - whenever possible - the ChemicalSpecies type that is implemented as part of AtomsBase.

  • ChemicalSpecies : a prototype implementation and recommended default for the species of an atom.

Convenience functions

AtomsBase provides a number of convenience utilities that should work for any system that implements the AtomsBase interface. If they not work as expected this is likely a bug and should be reported as an issue.

Testing Utilities

The AtomsBaseTesting package provides a few utility functions to test downstream packages for having properly implemented the AtomsBase interface. The tests are probably not complete, but they should be a good start ... and as always PRs are welcome.

Two functions are provided, namely make_test_system to generate standard FlexibleSystem test systems and test_approx_eq for testing approximate equality between AtomsBase systems (of not necessarily the same type). The basic idea of the functions is to use make_test_system to obtain a test system, construct an identical system in a downstream library and then use test_approx_eq to check they are actually equal.

For usage examples see the tests of ExtXYZ, AtomsIO, Chemfiles and ASEconnect.