changed SuperCell to Lattice, long overdue

CHANGELOG.md

@@ -24,6 +24,8 @@ we hit release version 1.0.0.
 - `BrillouinZone.merge` allows simple merging of several objects, #537
 
 ### Changed
+- SuperCell class is officially deprecated in favor of Lattice, see #95 for details
+  The old class will still be accessible and usable for some time (at least a year)
 - Enabled EigenState.wavefunction(grid) to accept grid as the initialization of
 	the grid argument, so one does not need to produce the Grid on before-hand
 - Geometry.rotate(only=) to (what=), this is to unify the interfaces across, #541

docs/api/basic.rst

@@ -30,7 +30,7 @@ Simple objects
    Atoms
    Geometry
    GeometryCollection
-   SuperCell
+   Lattice
    Grid
 
 

docs/tutorials/tutorial_01.rst

@@ -17,7 +17,7 @@ The *only* required information is the atomic coordinates::
    }
 
 this will create a `Geometry` object with 1 Hydrogen atom with a single orbital
-(default if not specified), and a supercell of 10 A in each Cartesian direction.
+(default if not specified), and a lattice of 10 A in each Cartesian direction.
 When printing a `Geometry` object a list of information is printed in an
 XML-like fashion. ``na`` corresponds to the total number of atoms in the
 geometry, while ``no`` refers to the total number of orbitals.

docs/tutorials/tutorial_04.rst

@@ -15,7 +15,7 @@ used. First, recall that the number of supercells can be retrieved by::
     },
     nsc: [1, 1, 1], maxR: -1.0
    }
-   >>> geometry.nsc # or geometry.sc.nsc
+   >>> geometry.nsc # or geometry.lattice.nsc
    array([1, 1, 1], dtype=int32)
 
 where ``nsc`` is the specific super-cell information. In the default
@@ -26,7 +26,7 @@ depending on the size of the supercell.
 Specifying the number of super-cells may be done when creating the geometry,
 or after it has been created::
 
-   >>> geometry = Geometry([[0, 0, 0]], sc=SuperCell(5, [3, 3, 3]))
+   >>> geometry = Geometry([[0, 0, 0]], lattice=Lattice(5, nsc=[3, 3, 3]))
    >>> geometry.nsc
    array([3, 3, 3], dtype=int32)
    >>> geometry.set_nsc([3, 1, 5])
@@ -46,7 +46,7 @@ Here we show a square 2D lattice with one atom in the unit-cell and a supercell
 which extends 2 cells along the Cartesian :math:`x` lattice vector (5 in total) and 1
 cell along the Cartesian :math:`y` lattice vector (3 in total)::
 
-  >>> square = Geometry([[0.5,0.5,0]], sc=SuperCell([1,1,10], [5, 3, 1]))
+  >>> square = Geometry([[0.5,0.5,0]], lattice=Lattice([1,1,10], nsc=[5, 3, 1]))
 
 which results in this underlying geometry:
 

docs/tutorials/tutorial_05.rst

@@ -5,7 +5,7 @@ Electronic structure setup -- part 1
 ------------------------------------
 
 A `Hamiltonian` is an extension of a `Geometry`. From the `Geometry` it
-reads the number of orbitals, the supercell information.
+reads the number of orbitals, the lattice information.
 
 Hamiltonians are matrices, and in sisl all Hamiltonians are treated
 as sparse matrices, i.e. matrices where there are an overweight of
@@ -45,7 +45,7 @@ Let us try and continue from :ref:`tutorial-01` and create a square
 2D lattice with one atom in the unit-cell and a supercell which couples only
 to nearest neighbour atoms.
 
-  >>> square = Geometry([[0.5,0.5,0]], sc=SuperCell([1, 1, 10], [3, 3, 1]))
+  >>> square = Geometry([[0.5,0.5,0]], lattice=Lattice([1, 1, 10], nsc=[3, 3, 1]))
   >>> H = Hamiltonian(square)
 
 Now we have a periodic structure with couplings allowed only to nearest neighbour

docs/tutorials/tutorial_05_square.py

@@ -4,7 +4,7 @@
 from sisl import *
 
 # Generate square lattice with nearest neighbour couplings
-square = Geometry([[0.5, 0.5, 0]], sc=SuperCell([1, 1, 10], [3, 3, 1]))
+square = Geometry([[0.5, 0.5, 0]], lattice=Lattice([1, 1, 10], [3, 3, 1]))
 
 # Generate Hamiltonian
 H = Hamiltonian(square)

docs/tutorials/tutorial_06.rst

@@ -14,7 +14,7 @@ atomic specie to be a Hydrogen atom with a single orbital with a range of :math:
 
   >>> Hydrogen = Atom(1, R=1.)
   >>> square = Geometry([[0.5, 0.5, 0]], Hydrogen,
-                        sc=SuperCell([1, 1, 10], [3, 3, 1]))
+                        lattice=Lattice([1, 1, 10], nsc=[3, 3, 1]))
   >>> H = Hamiltonian(square)
   >>> print(H)
   {spin: 1, non-zero: 0

docs/tutorials/tutorial_06_square.py

@@ -6,7 +6,7 @@
 # Generate square lattice with nearest neighbour couplings
 Hydrogen = Atom(1, R=1.)
 square = Geometry([[0.5, 0.5, 0]], Hydrogen,
-                  sc=SuperCell([1, 1, 10], [3, 3, 1]))
+                  lattice=Lattice([1, 1, 10], [3, 3, 1]))
 
 # Generate Hamiltonian
 H = Hamiltonian(square)

docs/tutorials/tutorial_siesta_1.ipynb

@@ -27,7 +27,7 @@
     "## Creating the geometry\n",
     "\n",
     "Our system of interest will be the $\\mathrm H_2\\mathrm O$ system. The first task will be to create the molecule geometry.\n",
-    "This is done using lists of atomic coordinates and atomic species. Additionally one needs to define the supercell (or if you prefer: unit-cell) where the molecule resides in. Siesta is a periodic DFT code and thus all directions are periodic. I.e. when simulating molecules it is vital to have a large vacuum gap between periodic images. In this case we use a supercell of side-lengths $10\\mathrm{Ang}$."
+    "This is done using lists of atomic coordinates and atomic species. Additionally one needs to define the lattice (or if you prefer: unit-cell) where the molecule resides in. Siesta is a periodic DFT code and thus all directions are periodic. I.e. when simulating molecules it is vital to have a large vacuum gap between periodic images. In this case we use a supercell of side-lengths $10\\mathrm{Ang}$."
    ]
   },
   {
@@ -38,16 +38,16 @@
    "source": [
     "h2o = Geometry([[0, 0, 0], [0.8, 0.6, 0], [-0.8, 0.6, 0.]], \n",
     "               [Atom('O'), Atom('H'), Atom('H')], \n",
-    "               sc=SuperCell(10, origin=[-5] * 3))"
+    "               lattice=Lattice(10, origin=[-5] * 3))"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The input are the 1) xyz coordinates, 2) the atomic species and 3) the supercell that is attached.\n",
+    "The input are the 1) xyz coordinates, 2) the atomic species and 3) the lattice that is attached.\n",
     "\n",
-    "By printing the object one gets basic information regarding the geometry, such as 1) number of atoms, 2) species of atoms, 3) number of orbitals, 4) orbitals associated with each atom and 5) number of supercells."
+    "By printing the object one gets basic information regarding the geometry, such as 1) number of atoms, 2) species of atoms, 3) number of orbitals, 4) orbitals associated with each atom and 5) number of supercells (should be 1 for molecules)."
    ]
   },
   {

examples/ex_03.py

@@ -187,7 +187,7 @@
 print('Reading output')
 gout = sisl.get_sile('zz.gout')
 # Correct what to read from the gulp output
-gout.set_supercell_key("Cartesian lattice vectors")
+gout.set_lattice_key("Cartesian lattice vectors")
 # Selectively decide whether you want to read the dynamical
 # matrix from the GULP output file or from the
 # FORCE_CONSTANTS_2ND file.

pyproject.toml

@@ -190,7 +190,7 @@ ignore-patterns = [
 extension-pkg-allow-list = [
    "sisl._math_small",
    "sisl._indices",
-   "sisl._supercell",
+   "sisl._lattice",
    "sisl.io.siesta._siesta",
    "sisl.physics._bloch",
    "sisl.physics._matrix_k",

setup.py

@@ -182,7 +182,7 @@ def run(self):
     "sisl._sparse": {
         "depends": [_ospath("sisl/_indices.pxd")]
     },
-    "sisl._supercell": {},
+    "sisl._lattice": {},
     "sisl.physics._bloch": {},
     "sisl.physics._phase": {},
     "sisl.physics._matrix_utils": {},

sisl/__init__.py

@@ -23,7 +23,7 @@
    AtomicOrbital
    Atoms
    Geometry
-   SuperCell
+   Lattice
    Grid
 
 Below are a group of advanced classes rarely needed.
@@ -107,7 +107,7 @@
 from .quaternion import *
 from .shape import *
 
-from .supercell import *
+from .lattice import *
 from .atom import *
 
 from .orbital import *

sisl/_typing.py

@@ -9,14 +9,14 @@
 #from typing import TYPE_CHECKING, final
 
 from sisl import (
-    Geometry, SuperCell,
+    Geometry, Lattice,
     Atom, Atoms
 )
 
 
-# A SuperCell or a Geometry
+# A Lattice or a Geometry
 CellOrGeometry = Union[
-    SuperCell,
+    Lattice,
     Geometry,
 ]
 

sisl/conftest.py

@@ -7,7 +7,7 @@
 
 from pathlib import Path
 import pytest
-from sisl import Atom, Geometry, SuperCell, Hamiltonian, _environ
+from sisl import Atom, Geometry, Lattice, Hamiltonian, _environ
 
 
 # Here we create the necessary methods and fixtures to enabled/disable
@@ -137,26 +137,26 @@ class System:
     alat = 1.42
     sq3h = 3.**.5 * 0.5
     C = Atom(Z=6, R=1.42)
-    sc = SuperCell(np.array([[1.5, sq3h, 0.],
-                             [1.5, -sq3h, 0.],
-                             [0., 0., 10.]], np.float64) * alat,
-                   nsc=[3, 3, 1])
+    lattice = Lattice(np.array([[1.5, sq3h, 0.],
+                                [1.5, -sq3h, 0.],
+                                [0., 0., 10.]], np.float64) * alat,
+                      nsc=[3, 3, 1])
     d.g = Geometry(np.array([[0., 0., 0.],
                              [1., 0., 0.]], np.float64) * alat,
-                   atoms=C, sc=sc)
+                   atoms=C, lattice=lattice)
 
     d.R = np.array([0.1, 1.5])
     d.t = np.array([0., 2.7])
     d.tS = np.array([(0., 1.0),
                      (2.7, 0.)])
     d.C = Atom(Z=6, R=max(d.R))
-    d.sc = SuperCell(np.array([[1.5, sq3h, 0.],
-                               [1.5, -sq3h, 0.],
-                               [0., 0., 10.]], np.float64) * alat,
-                     nsc=[3, 3, 1])
+    d.lattice = Lattice(np.array([[1.5, sq3h, 0.],
+                                  [1.5, -sq3h, 0.],
+                                  [0., 0., 10.]], np.float64) * alat,
+                        nsc=[3, 3, 1])
     d.gtb = Geometry(np.array([[0., 0., 0.],
                                [1., 0., 0.]], np.float64) * alat,
-                     atoms=C, sc=sc)
+                     atoms=C, lattice=lattice)
 
     d.ham = Hamiltonian(d.gtb)
     d.ham.construct([(0.1, 1.5), (0.1, 2.7)])
@@ -203,7 +203,7 @@ def pytest_configure(config):
     for mark in ['io', 'generic', 'bloch', 'hamiltonian', 'geometry', 'geom', 'shape',
                  'state', 'electron', 'phonon', 'utils', 'unit', 'distribution',
                  'spin', 'self_energy', 'help', 'messages', 'namedindex', 'sparse',
-                 'supercell', 'sc', 'quaternion', 'sparse_geometry', 'sparse_orbital',
+                 'lattice', 'supercell', 'sc', 'quaternion', 'sparse_geometry', 'sparse_orbital',
                  'ranges', 'physics', "physics_feature",
                  'orbital', 'oplist', 'grid', 'atoms', 'atom', 'sgrid', 'sdata', 'sgeom',
                  'version',

sisl/geom/basic.py

@@ -4,7 +4,7 @@
 import numpy as np
 
 from sisl._internal import set_module
-from sisl import Geometry, SuperCell
+from sisl import Geometry, Lattice
 from ._common import geometry_define_nsc, geometry2uc
 
 __all__ = ['sc', 'bcc', 'fcc', 'hcp', 'rocksalt']
@@ -32,10 +32,10 @@ def sc(alat, atom):
     atom : Atom
         the atom in the SC lattice
     """
-    sc = SuperCell(np.array([[1, 0, 0],
-                             [0, 1, 0],
-                             [0, 0, 1]], np.float64) * alat)
-    g = Geometry([0, 0, 0], atom, sc=sc)
+    lattice = Lattice(np.array([[1, 0, 0],
+                                [0, 1, 0],
+                                [0, 0, 1]], np.float64) * alat)
+    g = Geometry([0, 0, 0], atom, lattice=lattice)
     geometry_define_nsc(g)
     return g
 
@@ -54,16 +54,16 @@ def bcc(alat, atoms, orthogonal=False):
         whether the lattice is orthogonal (2 atoms)
     """
     if orthogonal:
-        sc = SuperCell(np.array([[1, 0, 0],
+        lattice = Lattice(np.array([[1, 0, 0],
                                  [0, 1, 0],
                                  [0, 0, 1]], np.float64) * alat)
         ah = alat / 2
-        g = Geometry([[0, 0, 0], [ah, ah, ah]], atoms, sc=sc)
+        g = Geometry([[0, 0, 0], [ah, ah, ah]], atoms, lattice=lattice)
     else:
-        sc = SuperCell(np.array([[-1, 1, 1],
+        lattice = Lattice(np.array([[-1, 1, 1],
                                  [1, -1, 1],
                                  [1, 1, -1]], np.float64) * alat / 2)
-        g = Geometry([0, 0, 0], atoms, sc=sc)
+        g = Geometry([0, 0, 0], atoms, lattice=lattice)
     geometry_define_nsc(g)
     return g
 
@@ -82,17 +82,17 @@ def fcc(alat, atoms, orthogonal=False):
         whether the lattice is orthogonal (4 atoms)
     """
     if orthogonal:
-        sc = SuperCell(np.array([[1, 0, 0],
+        lattice = Lattice(np.array([[1, 0, 0],
                                  [0, 1, 0],
                                  [0, 0, 1]], np.float64) * alat)
         ah = alat / 2
         g = Geometry([[0, 0, 0], [ah, ah, 0],
-                      [ah, 0, ah], [0, ah, ah]], atoms, sc=sc)
+                      [ah, 0, ah], [0, ah, ah]], atoms, lattice=lattice)
     else:
-        sc = SuperCell(np.array([[0, 1, 1],
+        lattice = Lattice(np.array([[0, 1, 1],
                                  [1, 0, 1],
                                  [1, 1, 0]], np.float64) * alat / 2)
-        g = Geometry([0, 0, 0], atoms, sc=sc)
+        g = Geometry([0, 0, 0], atoms, lattice=lattice)
     geometry_define_nsc(g)
     return g
 
@@ -116,26 +116,26 @@ def hcp(a, atoms, coa=1.63333, orthogonal=False):
     c = a * coa
     a3sq = a / 3 ** .5
     if orthogonal:
-        sc = SuperCell([[a + a * _c60 * 2, 0, 0],
+        lattice = Lattice([[a + a * _c60 * 2, 0, 0],
                         [0, a * _c30 * 2, 0],
                         [0, 0, c / 2]])
         gt = Geometry([[0, 0, 0],
                        [a, 0, 0],
                        [a * _s30, a * _c30, 0],
-                       [a * (1 + _s30), a * _c30, 0]], atoms, sc=sc)
+                       [a * (1 + _s30), a * _c30, 0]], atoms, lattice=lattice)
         # Create the rotated one on top
         gr = gt.copy()
         # mirror structure
-        gr.xyz[0, 1] += sc.cell[1, 1]
-        gr.xyz[1, 1] += sc.cell[1, 1]
+        gr.xyz[0, 1] += lattice.cell[1, 1]
+        gr.xyz[1, 1] += lattice.cell[1, 1]
         gr = gr.translate(-np.amin(gr.xyz, axis=0))
         # Now displace to get the correct offset
         gr = gr.translate([0, a * _s30 / 2, 0])
         g = gt.append(gr, 2)
     else:
-        sc = SuperCell([a, a, c, 90, 90, 60])
+        lattice = Lattice([a, a, c, 90, 90, 60])
         g = Geometry([[0, 0, 0], [a3sq * _c30, a3sq * _s30, c / 2]],
-                     atoms, sc=sc)
+                     atoms, lattice=lattice)
     geometry_define_nsc(g)
     return g