tbkit 0.6.0__tar.gz → 0.6.2__tar.gz

{tbkit-0.6.0/tbkit.egg-info → tbkit-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tbkit
-Version: 0.6.0
+Version: 0.6.2
 Summary: A Python package to build and solve Tight-Binding models.
 Author-email: Charles Poli <cpoli374@gmail.com>
 Maintainer-email: Charles Poli <cpoli374@gmail.com>
@@ -36,19 +36,22 @@ Requires-Dist: sympy>=1.12; extra == "test"
 Provides-Extra: docs
 Requires-Dist: sphinx>=7; extra == "docs"
 Requires-Dist: pydata-sphinx-theme>=0.15; extra == "docs"
-Requires-Dist: sphinx-gallery>=0.15; extra == "docs"
+Requires-Dist: sphinx-gallery>=0.17; extra == "docs"
+Requires-Dist: joblib>=1.3; extra == "docs"
 Requires-Dist: sympy>=1.12; extra == "docs"
+Requires-Dist: sphinx-sitemap>=2.6; extra == "docs"
+Requires-Dist: sphinxext-opengraph>=0.9; extra == "docs"
 Dynamic: license-file
 
 # tbkit — a Tight-Binding package
 
 | | |
 |:--|:-:|
-| Package | [![PyPI version](https://badgen.net/pypi/v/tbkit)](https://pypi.org/project/tbkit/) [![conda-forge](https://img.shields.io/conda/vn/conda-forge/tbkit)](https://anaconda.org/conda-forge/tbkit) [![Python versions](https://badgen.net/pypi/python/tbkit)](https://pypi.org/project/tbkit/) [![DOI](https://zenodo.org/badge/1381398706.svg)](https://zenodo.org/badge/latestdoi/1381398706) |
-| Quality | [![License](https://badgen.net/github/license/cpoli/tbkit)](https://github.com/cpoli/tbkit/blob/master/LICENSE) [![CI](https://github.com/cpoli/tbkit/actions/workflows/ci.yml/badge.svg)](https://github.com/cpoli/tbkit/actions/workflows/ci.yml) [![Coverage](https://codecov.io/gh/cpoli/tbkit/branch/master/graph/badge.svg)](https://codecov.io/gh/cpoli/tbkit) |
+| Package | [![PyPI version](https://badgen.net/pypi/v/tbkit)](https://pypi.org/project/tbkit/) [![conda-forge](https://img.shields.io/conda/vn/conda-forge/tbkit)](https://anaconda.org/conda-forge/tbkit) [![Python versions](https://badgen.net/pypi/python/tbkit)](https://pypi.org/project/tbkit/) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23386289.svg)](https://doi.org/10.5281/zenodo.23386289) |
+| Quality | [![License](https://img.shields.io/github/license/cpoli/tbkit)](https://github.com/cpoli/tbkit/blob/master/LICENSE) [![CI](https://github.com/cpoli/tbkit/actions/workflows/ci.yml/badge.svg)](https://github.com/cpoli/tbkit/actions/workflows/ci.yml) [![Coverage](https://codecov.io/gh/cpoli/tbkit/branch/master/graph/badge.svg)](https://codecov.io/gh/cpoli/tbkit) |
 | Documentation | [![Docs](https://badgen.net/badge/docs/cpoli.github.io%2Ftbkit/blue)](https://cpoli.github.io/tbkit/) |
 | Downloads | [![Downloads](https://static.pepy.tech/badge/tbkit)](https://pepy.tech/project/tbkit) [![Downloads/Month](https://static.pepy.tech/badge/tbkit/month)](https://pepy.tech/project/tbkit) |
-| Community | [![GitHub Stars](https://badgen.net/github/stars/cpoli/tbkit)](https://github.com/cpoli/tbkit) [![GitHub Forks](https://badgen.net/github/forks/cpoli/tbkit)](https://github.com/cpoli/tbkit) [![Contributors](https://badgen.net/github/contributors/cpoli/tbkit)](https://github.com/cpoli/tbkit/graphs/contributors) [![Last Commit](https://badgen.net/github/last-commit/cpoli/tbkit/master)](https://github.com/cpoli/tbkit/commits/master) |
+| Community | [![GitHub Stars](https://img.shields.io/github/stars/cpoli/tbkit)](https://github.com/cpoli/tbkit) [![GitHub Forks](https://img.shields.io/github/forks/cpoli/tbkit)](https://github.com/cpoli/tbkit) [![Contributors](https://img.shields.io/github/contributors/cpoli/tbkit)](https://github.com/cpoli/tbkit/graphs/contributors) [![Last Commit](https://img.shields.io/github/last-commit/cpoli/tbkit/master)](https://github.com/cpoli/tbkit/commits/master) |
 
 ![tbkit logo](https://raw.githubusercontent.com/cpoli/tbkit/master/docs/source/_static/image/tbkit_logo.png)
 

{tbkit-0.6.0 → tbkit-0.6.2}/README.md

@@ -2,11 +2,11 @@
 
 | | |
 |:--|:-:|
-| Package | [![PyPI version](https://badgen.net/pypi/v/tbkit)](https://pypi.org/project/tbkit/) [![conda-forge](https://img.shields.io/conda/vn/conda-forge/tbkit)](https://anaconda.org/conda-forge/tbkit) [![Python versions](https://badgen.net/pypi/python/tbkit)](https://pypi.org/project/tbkit/) [![DOI](https://zenodo.org/badge/1381398706.svg)](https://zenodo.org/badge/latestdoi/1381398706) |
-| Quality | [![License](https://badgen.net/github/license/cpoli/tbkit)](https://github.com/cpoli/tbkit/blob/master/LICENSE) [![CI](https://github.com/cpoli/tbkit/actions/workflows/ci.yml/badge.svg)](https://github.com/cpoli/tbkit/actions/workflows/ci.yml) [![Coverage](https://codecov.io/gh/cpoli/tbkit/branch/master/graph/badge.svg)](https://codecov.io/gh/cpoli/tbkit) |
+| Package | [![PyPI version](https://badgen.net/pypi/v/tbkit)](https://pypi.org/project/tbkit/) [![conda-forge](https://img.shields.io/conda/vn/conda-forge/tbkit)](https://anaconda.org/conda-forge/tbkit) [![Python versions](https://badgen.net/pypi/python/tbkit)](https://pypi.org/project/tbkit/) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23386289.svg)](https://doi.org/10.5281/zenodo.23386289) |
+| Quality | [![License](https://img.shields.io/github/license/cpoli/tbkit)](https://github.com/cpoli/tbkit/blob/master/LICENSE) [![CI](https://github.com/cpoli/tbkit/actions/workflows/ci.yml/badge.svg)](https://github.com/cpoli/tbkit/actions/workflows/ci.yml) [![Coverage](https://codecov.io/gh/cpoli/tbkit/branch/master/graph/badge.svg)](https://codecov.io/gh/cpoli/tbkit) |
 | Documentation | [![Docs](https://badgen.net/badge/docs/cpoli.github.io%2Ftbkit/blue)](https://cpoli.github.io/tbkit/) |
 | Downloads | [![Downloads](https://static.pepy.tech/badge/tbkit)](https://pepy.tech/project/tbkit) [![Downloads/Month](https://static.pepy.tech/badge/tbkit/month)](https://pepy.tech/project/tbkit) |
-| Community | [![GitHub Stars](https://badgen.net/github/stars/cpoli/tbkit)](https://github.com/cpoli/tbkit) [![GitHub Forks](https://badgen.net/github/forks/cpoli/tbkit)](https://github.com/cpoli/tbkit) [![Contributors](https://badgen.net/github/contributors/cpoli/tbkit)](https://github.com/cpoli/tbkit/graphs/contributors) [![Last Commit](https://badgen.net/github/last-commit/cpoli/tbkit/master)](https://github.com/cpoli/tbkit/commits/master) |
+| Community | [![GitHub Stars](https://img.shields.io/github/stars/cpoli/tbkit)](https://github.com/cpoli/tbkit) [![GitHub Forks](https://img.shields.io/github/forks/cpoli/tbkit)](https://github.com/cpoli/tbkit) [![Contributors](https://img.shields.io/github/contributors/cpoli/tbkit)](https://github.com/cpoli/tbkit/graphs/contributors) [![Last Commit](https://img.shields.io/github/last-commit/cpoli/tbkit/master)](https://github.com/cpoli/tbkit/commits/master) |
 
 ![tbkit logo](https://raw.githubusercontent.com/cpoli/tbkit/master/docs/source/_static/image/tbkit_logo.png)
 

{tbkit-0.6.0 → tbkit-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tbkit"
-version = "0.6.0"
+version = "0.6.2"
 description = "A Python package to build and solve Tight-Binding models."
 readme = "README.md"
 license = "BSD-3-Clause"
@@ -39,7 +39,7 @@ Documentation = "https://cpoli.github.io/tbkit/"
 [project.optional-dependencies]
 continuum = ["sympy>=1.12"]
 test = ["pytest>=7", "pytest-cov>=4", "pytest-xdist>=3.2", "sympy>=1.12"]
-docs = ["sphinx>=7", "pydata-sphinx-theme>=0.15", "sphinx-gallery>=0.15", "sympy>=1.12"]
+docs = ["sphinx>=7", "pydata-sphinx-theme>=0.15", "sphinx-gallery>=0.17", "joblib>=1.3", "sympy>=1.12", "sphinx-sitemap>=2.6", "sphinxext-opengraph>=0.9"]
 
 [tool.pytest.ini_options]
 # The suite is warning-free; keep it that way. A warning from tbkit itself is

{tbkit-0.6.0 → tbkit-0.6.2}/tbkit/__init__.py

@@ -6,7 +6,7 @@
 
 """tbkit: build and solve Tight-Binding models."""
 
-__version__ = "0.6.0"
+__version__ = "0.6.2"
 
 __all__ = [
     "Lattice", "System", "Plot", "Propagation", "Save", "KSpace",

{tbkit-0.6.0 → tbkit-0.6.2}/tbkit/bdg.py

@@ -30,13 +30,18 @@ def bdg_ham(ham, pairing, mu: float = 0.) -> sparse.csr_matrix:
     r'''
     Get the real-space BdG Hamiltonian (see the module docstring).
 
-    :param ham: Square Hermitian matrix, shape (N, N) (e.g. *System.ham*).
-    :param pairing: Square antisymmetric matrix, shape (N, N): :math:`\Delta`
+    Parameters
+    ----------
+    ham : Square Hermitian matrix, shape (N, N) (e.g. *System.ham*)
+    pairing
+        Square antisymmetric matrix, shape (N, N): :math:`\Delta`
         (see *pairing_bonds*, *pairing_s_wave*).
-    :param mu: Real number. Default value 0. Chemical potential.
+    mu : Real number, default 0
+        Chemical potential.
 
-    :returns:
-        * **ham_bdg** -- Sparse CSR matrix, shape (2N, 2N).
+    Returns
+    -------
+    ham_bdg : Sparse CSR matrix, shape (2N, 2N)
     '''
     h = sparse.csr_matrix(ham, dtype='c16')
     delta = sparse.csr_matrix(pairing, dtype='c16')
@@ -56,11 +61,15 @@ def pairing_bonds(sys, delta: complex) -> sparse.csr_matrix:
     them: angle in :math:`[0, 180)`). On a chain it is Kitaev's
     :math:`\Delta\,c^\dagger_jc^\dagger_{j+1}`.
 
-    :param sys: **System** instance, with hoppings.
-    :param delta: Complex number. :math:`\Delta`.
+    Parameters
+    ----------
+    sys : **System** instance, with hoppings
+    delta : Complex number
+        :math:`\Delta`.
 
-    :returns:
-        * **pairing** -- Sparse CSR matrix, shape (sites, sites).
+    Returns
+    -------
+    pairing : Sparse CSR matrix, shape (sites, sites)
     '''
     error_handling.empty_hop(sys.hop)
     error_handling.number(delta, 'delta')
@@ -78,11 +87,16 @@ def pairing_s_wave(n_sites: int, delta: complex) -> sparse.csr_matrix:
     for a spinful model with rows ordered site by site, spin up then down
     (as *KSpace* with ``spin=True`` and *OrbitalSystem* with one orbital).
 
-    :param n_sites: Positive integer. Number of sites.
-    :param delta: Complex number. :math:`\Delta`.
+    Parameters
+    ----------
+    n_sites : Positive integer
+        Number of sites.
+    delta : Complex number
+        :math:`\Delta`.
 
-    :returns:
-        * **pairing** -- Sparse CSR matrix, shape (2 n_sites, 2 n_sites).
+    Returns
+    -------
+    pairing : Sparse CSR matrix, shape (2 n_sites, 2 n_sites)
     '''
     error_handling.positive_int(n_sites, 'n_sites')
     error_handling.number(delta, 'delta')
@@ -105,15 +119,22 @@ def bdg_kspace(ks, pairing: list[dict], mu: float = 0.):
     same positions). Each pairing :math:`\Delta\,c^\dagger_{i,\mathbf{0}}c^\dagger_{j,\mathbf{R}} + h.c.`
     enters antisymmetrized, :math:`\Delta_{ij}(\mathbf{R}) = -\Delta_{ji}(-\mathbf{R})`.
 
-    :param ks: **KSpace** instance (Hermitian, orthogonal basis).
-    :param pairing: List of dictionaries with keys ('i', 'j', 'R', 'delta'):
+    Parameters
+    ----------
+    ks : **KSpace** instance (Hermitian, orthogonal basis)
+    pairing
+        List of dictionaries with keys ('i', 'j', 'R', 'delta'):
         orbital indices of *ks* (``0 ... norb-1``; with ``spin=True``,
         ``2*site + spin``), lattice vector, amplitude.
-    :param mu: Real number. Default value 0. Chemical potential.
+    mu : Real number, default 0
+        Chemical potential.
 
-    :returns:
-        * **ks_bdg** -- **KSpace** instance, 2 norb orbitals.
+    Returns
+    -------
+    ks_bdg : **KSpace** instance, 2 norb orbitals
 
+    Examples
+    --------
     Example usage::
 
         # Kitaev chain: E(k) = +-sqrt((2t cos k - mu)^2 + 4 Delta^2 sin^2 k)
@@ -154,10 +175,14 @@ def particle_hole(n: int) -> NDArray[np.float64]:
     orbitals: pass it to *KSpace.symmetry_error* (``antiunitary=True``,
     ``anti=True``) or *KSpace.tenfold_class* (``particle_hole=``).
 
-    :param n: Positive integer. Number of particle orbitals.
+    Parameters
+    ----------
+    n : Positive integer
+        Number of particle orbitals.
 
-    :returns:
-        * **tau_x** -- Real ndarray, shape (2n, 2n).
+    Returns
+    -------
+    tau_x : Real ndarray, shape (2n, 2n)
     '''
     error_handling.positive_int(n, 'n')
     return np.kron(np.array([[0., 1.], [1., 0.]]), np.eye(n))
@@ -171,10 +196,13 @@ def pfaffian(a) -> complex:
     (2012)). For a 2x2 block :math:`\begin{pmatrix}0 & a\\ -a & 0\end{pmatrix}`
     it is :math:`a`; it is 0 for an odd dimension.
 
-    :param a: Square antisymmetric matrix, shape (n, n).
+    Parameters
+    ----------
+    a : Square antisymmetric matrix, shape (n, n)
 
-    :returns:
-        * **pf** -- Complex number (a float for a real matrix).
+    Returns
+    -------
+    pf : Complex number (a float for a real matrix)
     '''
     real = not np.iscomplexobj(a)
     a = np.array(a, dtype='c16')
@@ -224,11 +252,15 @@ def majorana_number(ks) -> int:
     B 82, 184525 (2010)). The invariant changes only where the gap closes
     at one of the :math:`\Gamma_i`.
 
-    :param ks: **KSpace** instance of a BdG model, 2n orbitals: n particles
+    Parameters
+    ----------
+    ks
+        **KSpace** instance of a BdG model, 2n orbitals: n particles
         then their n holes (see *bdg_kspace*).
 
-    :returns:
-        * **m** -- Integer, -1 (topological) or +1 (trivial).
+    Returns
+    -------
+    m : Integer, -1 (topological) or +1 (trivial)
     '''
     from tbkit.kspace import KSpace
     error_handling.kspace(ks, KSpace)
@@ -249,12 +281,18 @@ class GapResult():
     r'''
     Self-consistent s-wave pairing of *s_wave_gap*.
 
-    :ivar delta: Complex ndarray. Gap :math:`\Delta_i` on every site.
-    :ivar energies: Real ndarray, shape (2N,). Spectrum of the reduced BdG
+    Attributes
+    ----------
+    delta : Complex ndarray
+        Gap :math:`\Delta_i` on every site.
+    energies : Real ndarray, shape (2N,)
+        Spectrum of the reduced BdG
         Hamiltonian (symmetric, :math:`\pm E_n`).
-    :ivar states: Complex ndarray, shape (2N, 2N). Its eigenvectors
+    states : Complex ndarray, shape (2N, 2N)
+        Its eigenvectors
         :math:`(u_n, v_n)` (columns).
-    :ivar iterations: Integer. Number of iterations.
+    iterations : Integer
+        Number of iterations.
     '''
 
     def __init__(self, delta, energies, states, iterations) -> None:
@@ -305,19 +343,26 @@ def s_wave_gap(
     :math:`T_c` the iteration slows down (the linearized map has an
     eigenvalue close to 1): raise *max_iter* there.
 
-    :param ham: Square Hermitian matrix, (N, N), spin independent (e.g. *System.ham*).
-    :param V: Positive real, or array of N non-negative reals. Attraction.
-    :param mu: Real number. Default value 0. Chemical potential.
-    :param temperature: Positive real or zero. Default value 0.
-    :param delta0: Number, or array of N numbers. Default value 0.1.
+    Parameters
+    ----------
+    ham : Square Hermitian matrix, (N, N), spin independent (e.g. *System.ham*)
+    V : Positive real, or array of N non-negative reals
+        Attraction.
+    mu : Real number, default 0
+        Chemical potential.
+    temperature : Positive real or zero, default 0
+    delta0 : Number, or array of N numbers, default 0.1
         Initial gap.
-    :param mixing: Real in (0, 1]. Default value 1 (plain iteration).
-    :param tol: Positive real. Default value 1e-8. Convergence threshold
+    mixing : Real in (0, 1]
+        Default value 1 (plain iteration).
+    tol : Positive real, default 1e-8
+        Convergence threshold
         on the largest change of :math:`\Delta_i`.
-    :param max_iter: Positive integer. Default value 10000.
+    max_iter : Positive integer, default 10000
 
-    :returns:
-        * **result** -- :class:`GapResult`.
+    Returns
+    -------
+    result : :class:`GapResult`
     '''
     h = ham.toarray() if hasattr(ham, 'toarray') else np.asarray(ham)
     error_handling.square_matrix(h, 'ham')

{tbkit-0.6.0 → tbkit-0.6.2}/tbkit/bridges.py

@@ -45,12 +45,18 @@ def cell_orbitals(lat: Lattice) -> tuple[NDArray[np.int64], NDArray[np.int64]]:
     :math:`\boldsymbol\tau_{o_s} + \sum_k n_{s,k}\mathbf{a}_k`, with the tag
     of orbital :math:`o_s` (within ``ATOL``).
 
-    :param lat: **Lattice** instance, after *get_lattice* (sites may have
+    Parameters
+    ----------
+    lat
+        **Lattice** instance, after *get_lattice* (sites may have
         been removed, but not moved).
 
-    :returns:
-        * **cells** -- Integer ndarray, shape (sites, dim). :math:`n_{s,k}`.
-        * **orbitals** -- Integer ndarray, shape (sites,). :math:`o_s`.
+    Returns
+    -------
+    cells : Integer ndarray, shape (sites, dim)
+        :math:`n_{s,k}`.
+    orbitals : Integer ndarray, shape (sites,)
+        :math:`o_s`.
     '''
     error_handling.lat(lat)
     error_handling.empty_coor(lat.coor)
@@ -90,19 +96,27 @@ def kspace_from_system(sys: System, periodic: bool | None = None, tol: float = 1
     element is kept, with ``hermitian=False``. Onsite energies are taken
     orbital by orbital.
 
-    :param sys: **System** instance with its hoppings set (one orbital per site).
-    :param periodic: Boolean. Default value None: True if *sys* has
+    Parameters
+    ----------
+    sys : **System** instance with its hoppings set (one orbital per site)
+    periodic : Boolean
+        Default value None: True if *sys* has
         periodic boundaries along some primitive vector (``System(lat,
         periodic=...)``, or *finite_system* with ``periodic=True``). The
         System is a torus of the *lat.n1* x *lat.n2* (x *lat.n3*) cells of
         *get_lattice*.
-    :param tol: Positive real number. Default value 1e-9. Largest allowed
+    tol : Positive real number, default 1e-9
+        Largest allowed
         difference between equivalent matrix elements.
 
-    :returns:
-        * **ks** -- **KSpace** instance (spinless), on a new **Lattice**
-          with the *unit_cell* and *prim_vec* of *sys.lat*.
+    Returns
+    -------
+    ks
+        **KSpace** instance (spinless), on a new **Lattice**
+        with the *unit_cell* and *prim_vec* of *sys.lat*.
 
+    Examples
+    --------
     Example usage::
 
         lat = lattices.honeycomb()
@@ -170,17 +184,23 @@ def finite_model(
     and tag of every row. Spinful models are supported (the two spin
     components of a site share its position).
 
-    :param ks: **KSpace** instance.
-    :param n_cells: Positive integer, or tuple of *dim* positive integers.
+    Parameters
+    ----------
+    ks : **KSpace** instance
+    n_cells : Positive integer, or tuple of *dim* positive integers
         Number of unit cells along each primitive vector.
-    :param periodic: Boolean. Default value False. Periodic boundaries (a torus).
+    periodic : Boolean, default False
+        Periodic boundaries (a torus).
 
-    :returns:
-        * **ham** -- Complex CSR matrix, shape (N*norb, N*norb).
-        * **positions** -- Real ndarray, shape (N*norb, space_dim). Row
-          :math:`c\,\mathrm{norb}+o` sits at :math:`\boldsymbol\tau_o + \sum_k n_k\mathbf{a}_k`
-          (cell *c* has :math:`c = n_1 + N_1 n_2 + N_1N_2 n_3`).
-        * **tags** -- String ndarray, shape (N*norb,). Sublattice tags.
+    Returns
+    -------
+    ham : Complex CSR matrix, shape (N*norb, N*norb)
+    positions : Real ndarray, shape (N*norb, space_dim)
+        Row
+        :math:`c\,\mathrm{norb}+o` sits at :math:`\boldsymbol\tau_o + \sum_k n_k\mathbf{a}_k`
+        (cell *c* has :math:`c = n_1 + N_1 n_2 + N_1N_2 n_3`).
+    tags : String ndarray, shape (N*norb,)
+        Sublattice tags.
     '''
     error_handling.kspace(ks, KSpace)
     error_handling.nk(n_cells, ks.dim)
@@ -210,13 +230,19 @@ def finite_system(ks: KSpace, n_cells: int | tuple[int, ...], periodic: bool = F
     (``sys.periodic``), so that further *set_hopping* calls, *Plot* and
     *get_bott_index* treat it as a torus.
 
-    :param ks: **KSpace** instance, with ``spin=False``.
-    :param n_cells: Positive integer, or tuple of *dim* positive integers.
-    :param periodic: Boolean. Default value False. Periodic boundaries (a torus).
+    Parameters
+    ----------
+    ks : **KSpace** instance, with ``spin=False``
+    n_cells : Positive integer, or tuple of *dim* positive integers
+    periodic : Boolean, default False
+        Periodic boundaries (a torus).
 
-    :returns:
-        * **sys** -- **System** instance, with its hoppings set.
+    Returns
+    -------
+    sys : **System** instance, with its hoppings set
 
+    Examples
+    --------
     Example usage::
 
         sys = finite_system(gra, (30, 30), periodic=True)

{tbkit-0.6.0 → tbkit-0.6.2}/tbkit/continuum.py

@@ -149,21 +149,29 @@ def discretize_symbolic(hamiltonian, dim: int | None = None) -> dict:
     the grid spacing *a* and the parameters of the Hamiltonian (see the
     module docstring for the scheme).
 
-    :param hamiltonian: sympy expression or Matrix, or a string, in the
+    Parameters
+    ----------
+    hamiltonian
+        sympy expression or Matrix, or a string, in the
         momenta ``k_x``, ``k_y``, ``k_z``: a polynomial in them with
         constant coefficients. Any other symbol is a parameter, taken real
         (the symbols ``x``, ``y``, ``z`` and ``a`` are not allowed). A
         string may use the Pauli matrices ``sigma_0``, ``sigma_x``,
         ``sigma_y``, ``sigma_z`` and ``kron`` (Kronecker product); ``I``
         is the imaginary unit.
-    :param dim: 1, 2 or 3. Default value None: the last axis whose momentum
+    dim : 1, 2 or 3
+        Default value None: the last axis whose momentum
         appears (1 if none).
 
-    :returns:
-        * **hoppings** -- Dictionary. key: tuple of *dim* integers
-          :math:`\mathbf{R}`, val: sympy Matrix :math:`T(\mathbf{R})`, in
-          the symbol ``a`` and those of *hamiltonian*.
+    Returns
+    -------
+    hoppings : Dictionary
+        key: tuple of *dim* integers
+        :math:`\mathbf{R}`, val: sympy Matrix :math:`T(\mathbf{R})`, in
+        the symbol ``a`` and those of *hamiltonian*.
 
+    Examples
+    --------
     Example usage::
 
         discretize_symbolic('k_x**2')
@@ -211,21 +219,29 @@ def discretize(hamiltonian, a: float = 1., dim: int | None = None,
     otherwise every matrix element is stored, with ``hermitian=False``.
     Constant onsite terms are in *ks.onsite*.
 
-    :param hamiltonian: sympy expression or Matrix, or a string (see
-        *discretize_symbolic*).
-    :param a: Real number, at least :math:`\sqrt{0.1}\approx 0.316` (the
+    Parameters
+    ----------
+    hamiltonian : sympy expression or Matrix, or a string (see *discretize_symbolic*)
+    a
+        Real number, at least :math:`\sqrt{0.1}\approx 0.316` (the
         shortest primitive vector of a **Lattice**). Default value 1. Grid
         spacing: to refine the grid, measure lengths in a smaller unit.
-    :param dim: 1, 2 or 3. Default value None: the last axis whose momentum
+    dim : 1, 2 or 3
+        Default value None: the last axis whose momentum
         appears (1 if none).
-    :param tags: String or list of one-character strings. Default value
+    tags : String or list of one-character strings
+        Default value
         None: 'a', 'b', 'c', ... Tag of each orbital.
 
-    :returns:
-        * **ks** -- **KSpace** instance (spinless, *norb* orbitals). Its
-          lattice has *prim_vec* :math:`a\hat{\mathbf{x}}, a\hat{\mathbf{y}},
-          (a\hat{\mathbf{z}})`.
+    Returns
+    -------
+    ks : **KSpace** instance (spinless, *norb* orbitals)
+        Its
+        lattice has *prim_vec* :math:`a\hat{\mathbf{x}}, a\hat{\mathbf{y}},
+        (a\hat{\mathbf{z}})`.
 
+    Examples
+    --------
     Example usage::
 
         # the BHZ model of HgTe quantum wells, one spin block

{tbkit-0.6.0 → tbkit-0.6.2}/tbkit/dos.py

@@ -36,20 +36,29 @@ def density_of_states(
     :math:`\int\rho(E)dE` equals the number of levels in *energies*,
     for an *e_grid* wide enough to contain the tails.
 
-    :param energies: Array of (real) eigenenergies. Any shape (e.g. the
+    Parameters
+    ----------
+    energies : Array of (real) eigenenergies
+        Any shape (e.g. the
         *en* attribute of **System**, or of **KSpace** after *get_bands*
         over a k-mesh -- flattened automatically).
-    :param e_grid: Real ndarray. Default value None. Energies at which to
+    e_grid : Real ndarray, default None
+        Energies at which to
         evaluate the density of states. If None, a grid of 401 points
         spanning ``[min(energies)-3*broadening, max(energies)+3*broadening]``
         is used.
-    :param broadening: Positive real number. Default value 0.05. Kernel width
+    broadening : Positive real number, default 0.05
+        Kernel width
         :math:`\sigma`.
-    :param kernel: String. Default value 'gaussian'. 'gaussian' or 'lorentzian'.
+    kernel : String, default 'gaussian'
+        'gaussian' or 'lorentzian'.
 
-    :returns:
-        * **e_grid** -- Real ndarray. The energy grid used.
-        * **dos** -- Real ndarray, same shape as *e_grid*. Density of states.
+    Returns
+    -------
+    e_grid : Real ndarray
+        The energy grid used.
+    dos : Real ndarray, same shape as *e_grid*
+        Density of states.
     '''
     error_handling.ndarray_empty(np.asarray(energies), 'energies')
     error_handling.positive_real(broadening, 'broadening')
@@ -153,18 +162,27 @@ def tetrahedron_dos(
     correction. Complex energies (non-Hermitian bands) are replaced by
     their real part.
 
-    :param energies: Real array, shape (n1, n2, ..., nbands): the bands on
+    Parameters
+    ----------
+    energies
+        Real array, shape (n1, n2, ..., nbands): the bands on
         a periodic mesh of 1, 2 or 3 dimensions, ``energies[i1, i2, ..., n]``
         at the k-point :math:`\sum_d (i_d/n_d)\mathbf{b}_d` (as given by
         ``KSpace.mesh_bands(nk).reshape(*nk, norb)``).
-    :param e_grid: Real ndarray, increasing. Default value None. Energies at
+    e_grid : Real ndarray, increasing, default None
+        Energies at
         which to evaluate the density of states. If None, 401 points
         spanning the bands, with a 2% margin on each side.
 
-    :returns:
-        * **e_grid** -- Real ndarray. The energy grid used.
-        * **dos** -- Real ndarray, same shape as *e_grid*. Density of states.
+    Returns
+    -------
+    e_grid : Real ndarray
+        The energy grid used.
+    dos : Real ndarray, same shape as *e_grid*
+        Density of states.
 
+    Examples
+    --------
     Example usage::
 
         en = ks.mesh_bands((40, 40)).reshape(40, 40, ks.norb)