From 946e3fc9022808499d71c5d2175ae6f2afc58385 Mon Sep 17 00:00:00 2001
From: Christoph Groth <christoph.groth@cea.fr>
Date: Tue, 27 Aug 2013 10:01:17 +0200
Subject: [PATCH] move the modules from kwant.contrib into the top level
 namespace; get rid of contrib

---
 TODO                                  |  2 +-
 doc/source/contrib/digest.rst         |  5 -----
 doc/source/contrib/index.rst          | 20 --------------------
 doc/source/contrib/rmt.rst            |  5 -----
 doc/source/index.rst                  | 17 -----------------
 doc/source/reference/index.rst        | 18 ++++++++++++++++--
 doc/source/reference/kwant.digest.rst |  5 +++++
 doc/source/reference/kwant.rmt.rst    |  5 +++++
 doc/source/whatsnew/1.0.rst           | 17 +++++++++++++----
 kwant/__init__.py                     |  3 ++-
 kwant/contrib/__init__.py             | 13 -------------
 kwant/contrib/tests/__init__.py       |  0
 kwant/{contrib => }/digest.py         | 14 +++++++-------
 kwant/{contrib => }/rmt.py            |  0
 kwant/tests/test_comprehensive.py     |  3 +--
 kwant/{contrib => }/tests/test_rmt.py |  2 +-
 16 files changed, 51 insertions(+), 78 deletions(-)
 delete mode 100644 doc/source/contrib/digest.rst
 delete mode 100644 doc/source/contrib/index.rst
 delete mode 100644 doc/source/contrib/rmt.rst
 create mode 100644 doc/source/reference/kwant.digest.rst
 create mode 100644 doc/source/reference/kwant.rmt.rst
 delete mode 100644 kwant/contrib/__init__.py
 delete mode 100644 kwant/contrib/tests/__init__.py
 rename kwant/{contrib => }/digest.py (89%)
 rename kwant/{contrib => }/rmt.py (100%)
 rename kwant/{contrib => }/tests/test_rmt.py (99%)

diff --git a/TODO b/TODO
index e815e85..b9a4746 100644
--- a/TODO
+++ b/TODO
@@ -99,7 +99,7 @@ Roughly in order of importance.                                     -*-org-*-
 * Adopt mincut/maxflow algorithm from networkx or python-graph to find the best
   representation of a lead unit cell.
 
-* Speed up kwant.contrib.digest
+* Speed up kwant.digest
   by using SipHash and Ziggurat algorithm in C/Cython
 
 * Improve finding of modes with zero velocity or infinite decay length
diff --git a/doc/source/contrib/digest.rst b/doc/source/contrib/digest.rst
deleted file mode 100644
index ee3460b..0000000
--- a/doc/source/contrib/digest.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-:mod:`kwant.contrib.digest` -- Random-access random numbers
-===========================================================
-
-.. automodule:: kwant.contrib.digest
-   :members:
diff --git a/doc/source/contrib/index.rst b/doc/source/contrib/index.rst
deleted file mode 100644
index 67c11ab..0000000
--- a/doc/source/contrib/index.rst
+++ /dev/null
@@ -1,20 +0,0 @@
-Contributed modules
-===================
-
-.. module:: kwant.contrib
-
-:mod:`kwant.contrib` is a collection of independent modules that is part of the
-official Kwant distribution, but is not considered to be an integral part of
-Kwant.  The intention is to keep interesting modules that are useful with Kwant
-here (maybe even experimental ones) to give users an easier access to them, and
-them wider exposure.  Users of Kwant are welcome to submit their own modules for
-inclusion.
-
-For simplicity, all contributions share the same license as Kwant.  (This
-requirement may be relaxed to allow other free licenses if requested.)
-
-.. toctree::
-   :maxdepth: 1
-
-   digest
-   rmt
diff --git a/doc/source/contrib/rmt.rst b/doc/source/contrib/rmt.rst
deleted file mode 100644
index 929b791..0000000
--- a/doc/source/contrib/rmt.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-:mod:`kwant.contrib.rmt` -- RMT (random matrix theory) Hamiltonians
-===================================================================
-
-.. automodule:: kwant.contrib.rmt
-   :members:
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 270cbde..d0bf73f 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -17,26 +17,9 @@ that have developed it <authors>`.
    license
    authors
    acknowledgements
-
-.. toctree::
-   :maxdepth: 1
-
    whatsnew/index
    install
-
-.. toctree::
-   :maxdepth: 2
-
    tutorial/index
-
-.. toctree::
-   :maxdepth: 2
-
    reference/index
 
-.. toctree::
-   :maxdepth: 2
-
-   contrib/index
-
 * :ref:`genindex`
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
index 1c54208..95fdcf4 100644
--- a/doc/source/reference/index.rst
+++ b/doc/source/reference/index.rst
@@ -1,8 +1,8 @@
 Reference guide
 ===============
 
-In the following, all Kwant modules appear in the order of decreasing end-user
-relevance.
+Core modules of Kwant, appearing in the order of decreasing
+end-user relevance.
 
 .. toctree::
    :maxdepth: 1
@@ -14,5 +14,19 @@ relevance.
    kwant.solvers
    kwant.physics
    kwant.system
+
+Miscellaneous modules for special applications.
+
+.. toctree::
+   :maxdepth: 1
+
+   kwant.digest
+   kwant.rmt
+
+Modules mainly for internal use.
+
+.. toctree::
+   :maxdepth: 1
+
    kwant.graph
    kwant.linalg
diff --git a/doc/source/reference/kwant.digest.rst b/doc/source/reference/kwant.digest.rst
new file mode 100644
index 0000000..ae9a724
--- /dev/null
+++ b/doc/source/reference/kwant.digest.rst
@@ -0,0 +1,5 @@
+:mod:`kwant.digest` -- Random-access random numbers
+===================================================
+
+.. automodule:: kwant.digest
+   :members:
diff --git a/doc/source/reference/kwant.rmt.rst b/doc/source/reference/kwant.rmt.rst
new file mode 100644
index 0000000..eb94c20
--- /dev/null
+++ b/doc/source/reference/kwant.rmt.rst
@@ -0,0 +1,5 @@
+:mod:`kwant.rmt` -- Random matrix theory Hamiltonians
+=====================================================
+
+.. automodule:: kwant.rmt
+   :members:
diff --git a/doc/source/whatsnew/1.0.rst b/doc/source/whatsnew/1.0.rst
index c9a3bc6..15bbde1 100644
--- a/doc/source/whatsnew/1.0.rst
+++ b/doc/source/whatsnew/1.0.rst
@@ -179,10 +179,19 @@ the `lead_info` attribute of `~kwant.solvers.common.SMatrix` contains the
 real space information about the modes in the leads (a list of
 `~kwant.physics.PropagatingModes` objects).
 
-Inclusion of contributed modules
---------------------------------
-Kwant now contains a sub-package :mod:`kwant.contrib` that contains various
-modules that are useful with Kwant but are not considered to be part of it.
+New module for random-access random numbers
+-------------------------------------------
+The module `kwant.digest` provides functions that given some input compute a
+"random" output that depends on the input in a (cryptographically) intractable
+way.  This functionality is useful for introducing disorder, e.g.::
+
+    def onsite(site):
+        return 0.3 * kwant.digest.gauss(repr(site)) + 4
+
+New module for random matrix theory Hamiltonians
+------------------------------------------------
+The module `kwant.rmt` supports the creation of random matrix theory
+Hamiltonians.
 
 Improved plotting functionality
 -------------------------------
diff --git a/kwant/__init__.py b/kwant/__init__.py
index ad89ef0..fbd14a0 100644
--- a/kwant/__init__.py
+++ b/kwant/__init__.py
@@ -6,7 +6,8 @@
 # the AUTHORS file at the top-level directory of this distribution and at
 # http://kwant-project.org/authors.
 
-__all__ = ['system', 'version', 'builder', 'lattice', 'solvers']
+__all__ = ['system', 'version', 'builder', 'lattice', 'solvers',
+           'digest', 'rmt']
 for module in __all__:
     exec 'from . import {0}'.format(module)
 
diff --git a/kwant/contrib/__init__.py b/kwant/contrib/__init__.py
deleted file mode 100644
index ac63bbc..0000000
--- a/kwant/contrib/__init__.py
+++ /dev/null
@@ -1,13 +0,0 @@
-# Copyright 2011-2013 Kwant authors.
-#
-# This file is part of Kwant.  It is subject to the license terms in the
-# LICENSE file found in the top-level directory of this distribution and at
-# http://kwant-project.org/license.  A list of Kwant authors can be found in
-# the AUTHORS file at the top-level directory of this distribution and at
-# http://kwant-project.org/authors.
-
-"""This package contains various sub-packages that are useful with Kwant, but
-are not considered to be a part of it.
-
-The sub-packages have to be imported explicitly.
-"""
diff --git a/kwant/contrib/tests/__init__.py b/kwant/contrib/tests/__init__.py
deleted file mode 100644
index e69de29..0000000
diff --git a/kwant/contrib/digest.py b/kwant/digest.py
similarity index 89%
rename from kwant/contrib/digest.py
rename to kwant/digest.py
index ef338a4..014ec63 100644
--- a/kwant/contrib/digest.py
+++ b/kwant/digest.py
@@ -25,7 +25,7 @@ from math import pi, log, sqrt, sin, cos
 from hashlib import md5
 from struct import unpack
 
-__all__ = ['digest', 'gauss', 'test']
+__all__ = ['uniform', 'gauss', 'test']
 
 
 TWOPI = 2 * pi
@@ -34,7 +34,7 @@ BPF_MASK = 2**53 - 1
 RECIP_BPF = 2**-BPF
 
 
-def digest2(input, salt=''):
+def uniform2(input, salt=''):
     """Return two independent [0,1)-distributed numbers."""
     input = memoryview(input).tobytes() + salt
     a, b = unpack('qq', md5(input).digest())
@@ -43,13 +43,13 @@ def digest2(input, salt=''):
     return a * RECIP_BPF, b * RECIP_BPF
 
 
-def digest(input, salt=''):
+def uniform(input, salt=''):
     """md5-hash `input` and `salt` and map the result to the [0,1) interval.
 
     `input` must be some object that supports the buffer protocol (i.e. a string
     or a numpy/tinyarray array).  `salt` must be a string or a bytes object.
     """
-    return digest2(input, salt)[0]
+    return uniform2(input, salt)[0]
 
 
 def gauss(input, salt=''):
@@ -61,12 +61,12 @@ def gauss(input, salt=''):
     """
     # This uses the Box-Muller transform.  Only one of the two results is
     # computed.
-    a, b = digest2(input, salt)
+    a, b = uniform2(input, salt)
     return cos(a * TWOPI) * sqrt(-2.0 * log(1.0 - b))
 
 
 def test(n=20000):
-    """Test func with the dieharder suite generating n**2 samples.
+    """Test the generator with the dieharder suite generating n**2 samples.
 
     Executing this function may take a very long time.
     """
@@ -81,7 +81,7 @@ def test(n=20000):
         for x in xrange(n):
             for y in xrange(n):
                 a = array((x, y))
-                i = int(2**32 * digest(a))
+                i = int(2**32 * uniform(a))
                 f.write(pack('I', i))
         f.close()
         subprocess.call(['dieharder', '-a', '-g', '201', '-f', f.name])
diff --git a/kwant/contrib/rmt.py b/kwant/rmt.py
similarity index 100%
rename from kwant/contrib/rmt.py
rename to kwant/rmt.py
diff --git a/kwant/tests/test_comprehensive.py b/kwant/tests/test_comprehensive.py
index 55494f2..8a6f39b 100644
--- a/kwant/tests/test_comprehensive.py
+++ b/kwant/tests/test_comprehensive.py
@@ -1,7 +1,6 @@
 import math
 from cmath import exp
 import kwant
-from kwant.contrib.digest import gauss
 
 
 def hopping(sitei, sitej, phi, salt):
@@ -11,7 +10,7 @@ def hopping(sitei, sitej, phi, salt):
 
 
 def onsite(site, phi, salt):
-    return 0.3 * gauss(repr(site), salt) + 4
+    return 0.3 * kwant.digest.gauss(repr(site), salt) + 4
 
 
 def test_qhe(W=16, L=8):
diff --git a/kwant/contrib/tests/test_rmt.py b/kwant/tests/test_rmt.py
similarity index 99%
rename from kwant/contrib/tests/test_rmt.py
rename to kwant/tests/test_rmt.py
index 8cc0bcc..87ef04f 100644
--- a/kwant/contrib/tests/test_rmt.py
+++ b/kwant/tests/test_rmt.py
@@ -9,7 +9,7 @@
 import numpy as np
 from scipy import stats
 from nose.tools import assert_raises
-from kwant.contrib import rmt
+from kwant import rmt
 assert_allclose = np.testing.assert_allclose
 
 
-- 
GitLab