SuperCell

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

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

cellarray_like

the lattice parameters of the unit cell (the actual cell is returned from tocell.

nscarray_like of int

number of supercells along each latticevector

origo(3,) of float

the origo of the supercell.

Attributes

cell(3, 3) of float

the lattice vectors (cell[i, :] is the i’th vector)

icell(3, 3) of float

Returns the reciprocal (inverse) cell for the SuperCell.

rcell(3, 3) of float

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

Attributes

cell
icell	Returns the reciprocal (inverse) cell for the SuperCell.
isc_off	Internal indexed supercell [ia, ib, ic] == i
length	Length of each lattice vector
n_s
nsc
origo	Origo for the cell
rcell	Returns the reciprocal cell for the SuperCell with 2*np.pi
sc_off	Integer supercell offsets
volume

Methods

__init__(self, cell[, nsc, origo])	Initialize self.
add(self, other)	Add two supercell lattice vectors to each other
add_vacuum(self, vacuum, axis)	Add vacuum along the axis lattice vector
angle(self, i, j[, rad])	The angle between two of the cell vectors
append(self, other, axis)	Appends other SuperCell to this grid along axis
area(self, ax0, ax1)	Calculate the area spanned by the two axis ax0 and ax1
cell_length(self, length)	Calculate cell vectors such that they each have length length
center(self[, axis])	Returns center of the SuperCell, possibly with respect to an axis
copy(self[, cell, origo])	A deepcopy of the object
cut(self, seps, axis)	Cuts the cell into several different sections.
equal(self, other[, tol])	Check whether two supercell are equivalent
fit(self, xyz[, axis, tol])	Fit the supercell to xyz such that the unit-cell becomes periodic in the specified directions
is_orthogonal(self)	Returns true if the cell vectors are orthogonal
move(self, v)	Appends additional space to the object
offset(self[, isc])	Returns the supercell offset of the supercell index
parallel(self, other[, axis])	Returns true if the cell vectors are parallel to other
parameters(self[, rad])	Cell parameters of this cell in 3 lengths and 3 angles
plane(self, ax1, ax2[, origo])	Query point and plane-normal for the plane spanning ax1 and ax2
prepend(self, 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(self, reps, axis)	Extend the unit-cell reps times along the axis lattice vector
rotate(self, angle, v[, only, rad])	Rotates the supercell, in-place by the angle around the vector
sc_index(self, sc_off)	Returns the integer index in the sc_off list that corresponds to sc_off
scale(self, scale)	Scale lattice vectors
set_nsc(self[, nsc, a, b, c])	Sets the number of supercells in the 3 different cell directions
swapaxes(self, a, b)	Swap axis a and b in a new SuperCell
tile(self, reps, axis)	Extend the unit-cell reps times along the axis lattice vector
toCuboid(self[, orthogonal])	A cuboid with vectors as this unit-cell and center with respect to its origo
tocell(\*args)	Returns a 3x3 unit-cell dependent on the input
translate(self, v)	Appends additional space to the object

add(self, other)

Add two supercell lattice vectors to each other

Parameters

otherSuperCell, array_like

the lattice vectors of the other supercell to add

add_vacuum(self, vacuum, axis)

Add vacuum along the axis lattice vector

Parameters

vacuumfloat

amount of vacuum added, in Ang

axisint

the lattice vector to add vacuum along

angle(self, i, j, rad=False)

The angle between two of the cell vectors

Parameters

iint

the first cell vector

jint

the second cell vector

radbool, optional

whether the returned value is in radians

append(self, other, axis)

Appends other SuperCell to this grid along axis

area(self, ax0, ax1)

Calculate the area spanned by the two axis ax0 and ax1

cell

cell_length(self, length)

Calculate cell vectors such that they each have length length

Parameters

lengthfloat or array_like

length for cell vectors, if an array it corresponds to the individual vectors and it must have length 3

Returns

numpy.ndarray

cell-vectors with prescribed length

center(self, axis=None)

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

copy(self, cell=None, origo=None)

A deepcopy of the object

Parameters

cellarray_like

the new cell parameters

origoarray_like

the new origo

cut(self, seps, axis)

Cuts the cell into several different sections.

equal(self, other, tol=0.0001)

Check whether two supercell are equivalent

Parameters

tolfloat, optional

tolerance value for the cell vectors and origo

fit(self, xyz, axis=None, tol=0.05)

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

xyzarray_like shape(*, 3)

the coordinates that we will wish to encompass and analyze.

axisNone or array_like

if None equivalent to [0, 1, 2], else only the cell-vectors along the provided axis will be used

tolfloat

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_orthogonal(self)

Returns true if the cell vectors are orthogonal

property isc_off

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

property length

Length of each lattice vector

move(self, v)

Appends additional space to the object

n_s

nsc

offset(self, isc=None)

Returns the supercell offset of the supercell index

property origo

Origo for the cell

parallel(self, other, axis=(0, 1, 2))

Returns true if the cell vectors are parallel to other

Parameters

otherSuperCell

the other object to check whether the axis are parallel

axisint or array_like

only check the specified axis (default to all)

parameters(self, rad=False)

Cell parameters of this cell in 3 lengths and 3 angles

Parameters

radbool, 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

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

plane(self, ax1, ax2, origo=True)

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

Parameters

ax1int

the first axis vector

ax2int

the second axis vector

origobool, optional

whether the plane intersects the origo or the opposite corner of the unit-cell.

Returns

numpy.ndarray

planes normal vector (pointing outwards with regards to the cell)

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(self, other, axis)

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.

static read(sile, *args, **kwargs)

Reads the supercell from the Sile using Sile.read_supercell

Parameters

sileSile, 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(self, reps, axis)

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

Parameters

repsint

number of times the unit-cell is repeated along the specified lattice vector

axisint

the lattice vector along which the repetition is performed

Notes

This is exactly equivalent to the tile routine.

rotate(self, angle, v, only='abc', rad=False)

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

anglefloat

the angle of which the geometry should be rotated

varray_like [3]

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

radbool, optional

Whether the angle is in radians (True) or in degrees (False)

only(‘abc’), str, optional

only rotate the designated cell vectors.

sc_index(self, sc_off)

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

Returns the integer for the supercell

property sc_off

Integer supercell offsets

scale(self, scale)

Scale lattice vectors

Does not scale origo.

Parameters

scalefloat

the scale factor for the new lattice vectors

set_nsc(self, nsc=None, a=None, b=None, c=None)

Sets the number of supercells in the 3 different cell directions

nsclist of int, optional

number of supercells in each direction

ainteger, optional

number of supercells in the first unit-cell vector direction

binteger, optional

number of supercells in the second unit-cell vector direction

cinteger, optional

number of supercells in the third unit-cell vector direction

swapaxes(self, a, b)

Swap axis a and b in a new SuperCell

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

tile(self, reps, axis)

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

Parameters

repsint

number of times the unit-cell is repeated along the specified lattice vector

axisint

the lattice vector along which the repetition is performed

Notes

This is exactly equivalent to the repeat routine.

toCuboid(self, orthogonal=False)

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

Parameters

orthogonalbool, optional

if true the cuboid has orthogonal sides such that the entire cell is contained

classmethod tocell(*args)

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

*argsfloat

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(self, v)

Appends additional space to the object

volume