diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 33f2c07..bc4f238 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-11-21T05:53:43","documenter_version":"1.8.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-11-21T06:26:24","documenter_version":"1.8.0"}} \ No newline at end of file diff --git a/dev/apireference/index.html b/dev/apireference/index.html index dc5aa55..77dda55 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 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)
+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)
@@ -32,22 +32,22 @@
 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...)
+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 c10765d..be95454 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 138f90f..2246733 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 64bea60..6c05e3e 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/tutorial/index.html b/dev/tutorial/index.html index 03bb980..aa70eae 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"#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):
+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"#59#60"{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"#59#60"{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"#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):
+pairs(atom)
Base.Generator{NTuple{5, Symbol}, AtomsBase.var"#59#60"{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"#59#60"{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
@@ -35,7 +35,7 @@
 pseudopotential  =  hgh/lda/c-q4

System interface and conventions

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:

box = ([10.0, 0.0, 0.0]u"Å", [0.0, 10.0, 0.0]u"Å", [0.0, 0.0, 10.0]u"Å")
 hydrogen = periodic_system([Atom(:H, [0, 0, 1.]u"Å"),
                             Atom(:H, [0, 0, 3.]u"Å")],
-                            box)
FlexibleSystem(H₂, pbc = TTT):
+                            box)
FlexibleSystem(H₂, periodicity = TTT):
     cell_vectors      : [      10        0        0;
                                 0       10        0;
                                 0        0       10]u"Å"
@@ -46,14 +46,14 @@
 AbstractSystem(hydrogen;
                cell_vectors=([5.0, 0.0, 0.0]u"Å",
                              [0.0, 5.0, 0.0]u"Å",
-                             [0.0, 0.0, 5.0]u"Å"))
FlexibleSystem(H₂, pbc = TTT):
+                             [0.0, 0.0, 5.0]u"Å"))
FlexibleSystem(H₂, periodicity = TTT):
     cell_vectors      : [       5        0        0;
                                 0        5        0;
                                 0        0        5]u"Å"
 
     Atom(H,  [       0,        0,        1]u"Å")
     Atom(H,  [       0,        0,        3]u"Å")
-

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.

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.

Similar to the atoms, system objects similarly support a functional-style access to system properties as well as a dict-style access:

cell_vectors(hydrogen)
(Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(Å,), 𝐋, nothing}}[10.0 Å, 0.0 Å, 0.0 Å], Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(Å,), 𝐋, nothing}}[0.0 Å, 10.0 Å, 0.0 Å], Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(Å,), 𝐋, nothing}}[0.0 Å, 0.0 Å, 10.0 Å])
hydrogen[:periodicity]
(true, true, true)
pairs(hydrogen)
Base.Generator{Tuple{Symbol, Symbol}, AtomsBase.var"#7#8"{FlexibleSystem{3, Atom{3, Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(Å,), 𝐋, nothing}}, Unitful.Quantity{Float64, 𝐋 𝐓^-1, Unitful.FreeUnits{(Å, fs^-1), 𝐋 𝐓^-1, nothing}}, Unitful.Quantity{Float64, 𝐌, Unitful.FreeUnits{(u,), 𝐌, nothing}}}, PeriodicCell{3, Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(Å,), 𝐋, nothing}}}}}}(AtomsBase.var"#7#8"{FlexibleSystem{3, Atom{3, Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(Å,), 𝐋, nothing}}, Unitful.Quantity{Float64, 𝐋 𝐓^-1, Unitful.FreeUnits{(Å, fs^-1), 𝐋 𝐓^-1, nothing}}, Unitful.Quantity{Float64, 𝐌, Unitful.FreeUnits{(u,), 𝐌, nothing}}}, PeriodicCell{3, Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(Å,), 𝐋, nothing}}}}}(FlexibleSystem(H₂, pbc = TTT)), (:cell_vectors, :periodicity))

Moreover atomic properties of a specific atom or all atoms can be directly queried using the indexing notation:

hydrogen[1, :position]  # Position of first atom
3-element StaticArraysCore.SVector{3, Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(Å,), 𝐋, nothing}}} with indices SOneTo(3):
+

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.

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.

Similar to the atoms, system objects similarly support a functional-style access to system properties as well as a dict-style access:

cell_vectors(hydrogen)
(Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(Å,), 𝐋, nothing}}[10.0 Å, 0.0 Å, 0.0 Å], Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(Å,), 𝐋, nothing}}[0.0 Å, 10.0 Å, 0.0 Å], Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(Å,), 𝐋, nothing}}[0.0 Å, 0.0 Å, 10.0 Å])
hydrogen[:periodicity]
(true, true, true)
pairs(hydrogen)
Base.Generator{Tuple{Symbol, Symbol}, AtomsBase.var"#7#8"{FlexibleSystem{3, Atom{3, Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(Å,), 𝐋, nothing}}, Unitful.Quantity{Float64, 𝐋 𝐓^-1, Unitful.FreeUnits{(Å, fs^-1), 𝐋 𝐓^-1, nothing}}, Unitful.Quantity{Float64, 𝐌, Unitful.FreeUnits{(u,), 𝐌, nothing}}}, PeriodicCell{3, Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(Å,), 𝐋, nothing}}}}}}(AtomsBase.var"#7#8"{FlexibleSystem{3, Atom{3, Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(Å,), 𝐋, nothing}}, Unitful.Quantity{Float64, 𝐋 𝐓^-1, Unitful.FreeUnits{(Å, fs^-1), 𝐋 𝐓^-1, nothing}}, Unitful.Quantity{Float64, 𝐌, Unitful.FreeUnits{(u,), 𝐌, nothing}}}, PeriodicCell{3, Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(Å,), 𝐋, nothing}}}}}(FlexibleSystem(H₂, periodicity = TTT, cell_vectors = [[10.0, 0.0, 0.0], [0.0, 10.0, 0.0], [0.0, 0.0, 10.0]]u"Å")), (:cell_vectors, :periodicity))

Moreover atomic properties of a specific atom or all atoms can be directly queried using the indexing notation:

hydrogen[1, :position]  # Position of first atom
3-element StaticArraysCore.SVector{3, Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(Å,), 𝐋, nothing}}} with indices SOneTo(3):
  0.0 Å
  0.0 Å
  1.0 Å
hydrogen[:, :position]  # All atomic symbols
2-element Vector{StaticArraysCore.SVector{3, Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(Å,), 𝐋, nothing}}}}:
@@ -61,7 +61,7 @@
  [0.0 Å, 0.0 Å, 3.0 Å]

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.

atomkeys(hydrogen)
(:position, :velocity, :species, :mass)

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

cell_vectors = ([10.0, 0.0, 0.0]u"Å", [0.0, 10.0, 0.0]u"Å", [0.0, 0.0, 10.0]u"Å")
 hydrogen = periodic_system([:H => [0, 0, 1.]u"Å",
                             :H => [0, 0, 3.]u"Å"],
-                           cell_vectors)
FlexibleSystem(H₂, pbc = TTT):
+                           cell_vectors)
FlexibleSystem(H₂, periodicity = TTT):
     cell_vectors      : [      10        0        0;
                                 0       10        0;
                                 0        0       10]u"Å"
@@ -71,7 +71,7 @@

To setup a silicon unit cell we can use fractional coordinates (which is common for solid-state simulations):

cell_vectors = 10.26 / 2 .*  ([0, 0, 1]u"bohr", [1, 0, 1]u"bohr", [1, 1, 0]u"bohr")
 silicon = periodic_system([:Si =>  ones(3)/8,
                            :Si => -ones(3)/8],
-                           cell_vectors, fractional=true)
FlexibleSystem(Si₂, pbc = TTT):
+                           cell_vectors, fractional=true)
FlexibleSystem(Si₂, periodicity = TTT):
     cell_vectors      : [       0        0     5.13;
                              5.13        0     5.13;
                              5.13     5.13        0]u"a₀"
@@ -79,12 +79,12 @@
     Atom(Si, [  1.2825,  0.64125,   1.2825]u"a₀")
     Atom(Si, [ -1.2825, -0.64125,  -1.2825]u"a₀")

Alternatively we can also place an isolated H2 molecule in vacuum, which is the standard setup for molecular simulations:

hydrogen = isolated_system([:H => [0, 0, 1.]u"bohr",
-                            :H => [0, 0, 3.]u"bohr"])
FlexibleSystem(H₂, pbc = FFF):
+                            :H => [0, 0, 3.]u"bohr"])
FlexibleSystem(H₂, periodicity = FFF):
     Atom(H,  [       0,        0,        1]u"a₀")
     Atom(H,  [       0,        0,        3]u"a₀")
-

Optional system properties

Similar to atoms, FlexibleSystem and FastSystem also support storing arbitrary data, for example

system = isolated_system([:H => [0, 0, 1.]u"bohr", :H => [0, 0, 3.]u"bohr"]; extra_data=42)
FlexibleSystem(H₂, pbc = FFF):
+

Optional system properties

Similar to atoms, FlexibleSystem and FastSystem also support storing arbitrary data, for example

system = isolated_system([:H => [0, 0, 1.]u"bohr", :H => [0, 0, 3.]u"bohr"]; extra_data=42)
FlexibleSystem(H₂, periodicity = FFF):
     extra_data        : 42
 
     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 2959b7e..6857dcc 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.