Skip to content

kwant
kwant
Commit 0cc83115 authored by Joseph Weston's avatar Joseph Weston
Browse files
Options

apply deprecation decorator to all functions that take 'args' 

Additionally update all associated docstrings to say that 'args'
is deprecated in favor of 'params'.
parent da67ff86
Hide whitespace changes
Inline Side-by-side
Showing with 109 additions and 22 deletions
kwant/_system.pyx
View file @ 0cc83115
......@@ -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,
......
kwant/builder.py
View file @ 0cc83115
......@@ -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
......
kwant/operator.pyx
View file @ 0cc83115
......@@ -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)
......
kwant/physics/dispersion.py
View file @ 0cc83115
......@@ -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)
......
kwant/plotter.py
View file @ 0cc83115
......@@ -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.
......
kwant/solvers/common.py
View file @ 0cc83115
......@@ -14,7 +14,7 @@ import abc
from numbers import Integral
import numpy as np
import scipy.sparse as sp
from .._common import ensure_isinstance
from .._common import ensure_isinstance, deprecate_args
from .. import system
from functools import reduce
......@@ -113,7 +113,7 @@ class SparseSolver(metaclass=abc.ABCMeta):
Excitation energy at which to solve the scattering problem.
args : tuple, defaults to empty
Positional arguments to pass to the ``hamiltonian`` method.
Mutually exclusive with 'params'.
Deprecated in favor of 'params' (and mutually exclusive with it).
check_hermiticity : bool
Check if Hamiltonian matrices are in fact Hermitian.
Enables deduction of missing transmission coefficients.
......@@ -296,6 +296,7 @@ class SparseSolver(metaclass=abc.ABCMeta):
return LinearSys(lhs, rhs, indices, num_orb), lead_info
@deprecate_args
def smatrix(self, sys, energy=0, args=(),
out_leads=None, in_leads=None, check_hermiticity=True,
*, params=None):
......@@ -313,7 +314,7 @@ class SparseSolver(metaclass=abc.ABCMeta):
Excitation energy at which to solve the scattering problem.
args : tuple, defaults to empty
Positional arguments to pass to the ``hamiltonian`` method.
Mutually exclusive with 'params'.
Deprecated in favor of 'params' (and mutually exclusive with it).
out_leads : sequence of integers or ``None``
Numbers of leads where current or wave function is extracted. None
is interpreted as all leads. Default is ``None`` and means "all
......@@ -390,6 +391,7 @@ class SparseSolver(metaclass=abc.ABCMeta):
return SMatrix(data, lead_info, out_leads, in_leads, check_hermiticity)
@deprecate_args
def greens_function(self, sys, energy=0, args=(),
out_leads=None, in_leads=None, check_hermiticity=True,
*, params=None):
......@@ -407,7 +409,7 @@ class SparseSolver(metaclass=abc.ABCMeta):
Excitation energy at which to solve the scattering problem.
args : tuple, defaults to empty
Positional arguments to pass to the ``hamiltonian`` method.
Mutually exclusive with 'params'.
Deprecated in favor of 'params' (and mutually exclusive with it).
out_leads : sequence of integers or ``None``
Numbers of leads where current or wave function is extracted. None
is interpreted as all leads. Default is ``None`` and means "all
......@@ -488,6 +490,7 @@ class SparseSolver(metaclass=abc.ABCMeta):
return GreensFunction(data, lead_info, out_leads, in_leads,
check_hermiticity)
@deprecate_args
def ldos(self, sys, energy=0, args=(), check_hermiticity=True,
*, params=None):
"""
......@@ -504,8 +507,8 @@ class SparseSolver(metaclass=abc.ABCMeta):
Excitation energy at which to solve the scattering problem.
args : tuple of arguments, or empty tuple
Positional arguments to pass to the function(s) which
evaluate the hamiltonian matrix elements. Mutually exclusive
with 'params'.
evaluate the hamiltonian matrix elements.
Deprecated in favor of 'params' (and mutually exclusive with it).
check_hermiticity : ``bool``
Check if the Hamiltonian matrices are Hermitian.
params : dict, optional
......@@ -553,6 +556,7 @@ class SparseSolver(metaclass=abc.ABCMeta):
return ldos * (0.5 / np.pi)
@deprecate_args
def wave_function(self, sys, energy=0, args=(), check_hermiticity=True,
*, params=None):
r"""
......@@ -568,8 +572,8 @@ class SparseSolver(metaclass=abc.ABCMeta):
calculated.
args : tuple of arguments, or empty tuple
Positional arguments to pass to the function(s) which
evaluate the hamiltonian matrix elements. Mutually exclusive
with 'params'.
evaluate the hamiltonian matrix elements.
Deprecated in favor of 'params' (and mutually exclusive with it).
check_hermiticity : ``bool``
Check if the Hamiltonian matrices are Hermitian.
params : dict, optional
......
kwant/system.py
View file @ 0cc83115
......@@ -14,6 +14,7 @@ import abc
import warnings
from copy import copy
from . import _system
from ._common import deprecate_args
class System(metaclass=abc.ABCMeta):
......@@ -59,12 +60,20 @@ class System(metaclass=abc.ABCMeta):
if ``i != j``, return the hopping between site ``i`` and ``j``.
Hamiltonians may depend (optionally) on positional and
keyword arguments
keyword arguments.
Providing positional arguments via 'args' is deprecated,
instead, provide named parameters as a dictionary via 'params'.
"""
pass
@deprecate_args
def discrete_symmetry(self, args, *, params=None):
"""Return the discrete symmetry of the system."""
"""Return the discrete symmetry of the system.
Providing positional arguments via 'args' is deprecated,
instead, provide named parameters as a dictionary via 'params'.
"""
# Avoid the circular import.
from .physics import DiscreteSymmetry
return DiscreteSymmetry()
......@@ -131,6 +140,7 @@ class FiniteSystem(System, metaclass=abc.ABCMeta):
"""
@deprecate_args
def precalculate(self, energy=0, args=(), leads=None,
what='modes', *, params=None):
"""
......@@ -147,7 +157,7 @@ class FiniteSystem(System, metaclass=abc.ABCMeta):
evaluated.
args : sequence
Additional parameters required for calculating the Hamiltionians.
Mutually exclusive with 'params'.
Deprecated in favor of 'params' (and mutually exclusive with it).
leads : sequence of integers or None
Numbers of the leads to be precalculated. If ``None``, all are
precalculated.
......@@ -194,12 +204,16 @@ class FiniteSystem(System, metaclass=abc.ABCMeta):
result.leads = new_leads
return result
@deprecate_args
def validate_symmetries(self, args=(), *, params=None):
"""Check that the Hamiltonian satisfies discrete symmetries.
Applies `~kwant.physics.DiscreteSymmetry.validate` to the
Hamiltonian, see its documentation for details on the return
format.
Providing positional arguments via 'args' is deprecated,
instead, provide named parameters as a dictionary via 'params'.
"""
symmetries = self.discrete_symmetry(args=args, params=params)
ham = self.hamiltonian_submatrix(args, sparse=True, params=params)
......@@ -248,19 +262,30 @@ class InfiniteSystem(System, metaclass=abc.ABCMeta):
exchanged, as well as of site 3 and 4.
"""
@deprecate_args
def cell_hamiltonian(self, args=(), sparse=False, *, params=None):
"""Hamiltonian of a single cell of the infinite system."""
"""Hamiltonian of a single cell of the infinite system.
Providing positional arguments via 'args' is deprecated,
instead, provide named parameters as a dictionary via 'params'.
"""
cell_sites = range(self.cell_size)
return self.hamiltonian_submatrix(args, cell_sites, cell_sites,
sparse=sparse, params=params)
@deprecate_args
def inter_cell_hopping(self, args=(), sparse=False, *, params=None):
"""Hopping Hamiltonian between two cells of the infinite system."""
"""Hopping Hamiltonian between two cells of the infinite system.
Providing positional arguments via 'args' is deprecated,
instead, provide named parameters as a dictionary via 'params'.
"""
cell_sites = range(self.cell_size)
interface_sites = range(self.cell_size, self.graph.num_nodes)
return self.hamiltonian_submatrix(args, cell_sites, interface_sites,
sparse=sparse, params=params)
@deprecate_args
def modes(self, energy=0, args=(), *, params=None):
"""Return mode decomposition of the lead
......@@ -272,6 +297,9 @@ class InfiniteSystem(System, metaclass=abc.ABCMeta):
freedom on the first ``cell_sites`` sites of the system
(recall that infinite systems store first the sites in the unit
cell, then connected sites in the neighboring unit cell).
Providing positional arguments via 'args' is deprecated,
instead, provide named parameters as a dictionary via 'params'.
"""
from . import physics # Putting this here avoids a circular import.
ham = self.cell_hamiltonian(args, params=params)
......@@ -301,12 +329,16 @@ class InfiniteSystem(System, metaclass=abc.ABCMeta):
symmetries.particle_hole = symmetries.chiral = None
return physics.modes(ham, hop, discrete_symmetry=symmetries)
@deprecate_args
def selfenergy(self, energy=0, args=(), *, params=None):
"""Return self-energy of a lead.
The returned matrix has the shape (s, s), where s is
``sum(len(self.hamiltonian(i, i)) for i in range(self.graph.num_nodes -
self.cell_size))``.
Providing positional arguments via 'args' is deprecated,
instead, provide named parameters as a dictionary via 'params'.
"""
from . import physics # Putting this here avoids a circular import.
ham = self.cell_hamiltonian(args, params=params)
......@@ -318,12 +350,16 @@ class InfiniteSystem(System, metaclass=abc.ABCMeta):
return physics.selfenergy(ham,
self.inter_cell_hopping(args, params=params))
@deprecate_args
def validate_symmetries(self, args=(), *, params=None):
"""Check that the Hamiltonian satisfies discrete symmetries.
Returns `~kwant.physics.DiscreteSymmetry.validate` applied
to the onsite matrix and the hopping. See its documentation for
details on the return format.
Providing positional arguments via 'args' is deprecated,
instead, provide named parameters as a dictionary via 'params'.
"""
symmetries = self.discrete_symmetry(args=args, params=params)
ham = self.cell_hamiltonian(args=args, sparse=True, params=params)
......@@ -355,6 +391,7 @@ class PrecalculatedLead:
# is no parametric dependence anymore
self.parameters = frozenset()
@deprecate_args
def modes(self, energy=0, args=(), *, params=None):
if self._modes is not None:
return self._modes
......@@ -363,6 +400,7 @@ class PrecalculatedLead:
"Consider using precalculate() with "
"what='modes' or what='all'")
@deprecate_args
def selfenergy(self, energy=0, args=(), *, params=None):
if self._selfenergy is not None:
return self._selfenergy
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment