Verified Commit 40564545 authored by Adel Kara Slimane's avatar Adel Kara Slimane
Browse files

Add Python 3 type hinting and improve docstring typing

parent 5d014322
......@@ -9,6 +9,8 @@ import kwant
import tkwant
import numpy as np
from typing import Union, Iterable, Tuple, List, Callable, Optional, Sequence, Dict
from kwant.graph.defs import gint_dtype
from kwant.graph.defs cimport gint
......@@ -40,15 +42,15 @@ class EnergySiteValidator:
syst : `~kwant.system.FiniteSystem`
The finalized system for which sites/hoppings are checked.
interface_site_ids : :py:class:`list` of :py:class:`int`
interface_site_ids : list[int]
List of all lead-interface sites
interface_site_and_neighbors_ids : :py:class:`list` of :py:class:`int`
interface_site_and_neighbors_ids : list[int]
List of all lead-interface sites and their neighbors
"""
@cython.embedsignature
def __init__(self, syst):
def __init__(self, syst: kwant.system.FiniteSystem):
if not isinstance(syst, kwant.system.FiniteSystem):
raise ValueError("The argument given to 'syst' is not a kwant.system.FiniteSystem class instance.")
self.syst = syst
......@@ -64,8 +66,8 @@ class EnergySiteValidator:
if isinstance(site, (int, np.integer)):
if not (0 <= site < len(self.syst.sites)):
raise ValueError("The integer value given in 'site' is not a valid site id.")
elif not isinstance(site, kwant.Builder.Site):
raise ValueError("The argument given as `site' is not a kwant.Builder.Site class instance.")
elif not isinstance(site, kwant.builder.Site):
raise ValueError("The argument given as `site' is not a kwant.builder.Site class instance.")
def _get_site_id(self, site):
......@@ -79,7 +81,7 @@ class EnergySiteValidator:
@cython.embedsignature
def is_site_valid_for_divergence(self, site):
def is_site_valid_for_divergence(self, site: Union[int, kwant.builder.Site]) -> bool:
r"""
Tells if the energy current divergence can be calculated correctly in the given site.
......@@ -87,12 +89,12 @@ class EnergySiteValidator:
Parameters
----------
site : `~kwant.Builder.Site` or :py:class:`int`
site : `~kwant.builder.Site` or :py:class:`int`
The Site to validate
Returns
-------
is_valid : :py:class:`bool`
bool
Whether the site is valid of a divergence calculation.
"""
self._validate_site_type(site)
......@@ -100,7 +102,7 @@ class EnergySiteValidator:
@cython.embedsignature
def is_site_valid_for_density(self, site):
def is_site_valid_for_density(self, site: Union[int, np.integer, kwant.builder.Site]) -> bool:
r"""
Tells if the energy density or source can be calculated correctly in the given site.
......@@ -108,12 +110,12 @@ class EnergySiteValidator:
Parameters
----------
site : `~kwant.Builder.Site` or :py:class:`int`
site : `~kwant.builder.Site` or :py:class:`int`
The Site to validate
Returns
-------
is_valid : :py:class:`bool`
:py:class:`bool`
Whether the site is valid for a density calculation.
"""
......@@ -122,18 +124,19 @@ class EnergySiteValidator:
@cython.embedsignature
def is_hopping_valid_for_current(self, hopping):
def is_hopping_valid_for_current(self,
hopping: Union[Tuple[kwant.builder.Site, kwant.builder.Site], Tuple[int, int]]) -> bool:
r"""
Returns if the energy current can be calculated correctly between the two sites of the given hopping. Sites at the interface with leads would give wrong results.
Parameters
----------
hopping : array of two `~kwant.Builder.Site` or two :py:class:`int`
hopping : :py:class:`tuple` [`~kwant.builder.Site`, `~kwant.builder.Site`] or :py:class:`tuple` [:py:class:`int`, :py:class:`int`]
The hopping to validate
Returns
-------
is_valid : :py:class:`bool`
bool
Whether the hopping is valid for an energy current calculation.
"""
normalized_hop = kwant.operator._normalize_hopping_where(self.syst, [hopping])[0]
......@@ -145,21 +148,25 @@ cdef class EnergyCurrent:
r"""
An operator for calculating the local energy current between two sites.
The value of current between two sites has no physical meaning as it is not uniquely defined.
However, the total outgoing current from a site (*i.e.* the sum of the energy currents
The value of the energy current between two sites has no physical meaning as it is not uniquely defined. However, the total outgoing current from a site (*i.e.* the sum of the energy currents
from a site :math:`i` to all its neighbors :math:`j`), calculated by the class
`~tkwantoperator.EnergyCurrentDivergence`, is uniquely defined.
"""
@cython.embedsignature
def __init__(self, syst, where, baseOperator="Kinetic+", customOnsite=None, sum=False):
def __init__(self,\
syst: kwant.system.FiniteSystem,\
where: Union[List[Tuple[int, int]], List[Tuple[kwant.builder.Site, kwant.builder.Site]]],\
baseOperator: str = "Kinetic+",\
customOnsite: Optional[Callable[[kwant.builder.Site, dict], complex]] = None,\
sum: bool = False):
r"""
Parameters
----------
syst : `~kwant.system.FiniteSystem`
The finalized Kwant system for which energy currents will be calculated.
where : list of pairs of :py:class:`int` or `~kwant.builder.Site`
where : :py:class:`list` [(:py:class:`int`, :py:class:`int`)] or :py:class:`list` [(`~kwant.builder.Site`, `~kwant.builder.Site`)]
The hoppings on which the current will be evaluated. It is
saved in a normalized way, with the same order, in the `where`
attribute of this class.
......@@ -311,7 +318,9 @@ cdef class EnergyCurrent:
@cython.boundscheck(False)
@cython.wraparound(False)
@cython.embedsignature
def __call__(self, psi, params=None):
def __call__(self,
psi: Sequence[complex],
params: Optional[Dict[str, Union[float, complex]]] = None) -> Union[float, List[float]]:
r"""Returns the contribution :math:`I_{ji}^ε(ψ, t)` of ``psi`` to the expectation value
of the current flowing through the hoppings given in `where`.
......@@ -337,7 +346,7 @@ cdef class EnergyCurrent:
Returns
-------
current_values : (:py:class:`list` of :py:class:`float`) or :py:class:`float`
(:py:class:`list` of :py:class:`float`) or :py:class:`float`
List of the values fo the contribution of ``psi`` to the currents on each hopping :math:`\left [ I_{ji}^E(ψ, t) \right ]_{(j,i) \in \text{where}}`, when `sum` :math:`= 0`.
Otherwise the sum of these values :math:`\sum_{(j,i) \in \text{where}} I_{ji}^E(ψ, t)`.
"""
......@@ -443,8 +452,15 @@ cdef class EnergySource:
"""
@cython.embedsignature
def __init__(self, syst, where, baseOperator="Kinetic+", dt_hamiltonian=None,\
dt_customOnsite=None, customOnsite=None, sum=False, dt=1E-3):
def __init__(self,
syst: kwant.system.FiniteSystem,
where: Union[List[int], List[kwant.builder.Site]],
baseOperator: str ="Kinetic+",
dt_hamiltonian: Optional[Callable[[Tuple[kwant.builder.Site, kwant.builder.Site], Dict[str, Union[float, complex]]], Union[complex, ta.matrix]]]=None,
dt_customOnsite: Optional[Callable[[kwant.builder.Site, Dict[str, Union[float, complex]]], Union[complex, ta.matrix]]]=None,
customOnsite: Optional[Callable[[kwant.builder.Site, Dict[str, Union[float, complex]]], Union[complex, ta.matrix]]]=None,
sum: bool =False,
dt: float =1E-3):
r"""
Parameters
......@@ -452,7 +468,7 @@ cdef class EnergySource:
syst : `~kwant.system.FiniteSystem`
The finalized Kwant system on which the input power will be calculated.
where : list of :py:class:`int` or `~kwant.builder.Site`
where : :py:class:`list` [:py:class:`int`] or :py:class:`list` [`~kwant.builder.Site`]
The sites on which the input power will be evaluated. It is
saved in a normalized way, with the same order, in the `where`
attribute of this class.
......@@ -662,7 +678,9 @@ cdef class EnergySource:
@cython.boundscheck(False)
@cython.wraparound(False)
@cython.embedsignature
def __call__(self, psi, params=None):
def __call__(self,
psi: Sequence[complex],
params: Optional[Dict[str, Union[float, complex]]] = None) -> Union[float, List[float]]:
r"""Returns the contribution :math:`S_i^ε(ψ, t)` of ``psi`` to the expectation value
of the power given to the particles on each site of the `where` list.
......@@ -688,7 +706,7 @@ cdef class EnergySource:
Returns
-------
source_values : (:py:class:`list` of :py:class:`float`) or :py:class:`float`
(:py:class:`list` of :py:class:`float`) or :py:class:`float`
List of the values of the contribution of ``psi`` to the input power on each site
:math:`\left [ S_i^ε(ψ, t) \right ]_{i \in \text{where}}`,
when `sum` :math:`= 0`. Otherwise the sum of these values
......@@ -846,7 +864,12 @@ cdef class EnergyDensity:
"""
@cython.embedsignature
def __init__(self, syst, where, baseOperator="Kinetic+", customOnsite=None, sum=False):
def __init__(self,
syst: kwant.system.FiniteSystem,
where: Union[List[int], List[kwant.builder.Site]],
baseOperator: str ="Kinetic+",
customOnsite: Optional[Callable[[kwant.builder.Site, Dict[str, Union[float, complex]]], Union[complex, ta.matrix]]]=None,
sum: bool =False):
r"""
Parameters
......@@ -854,7 +877,7 @@ cdef class EnergyDensity:
syst : `~kwant.system.FiniteSystem`
The finalized Kwant system on which energy density will be calculated.
where : list of :py:class:`int` or `~kwant.builder.Site`
where : :py:class:`list` [:py:class:`int`] or :py:class:`list` [`~kwant.builder.Site`]
The sites on which the energy density will be evaluated. It is
saved in a normalized way, with the same order, in the `where`
attribute of this class.
......@@ -999,7 +1022,9 @@ cdef class EnergyDensity:
@cython.boundscheck(False)
@cython.wraparound(False)
@cython.embedsignature
def __call__(self, psi, params=None):
def __call__(self,
psi: Sequence[complex],
params: Optional[Dict[str, Union[float, complex]]] = None) -> Union[float, List[float]]:
r"""Returns the contribution :math:`ρ_i^E(ψ, t)` of ``psi`` to the expectation value
of the energy density on each site of the `where` list.
......@@ -1107,10 +1132,16 @@ cdef class LeadHeatCurrent:
An operator that calculates the heat current out of a specific lead,
into the central system.
"""
@cython.embedsignature
def __init__(self, syst, chemical_potential=None, added_lead_sites=None, baseOperator="Kinetic+",\
customOnsite=None, dt_hamiltonian=None, dt_customOnsite=None, dt=1E-3):
def __init__(self,
syst: kwant.system.FiniteSystem,
chemical_potential: float,
added_lead_sites: Union[Iterable[int], Iterable[kwant.builder.Site]],
baseOperator: str ="Kinetic+",
customOnsite: Optional[Callable[[kwant.builder.Site, Dict[str, Union[float, complex]]], Union[complex, ta.matrix]]]=None,
dt_hamiltonian: Optional[Callable[[Tuple[kwant.builder.Site, kwant.builder.Site], Dict[str, Union[float, complex]]], Union[complex, ta.matrix]]]=None,
dt_customOnsite: Optional[Callable[[kwant.builder.Site, Dict[str, Union[float, complex]]], Union[complex, ta.matrix]]]=None,
dt: float =1E-3):
r"""
Parameters
......@@ -1356,7 +1387,9 @@ cdef class LeadHeatCurrent:
@cython.boundscheck(False)
@cython.wraparound(False)
@cython.embedsignature
def __call__(self, psi, params=None):
def __call__(self,
psi: Sequence[complex],
params: Optional[Dict[str, Union[float, complex]]] = None) -> Union[float, List[float]]:
r"""Returns the contribution :math:`I^H(ψ, t)` of ``psi`` to the expectation value
of the lead's outgoing heat current.
......@@ -1398,16 +1431,20 @@ cdef class EnergyCurrentDivergence:
of the system by summing the outgoing energy currents towards its neighbors.
"""
@cython.embedsignature
def __init__(self, syst, where, baseOperator="Kinetic+", customOnsite=None, sum=False):
def __init__(self,
syst: kwant.system.FiniteSystem,
where: Union[List[int], List[kwant.builder.Site]],
baseOperator: str ="Kinetic+",
customOnsite: Optional[Callable[[kwant.builder.Site, Dict[str, Union[float, complex]]], Union[complex, ta.matrix]]]=None,
sum: bool =False):
r"""
Parameters
----------
syst : `~kwant.system.FiniteSystem`
The finalized Kwant system on which the current divergence will be calculated.
where : list of pairs of :py:class:`int` or `~kwant.builder.Site`
The hoppings on which the current will be evaluated. It is
where : :py:class:`list` [:py:class:`int`] or :py:class:`list` [`~kwant.builder.Site`]
The sites on which the net outgoing energy current will be evaluated. It is
saved in a normalized way, with the same order, in the `where`
attribute of this class.
......@@ -1469,7 +1506,7 @@ cdef class EnergyCurrentDivergence:
Number of neighbors of each site of the `where` list, with the same order. This
attribute is not used if `sum` is set to :math:`1`.
_energy_current_where : :py:class:`list` of :py:class:`tuple` of `~kwant.builder.Site`
_energy_current_where : :py:class:`list` [(`~kwant.builder.Site`, `~kwant.builder.Site`)]
List of hoppings on which the energy current will be calculated. Slices of
this list are then made, with the help of `_neighbors_num`, to calculate the current
divergence on each site of the `where` list. if `sum` is set to :math:`1`, this list
......@@ -1508,7 +1545,9 @@ cdef class EnergyCurrentDivergence:
@cython.boundscheck(False)
@cython.wraparound(False)
@cython.embedsignature
def __call__(self, psi, params=None):
def __call__(self,
psi: Sequence[complex],
params: Optional[Dict[str, Union[float, complex]]] = None) -> Union[float, List[float]]:
r"""Returns the contribution :math:`D_i^E(ψ, t)` of ``psi`` to the expectation value
of the current divergence on each site of the `where` list.
......
Supports Markdown
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