soprano.selection

selection.py

Contains the definition of an AtomSelection class, namely a group of selected atoms for a given structure, and methods to build it.

Classes

AtomSelection(atoms, sel_indices[, authenticate])

AtomSelection object.

class soprano.selection.AtomSelection(atoms, sel_indices, authenticate=True)

Bases: object

AtomSelection object.

An AtomSelection represents a group of atoms from an ASE Atoms object. It keeps track of them and can be used to perform operations on them (for example geometrical transformation or extraction of specific properties). It does not keep track of the original Atoms object it’s been created from, but can be “authenticated” to verify that it is indeed operating consistently on the same structure. It also provides a series of static methods to build selections with various criteria.

Initialize the AtomSelection.

Args:

atoms (ase.Atoms): the atoms object on which the selection is

applied

sel_indices (list[int]): the list of indices of the atoms that

are to be selected

authenticate (Optional[bool]): whether to use hashing to confirm

the identity of the atoms object

we’re operating with

__getitem__(indices)

Slicing: take only part of a selection

_hash(atoms)

A function to create an identifying hash for a given Atoms system. This is used later to check that the system is indeed unchanged when the Selection is reused.

While changes in positions or cell don’t invalidate the Selection, changes in composition potentially do (indices of atoms can change).

static all(atoms)

Generate a selection for the given Atoms object of all atoms.

Args:

atoms (ase.Atoms): Atoms object on which to perform selection

Returns:

selection (AtomSelection)

static from_array(atoms, name, value, op='eq')

Generate a selection for the given Atoms object of other atoms based on a comparison with some array value. Default is selection of all atoms that have the same exact value. However different operators can be specified for different selection criteria.

Args:

atoms (ase.Atoms): Atoms object on which to perform selection

name (str): name of the array to select with

value (any type): value to compare the contents of the array with

op (Optional[str]): operator to use for comparison with the given

value. By default it’s eq, meaning

“equal” to value, which means all atoms

will be selected for whose the array of given

name has the given value.

Other options are the functions present in the

operator module and are:

- lt : less than

- le : less or equal

- eq : exactly equal

- ge : greater or equal

- gt : greater than

static from_bonds(atoms, center, n, op='le')

Generate a selection for the given Atoms object of other atoms based on their reciprocal bonding distance. Default is selection of all atoms that are within a certain bonding distance (less-or-equal than n). However different operators can be specified for different selection criteria. Atoms that do not belong to the same tree of the bonding graph are never selected.

Args:

atoms (ase.Atoms): Atoms object on which to perform selection

center (int): index of the atom to compute the bonding distance

from

n (int): bonding distance to compare

op (Optional[str]): operator to use for comparison with the given

bonding distance. By default it’s le, meaning

“less or equal” than n, which means all atoms

will be selected that are at most n bonds away

from the center.

Other options are the functions present in the

operator module and are:

- lt : less than

- le : less or equal

- eq : exactly equal

- ge : greater or equal

- gt : greater than

static from_box(atoms, abc0, abc1, periodic=False, scaled=False)

Generate a selection for the given Atoms object of all atoms within a given box volume.

Args:

atoms (ase.Atoms): Atoms object on which to perform selection

abc0 ([float, float, float]): bottom corner of box

abc1 ([float, float, float]): top corner of box

periodic (Optional[bool]): if True, include periodic copies of the

atoms

scaled (Optional[bool]): if True, consider scaled (fractional)

coordinates instead of absolute ones

Returns:

selection (AtomSelection)

static from_element(atoms, element)

Generate a selection for the given Atoms object of all atoms of a specific element.

Args:

atoms (ase.Atoms): Atoms object on which to perform selection

element (str): symbol of the element to select

Returns:

selection (AtomSelection)

static from_selection_string(atoms, selection_string)

Generate a selection for the given Atoms object based on a standardised string format. (Useful to parse command-line-arguments.)

Args:

atoms (ase.Atoms): Atoms object on which to perform selection

selection_string (str): string specifying a subset of atoms. See example below.

Returns:

selection (AtomSelection)

Examples of selection_string: ‘Si’ - select all Si atoms ‘Si.1’ - select the first Si atom ‘Si.1-3’ - select the first three Si atoms ‘Si.1-3,5’ - select the first three and fifth Si atoms ‘C.1,H.2’ - select the first carbon and second hydrogen atoms ‘C1’ - select the atom with ‘C1’ label, regardles of where it appears. ‘C1,C3a’ - select the atoms with ‘C1’ and ‘C3a’ labels, regardles of where they appear.

static from_sphere(atoms, center, r, periodic=False, scaled=False)

Generate a selection for the given Atoms object of all atoms within a given spherical volume.

Args:

atoms (ase.Atoms): Atoms object on which to perform selection

center ([float, float, float]): center of the sphere

r (float): radius of the sphere

periodic (Optional[bool]): if True, include periodic copies of the

atoms

scaled (Optional[bool]): if True, consider scaled (fractional)

coordinates instead of absolute ones

Returns:

selection (AtomSelection)

get_array(name)

Retrieve a previously stored data array.

Args:

name (str): name of the array to be set or created

Returns:

array (np.ndarray): array of data to be saved

has(name)

Check if the selection has a given array

Args:

name (str): name of the array to be checked for

Returns:

has (bool): if the array is present or not

set_array(name, array)

Save an array of given name containing arbitraty information tied to the selected atoms. This must match the length of the selection and will be passed on to any Atoms objects created with .subset.

Args:

name (str): name of the array to be set or created

array (np.ndarray): array of data to be saved

subset(atoms, use_cell_indices=False)

Generate an Atoms object containing only the selected atoms.

Args:

atoms (ase.Atoms): Atoms object from which to take the

selection

use_cell_indices (bool): If True, use the cell_indices array to

pick the specified periodic copies of

the corresponding atoms (useful e.g. to

take the correct periodic copies for a

molecule). Default is False

Returns:

subset (ase.Atoms): Atoms object containing only the

specified selection

static unique(atoms, symprec=0.0001)

Generate a selection for the given Atoms object containing only the symmetry-unique atoms.

We use the spacegroup as found by spglib to determine the symmetry operations and then use these to tag the equivalent atoms.

Args:

atoms (ase.Atoms): Atoms object on which to perform selection

sympres (float): tolerance for symmetry equivalence

Returns:

selection (AtomSelection)

validate(atoms)

Check that the given Atoms object validates with this selection.