sisl.Atoms

class sisl.Atoms(atoms='H', na=None)

Bases: object

A list-like object to contain a list of different atoms with minimum data duplication.

This holds multiple Atom objects which are indexed via a species index. This is convenient when having geometries with millions of atoms because it will not duplicate the Atom object, only a list index.

Parameters

• atoms (str, Atom or list-like) – atoms to be contained in this list of atoms If a str, or a single Atom it will be the only atom in the resulting class repeated na times. If a list, it will create all unique atoms and retain these, each item in the list may a single argument passed to the Atom or a dictionary that is passed to Atom, see examples.

• na (int or None) – total number of atoms, if len(atom) is smaller than na it will be repeated to match na.

Examples

Creating an atoms object consisting of 5 atoms, all the same.

>>> atoms = Atoms("H", na=5)

Creating a set of 4 atoms, 2 Hydrogen, 2 Helium, in an alternate ordere

>>> Z = [1, 2, 1, 2]
>>> atoms = Atoms(Z)

Creating individual atoms using dictionary entries, two Hydrogen atoms, one with a tag H_ghost.

>>> Atoms([dict(Z=1, tag="H_ghost"), 1])

Methods

add(other)	Append other to this list of atoms and return the appended version
append(other)	Append other to this list of atoms and return the appended version
copy()	Return a copy of this atom
equal(other[, R])	True if the contained atoms are the same in the two lists (also checks indices)
formula([system])	Return the chemical formula for the species in this object
group_atom_data(data[, axis])	Group data for each atom based on number of orbitals
hassame(other[, R])	True if the contained atoms are the same in the two lists
index(atom)	Return the indices of the atom object
insert(index, other)	Insert other atoms into the list of atoms at index
iter([species])	Loop on all atoms
maxR([all])	The maximum radius of the atoms
orbital(io)	Return an array of orbital of the contained objects
prepend(other)
reduce([in_place])	Returns a new Atoms object by removing non-used atoms
remove(atoms)	Remove a set of atoms
reorder([in_place])	Reorders the atoms and species index so that they are ascending (starting with a specie that exists)
repeat(reps)	Repeat this atom object
replace(index, atom)	Replace all atomic indices index with the atom atom (in-place)
replace_atom(atom_from, atom_to)	Replace all atoms equivalent to atom_from with atom_to (in-place)
reverse([atoms])	Returns a reversed geometry
scale(scale)	Scale the atomic radii and return an equivalent atom.
specie_index(atom)	Return the species index of the atom object
sub(atoms)	Return a subset of the list
swap(a, b)	Swaps all atoms
swap_atom(a, b)	Swap specie index positions
tile(reps)	Tile this atom object
Z	Array of atomic numbers
atom	List of unique atoms in this group of atoms
firsto	First orbital of the corresponding atom in the consecutive list of orbitals
lasto	Last orbital of the corresponding atom in the consecutive list of orbitals
mass	Array of masses of the contained objects
no	Total number of orbitals in this list of atoms
nspecie	Number of different species
orbitals	Array of orbitals of the contained objects
q0	Initial charge per atom
specie	List of atomic species

property Z

Array of atomic numbers

__init__(atoms='H', na=None)

add(other)

Append other to this list of atoms and return the appended version

Parameters

other (Atoms or Atom) – new atoms to be added

Returns

merging of this objects atoms and the other objects atoms.

Return type

Atoms

append(other)

Append other to this list of atoms and return the appended version

Parameters

other (Atoms or Atom) – new atoms to be added

Returns

merging of this objects atoms and the other objects atoms.

Return type

Atoms

property atom

List of unique atoms in this group of atoms

copy()

Return a copy of this atom

equal(other, R=True)

True if the contained atoms are the same in the two lists (also checks indices)

Parameters

• other (Atoms) – the list of atoms to check against

• R (bool, optional) – if True also checks that the orbital radius are the same

See also

hassame

only check whether the two atoms are contained in both

property firsto

First orbital of the corresponding atom in the consecutive list of orbitals

formula(system='Hill')

Return the chemical formula for the species in this object

Parameters

system ({"Hill"}, optional) – which notation system to use Is not case-sensitive

group_atom_data(data, axis=0)

Group data for each atom based on number of orbitals

This is useful for grouping data that is orbitally resolved. This will return a list of length len(self) and with each item having the sub-slice of the data corresponding to the orbitals on the given atom.

Examples

>>> atoms = Atoms([Atom(4, [0.1, 0.2]), Atom(6, [0.2, 0.3, 0.5])])
>>> orb_data = np.arange(10).reshape(2, 5)
>>> atoms.group_data(orb_data, axis=1)
[
 [[0, 1], [2, 3]],
 [[4, 5, 6], [7, 8, 9]]
]

Parameters

• data (numpy.ndarray) – data to be grouped

• axis (int, optional) – along which axis one should split the data

hassame(other, R=True)

True if the contained atoms are the same in the two lists

Notes

This does not necessarily mean that the order, nor the number of atoms are the same.

Parameters

• other (Atoms) – the list of atoms to check against

• R (bool, optional) – if True also checks that the orbital radius are the same

See also

equal

explicit check of the indices and the contained atoms

index(atom)

Return the indices of the atom object

insert(index, other)

Insert other atoms into the list of atoms at index

iter(species=False)

Loop on all atoms

This iterator may be used in two contexts:

1. species is False, this is the slowest method and will yield the Atom per contained atom.

2. species is True, which yields a tuple of (Atom, list) where list contains all indices of atoms that has the Atom specie. This is much faster than the first option.

Parameters

species (bool, optional) – If True loops only on different species and yields a tuple of (Atom, list) Else yields the atom for the equivalent index.

property lasto

Last orbital of the corresponding atom in the consecutive list of orbitals

property mass

Array of masses of the contained objects

maxR(all=False)

The maximum radius of the atoms

Parameters

all (bool) – determine the returned maximum radii. If True is passed an array of all atoms maximum radii is returned (array). Else, if False the maximum of all atoms maximum radii is returned (scalar).

property no

Total number of orbitals in this list of atoms

property nspecie

Number of different species

orbital(io)

Return an array of orbital of the contained objects

property orbitals

Array of orbitals of the contained objects

prepend(other)

property q0

Initial charge per atom

reduce(in_place=False)

Returns a new Atoms object by removing non-used atoms

remove(atoms)

Remove a set of atoms

reorder(in_place=False)

Reorders the atoms and species index so that they are ascending (starting with a specie that exists)

Parameters

in_place (bool, optional) – whether the re-order is done in-place

repeat(reps)

Repeat this atom object

replace(index, atom)

Replace all atomic indices index with the atom atom (in-place)

This is the preferred way of replacing atoms in geometries.

Parameters

• index (list of int or Atom) – the indices of the atoms that should be replaced by the new atom. If an Atom is passed, this routine defers its call to replace_atom.

• atom (Atom) – the replacement atom.

replace_atom(atom_from, atom_to)

Replace all atoms equivalent to atom_from with atom_to (in-place)

I.e. this is the preferred way of adapting all atoms of a specific type with another one.

If the two atoms does not have the same number of orbitals a warning will be raised.

Parameters

• atom_from (Atom) – the atom that should be replaced, if not found in the current list of atoms, nothing will happen.

• atom_to (Atom) – the replacement atom.

Raises

• KeyError – if atom_from does not exist in the list of atoms

• UserWarning – if the atoms does not have the same number of orbitals.

reverse(atoms=None)

Returns a reversed geometry

Also enables reversing a subset of the atoms.

scale(scale)

Scale the atomic radii and return an equivalent atom.

Parameters

scale (float) – the scale factor for the atomic radii

property specie

List of atomic species

specie_index(atom)

Return the species index of the atom object

sub(atoms)

Return a subset of the list

swap(a, b)

Swaps all atoms

swap_atom(a, b)

Swap specie index positions

tile(reps)

Tile this atom object