# sisl.SuperCell

class sisl.SuperCell(cell, nsc=None, origin=None)

Bases: object

A cell class to retain lattice vectors and a supercell structure

The supercell structure is comprising the primary unit-cell and neighbouring unit-cells. The number of supercells is given by the attribute nsc which is a vector with 3 elements, one per lattice vector. It describes how many times the primary unit-cell is extended along the i’th lattice vector. For nsc[i] == 3 the supercell is made up of 3 unit-cells. One behind, the primary unit-cell and one after.

Parameters
• cell (array_like) – the lattice parameters of the unit cell (the actual cell is returned from tocell.

• nsc (array_like of int) – number of supercells along each latticevector

• origin ((3,) of float, optional) – the origin of the supercell.

Methods

 add(other) Add two supercell lattice vectors to each other add_vacuum(vacuum, axis) Add vacuum along the axis lattice vector angle(i, j[, rad]) The angle between two of the cell vectors append(other, axis) Appends other SuperCell to this grid along axis area(ax0, ax1) Calculate the area spanned by the two axis ax0 and ax1 cell2length(length[, axes]) Calculate cell vectors such that they each have length length center([axis]) Returns center of the SuperCell, possibly with respect to an axis copy([cell, origin]) A deepcopy of the object equal(other[, tol]) Check whether two supercell are equivalent fit(xyz[, axis, tol]) Fit the supercell to xyz such that the unit-cell becomes periodic in the specified directions is_cartesian([tol]) Checks if cell vectors a,b,c are multiples of the cartesian axis vectors (x, y, z) is_orthogonal([tol]) Returns true if the cell vectors are orthogonal. Appends additional space to the object offset([isc]) Returns the supercell offset of the supercell index parallel(other[, axis]) Returns true if the cell vectors are parallel to other parameters([rad]) Cell parameters of this cell in 3 lengths and 3 angles plane(ax1, ax2[, origin]) Query point and plane-normal for the plane spanning ax1 and ax2 prepend(other, axis) Prepends other SuperCell to this grid along axis read(sile, *args, **kwargs) Reads the supercell from the Sile using Sile.read_supercell repeat(reps, axis) Extend the unit-cell reps times along the axis lattice vector rotate(angle, v[, only, rad]) Rotates the supercell, in-place by the angle around the vector sc_index(sc_off) Returns the integer index in the sc_off list that corresponds to sc_off scale(scale[, what]) Scale lattice vectors set_nsc([nsc, a, b, c]) Sets the number of supercells in the 3 different cell directions swapaxes(a, b) Swap axis a and b in a new SuperCell tile(reps, axis) Extend the unit-cell reps times along the axis lattice vector toCuboid([orthogonal]) A cuboid with vectors as this unit-cell and center with respect to its origin tocell(*args) Returns a 3x3 unit-cell dependent on the input Appends additional space to the object unrepeat(reps, axis) Reverses a SuperCell.tile and returns the segmented version untile(reps, axis) Reverses a SuperCell.tile and returns the segmented version Vertices of the cell cell nsc n_s icell Returns the reciprocal (inverse) cell for the SuperCell. isc_off Internal indexed supercell [ia, ib, ic] == i length Length of each lattice vector origin Origin for the cell rcell Returns the reciprocal cell for the SuperCell with 2*np.pi sc_off Integer supercell offsets volume Volume of cell
__init__(cell, nsc=None, origin=None)[source]

Add two supercell lattice vectors to each other

Parameters

other (SuperCell, array_like) – the lattice vectors of the other supercell to add

Add vacuum along the axis lattice vector

Parameters
• vacuum (float) – amount of vacuum added, in Ang

• axis (int) – the lattice vector to add vacuum along

The angle between two of the cell vectors

Parameters
• i (int) – the first cell vector

• j (int) – the second cell vector

• rad (bool, optional) – whether the returned value is in radians

append(other, axis)[source]

Appends other SuperCell to this grid along axis

area(ax0, ax1)[source]

Calculate the area spanned by the two axis ax0 and ax1

cell
cell2length(length, axes=(0, 1, 2)) [source]

Calculate cell vectors such that they each have length length

Parameters
• length (float or array_like) – length for cell vectors, if an array it corresponds to the individual vectors and it must have length equal to axes

• axes (int or array_like, optional) – which axes the length variable refers too.

Returns

cell-vectors with prescribed length, same order as axes

Return type

numpy.ndarray

center(axis=None)[source]

Returns center of the SuperCell, possibly with respect to an axis

copy(cell=None, origin=None)[source]

A deepcopy of the object

Parameters
• cell (array_like) – the new cell parameters

• origin (array_like) – the new origin

equal(other, tol=0.0001)[source]

Check whether two supercell are equivalent

Parameters

tol (float, optional) – tolerance value for the cell vectors and origin

fit(xyz, axis=None, tol=0.05)[source]

Fit the supercell to xyz such that the unit-cell becomes periodic in the specified directions

The fitted supercell tries to determine the unit-cell parameters by solving a set of linear equations corresponding to the current supercell vectors.

>>> numpy.linalg.solve(self.cell.T, xyz.T)


It is important to know that this routine will only work if at least some of the atoms are integer offsets of the lattice vectors. I.e. the resulting fit will depend on the translation of the coordinates.

Parameters
• xyz (array_like shape(*, 3)) – the coordinates that we will wish to encompass and analyze.

• axis (None or array_like) – if None equivalent to [0, 1, 2], else only the cell-vectors along the provided axis will be used

• tol (float) – tolerance (in Angstrom) of the positions. I.e. we neglect coordinates which are not within the radius of this magnitude

property icell

Returns the reciprocal (inverse) cell for the SuperCell.

Note: The returned vectors are still in [0, :] format and not as returned by an inverse LAPACK algorithm.

is_cartesian(tol=0.001)[source]

Checks if cell vectors a,b,c are multiples of the cartesian axis vectors (x, y, z)

Parameters

tol (float, optional) – the threshold above which an off diagonal term will be considered non-zero.

is_orthogonal(tol=0.001)[source]

Returns true if the cell vectors are orthogonal.

Parameters

tol (float, optional) – the threshold above which the scalar product of two cell vectors will be considered non-zero.

property isc_off: ndarray

Internal indexed supercell [ia, ib, ic] == i

property length: ndarray

Length of each lattice vector

move(v)

Appends additional space to the object

n_s
nsc
offset(isc=None)[source]

Returns the supercell offset of the supercell index

property origin: ndarray

Origin for the cell

parallel(other, axis=(0, 1, 2))[source]

Returns true if the cell vectors are parallel to other

Parameters
• other (SuperCell) – the other object to check whether the axis are parallel

• axis (int or array_like) – only check the specified axis (default to all)

Cell parameters of this cell in 3 lengths and 3 angles

Notes

Since we return the length and angles between vectors it may not be possible to recreate the same cell. Only in the case where the first lattice vector only has a Cartesian $$x$$ component will this be the case

Parameters

rad (bool, optional) – whether the angles are returned in radians (otherwise in degree)

Returns

• float – length of first lattice vector

• float – length of second lattice vector

• float – length of third lattice vector

• float – angle between b and c vectors

• float – angle between a and c vectors

• float – angle between a and b vectors

plane(ax1, ax2, origin=True)[source]

Query point and plane-normal for the plane spanning ax1 and ax2

Parameters
• ax1 (int) – the first axis vector

• ax2 (int) – the second axis vector

• origin (bool, optional) – whether the plane intersects the origin or the opposite corner of the unit-cell.

Returns

• normal_V (numpy.ndarray) – planes normal vector (pointing outwards with regards to the cell)

• p (numpy.ndarray) – a point on the plane

Examples

All 6 faces of the supercell can be retrieved like this:

>>> sc = SuperCell(4)
>>> n1, p1 = sc.plane(0, 1, True)
>>> n2, p2 = sc.plane(0, 1, False)
>>> n3, p3 = sc.plane(0, 2, True)
>>> n4, p4 = sc.plane(0, 2, False)
>>> n5, p5 = sc.plane(1, 2, True)
>>> n6, p6 = sc.plane(1, 2, False)


However, for performance critical calculations it may be advantageous to do this:

>>> sc = SuperCell(4)
>>> uc = sc.cell.sum(0)
>>> n1, p1 = sc.plane(0, 1)
>>> n2 = -n1
>>> p2 = p1 + uc
>>> n3, p3 = sc.plane(0, 2)
>>> n4 = -n3
>>> p4 = p3 + uc
>>> n5, p5 = sc.plane(1, 2)
>>> n6 = -n5
>>> p6 = p5 + uc


Secondly, the variables p1, p3 and p5 are always [0, 0, 0] and p2, p4 and p6 are always uc. Hence this may be used to further reduce certain computations.

prepend(other, axis)[source]

Prepends other SuperCell to this grid along axis

For a SuperCell object this is equivalent to append.

property rcell

Returns the reciprocal cell for the SuperCell with 2*np.pi

Note: The returned vectors are still in [0, :] format and not as returned by an inverse LAPACK algorithm.

Reads the supercell from the Sile using Sile.read_supercell

Parameters

sile (Sile, str or pathlib.Path) – a Sile object which will be used to read the supercell if it is a string it will create a new sile using sisl.io.get_sile.

repeat(reps, axis)[source]

Extend the unit-cell reps times along the axis lattice vector

Notes

This is exactly equivalent to the tile routine.

Parameters
• reps (int) – number of times the unit-cell is repeated along the specified lattice vector

• axis (int) – the lattice vector along which the repetition is performed

Rotates the supercell, in-place by the angle around the vector

One can control which cell vectors are rotated by designating them individually with only='[abc]'.

Parameters
• angle (float) – the angle of which the geometry should be rotated

• v (array_like) – the vector around the rotation is going to happen v = [1,0,0] will rotate in the yz plane

• rad (bool, optional) – Whether the angle is in radians (True) or in degrees (False)

• only (('abc'), str, optional) – only rotate the designated cell vectors.

sc_index(sc_off)[source]

Returns the integer index in the sc_off list that corresponds to sc_off

Returns the index for the supercell in the global offset.

Parameters

sc_off ((3,) or list of (3,)) – super cell specification. For each axis having value None all supercells along that axis is returned.

property sc_off: ndarray

Integer supercell offsets

scale(scale, what='abc')[source]

Scale lattice vectors

Does not scale origin.

Parameters
• scale (float or (3,)) – the scale factor for the new lattice vectors.

• what ({"abc", "xyz"}) – If three different scale factors are provided, whether each scaling factor is to be applied on the corresponding lattice vector (“abc”) or on the corresponding cartesian coordinate (“xyz”).

set_nsc(nsc=None, a=None, b=None, c=None)[source]

Sets the number of supercells in the 3 different cell directions

Parameters
• nsc (list of int, optional) – number of supercells in each direction

• a (integer, optional) – number of supercells in the first unit-cell vector direction

• b (integer, optional) – number of supercells in the second unit-cell vector direction

• c (integer, optional) – number of supercells in the third unit-cell vector direction

swapaxes(a, b)[source]

Swap axis a and b in a new SuperCell

If swapaxes(0,1) it returns the 0 in the 1 values.

tile(reps, axis)[source]

Extend the unit-cell reps times along the axis lattice vector

Notes

This is exactly equivalent to the repeat routine.

Parameters
• reps (int) – number of times the unit-cell is repeated along the specified lattice vector

• axis (int) – the lattice vector along which the repetition is performed

toCuboid(orthogonal=False)[source]

A cuboid with vectors as this unit-cell and center with respect to its origin

Parameters

orthogonal (bool, optional) – if true the cuboid has orthogonal sides such that the entire cell is contained

classmethod tocell(*args)[source]

Returns a 3x3 unit-cell dependent on the input

1 argument

a unit-cell along Cartesian coordinates with side-length equal to the argument.

3 arguments

the diagonal components of a Cartesian unit-cell

6 arguments

the cell parameters give by $$a$$, $$b$$, $$c$$, $$\alpha$$, $$\beta$$ and $$\gamma$$ (angles in degrees).

9 arguments

a 3x3 unit-cell.

Parameters

*args (float) – May be either, 1, 3, 6 or 9 elements. Note that the arguments will be put into an array and flattened before checking the number of arguments.

Examples

>>> cell_1_1_1 = SuperCell.tocell(1.)
>>> cell_1_2_3 = SuperCell.tocell(1., 2., 3.)
>>> cell_1_2_3 = SuperCell.tocell([1., 2., 3.]) # same as above

translate(v)[source]

Appends additional space to the object

unrepeat(reps, axis)

Reverses a SuperCell.tile and returns the segmented version

tile

opposite of this method

untile(reps, axis)[source]

Reverses a SuperCell.tile and returns the segmented version

tile

opposite of this method

vertices()[source]

Vertices of the cell

Returns

The coordinates of the vertices of the cell. The first three dimensions correspond to each cell axis (off, on), and the last one contains the xyz coordinates.

Return type

array of shape (2, 2, 2, 3)

property volume

Volume of cell