SuperCell

class sisl.SuperCell(cell, nsc=None)

Object to retain a super-cell and its nested values.

This supercell object handles cell vectors and its supercell mirrors.

Attributes

cell
isc_off	Internal indexed supercell [ia, ib, ic] == i
n_s
nsc
rcell	Returns the reciprocal cell for the SuperCell without 2*np.pi
sc_off	Integer supercell offsets
vol

Methods

__init__(cell[, nsc])	Initialize a SuperCell object from initial quantities
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
center([axis])	Returns center of the SuperCell, possibly with respect to an axis
copy([cell])	Returns a copy of the object.
cut(seps, axis)	Cuts the cell into several different sections.
fit(xyz[, axis, tol])	Fit the supercell to xyz such that the unit-cell becomes periodic in the specified directions
is_orthogonal()	Returns true if the cell vectors are orthogonal
move(v)	Appends additional space in the SuperCell object
offset([isc])	Returns the supercell offset of the supercell index
parallel(other[, axis])	Returns true if the cell vectors are parallel to other
plane(ax1, ax2[, origo])	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 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
rotatea(angle[, only, rad])
rotateb(angle[, only, rad])
rotatec(angle[, only, rad])
sc_index(sc_off)	Returns the integer index in the sc_off list that corresponds to sc_off
scale(scale)	Scale lattice vectors
set_nsc([nsc, a, b, c])	Sets the number of supercells in the 3 different cell directions
set_supercell([nsc, a, b, c])	Sets the number of supercells in the 3 different cell directions
swapaxes(a, b)	Returns SuperCell with swapped axis
tile(reps, axis)	Extend the unit-cell reps times along the axis lattice vector
tocell(*args)	Returns a 3x3 unit-cell dependent on the input
translate(v)	Appends additional space in the SuperCell object

add_vacuum(vacuum, axis)

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

angle(i, j, rad=False)

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)

Appends other SuperCell to this grid along axis

cell

center(axis=None)

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

copy(cell=None)

Returns a copy of the object.

cut(seps, axis)

Cuts the cell into several different sections.

fit(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) 

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

is_orthogonal()

Returns true if the cell vectors are orthogonal

isc_off

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

move(v)

Appends additional space in the SuperCell object

n_s

nsc

offset(isc=None)

Returns the supercell offset of the supercell index

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

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)

plane(ax1, ax2, origo=True)

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

origo : bool, optional

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

Returns:

n : array_like

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

p : array_like

a point on the plane

Examples

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

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

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

>>> uc = self.cell.sum(0) 
>>> n1, p1 = self.sc.plane(0, 1) 
>>> n2 = -n1 
>>> p2 = p1 + uc 
>>> n3, p3 = self.sc.plane(0, 2) 
>>> n4 = -n3 
>>> p4 = p3 + uc 
>>> n5, p5 = self.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)

Prepends other SuperCell to this grid along axis

For a SuperCell object this is equivalent to append.

rcell

Returns the reciprocal cell for the SuperCell without 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 SuperCell from the Sile using Sile.read_supercell

Parameters:

sile : Sile or str

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)

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

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

Notes

This is exactly equivalent to the tile routine.

rotate(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:

angle : float

the angle of which the geometry should be rotated

v : array_like [3]

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.

rotatea(angle, only='abc', rad=False)

rotateb(angle, only='abc', rad=False)

rotatec(angle, only='abc', rad=False)

sc_index(sc_off)

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

Returns the integer for the supercell

sc_off

Integer supercell offsets

scale(scale)

Scale lattice vectors

Parameters:

scale : float

the scale factor for the new lattice vectors

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

Sets the number of supercells in the 3 different cell directions

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

set_supercell(nsc=None, a=None, b=None, c=None)

Sets the number of supercells in the 3 different cell directions

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)

Returns SuperCell with swapped axis

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

tile(reps, axis)

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

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

Notes

This is exactly equivalent to the repeat routine.

classmethod tocell(*args)

Returns a 3x3 unit-cell dependent on the input

If you supply a single argument it is regarded as either a) a proper unit-cell b) the diagonal elements in the unit-cell

If you supply 3 arguments it will be the same as the diagonal elements of the unit-cell

If you supply 6 arguments it will be the same as the cell parameters, a, b, c, alpha, beta, gamma. The angles should be provided in degree (not radians).

translate(v)

Appends additional space in the SuperCell object

vol