AtomsSystems.jl

add_systems(sys1::T, sys2::T) where {T<:AbstractIsolatedSystem}

Append two systems of the same type, returning a new system.

bond_angle(sys, i, j, k)

Calculate the angle between atoms i, j, and k in the system sys.

The angle is defined as the angle between the vectors r_ij (from atom j to atom i) and r_jk (from atom j to atom k).

You can use rad2deg to convert the result to degrees.

cell_matrix(sys)

Return the cell matrix of the sys with the cell vectors as columns.

Works when sys has cell_vectors defined.

center_of_mass(sys)

Return the center of mass of the system sys.

dihedral_angle(sys, i, j, k, m)

Calculate the dihedral angle between atoms i, j, k, and m in the system sys.

The dihedral angle is defined as the angle between the planes defined by the atoms i, j, k and j, k, m.

You can use rad2deg to convert the result to degrees.

distance(sys, i, j)

Return the distance between atom i and atom j in the system sys.

distance_vector(sys, i, j)

Return the distance vector between atom i and atom j in the system sys.

Note, currently only works for orthorombic cells or isolated systems.

fractional_coordinates(sys, r)
fractional_coordinates(cell, r)

Return the fractional coordinates of the position r in the cell cell. If AtomsBase.AbstractSystem sys is given, the cell is taken from it.

fractional_coordinates_as_matrix(sys, i)

Return the fractional coordinates of atom(s) i in the system sys as a matrix.

fractional_coordinates_as_matrix(cell, coord)

Same as fractional_coordinates, but returns the fractional coordinates as a matrix.

generic_system(vec_atoms::AbstractVector{<:AtomsBase.Atom}; kwargs...)

Create a system from an array of atoms, with optional keyword arguments to set system properties.

If cell is not specified, the new system will have an isolated cell.

Examples

# Create a system from an array of atoms
sys = generic_system([
    SimpleAtom(:H, [0.0, 0.0, 0.0]u"Å"), 
    SimpleAtom(:O, [1.0, 0.0, 0.0]u"Å")]
)

# Create a system and set energy
sys = generic_system([
    SimpleAtom(:H, [0.0, 0.0, 0.0]u"Å"),
    SimpleAtom(:O, [1.0, 0.0, 0.0]u"Å")];
    energy = 10.0u"eV"
)

# Create a system and set cell vectors and periodicity
sys = generic_system([
    SimpleAtom(:H, [0.0, 0.0, 0.0]u"Å"),
    SimpleAtom(:O, [1.0, 0.0, 0.0]u"Å")]; 
    cell_vectors = [[1.0, 0.0, 0.0]u"Å", [0.0, 1.0, 0.0]u"Å", [0.0, 0.0, 1.0]u"Å"], 
    periodicity = (true, true, true)
)

generic_system(sys::AbstractSystem, i; kwargs...)
generic_system(sys::AbstractSystem, vspc::ChemicalSpecies...; kwargs...)

Create a subsystem from an existing system and a selection of atoms, allowing to set additional properties via keyword arguments.

The new subsystem allocates its own data and does not share any data with the original system.

Examples

# Create a subsystem with atoms 1:5 from an existing system
sys = generic_system(some_system, 1:5)

# Create a sybsys with specific species from an existing system
sys = generic_system(some_system, ChemicalSpecies(:H), ChemicalSpecies(:O))

# Create a subsystem and set energy
sys = generic_system(some_system, 1:5; energy = 10.0u"eV")

generic_system(sys::AbstractSystem; kwargs...)

Create a system from an existing system, allowing to update the cell or other system wide properties.

The new system is a copy of the original system, it does not share any data with the original system.

Examples

# form a come of a system
sys = generic_system(some_system)

# form a copy and add energy
sys = generic_system(some_system; energy = 10.0u"eV")

# Create a system with updated cell vectors and periodicity
sys = generic_system(some_system; cell_vectors = [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]]u"Å", periodicity = (true, true, true))
my_cell = PeriodicCell([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]]u"Å", (true, true, true))
sys = generic_system(some_system; cell = my_cell)

# Copy of a system with changed cell vectors
sys = generic_system(some_system; cell_vectors = [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]]u"Å")

# Copy some_system and take cell from another system
sys = generic_system(some_system; cell = cell(another_system))

generic_system(prs::AbstractVector{<:Pair}; kwargs...)

Create a system from an array of pairs, where each pair consists of a species and a position. The new system is a copy of the original system, allowing to set additional properties via keyword arguments.

If cell is not specified, the new system will have an isolated cell.

Examples

# Create a system from an array of pairs
sys = generic_system([:H => [0.0, 0.0, 0.0]u"Å", :O => [1.0, 0.0, 0.0]u"Å"])

# Create a system and set energy
sys = generic_system([:H => [0.0, 0.0, 0.0]u"Å", :O => [1.0, 0.0, 0.0]u"Å"]; energy = 10.0u"eV")

# Create a system with cell vectors and periodicity
sys = generic_system([
    :H => [0.0, 0.0, 0.0]u"Å", 
    :O => [1.0, 0.0, 0.0]u"Å"];
    cell_vectors = [[1.0, 0.0, 0.0]u"Å", [0.0, 1.0, 0.0]u"Å", [0.0, 0.0, 1.0]u"Å"], 
    periodicity = (true, true, true)
)

generic_system(species, r; kwargs...)
generic_system(species, r, v; kwargs...)

Create a system from an array of species and positions, with optional keyword arguments to set system properties.

If cell is not specified, the new system will have an isolated cell.

Examples

# Create a system from species and positions
sys = generic_system([:H, :O], [[0.0, 0.0, 0.0]u"Å", [1.0, 0.0, 0.0]u"Å"])

# Create a system and set energy
sys = generic_system([:H, :O], [[0.0, 0.0, 0.0]u"Å", [1.0, 0.0, 0.0]u"Å"]; energy = 10.0u"eV")

# Create a system and set cell vectors and periodicity
sys = generic_system(
    [:H, :O],
    [[0.0, 0.0, 0.0]u"Å", [1.0, 0.0, 0.0]u"Å"]; 
    cell_vectors = [[1.0, 0.0, 0.0]u"Å", [0.0, 1.0, 0.0]u"Å", [0.0, 0.0, 1.0]u"Å"], 
    periodicity = (true, true, true)
)

# Create a system with velocities
sys = generic_system(
    [:H, :O],
    [[0.0, 0.0, 0.0]u"Å", [1.0, 0.0, 0.0]u"Å"],
    [[0.1, 0.0, 0.0]u"Å/s", [0.2, 0.0, 0.0]u"Å/s"];
    energy = 10.0u"eV"
)

inv_cell(sys)

Return the inverse of the cell matrix of the AbstractSystem sys or cell.

position_as_matrix(sys, i)

Return the position of atom(s) i in the system sys as a matrix.

rotate_system!(sys, r)

Rotate the system sys by the rotation r.

Note, this function does work only for isolated systems.

rotate_system(sys, r)

Copy system sys and rotate it by the rotation r. Orignal system is not modified.

system_view(sys, i)
system_view(sys, spc...)

Create a view of a system for the given indices or species.

This does not create a copy of the system, but rather a view of the existing system and thus does not allocate memory (except for the view itself).

Example

# Create a view of a system with atoms 2 to 30
subsys = system_view(sys, 2:30)

# Create a view of a system with species Si and Al
subsys = system_view(sys, ChemicalSpecies(:Si), ChemicalSpecies(:Al))

translate_system!(sys, r)

Translate the system sys by the vector r.

translate_system(sys, r)

Copy system sys and translate it by the vector r. Orignal system is not modified.

wrap_coordinates!(sys)
wrap_coordinates!(cell, coord)

Wrap the coordinates to given cell.

If sys is given, the cell is taken from it.

If cell is given, the new coordinates are returned.

repeat(sys, n)

Repeat the system sys in all three dimensions by the factors n and return the new system. Original system is not modified.

AtomicPropertySystem{D, LU, TB, TP, SM}

A system that contains atomic properties in addition to the basic attributes of atoms.

This system is designed to work with AbstractSimpleSystem and allows for the storage of additional properties for each atom, such as custom mass, charge, or any other custom property.

It is recommeded to use generic_system to create instances of this system.

Type Parameters

• D: Dimension of the system (e.g., 2 or 3).
• LU: Unit of length for positions.
• TB: Type of the base system, either SimpleSystem or SimpleVelocitySystem.
• TP: Type of the atomic properties (NamedTuple).
• SM: Boolean indicating if the system has a custom mass property.

Fields

• base_system: The base system, which is either a SimpleSystem or a SimpleVelocitySystem.
• atom_properties: A vector of TB containing the properties of each atom.

AtomicPropertySystemView{D, LU, TB, TP, TI, SM, L}

View subsystem of a system that contains species, position, and additional atomic properties.

It is recommended to use system_view function to create a view of the system instead of creating this type directly.

Parameter Definitions

• D: Dimension of the system (e.g., 2 or 3).
• LU: Unit length of the system.
• TB: Type of the base system (e.g., SimpleSystemView).
• TP: Type of the atomic properties (e.g., SVector{D, T}).
• TI: Type index for SubArray used for the view.
• SM: Type of the atomic properties (e.g., SVector{D, T}).
• L: True when SybArray uses linear indexing, false otherwise.

CellSystem{D, LU, TB, TC}

A system that represents a collection of atoms in a PeriodicCell.

Not intended to be called directly. Instead, use generic_system to build systems.

Type Parameters

• D: Dimension of the system (e.g., 2 or 3).
• LU: Unit of length for positions.
• TB: Type of the base system.
• TC: Type of the cell, which is a PeriodicCell{D}.

Fields

• base_system: The base system, which is either an AtomicPropertySystem or a SimpleSystem or a SimpleVelocitySystem.
• cell: The periodic cell that defines the boundaries and periodicity of the system.

CellSystemView{D, LU, TB, TC}

View subsystem of a system that contains a base system and a cell.

It is recommended to use system_view function to create a view of the system instead of creating this type directly.

Parameter Definitions

• D: Dimension of the system (e.g., 2 or 3).
• LU: Unit length of the system.
• TB: Type of the base system (e.g., SimpleSystemView).
• TC: Type of the cell (has to be subtype of PeriodicCell).

SimpleAtom(id::AtomsBase.AtomId, r::SVector; kwargs...)
SimpleAtom(id::AtomsBase.AtomId, r::SVector, v::SVector; kwargs...)
SimpleAtom(sa::SimpleAtom; kwargs...

Stucture to represent a single atom with species, position, and optional velocity and other properties.

The SimpleAtom is bitstype when the data is bitstypes.

Mass is set to the mass of the species by default, but can be overridden with a keyword argument.

Examples

SimpleAtom(:H, [0.0, 0.0, 0.0]u"Å")
SimpleAtom(:O, [1.0, 0.0, 0.0]u"Å", [0.1, 0.0, 0.0]u"Å/s"; mass = 16.0u"u", charge = -1.0u"q")
SimpleAtom(ChemicalSpecies(:H), [0.0, 0.0, 0.0]u"Å")
SimpleAtom( :O => [1.0, 0.0, 0.0]u"Å" )

SimpleSystem{D, LU, TP} <: AbstractSimpleSystem{D, LU}

A simple system that holds only species and positions of atoms, without any additional properties.

SimpleSystem has IsolatedCell as its cell.

No intended to be called directly. Intead use generic_system to build systems.

Type Parameters

• D: Dimension of the system (e.g., 2 or 3).
• LU: Unit of length for positions (LU=unit(TP)).
• TP: Type of position vector, in form of SVector{D, TP} where TP is a unitful length type.

Fields

• species: A vector of ChemicalSpecies representing the species of each atom.
• position: A vector of position vectors, each of type SVector{D, TP}.

SimpleSystemView{D, LU, TP, TI, L}

View subsystem of a system that contains only species and position.

It is recommended to use system_view function to create a view of the system instead of creating this type directly.

Parameter Definitions

• D: Dimension of the system (e.g., 2 or 3).
• LU: Unit length of the system.
• TP: Type of position vector (e.g., SVector{D, T}).
• TI: Type index for SubArray used for the view.
• L: True when SybArray uses linear indexing, false otherwise.

Example

# crete view of a system with atoms 2 to 30
subsys = SimpleSystemView(sys, 2:30)

SimpleVelocitySystemView{D, LU, TP, TV, TI, L}

View subsystem of a system that contains species, position, and velocity.

It is recommended to use system_view function to create a view of the system instead of creating this type directly.

Parameter Definitions

• D: Dimension of the system (e.g., 2 or 3).
• LU: Unit length of the system.
• TP: Type of position vector (e.g., SVector{D, T}).
• TV: Type of velocity vector (e.g., SVector{D, T}).
• TI: Type index for SubArray used for the view.
• L: True when SybArray uses linear indexing, false otherwise.

Example

```julia

Create view of a system with atoms 2 to 30

subsys = SimpleVelocitySystemView(sys, 2:30) ````