sisl.Atoms

class sisl.Atoms(atoms: AtomsLike = 'H', na: int | None = None)

Bases: object

Efficient collection of Atom objects

A container object for Atom objects in a specific order. No two Atom objects will be duplicated and indices will be used to determine which Atom any indexable atom corresponds to. 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, dict 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(atoms) 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)
>>> atoms = Atoms([1, 2], na=4) # equivalent

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([inplace])

Returns a new Atoms object by removing non-used atoms

remove(atoms)

Remove a set of atoms

reorder([inplace])

Reorders the atoms and species index so that they are ascending (starting with a species 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

species_index(atom)

Return the species index of the atom object

sub(atoms)

Return a subset of the list

swap(atoms1, atoms2)

Swaps atoms by index

swap_atom(a, b)

Swap species 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

nspecies

Number of different species

orbitals

Array of orbitals of the contained objects

q0

Initial charge per atom

specie

List of atomic species

species

List of atomic species
property Z

Array of atomic numbers

__init__(atoms: AtomsLike = 'H', na: int | None = None)[source]
Parameters:

  • atoms (AtomsLike)

  • na (Optional[int])

add(other: Atom | Atoms) → Atoms

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

Parameters:
Returns:

merging of this objects atoms and the other objects atoms.

Return type:

Atoms

append(other: Atom | Atoms) → Atoms

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

Parameters:
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() → Atoms

Return a copy of this atom

Parameters:

atoms (Atoms)

Return type:

Atoms

equal(other, R=True)[source]

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')[source]

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)[source]

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 (ndarray) – data to be grouped

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

hassame(other, R=True)[source]

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)[source]

Return the indices of the atom object

insert(index: sisl.typing.SimpleIndex, other: Atom | Atoms) → Atoms

Insert other atoms into the list of atoms at index

Parameters:
Return type:

Atoms

iter(species=False)[source]

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 species. 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)[source]

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

property nspecies

Number of different species

orbital(io)[source]

Return an array of orbital of the contained objects

property orbitals

Array of orbitals of the contained objects

prepend(other: Atom | Atoms) → Atoms
Parameters:
Return type:

Atoms

property q0

Initial charge per atom

reduce(inplace: bool = False)[source]

Returns a new Atoms object by removing non-used atoms

Parameters:

inplace (bool)

remove(atoms: sisl.typing.SimpleIndex) → Atoms

Remove a set of atoms

Parameters:

  • atom (Atoms)

  • atoms (sisl.typing.SimpleIndex)

Return type:

Atoms

reorder(inplace: bool = False)[source]

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

Parameters:

inplace (bool) – whether the re-order is done in-place

repeat(reps: int) → Atoms

Repeat this atom object

Parameters:
Return type:

Atoms

replace(index, atom)[source]

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)[source]

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)[source]

Returns a reversed geometry

Also enables reversing a subset of the atoms.

scale(scale: float) → Atoms

Scale the atomic radii and return an equivalent atom.

Parameters:

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

  • atoms (Atoms)

Return type:

Atoms

property specie

List of atomic species

specie_index(atom)

Return the species index of the atom object

property species

List of atomic species

species_index(atom)[source]

Return the species index of the atom object

sub(atoms: sisl.typing.SimpleIndex) → Atoms

Return a subset of the list

Parameters:

  • atom (Atoms)

  • atoms (sisl.typing.SimpleIndex)

Return type:

Atoms

swap(atoms1: sisl.typing.SimpleIndex, atoms2: sisl.typing.SimpleIndex) → Atoms

Swaps atoms by index

Parameters:

  • atom (Atoms)

  • atoms1 (sisl.typing.SimpleIndex)

  • atoms2 (sisl.typing.SimpleIndex)

Return type:

Atoms

swap_atom(a, b)[source]

Swap species index positions

tile(reps: int) → Atoms

Tile this atom object

Parameters:
Return type:

Atoms