Commit 5fa767d1 by Joseph Weston

### Merge branch 'feature/deprecate-args' into 'master'

```Deprecate 'args' parameter in favor of 'params'

Closes #272

See merge request !280```
parents e9557cf7 d44ecee2
Pipeline #15424 passed with stages
in 42 minutes and 58 seconds
 ... ... @@ -143,7 +143,7 @@ normalized_fluxes = [flux / (2 * pi) for flux in fluxes] data = [] for flux in fluxes: smatrix = kwant.smatrix(syst, energy, args=[flux]) smatrix = kwant.smatrix(syst, energy, params=dict(phi=flux)) data.append(smatrix.transmission(1, 0)) - pyplot.figure() ... ...
 ... ... @@ -68,7 +68,7 @@ energies = [] for B in Bfields: # Obtain the Hamiltonian as a dense matrix ham_mat = syst.hamiltonian_submatrix(args=[B], sparse=True) ham_mat = syst.hamiltonian_submatrix(params=dict(B=B), sparse=True) # we only calculate the 15 lowest eigenvalues ev = sla.eigsh(ham_mat.tocsc(), k=15, sigma=0, ... ... @@ -105,7 +105,7 @@ + size = (_defs.figwidth_in, _defs.figwidth_in) + # Calculate the wave functions in the system. ham_mat = syst.hamiltonian_submatrix(sparse=True, args=[B]) ham_mat = syst.hamiltonian_submatrix(sparse=True, params=dict(B=B)) evals, evecs = sorted_eigs(sla.eigsh(ham_mat.tocsc(), k=20, sigma=0)) # Plot the probability density of the 10th eigenmode. ... ... @@ -124,12 +124,12 @@ + size = (_defs.figwidth_in, _defs.figwidth_in) + # Calculate the wave functions in the system. ham_mat = syst.hamiltonian_submatrix(sparse=True, args=[B]) ham_mat = syst.hamiltonian_submatrix(sparse=True, params=dict(B=B)) evals, evecs = sorted_eigs(sla.eigsh(ham_mat.tocsc(), k=20, sigma=0)) # Calculate and plot the local current of the 10th eigenmode. J = kwant.operator.Current(syst) current = J(evecs[:, 9], args=[B]) current = J(evecs[:, 9], params=dict(B=B)) - kwant.plotter.current(syst, current, colorbar=False) + for extension in ('pdf', 'png'): + kwant.plotter.current( ... ...
 ... ... @@ -59,7 +59,7 @@ # Compute conductance data = [] for welldepth in welldepths: smatrix = kwant.smatrix(syst, energy, args=[-welldepth]) smatrix = kwant.smatrix(syst, energy, params=dict(pot=-welldepth)) data.append(smatrix.transmission(1, 0)) - pyplot.figure() ... ...
 ... ... @@ -170,6 +170,27 @@ parameters that the system (and its leads) expects:: This is a provisional API that may be changed in a future version of Kwant. Passing system arguments via ``args`` is deprecated in favor of ``params`` -------------------------------------------------------------------------- It is now deprecated to pass arguments to systems by providing the ``args`` parameter (in ``kwant.smatrix`` and elsewhere). This is error prone and requires that all value functions take the same formal parameters, even if they do not depend on all of them. The preferred way of passing parameters to Kwant systems is by passing a dictionary using ``params``:: def onsite(site, magnetic_field, voltage): return magnetic_field * sigma_z + voltage * sigma_0 syst = make_system(onsite).finalized() kwant.smatrix(syst, params=dict(magnetic_field=0.5, voltage=0.2)) # Compare this to the deprecated 'args' kwant.smatrix(syst, args=(0.5, 0.2)) The ability to provide ``args`` will be removed in a future Kwant version. Interpolated density plots -------------------------- A new function `~kwant.plotter.density` has been added that can be used to ... ...
 ... ... @@ -160,9 +160,9 @@ energy eigenstates: .. image:: /code/figure/discretizer_gs.* Note in the above that we provided the function ``V`` to ``syst.hamiltonian_submatrix`` using ``params=dict(V=potential)``, rather than via ``args``. Note in the above that we pass the spatially varying potential *function* to our system via a parameter called ``V``, because the symbol \$V\$ was used in the intial, symbolic, definition of the Hamiltonian. In addition, the function passed as ``V`` expects two input parameters ``x`` and ``y``, the same as in the initial continuum Hamiltonian. ... ...
 ... ... @@ -184,10 +184,12 @@ Finally, we compute the transmission probability: :start-after: #HIDDEN_BEGIN_sqvr :end-before: #HIDDEN_END_sqvr ``kwant.smatrix`` allows us to specify a list, `args`, that will be passed as additional arguments to the functions that provide the Hamiltonian matrix elements. In this example we are able to solve the system for different depths of the potential well by passing the potential value. We obtain the result: ``kwant.smatrix`` allows us to specify a dictionary, `params`, that contains the additional arguments required by the Hamiltonian matrix elements. In this example we are able to solve the system for different depths of the potential well by passing the potential value (remember above we defined our `onsite` function that takes a parameter named `pot`). We obtain the result: .. image:: /code/figure/quantum_well_result.* ... ...
 ... ... @@ -12,6 +12,7 @@ import numbers import inspect import warnings import importlib import functools from contextlib import contextmanager __all__ = ['KwantDeprecationWarning', 'UserCodeError'] ... ... @@ -41,6 +42,46 @@ class UserCodeError(Exception): pass def deprecate_parameter(parameter_name, version=None, help=None, stacklevel=3): """Trigger a deprecation warning if the wrapped function is called with the provided parameter.""" message = ("The '{}' parameter has been deprecated since version {} -- {}" .format(parameter_name, version, help)) def warn(): warnings.warn(message, KwantDeprecationWarning, stacklevel=stacklevel) def wrapper(f=None): # Instead of being used as a decorator, can be called with # no arguments to just raise the warning. if f is None: warn() return sig = inspect.signature(f) @functools.wraps(f) def inner(*args, **kwargs): # If the named argument is truthy if sig.bind(*args, **kwargs).arguments.get(parameter_name): warn() return f(*args, **kwargs) return inner return wrapper # Deprecation for 'args' parameter; defined once to minimize boilerplate, # as this parameter is present all over Kwant. deprecate_args = deprecate_parameter('args', version=1.4, help= "Instead, provide named parameters as a dictionary via 'params'.") def interleave(seq): """Return an iterator that yields pairs of elements from a sequence. ... ...
 ... ... @@ -16,6 +16,7 @@ import types from .graph.core cimport CGraph, gintArraySlice from .graph.defs cimport gint from .graph.defs import gint_dtype from ._common import deprecate_args msg = ('Hopping from site {0} to site {1} does not match the ' 'dimensions of onsite Hamiltonians of these sites.') ... ... @@ -253,6 +254,7 @@ def _check_parameters_match(expected_parameters, params): raise TypeError(''.join(msg)) @deprecate_args @cython.binding(True) @cython.embedsignature(True) def hamiltonian_submatrix(self, args=(), to_sites=None, from_sites=None, ... ...
 ... ... @@ -22,7 +22,7 @@ from .linalg import lll from .operator import Density from .physics import DiscreteSymmetry from ._common import (ensure_isinstance, get_parameters, reraise_warnings, interleave) interleave, deprecate_args) __all__ = ['Builder', 'Site', 'SiteFamily', 'SimpleSiteFamily', 'Symmetry', ... ... @@ -617,6 +617,7 @@ def _ensure_signature(func): return func # function conforming to old API: needs wrapping @deprecate_args def wrapper(energy, args=(), *, params=None): return func(energy, args) ... ... @@ -647,6 +648,7 @@ class SelfEnergyLead(Lead): """Trivial finalization: the object is returned itself.""" return self @deprecate_args def selfenergy(self, energy, args=(), *, params=None): return self.selfenergy_func(energy, args, params=params) ... ... @@ -677,9 +679,11 @@ class ModesLead(Lead): """Trivial finalization: the object is returned itself.""" return self @deprecate_args def modes(self, energy, args=(), *, params=None): return self.modes_func(energy, args, params=params) @deprecate_args def selfenergy(self, energy, args=(), *, params=None): stabilized = self.modes(energy, args, params=params)[1] return stabilized.selfenergy() ... ... @@ -1894,6 +1898,7 @@ class _FinalizedBuilderMixin: value = herm_conj(value) return value @deprecate_args def discrete_symmetry(self, args=(), *, params=None): if self._cons_law is not None: eigvals, eigvecs = self._cons_law ... ...
 ... ... @@ -24,7 +24,7 @@ from .graph.core cimport EdgeIterator from .graph.defs cimport gint from .graph.defs import gint_dtype from .system import InfiniteSystem from ._common import UserCodeError, get_parameters from ._common import UserCodeError, get_parameters, deprecate_args ################ Generic Utility functions ... ... @@ -499,7 +499,7 @@ cdef class _LocalOperator: args : tuple, optional The arguments to pass to the system. Used to evaluate the ``onsite`` elements and, possibly, the system Hamiltonian. Mutually exclusive with 'params'. Deprecated in favor of 'params' (and mutually exclusive with it). params : dict, optional Dictionary of parameter names and their values. Mutually exclusive with 'args'. ... ... @@ -514,6 +514,11 @@ cdef class _LocalOperator: raise ValueError("Extra arguments are already bound to this " "operator. You should call this operator " "providing neither 'args' nor 'params'.") if args: # deprecate_args does not play nicely with methods of cdef classes, # when used as a decorator, so we manually raise the # deprecation warning here. deprecate_args() if args and params: raise TypeError("'args' and 'params' are mutually exclusive.") if bra is None: ... ... @@ -555,7 +560,8 @@ cdef class _LocalOperator: Wavefunctions defined over all the orbitals of the system. args : tuple The extra arguments to the Hamiltonian value functions and the operator ``onsite`` function. Mutually exclusive with 'params'. the operator ``onsite`` function. Deprecated in favor of 'params' (and mutually exclusive with it). params : dict, optional Dictionary of parameter names and their values. Mutually exclusive with 'args'. ... ... @@ -568,6 +574,11 @@ cdef class _LocalOperator: raise ValueError("Extra arguments are already bound to this " "operator. You should call this operator " "providing neither 'args' nor 'params'.") if args: # deprecate_args does not play nicely with methods of cdef classes, # when used as a decorator, so we manually raise the # deprecation warning here. deprecate_args() if args and params: raise TypeError("'args' and 'params' are mutually exclusive.") ... ... @@ -588,7 +599,15 @@ cdef class _LocalOperator: Returns a copy of this operator that does not need to be passed extra arguments when subsequently called or when using the ``act`` method. Providing positional arguments via 'args' is deprecated, instead provide named parameters as a dictionary via 'params'. """ if args: # deprecate_args does not play nicely with methods of cdef classes, # when used as a decorator, so we manually raise the # deprecation warning here. deprecate_args() if args and params: raise TypeError("'args' and 'params' are mutually exclusive.") # generic creation of new instance ... ... @@ -621,7 +640,8 @@ cdef class _LocalOperator: If `op` is `ACT` then `bra` is None. args : tuple The extra arguments to the Hamiltonian value functions and the operator ``onsite`` function. Mutually exclusive with 'params'. the operator ``onsite`` function. Deprecated in favor of 'params' (and mutually exclusive with it). op : operation The operation to perform. `MAT_ELS`: calculate matrix elements between `bra` and `ket` ... ... @@ -786,7 +806,11 @@ cdef class Density(_LocalOperator): @cython.cdivision(True) @cython.embedsignature def tocoo(self, args=(), *, params=None): """Convert the operator to coordinate format sparse matrix.""" """Convert the operator to coordinate format sparse matrix. Providing positional arguments via 'args' is deprecated, instead provide named parameters as a dictionary via 'params'. """ cdef int blk, blk_size, n_blocks, n, k = 0 cdef int [:, :] offsets, shapes cdef int [:] row, col ... ... @@ -794,6 +818,11 @@ cdef class Density(_LocalOperator): raise ValueError("Extra arguments are already bound to this " "operator. You should call this operator " "providing neither 'args' nor 'params'.") if args: # deprecate_args does not play nicely with methods of cdef classes, # when used as a decorator, so we manually raise the # deprecation warning here. deprecate_args() if args and params: raise TypeError("'args' and 'params' are mutually exclusive.") ... ... @@ -887,6 +916,9 @@ cdef class Current(_LocalOperator): Returns a copy of this operator that does not need to be passed extra arguments when subsequently called or when using the ``act`` method. Providing positional arguments via 'args' is deprecated, instead provide named parameters as a dictionary via 'params'. """ q = super().bind(args, params=params) q._bound_hamiltonian = self._eval_hamiltonian(args, params) ... ... @@ -1012,6 +1044,9 @@ cdef class Source(_LocalOperator): Returns a copy of this operator that does not need to be passed extra arguments when subsequently called or when using the ``act`` method. Providing positional arguments via 'args' is deprecated, instead provide named parameters as a dictionary via 'params'. """ q = super().bind(args, params=params) q._bound_hamiltonian = self._eval_hamiltonian(args, params) ... ...
 ... ... @@ -11,7 +11,7 @@ import math import numpy as np from .. import system from .._common import ensure_isinstance from .._common import ensure_isinstance, deprecate_args __all__ = ['Bands'] ... ... @@ -27,7 +27,7 @@ class Bands: calculated. args : tuple, defaults to empty Positional arguments to pass to the ``hamiltonian`` method. Mutually exclusive with 'params'. Deprecated in favor or 'params' (and mutually exclusive with it). params : dict, optional Dictionary of parameter names and their values. Mutually exclusive with 'args'. ... ... @@ -50,6 +50,7 @@ class Bands: """ _crossover_size = 8 @deprecate_args def __init__(self, sys, args=(), *, params=None): syst = sys ensure_isinstance(syst, system.InfiniteSystem) ... ...
 ... ... @@ -27,6 +27,7 @@ from scipy import spatial, interpolate from math import cos, sin, pi, sqrt from . import system, builder, _common from ._common import deprecate_args __all__ = ['plot', 'map', 'bands', 'spectrum', 'current', 'density', ... ... @@ -1348,6 +1349,7 @@ def map(sys, value, colorbar=True, cmap=None, vmin=None, vmax=None, a=None, return fig @deprecate_args def bands(sys, args=(), momenta=65, file=None, show=True, dpi=None, fig_size=None, ax=None, *, params=None): """Plot band structure of a translationally invariant 1D system. ... ... @@ -1358,7 +1360,7 @@ def bands(sys, args=(), momenta=65, file=None, show=True, dpi=None, A system bands of which are to be plotted. args : tuple, defaults to empty Positional arguments to pass to the ``hamiltonian`` method. Mutally exclusive with 'params'. Deprecated in favor of 'params' (and mutually exclusive with it). momenta : int or 1D array-like Either a number of sampling points on the interval [-pi, pi], or an array of points at which the band structure has to be evaluated. ... ...