sisl.SuperCell¶
- class sisl.SuperCell(cell, nsc=None, origo=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. 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.
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 axisarea
(ax0, ax1)Calculate the area spanned by the two axis ax0 and ax1
cell_length
(length)Calculate cell vectors such that they each have length
length
center
([axis])Returns center of the
SuperCell
, possibly with respect to an axiscopy
([cell, origo])A deepcopy of the object
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_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.
move
(v)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[, 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 the supercell from the
Sile
usingSile.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)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 origo
tocell
(*args)Returns a 3x3 unit-cell dependent on the input
translate
(v)Appends additional space to the object
Returns the reciprocal (inverse) cell for the
SuperCell
.Internal indexed supercell
[ia, ib, ic] == i
Length of each lattice vector
Origo for the cell
Returns the reciprocal cell for the
SuperCell
with2*np.pi
Integer supercell offsets
- 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
- cell¶
- cell_length(length)[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 3
- Returns
cell-vectors with prescribed length
- Return type
- copy(cell=None, origo=None)[source]¶
A deepcopy of the object
- 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 usedtol (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¶
Internal indexed supercell
[ia, ib, ic] == i
- property length¶
Length of each lattice vector
- n_s¶
- nsc¶
- property origo¶
Origo for the cell
- parameters(rad=False)[source]¶
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, origo=True)[source]¶
Query point and plane-normal for the plane spanning ax1 and ax2
- Parameters
- 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
andp5
are always[0, 0, 0]
andp2
,p4
andp6
are alwaysuc
. Hence this may be used to further reduce certain computations.
- property 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 the supercell from the
Sile
usingSile.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 usingsisl.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.
- 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) – the vector around the rotation is going to happen
v = [1,0,0]
will rotate in theyz
planerad (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¶
Integer supercell offsets
- scale(scale)[source]¶
Scale lattice vectors
Does not scale
origo
.- Parameters
scale (
float
) – the scale factor for the new lattice vectors
- 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.
- 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 to the object
- volume¶