Geometry tools¶

ase.geometry.
wrap_positions
(positions, cell, pbc=True, center=(0.5, 0.5, 0.5), eps=1e07)[source]¶ Wrap positions to unit cell.
Returns positions changed by a multiple of the unit cell vectors to fit inside the space spanned by these vectors. See also the
ase.Atoms.wrap()
method.Parameters:
 positions: float ndarray of shape (n, 3)
 Positions of the atoms
 cell: float ndarray of shape (3, 3)
 Unit cell vectors.
 pbc: one or 3 bool
 For each axis in the unit cell decides whether the positions will be moved along this axis.
 center: three float
 The positons in fractional coordinates that the new positions will be nearest possible to.
 eps: float
 Small number to prevent slightly negative coordinates from being wrapped.
Example:
>>> from ase.geometry import wrap_positions >>> wrap_positions([[0.1, 1.01, 0.5]], ... [[1, 0, 0], [0, 1, 0], [0, 0, 4]], ... pbc=[1, 1, 0]) array([[ 0.9 , 0.01, 0.5 ]])

ase.geometry.
complete_cell
(cell)[source]¶ Calculate complete cell with missing lattice vectors.
Returns a new 3x3 ndarray.

ase.geometry.
get_layers
(atoms, miller, tolerance=0.001)[source]¶ Returns two arrays describing which layer each atom belongs to and the distance between the layers and origo.
Parameters:
 miller: 3 integers
 The Miller indices of the planes. Actually, any direction in reciprocal space works, so if a and b are two float vectors spanning an atomic plane, you can get all layers parallel to this with miller=np.cross(a,b).
 tolerance: float
 The maximum distance in Angstrom along the plane normal for counting two atoms as belonging to the same plane.
Returns:
 tags: array of integres
 Array of layer indices for each atom.
 levels: array of floats
 Array of distances in Angstrom from each layer to origo.
Example:
>>> import numpy as np >>> from ase.spacegroup import crystal >>> atoms = crystal('Al', [(0,0,0)], spacegroup=225, cellpar=4.05) >>> np.round(atoms.positions, decimals=5) array([[ 0. , 0. , 0. ], [ 0. , 2.025, 2.025], [ 2.025, 0. , 2.025], [ 2.025, 2.025, 0. ]]) >>> get_layers(atoms, (0,0,1)) (array([0, 1, 1, 0]...), array([ 0. , 2.025]))

ase.geometry.
find_mic
(D, cell, pbc=True)[source]¶ Finds the minimumimage representation of vector(s) D

ase.geometry.
get_duplicate_atoms
(atoms, cutoff=0.1, delete=False)[source]¶ Get list of duplicate atoms and delete them if requested.
Identify all atoms which lie within the cutoff radius of each other. Delete one set of them if delete == True.

ase.geometry.
cell_to_cellpar
(cell, radians=False)[source]¶ Returns the cell parameters [a, b, c, alpha, beta, gamma].
Angles are in degrees unless radian=True is used.

ase.geometry.
cellpar_to_cell
(cellpar, ab_normal=(0, 0, 1), a_direction=None)[source]¶ Return a 3x3 cell matrix from cellpar=[a,b,c,alpha,beta,gamma].
Angles must be in degrees.
The returned cell is orientated such that a and b are normal to \(ab_normal\) and a is parallel to the projection of \(a_direction\) in the ab plane.
Default \(a_direction\) is (1,0,0), unless this is parallel to \(ab_normal\), in which case default \(a_direction\) is (0,0,1).
The returned cell has the vectors va, vb and vc along the rows. The cell will be oriented such that va and vb are normal to \(ab_normal\) and va will be along the projection of \(a_direction\) onto the ab plane.
Example:
>>> cell = cellpar_to_cell([1, 2, 4, 10, 20, 30], (0, 1, 1), (1, 2, 3)) >>> np.round(cell, 3) array([[ 0.816, 0.408, 0.408], [ 1.992, 0.13 , 0.13 ], [ 3.859, 0.745, 0.745]])

ase.geometry.
crystal_structure_from_cell
(cell, eps=0.0002, niggli_reduce=True)[source]¶ Return the crystal structure as a string calculated from the cell.
Supply a cell (from atoms.get_cell()) and get a string representing the crystal structure returned. Works exactly the opposite way as ase.dft.kpoints.get_special_points().
Parameters:
 cell : numpy.array or list
 An array like atoms.get_cell()
Returns:
 crystal structure : str
 ‘cubic’, ‘fcc’, ‘bcc’, ‘tetragonal’, ‘orthorhombic’, ‘hexagonal’ or ‘monoclinic’

ase.geometry.
distance
(s1, s2, permute=True)[source]¶ Get the distance between two structures s1 and s2.
The distance is defined by the Frobenius norm of the spatial distance between all coordinates (see numpy.linalg.norm for the definition).
permute: minimise the distance by ‘permuting’ same elements

ase.geometry.
get_angles
(v1, v2, cell=None, pbc=None)[source]¶ Get angles formed by two lists of vectors.
calculate angle in degrees between vectors v1 and v2
Set a cell and pbc to enable minimum image convention, otherwise angles are taken asis.

ase.geometry.
get_distances
(p1, p2=None, cell=None, pbc=None)[source]¶ Return distance matrix of every position in p1 with every position in p2
if p2 is not set, it is assumed that distances between all positions in p1 are desired. p2 will be set to p1 in this case.
Use set cell and pbc to use the minimum image convention.
Analysis tools¶
Provides the class Analysis
for structural analysis of any Atoms
object or list thereof (trajectories).
Example:
>>> import numpy as np
>>> from ase.build import molecule
>>> from ase.geometry.analysis import Analysis
>>> mol = molecule('C60')
>>> ana = Analysis(mol)
>>> CCBonds = ana.get_bonds('C', 'C', unique=True)
>>> CCCAngles = ana.get_angles('C', 'C', 'C', unique=True)
>>> print("There are {} CC bonds in C60.".format(len(CCBonds[0])))
>>> print("There are {} CCC angles in C60.".format(len(CCCAngles[0])))
>>> CCBondValues = ana.get_values(CCBonds)
>>> CCCAngleValues = ana.get_values(CCCAngles)
>>> print("The average CC bond length is {}.".format(np.average(CCBondValues)))
>>> print("The average CCC angle is {}.".format(np.average(CCCAngleValues)))
The Analysis
class provides a getter and setter for the images.
This allows you to use the same neighbourlist for different images, e.g. to analyze two MD simulations at different termperatures but constant bonding patterns.
Using this approach saves the time to recalculate all bonds, angles and dihedrals and therefore speeds up your analysis.
Using the Analysis.clear_cache()
function allows you to clear the calculated matrices/lists to reduce your memory usage.
The entire class can be used with few commands:
 To retrieve tuples of bonds/angles/dihedrals (they are calculated the first time they are accessed) use
instance.all_xxx
where xxx is one of bonds/angles/dihedrals.  If you only want those oneway (meaning e.g. not bonds ij and ji but just ij) use
instance.unique_xxx
.  To get selected bonds/angles/dihedrals use
instance.get_xxx(A,B,...)
, see the API section for details on which arguments you can pass.  To get the actual value of a bond/angle/dihedral use
instance.get_xxx_value(tuple)
.  To get a lot of bond/angle/dihedral values at once use
Analysis.get_values()
.  There is also a wrapper to get radial distribution functions
Analysis.get_rdf()
.
The main difference between properties (getters) and functions here is, that getters provide data that is cached.
This means that getting information from Analysis.all_bonds
more than once is instantanious, since the information is cached in Analysis._cache
.
If you call any Analysis.get_xxx()
the information is calculated from the cached data, meaning each call will take the same amount of time.
API:

class
ase.geometry.analysis.
Analysis
(images, nl=None, **kwargs)[source]¶ Analysis class
Parameters for initialization:
 images:
Atoms
object or list of such  Images to analyze.
 nl: None,
NeighborList
object or list of such  Neighborlist(s) for the given images. One or nImages, depending if bonding pattern changes or is constant. Using one Neigborlist greatly improves speed.
 kwargs: options, dict
 Arguments for constructing
NeighborList
object ifnl
is None.
The choice of
bothways=True
for theNeighborList
object will not influence the amount of bonds/angles/dihedrals you get, all are reported in both directions. Use the uniquelabeled properties to get lists without duplicates.
adjacency_matrix
¶ The adjacency/connectivity matrix.
If not already done, build a list of adjacency matrices for all
nl
.No setter or deleter, only getter

all_angles
¶ All angles
A list with indices of atoms in angles for each neighborlist in self. Atom i forms an angle to the atoms inside the tuples in result[i]: i – result[i][x][0] – result[i][x][1] where x is in range(number of angles from i). See also
unique_angles
.No setter or deleter, only getter

all_bonds
¶ All Bonds.
A list with indices of bonded atoms for each neighborlist in self. Atom i is connected to all atoms inside result[i]. Duplicates from PBC are removed. See also
unique_bonds
.No setter or deleter, only getter

all_dihedrals
¶ All dihedrals
Returns a list with indices of atoms in dihedrals for each neighborlist in this instance. Atom i forms a dihedral to the atoms inside the tuples in result[i]: i – result[i][x][0] – result[i][x][1] – result[i][x][2] where x is in range(number of dihedrals from i). See also
unique_dihedrals
.No setter or deleter, only getter

distance_matrix
¶ The distance matrix.
If not already done, build a list of distance matrices for all
nl
. Seease.neighborlist.get_distance_matrix()
.No setter or deleter, only getter

get_angle_value
(imIdx, idxs, **kwargs)[source]¶ Get angle.
Parameters:
 imIdx: int
 Index of Image to get value from.
 idxs: tuple or list of integers
 Get angle between atoms idxs[0]idxs[1]idxs[2].
 kwargs: options or dict
 Passed on to
ase.Atoms.get_angle()
.
Returns:
 return: float
 Value returned by image.get_angle.

get_angles
(A, B, C, unique=True)[source]¶ Get angles from given elements ABC.
Parameters:
 A, B, C: str
 Get Angles between elements A, B and C. B will be the central atom.
 unique: bool
 Return the angles both ways or just one way (ABC and CBA or only ABC)
Returns:
 return: list of lists of tuples
 return[imageIdx][atomIdx][angleI], each tuple starts with atomIdx.
Use
get_values()
to convert the returned list to values.

get_bond_value
(imIdx, idxs, **kwargs)[source]¶ Get bond length.
Parameters:
 imIdx: int
 Index of Image to get value from.
 idxs: tuple or list of integers
 Get distance between atoms idxs[0]idxs[1].
 kwargs: options or dict
 Passed on to
ase.Atoms.get_distance()
.
Returns:
 return: float
 Value returned by image.get_distance.

get_bonds
(A, B, unique=True)[source]¶ Get bonds from element A to element B.
Parameters:
 A, B: str
 Get Bonds between elements A and B
 unique: bool
 Return the bonds both ways or just one way (AB and BA or only AB)
Returns:
 return: list of lists of tuples
 return[imageIdx][atomIdx][bondI], each tuple starts with atomIdx.
Use
get_values()
to convert the returned list to values.

get_dihedral_value
(imIdx, idxs, **kwargs)[source]¶ Get dihedral.
Parameters:
 imIdx: int
 Index of Image to get value from.
 idxs: tuple or list of integers
 Get angle between atoms idxs[0]idxs[1]idxs[2]idxs[3].
 kwargs: options or dict
 Passed on to
ase.Atoms.get_dihedral()
.
Returns:
 return: float
 Value returned by image.get_dihedral.

get_dihedrals
(A, B, C, D, unique=True)[source]¶ Get dihedrals ABCD.
Parameters:
 A, B, C, D: str
 Get Dihedralss between elements A, B, C and D. BC will be the central axis.
 unique: bool
 Return the dihedrals both ways or just one way (ABCD and DCBA or only ABCD)
Returns:
 return: list of lists of tuples
 return[imageIdx][atomIdx][dihedralI], each tuple starts with atomIdx.
Use
get_values()
to convert the returned list to values.

get_rdf
(rmax, nbins, imageIdx=None, elements=None, return_dists=False)[source]¶ Get RDF.
Wrapper for
ase.ga.utilities.get_rdf()
with more selection possibilities.Parameters:
 rmax: float
 Maximum distance of RDF.
 nbins: int
 Number of bins to devide RDF.
 imageIdx: int/slice/None
 Images to analyze, see
_get_slice()
for details.  elements: str/int/list/tuple
 Make partial RDFs.
If elements is \(None\), a full RDF is calculated. If elements is an integer or a list/tuple of integers, only those atoms will contribute to the RDF (like a mask). If elements is a string or a list/tuple of strings, only Atoms of those elements will contribute.
Returns:
 return: list of lists / list of tuples of lists
 If return_dists is True, the returned tuples contain (rdf, distances). Otherwise only rdfs for each image are returned.

get_values
(inputList, imageIdx=None, **kwargs)[source]¶ Get Bond/Angle/Dihedral values.
Parameters:
 inputList: list of lists of tuples
 Can be any list provided by
get_bonds()
,get_angles()
orget_dihedrals()
.  imageIdx: integer or slice
 The images from
images
to be analyzed. If None, all frames will be analyzed. See_get_slice()
for details.  kwargs: options or dict
 Passed on to the
Atoms
classes functions for retrieving the values.
Returns:
 return: list of lists of floats
 return[imageIdx][valueIdx]. Has the same shape as the inputList, instead of each tuple there is a float with the value this tuple yields.
The type of value requested is determined from the length of the tuple inputList[0][0]. The methods from the
Atoms
class are used.

images
¶ Images.
Set during initialization but can also be set later.

nImages
¶ Number of Images in this instance.
Cannot be set, is determined automatically.

nl
¶ Neighbor Lists in this instance.
Set during initialization.
No setter or deleter, only getter

unique_angles
¶ Get Unique Angles.
all_angles
ijk without kji.

unique_bonds
¶ Get Unique Bonds.
all_bonds
ij without ji. This is the upper triangle of the connectivity matrix (i,j), \(i < j\)

unique_dihedrals
¶ Get Unique Dihedrals.
all_dihedrals
ijkl without lkji.
 images: