SuperCell¶
-
class
sisl.
SuperCell
(cell, nsc=None, origo=None)[source]¶ 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. Fornsc[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
- origo : (3,) of float
the origo of the supercell.
Attributes: Attributes
cell
icell
Returns the reciprocal (inverse) cell for the SuperCell
.isc_off
Internal indexed supercell [ia, ib, ic] == i
n_s
nsc
origo
Origo for the cell rcell
Returns the reciprocal cell for the SuperCell
with2*np.pi
sc_off
Integer supercell offsets volume
Methods
__init__
(cell[, nsc, origo])Initialize self. 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 axiscenter
([axis])Returns center of the SuperCell
, possibly with respect to an axiscopy
([cell, origo])Returns a copy of the object with possibly some quantities overwritten cut
(seps, axis)Cuts the cell into several different sections. 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_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 parameters
([rad])Return the cell-parameters of this cell 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 axisread
(sile, *args, **kwargs)Reads SuperCell from the Sile
using Sile.read_supercellrepeat
(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 swapaxes
(a, b)Returns SuperCell
with swapped axistile
(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 origo tocell
(*args)Returns a 3x3 unit-cell dependent on the input translate
(v)Appends additional space in the SuperCell object -
add
(other)[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
(vacuum, axis)[source]¶ 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)[source]¶ 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
-
cell
¶
-
copy
(cell=None, origo=None)[source]¶ Returns a copy of the object with possibly some quantities overwritten
Parameters: - cell : array_like
the new cell parameters
- origo : array_like
the new origo
-
equal
(other, tol=0.0001)[source]¶ Check whether two supercell are equivalent
Parameters: - tol : float, optional
tolerance value for the cell vectors and origo
-
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
- xyz : array_like
-
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.
-
isc_off
¶ Internal indexed supercell
[ia, ib, ic] == i
-
n_s
¶
-
nsc
¶
-
origo
¶ Origo 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)
-
parameters
(rad=False)[source]¶ Return the cell-parameters of this cell
Parameters: - rad : bool, optional
whether the angles are returned in radians (otherwise in degree)
Returns: - a : length of first lattice vector
- b : length of second lattice vector
- c : length of third lattice vector
- alpha : angle between b and c vectors
- beta : angle between a and c vectors
- gamma : 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
(ax1, ax2, origo=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
- 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:
>>> 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
andp5
are always[0, 0, 0]
andp2
,p4
andp6
are alwaysuc
. Hence this may be used to further reduce certain computations.
-
rcell
¶ Returns the reciprocal cell for the
SuperCell
with2*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)[source]¶ Reads SuperCell from the
Sile
using Sile.read_supercellParameters: - 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 usingsisl.io.get_sile
.
- sile :
-
repeat
(reps, axis)[source]¶ 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)[source]¶ 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.
-
sc_index
(sc_off)[source]¶ 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)[source]¶ Scale lattice vectors
Does not scale
origo
.Parameters: - scale :
float
the scale factor for the new lattice vectors
- scale :
-
set_nsc
(nsc=None, a=None, b=None, c=None)[source]¶ 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)[source]¶ Returns
SuperCell
with swapped axisIf
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
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.
-
toCuboid
(orthogonal=False)[source]¶ A cuboid with vectors as this unit-cell and center with respect to its origo
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)¶ Appends additional space in the SuperCell object
-
volume
¶