update argument names for keyword only and more explicit naming

kwant/physics/dispersion.py

@@ -36,7 +36,7 @@ class Bands:
     (currently this must be a scalar as all infinite systems are quasi-1-d), it
     returns a NumPy array containing the eigenenergies of all modes at this
     momentum. Velocities and velocity derivatives are calculated if the flag
-    ``deriv`` is set.
+    ``derivative_order`` is set.
 
     Examples
     --------
@@ -58,7 +58,7 @@ class Bands:
         self.hop[:, : hop.shape[1]] = hop
         self.hop[:, hop.shape[1]:] = 0
 
-    def __call__(self, k, deriv=0):
+    def __call__(self, k, *, derivative_order=0):
         """Calculate all energies :math:`E`, velocities :math:`v`
         and velocity derivatives `v'` for a given momentum :math:`k`
 
@@ -72,7 +72,7 @@ class Bands:
         k : float
             momentum
 
-        deriv : {0, 1, 2}, optional
+        derivative_order : {0, 1, 2}, optional
             Maximal derivative order to calculate. Default is zero
 
 
@@ -81,10 +81,10 @@ class Bands:
         ener : numpy float array
             energies (and optionally also higher momentum derivatives)
 
-            if deriv = 0
+            if derivative_order = 0
                 numpy float array of the energies :math:`E`, shape (nbands,)
-            if deriv > 0
-                numpy float array, shape (deriv + 1, nbands) of
+            if derivative_order > 0
+                numpy float array, shape (derivative_order + 1, nbands) of
                 energies and derivatives :math:`(E, E', E'')`
 
         Notes
@@ -101,14 +101,14 @@ class Bands:
 
         mat = self.hop * complex(math.cos(k), -math.sin(k))
         ham = mat + mat.conjugate().transpose() + self.ham
-        if deriv == 0:
+        if derivative_order == 0:
             return np.sort(np.linalg.eigvalsh(ham).real)
 
         ener, psis = np.linalg.eigh(ham)
         h1 = 1j*(- mat + mat.conjugate().transpose())
         ph1p = np.dot(psis.conjugate().transpose(), np.dot(h1, psis))
         velo = np.real(np.diag(ph1p))
-        if deriv == 1:
+        if derivative_order == 1:
             return np.array([ener, velo])
 
         ediff = ener.reshape(-1, 1) - ener.reshape(1, -1)
@@ -117,6 +117,7 @@ class Bands:
         curv = (np.real(np.diag(
                 np.dot(psis.conjugate().transpose(), np.dot(h2, psis)))) +
                 2 * np.sum(ediff * np.abs(ph1p)**2, axis=1))
-        if deriv == 2:
+        if derivative_order == 2:
             return np.array([ener, velo, curv])
-        raise NotImplementedError('deriv= {} not implemented'.format(deriv))
+        raise NotImplementedError('derivative_order= {} not implemented'
+                                  .format(derivative_order))

kwant/physics/tests/test_dispersion.py

@@ -62,7 +62,7 @@ def test_band_velocities():
     bands = kwant.physics.Bands(syst.finalized())
     eps = 1E-4
     for k in linspace(-pi, pi, 200):
-        vel = bands(k, deriv=1)[1]
+        vel = bands(k, derivative_order=1)[1]
         # higher order formula for first derivative to get required accuracy
         num_vel = (- bands(k+2*eps) + bands(k-2*eps) +
                    8*(bands(k+eps) - bands(k-eps))) / (12 * eps)
@@ -84,7 +84,7 @@ def test_band_velocity_derivative():
     c1 = 3 / 2
     c0 = - 49 / 18
     for k in linspace(-pi, pi, 200):
-        dvel = bands(k, deriv=2)[2]
+        dvel = bands(k, derivative_order=2)[2]
         # higher order formula for second derivative to get required accuracy
         num_dvel = (c3 * (bands(k+3*eps) + bands(k-3*eps)) +
                     c2 * (bands(k+2*eps) + bands(k-2*eps)) +
@@ -101,8 +101,8 @@ def test_raise_implemented():
     syst[((lat(1, y), lat(0, y)) for y in range(2))] = -1
     bands = kwant.physics.Bands(syst.finalized())
     assert bands(1.).shape == (2,)
-    assert bands(1., deriv=0).shape == (2,)
-    assert bands(1., deriv=1).shape == (2, 2)
-    assert bands(1., deriv=2).shape == (3, 2)
-    raises(NotImplementedError, bands, 1., -1)
-    raises(NotImplementedError, bands, 1., 3)
+    assert bands(1., derivative_order=0).shape == (2,)
+    assert bands(1., derivative_order=1).shape == (2, 2)
+    assert bands(1., derivative_order=2).shape == (3, 2)
+    raises(NotImplementedError, bands, 1., derivative_order=-1)
+    raises(NotImplementedError, bands, 1., derivative_order=3)