Geometry tools — ASE documentation (2024)

Parallel epipedal unit cell of up to three dimensions.

This object resembles a 3x3 array whose [i, j]-th element is the jthCartesian coordinate of the ith unit vector.

Cells of less than three dimensions are represented by placeholderunit vectors that are zero.

Create cell.

Parameters:

array: 3x3 arraylike object

The three cell vectors: cell[0], cell[1], and cell[2].

angles()[source]

Return an array with the three angles alpha, beta, and gamma.

area(i)[source]

Area spanned by the two vectors with index different from i.

areas()[source]

Areas spanned by cell vector pairs (1, 2), (2, 0), and (0, 2).

classmethod ascell(cell)[source]

Return argument as a Cell object. See ase.cell.Cell.new().

A new Cell object is created if necessary.

bandpath(path: str = None, npoints: int = None, *, density: float = None, special_points: Mapping[str, Sequence[float]] = None, eps: float = 0.0002, pbc: bool | Sequence[bool] = True) → BandPath[source]

Build a BandPath for this cell.

If special points are None, determine the Bravais lattice ofthis cell and return a suitable Brillouin zone path withstandard special points.

If special special points are given, interpolate the pathdirectly from the available data.

Parameters:

path: string

String of special point names defining the path, e.g. ‘GXL’.

npoints: int

Number of points in total. Note that at least one pointis added for each special point in the path.

density: float

density of kpoints along the path in Å⁻¹.

special_points: dict

Dictionary mapping special points to scaled kpoint coordinates.For example {'G': [0, 0, 0], 'X': [1, 0, 0]}.

eps: float

Tolerance for determining Bravais lattice.

pbc: three bools

Whether cell is periodic in each direction. Normally notnecessary. If cell has three nonzero cell vectors, usee.g. pbc=[1, 1, 0] to request a 2D bandpath nevertheless.

Example

>>> from ase.cell import Cell

>>> cell = Cell.fromcellpar([4, 4, 4, 60, 60, 60])>>> cell.bandpath('GXW', npoints=20)BandPath(path='GXW', cell=[3x3], special_points={GKLUWX}, kpts=[20x3])

cartesian_positions(scaled_positions) → ndarray[source]

Calculate Cartesian positions from scaled positions.

cellpar(radians=False)[source]

Get unit cell parameters. Sequence of 6 numbers.

First three are unit cell vector lengths and second threeare angles between them:

[len(a), len(b), len(c), angle(b,c), angle(a,c), angle(a,b)]

in degrees.

See also ase.geometry.cell.cell_to_cellpar().

complete()[source]

Convert missing cell vectors into orthogonal unit vectors.

copy()[source]

Return a copy of this cell.

classmethod fromcellpar(cellpar, ab_normal=(0, 0, 1), a_direction=None)[source]

Return new Cell from cell lengths and angles.

See also cellpar_to_cell().

get_bravais_lattice(eps=0.0002, *, pbc=True)[source]

Return BravaisLattice for this cell:

>>> from ase.cell import Cell

>>> cell = Cell.fromcellpar([4, 4, 4, 60, 60, 60])>>> print(cell.get_bravais_lattice())FCC(a=5.65685)

Note

The Bravais lattice object follows the AFlowconventions. cell.get_bravais_lattice().tocell() maydiffer from the original cell by a permutation or otheroperation which maps it to the AFlow convention. Forexample, the orthorhombic lattice enforces a < b < c.

To build a bandpath for a particular cell, usease.cell.Cell.bandpath() instead of this method.This maps the kpoints back to the original input cell.

property handedness: int

Sign of the determinant of the matrix of cell vectors.

1 for right-handed cells, -1 for left, and 0 for cells thatdo not span three dimensions.

lengths()[source]

Return the length of each lattice vector as an array.

mask()[source]

Boolean mask of which cell vectors are nonzero.

minkowski_reduce()[source]

Minkowski-reduce this cell, returning new cell and mapping.

See also ase.geometry.minkowski_reduction.minkowski_reduce().

classmethod new(cell=None)[source]

Create new cell from any parameters.

If cell is three numbers, assume three lengths with right angles.

If cell is six numbers, assume three lengths, then three angles.

If cell is 3x3, assume three cell vectors.

niggli_reduce(eps=1e-05)[source]

Niggli reduce this cell, returning a new cell and mapping.

See also ase.build.tools.niggli_reduce_cell().

normal(i)[source]

Normal vector of the two vectors with index different from i.

This is the cross product of those vectors in cyclic order from i.

normals()[source]

Normal vectors of each axis as a 3x3 matrix.

property orthorhombic: bool

Return whether this cell is represented by a diagonal matrix.

permute_axes(permutation)[source]

Permute axes of cell.

property rank: int

“Return the dimension of the cell.

Equal to the number of nonzero lattice vectors.

reciprocal() → Cell[source]

Get reciprocal lattice as a Cell object.

The reciprocal cell is defined such that

cell.reciprocal() @ cell.T == np.diag(cell.mask())

within machine precision.

See Also

ase.geometry.geometry — ASE documentationThe Cell object — ASE documentationQuadratic forms, reduction of - Encyclopedia of Mathematics

Does not include factor of 2 pi.

scaled_positions(positions) → ndarray[source]

Calculate scaled positions from Cartesian positions.

The scaled positions are the positions given in the basisof the cell vectors. For the purpose of defining the basis, cellvectors that are zero will be replaced by unit vectors as percomplete().

standard_form()[source]

Rotate axes such that unit cell is lower triangular. The cellhandedness is preserved.

A lower-triangular cell with positive diagonal entries is a canonical(i.e. unique) description. For a left-handed cell the diagonal entriesare negative.

Returns:

rcell: the standardized cell object

Q: ndarray

The orthogonal transformation. Here, rcell @ Q = cell, where cellis the input cell and rcell is the lower triangular (output) cell.

uncomplete(pbc)[source]

Return new cell, zeroing cell vectors where not periodic.

property volume: float

Get the volume of this cell.

If there are less than 3 lattice vectors, return 0.

Returns the cell parameters [a, b, c, alpha, beta, gamma].

Angles are in degrees unless radian=True is used.

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 bare normal to \(ab_normal\) and a is parallel to the projection of\(a_direction\) in the a-b 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. Thecell 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 a-bplane.

Example:

>>> from ase.geometry.cell import cellpar_to_cell

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

Calculate complete cell with missing lattice vectors.

Returns a new 3x3 ndarray.

Return vectors and their lengths considering cell and pbc.

The minimum image convention is applied if cell and pbc are set.This can be used like a simple version of get_distances.

Get the distance between two structures s1 and s2.

The distance is defined by the Frobenius norm ofthe spatial distance between all coordinates (seenumpy.linalg.norm for the definition).

permute: minimise the distance by ‘permuting’ same elements

Finds the minimum-image representation of vector(s) v using either oneof two find mic algorithms depending on the given cell, v and pbc.

Get angles formed by two lists of vectors.

Calculate angle in degrees between vectors v0 and v1

Set a cell and pbc to enable minimum imageconvention, otherwise angles are taken as-is.

Get derivatives of angles formed by two lists of vectors (v0, v1) w.r.t.Cartesian coordinates in degrees.

Set a cell and pbc to enable minimum imageconvention, otherwise derivatives of angles are taken as-is.

There is a singularity in the derivatives for sin(angle) -> 0 for whicha ZeroDivisionError is raised.

Derivative output format: [[dx_a0, dy_a0, dz_a0], […], […, dz_a2].

Get dihedral angles formed by three lists of vectors.

Calculate dihedral angle (in degrees) between the vectors a0->a1,a1->a2 and a2->a3, written as v0, v1 and v2.

Set a cell and pbc to enable minimum imageconvention, otherwise angles are taken as-is.

Get derivatives of dihedrals formed by three lists of vectors(v0, v1, v2) w.r.t Cartesian coordinates in degrees.

Set a cell and pbc to enable minimum imageconvention, otherwise dihedrals are taken as-is.

Derivative output format: [[dx_a0, dy_a0, dz_a0], …, […, dz_a3]].

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 p1are desired. p2 will be set to p1 in this case.

Use set cell and pbc to use the minimum image convention.

Get derivatives of distances for all vectors in v0 w.r.t. Cartesiancoordinates in Angstrom.

Set cell and pbc to use the minimum image convention.

There is a singularity for distances -> 0 for which a ZeroDivisionError israised.Derivative output format: [[dx_a0, dy_a0, dz_a0], [dx_a1, dy_a1, dz_a1]].

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.

Returns two arrays describing which layer each atom belongsto and the distance between the layers and origo.

Parameters:

miller: 3 integers

The Miller indices of the planes. Actually, any directionin reciprocal space works, so if a and b are two floatvectors spanning an atomic plane, you can get all layersparallel to this with miller=np.cross(a,b).

tolerance: float

The maximum distance in Angstrom along the plane normal forcounting 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>>> from ase.geometry.geometry import get_layers

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

Tests if a cell is Minkowski-reduced.

Parameters:

cell: array

The lattice basis to test (in row-vector format).

pbc: array, optional

The periodic boundary conditions of the cell (Default \(True\)).If \(pbc\) is provided, only periodic cell vectors are tested.

Returns:

is_reduced: bool

True if cell is Minkowski-reduced, False otherwise.

Check that cell only has stuff in the diagonal.

Calculate a Minkowski-reduced lattice basis. The reduced basishas the shortest possible vector lengths and hasnorm(a) <= norm(b) <= norm(c).

Implements the method described in:

Low-dimensional Lattice Basis Reduction RevisitedNguyen, Phong Q. and Stehlé, Damien,ACM Trans. Algorithms 5(4) 46:1–46:48, 2009doi: 10.1145/1597036.1597050

Parameters:

cell: array

The lattice basis to reduce (in row-vector format).

pbc: array, optional

The periodic boundary conditions of the cell (Default \(True\)).If \(pbc\) is provided, only periodic cell vectors are reduced.

Returns:

rcell: array

The reduced lattice basis.

op: array

The unimodular matrix transformation (rcell = op @ cell).

Return cell as three box dimensions or raise ValueError.

Permute axes of unit cell and atom positions. Considers only cell andatomic positions. Other vector quantities such as momenta are notmodified.

Wrap positions to unit cell.

Returns positions changed by a multiple of the unit cell vectors tofit inside the space spanned by these vectors. See also thease.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 positionswill be moved along this axis.

center: three float

The positons in fractional coordinates that the new positionswill be nearest possible to.

pretty_translation: bool

Translates atoms such that fractional coordinates are minimized.

eps: float

Small number to prevent slightly negative coordinates from beingwrapped.

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