add warning to "continuum.sympify"; small improvment to "discretizer" docstrings

If "expr" is already a SymPy object and "locals" are provided the
RuntimeWarning will be triggered.

kwant/continuum/_common.py

@@ -18,8 +18,10 @@ import sympy.abc
 import sympy.physics.quantum
 from sympy.core.function import AppliedUndef
 from sympy.core.sympify import converter
+from sympy.core.core import all_classes as sympy_classes
 from sympy.physics.matrices import msigma as _msigma
 
+import warnings
 
 momentum_operators = sympy.symbols('k_x k_y k_z', commutative=False)
 position_operators = sympy.symbols('x y z', commutative=False)
@@ -82,7 +84,9 @@ def lambdify(expr, locals=None):
 def sympify(expr, locals=None):
     """Sympify object using special rules for Hamiltonians.
 
-    If ``expr`` is a SymPy object, it is returned unmodified.
+    If `'expr`` is already a type that SymPy understands, it will do nothing
+    but return that value. Note that ``locals`` will not be used in this
+    situation.
 
     Otherwise, it is sympified by ``sympy.sympify`` with a modified namespace
     such that
@@ -143,13 +147,18 @@ def sympify(expr, locals=None):
 
     """
     stored_value = None
-    sympified_types = (sympy.Expr, sympy.matrices.MatrixBase)
-    if locals is None:
-        locals = {}
 
-    if isinstance(expr, sympified_types):
+    # if ``expr`` is already a ``sympy`` object we may terminate a code path
+    if isinstance(expr, tuple(sympy_classes)):
+        if locals:
+            warnings.warn('Input expression is already SymPy object: ' +
+                          '"locals" will not be used.', RuntimeWarning)
         return expr
 
+    # if ``expr`` is not a "sympy" then we proceed with sympifying process
+    if locals is None:
+        locals = {}
+
     for k in locals:
         if (not isinstance(k, str)
             or not k.isidentifier() or keyword.iskeyword(k)):

kwant/continuum/discretizer.py

@@ -99,7 +99,7 @@ def discretize(hamiltonian, coords=None, *, grid_spacing=1,
 
     Parameters
     ----------
-    hamiltonian : str, or sympy.Expr, or sympy.Matrix
+    hamiltonian : str or SymPy expression
         Symbolic representation of a continuous Hamiltonian.  It is
         converted to a SymPy expression using `kwant.continuum.sympify`.
     coords : sequence of strings, or ``None`` (default)
@@ -118,7 +118,7 @@ def discretize(hamiltonian, coords=None, *, grid_spacing=1,
 
     Returns
     -------
-    model: `~kwant.builder.Builder`
+    model : `~kwant.builder.Builder`
         The translationally symmetric builder that corresponds to the provided
         Hamiltonian.
 
@@ -143,7 +143,7 @@ def discretize_symbolic(hamiltonian, coords=None, *, locals=None):
 
     Parameters
     ----------
-    hamiltonian : str, or sympy.Expr, or sympy.Matrix
+    hamiltonian : str or SymPy expression
         Symbolic representation of a continuous Hamiltonian.  It is
         converted to a SymPy expression using `kwant.continuum.sympify`.
     coords : sequence of strings, or ``None`` (default)