sparse-ir 2.1.4__tar.gz → 2.1.6__tar.gz

{sparse_ir-2.1.4/src/sparse_ir.egg-info → sparse_ir-2.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sparse-ir
-Version: 2.1.4
+Version: 2.1.6
 Summary: Python bindings for the libsparseir library, providing efficient sparse intermediate representation for many-body physics calculations
 Author: SpM-lab
 License-Expression: MIT
@@ -20,7 +20,7 @@ Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
 Requires-Dist: numpy
 Requires-Dist: scipy
-Requires-Dist: pylibsparseir<0.10.0,>=0.8.3
+Requires-Dist: pylibsparseir<0.13.0,>=0.8.3
 Dynamic: license-file
 
 sparse-ir - A library for the intermediate representation of propagators
@@ -45,7 +45,7 @@ Install via `conda <https://anaconda.org/spm-lab/sparse-ir>`_::
 
 sparse-ir requires `numpy <https://numpy.org/>`_, `scipy <https://scipy.org/>`_,
 and `pylibsparseir <https://pypi.org/project/pylibsparseir>`_ (a thin Python wrapper
-for the `libsparseir <https://github.com/SpM-lab/libsparseir>`_ C API).
+for the libsparseir C API from `sparse-ir-rs <https://github.com/SpM-lab/sparse-ir-rs>`_).
 
 To manually install the current development version, you can use the following::
 
@@ -78,13 +78,21 @@ Lichtenstein formula, FLEX, ... - are presented.
 Refer to the `API documentation`_ for more details on how to work
 with the python library.
 
+The symbols and conventions are defined on the `notation page`_, shared with
+the tutorial and the Julia and C libraries.  In short: G(τ) = -⟨T c(τ) c†(0)⟩
+for both statistics; Matsubara frequencies iν are passed as the reduced
+frequency n, an integer with ν = nπ/β (odd for fermions, even for bosons);
+G(iν) = ∫₀^β dτ e^{iντ} G(τ); and G(τ) is evaluated for τ in [-β, β], where
+``-0.0`` stands for 0⁻.
+
 There is also a `Julia library`_ and (currently somewhat restricted)
 `C library with Fortran bindings`_ available for the IR basis and sparse sampling.
 
-.. _comprehensive tutorial: https://spm-lab.github.io/sparse-ir-tutorial
+.. _comprehensive tutorial: https://spm-lab.github.io/sparse-ir-tutorial-v2/
 .. _API documentation: https://sparse-ir.readthedocs.io
+.. _notation page: https://spm-lab.github.io/sparse-ir-doc/src/notation.html
 .. _Julia library: https://github.com/SpM-lab/SparseIR.jl
-.. _C library with Fortran bindings: https://github.com/SpM-lab/libsparseir
+.. _C library with Fortran bindings: https://github.com/SpM-lab/sparse-ir-rs
 
 Getting started
 ---------------
@@ -95,15 +103,16 @@ lines of Python code::
     import sparse_ir, numpy as np
     basis = sparse_ir.FiniteTempBasis('F', beta=10, wmax=8, eps=1e-6)
     stau = sparse_ir.TauSampling(basis)
-    siw = sparse_ir.MatsubaraSampling(basis, positive_only=True)
+    siv = sparse_ir.MatsubaraSampling(basis, positive_only=True)
 
     # Solve the single impurity Anderson model coupled to a bath with a
-    # semicircular states with unit half bandwidth.
+    # semicircular density of states with unit half bandwidth.
     U = 1.2
     def rho0w(w):
         return np.sqrt(1-w.clip(-1,1)**2) * 2/np.pi
 
-    # Compute the IR basis coefficients for the non-interacting propagator
+    # Compute the IR basis coefficients G0_l = -S_l rho0_l for the
+    # non-interacting propagator
     rho0l = basis.v.overlap(rho0w)
     G0l = -basis.s * rho0l
 
@@ -116,23 +125,27 @@ lines of Python code::
         Gtau = stau.evaluate(Gl)
         Sigmatau = U**2 * Gtau**3
         Sigmal = stau.fit(Sigmatau)
-        Sigmaiw = siw.evaluate(Sigmal)
-        G0iw = siw.evaluate(G0l)
-        Giw = 1/(1/G0iw - Sigmaiw)
-        Gl = siw.fit(Giw)
+        Sigmaiv = siv.evaluate(Sigmal)
+        G0iv = siv.evaluate(G0l)
+        Giv = 1/(1/G0iv - Sigmaiv)
+        Gl = siv.fit(Giv)
 
 You may want to start with reading up on the `intermediate representation`_.
 It is tied to the analytic continuation of bosonic/fermionic spectral
 functions from (real) frequencies to imaginary time, a transformation mediated
-by a kernel ``K``.  The kernel depends on a cutoff, which you should choose to
-be ``lambda_ >= beta * W``, where ``beta`` is the inverse temperature and ``W``
-is the bandwidth.
+by the kernel K(τ, ω) = e^{-τω}/(1 + e^{-βω}).  The basis depends on the
+inverse temperature ``beta`` and on the frequency cutoff ``wmax``, which you
+should choose so that the spectral function vanishes outside [-wmax, wmax].
+In the dimensionless variables x = 2τ/β - 1 and y = ω/wmax, the kernel, and
+hence its singular value expansion, depends on them only through the cutoff
+Λ = ``beta * wmax`` (``basis.lambda_``).
 
 One can now perform a `singular value expansion`_ on this kernel, which
-generates two sets of orthonormal basis functions, one set ``v[l](w)`` for
-real frequency side ``w``, and one set ``u[l](tau)`` for the same obejct in
-imaginary (Euclidean) time ``tau``, together with a "coupling" strength
-``s[l]`` between the two sides.
+generates two sets of orthonormal basis functions, one set V_l(ω),
+``basis.v[l](w)``, on the real-frequency axis, orthonormal on
+[-wmax, wmax], and one set U_l(τ), ``basis.u[l](tau)``, for the same object in
+imaginary (Euclidean) time, orthonormal on [0, beta], together with the
+singular values S_l, ``basis.s[l]``, which couple the two sides.
 
 By this construction, the imaginary time basis can be shown to be *optimal* in
 terms of compactness.

{sparse_ir-2.1.4 → sparse_ir-2.1.6}/README.rst

@@ -20,7 +20,7 @@ Install via `conda <https://anaconda.org/spm-lab/sparse-ir>`_::
 
 sparse-ir requires `numpy <https://numpy.org/>`_, `scipy <https://scipy.org/>`_,
 and `pylibsparseir <https://pypi.org/project/pylibsparseir>`_ (a thin Python wrapper
-for the `libsparseir <https://github.com/SpM-lab/libsparseir>`_ C API).
+for the libsparseir C API from `sparse-ir-rs <https://github.com/SpM-lab/sparse-ir-rs>`_).
 
 To manually install the current development version, you can use the following::
 
@@ -53,13 +53,21 @@ Lichtenstein formula, FLEX, ... - are presented.
 Refer to the `API documentation`_ for more details on how to work
 with the python library.
 
+The symbols and conventions are defined on the `notation page`_, shared with
+the tutorial and the Julia and C libraries.  In short: G(τ) = -⟨T c(τ) c†(0)⟩
+for both statistics; Matsubara frequencies iν are passed as the reduced
+frequency n, an integer with ν = nπ/β (odd for fermions, even for bosons);
+G(iν) = ∫₀^β dτ e^{iντ} G(τ); and G(τ) is evaluated for τ in [-β, β], where
+``-0.0`` stands for 0⁻.
+
 There is also a `Julia library`_ and (currently somewhat restricted)
 `C library with Fortran bindings`_ available for the IR basis and sparse sampling.
 
-.. _comprehensive tutorial: https://spm-lab.github.io/sparse-ir-tutorial
+.. _comprehensive tutorial: https://spm-lab.github.io/sparse-ir-tutorial-v2/
 .. _API documentation: https://sparse-ir.readthedocs.io
+.. _notation page: https://spm-lab.github.io/sparse-ir-doc/src/notation.html
 .. _Julia library: https://github.com/SpM-lab/SparseIR.jl
-.. _C library with Fortran bindings: https://github.com/SpM-lab/libsparseir
+.. _C library with Fortran bindings: https://github.com/SpM-lab/sparse-ir-rs
 
 Getting started
 ---------------
@@ -70,15 +78,16 @@ lines of Python code::
     import sparse_ir, numpy as np
     basis = sparse_ir.FiniteTempBasis('F', beta=10, wmax=8, eps=1e-6)
     stau = sparse_ir.TauSampling(basis)
-    siw = sparse_ir.MatsubaraSampling(basis, positive_only=True)
+    siv = sparse_ir.MatsubaraSampling(basis, positive_only=True)
 
     # Solve the single impurity Anderson model coupled to a bath with a
-    # semicircular states with unit half bandwidth.
+    # semicircular density of states with unit half bandwidth.
     U = 1.2
     def rho0w(w):
         return np.sqrt(1-w.clip(-1,1)**2) * 2/np.pi
 
-    # Compute the IR basis coefficients for the non-interacting propagator
+    # Compute the IR basis coefficients G0_l = -S_l rho0_l for the
+    # non-interacting propagator
     rho0l = basis.v.overlap(rho0w)
     G0l = -basis.s * rho0l
 
@@ -91,23 +100,27 @@ lines of Python code::
         Gtau = stau.evaluate(Gl)
         Sigmatau = U**2 * Gtau**3
         Sigmal = stau.fit(Sigmatau)
-        Sigmaiw = siw.evaluate(Sigmal)
-        G0iw = siw.evaluate(G0l)
-        Giw = 1/(1/G0iw - Sigmaiw)
-        Gl = siw.fit(Giw)
+        Sigmaiv = siv.evaluate(Sigmal)
+        G0iv = siv.evaluate(G0l)
+        Giv = 1/(1/G0iv - Sigmaiv)
+        Gl = siv.fit(Giv)
 
 You may want to start with reading up on the `intermediate representation`_.
 It is tied to the analytic continuation of bosonic/fermionic spectral
 functions from (real) frequencies to imaginary time, a transformation mediated
-by a kernel ``K``.  The kernel depends on a cutoff, which you should choose to
-be ``lambda_ >= beta * W``, where ``beta`` is the inverse temperature and ``W``
-is the bandwidth.
+by the kernel K(τ, ω) = e^{-τω}/(1 + e^{-βω}).  The basis depends on the
+inverse temperature ``beta`` and on the frequency cutoff ``wmax``, which you
+should choose so that the spectral function vanishes outside [-wmax, wmax].
+In the dimensionless variables x = 2τ/β - 1 and y = ω/wmax, the kernel, and
+hence its singular value expansion, depends on them only through the cutoff
+Λ = ``beta * wmax`` (``basis.lambda_``).
 
 One can now perform a `singular value expansion`_ on this kernel, which
-generates two sets of orthonormal basis functions, one set ``v[l](w)`` for
-real frequency side ``w``, and one set ``u[l](tau)`` for the same obejct in
-imaginary (Euclidean) time ``tau``, together with a "coupling" strength
-``s[l]`` between the two sides.
+generates two sets of orthonormal basis functions, one set V_l(ω),
+``basis.v[l](w)``, on the real-frequency axis, orthonormal on
+[-wmax, wmax], and one set U_l(τ), ``basis.u[l](tau)``, for the same object in
+imaginary (Euclidean) time, orthonormal on [0, beta], together with the
+singular values S_l, ``basis.s[l]``, which couple the two sides.
 
 By this construction, the imaginary time basis can be shown to be *optimal* in
 terms of compactness.

{sparse_ir-2.1.4 → sparse_ir-2.1.6}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "sparse-ir"
-version = "2.1.4"
+version = "2.1.6"
 description = "Python bindings for the libsparseir library, providing efficient sparse intermediate representation for many-body physics calculations"
 readme = "README.rst"
 requires-python = ">=3.10"
 dependencies = [
     "numpy",
     "scipy",
-    "pylibsparseir>=0.8.3,<0.10.0",
+    "pylibsparseir>=0.8.3,<0.13.0",
 ]
 authors = [
     {name = "SpM-lab"}
@@ -56,6 +56,14 @@ doc = [
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+# RegularizedBoseKernel is deprecated but still tested; test_kernel.py asserts
+# the warning itself (pytest.warns records it regardless of this filter).
+# An exception in a finalizer (__del__) must fail the suite, not be reported
+# as a warning (SpM-lab/sparse-ir-rs#282).
+filterwarnings = [
+    "ignore:RegularizedBoseKernel is deprecated:DeprecationWarning",
+    "error::pytest.PytestUnraisableExceptionWarning",
+]
 python_files = ["test_*.py", "*_tests.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]

{sparse_ir-2.1.4 → sparse_ir-2.1.6}/src/sparse_ir/_util.py

@@ -1,9 +1,41 @@
 # Copyright (C) 2020-2025 Satoshi Terasaki, Markus Wallerberger, Hiroshi Shinaoka, and others
 # SPDX-License-Identifier: MIT
 import functools
+import inspect
 import numpy as np
 
 
+def release_handle(handle, release):
+    """Release a C handle obtained from pylibsparseir or its ``_lib``.
+
+    pylibsparseir >= 0.10 returns handles that own their C object and are
+    released with ``close()``; its raw ``_lib.spir_*_release`` entry points
+    refuse them (SpM-lab/sparse-ir-rs#282).  Earlier releases, and direct
+    ``_lib`` calls in any release, return raw pointers that must be passed to
+    ``release``.
+    """
+    close = getattr(handle, "close", None)
+    if close is not None:
+        close()
+    else:
+        release(handle)
+
+
+def has_basis_size_argument(fn):
+    """True if the pylibsparseir function ``fn`` takes ``basis_size``.
+
+    pylibsparseir >= 0.10 changed ``basis_get_default_matsus_ext`` from
+    ``(basis, positive_only, points)`` to
+    ``(basis, basis_size, positive_only, fence=False)``, returning the points
+    (SpM-lab/sparse-ir-rs#274).  The signature is checked rather than the
+    version, since development builds may report an older version.
+    """
+    try:
+        return "basis_size" in inspect.signature(fn).parameters
+    except (TypeError, ValueError):
+        return False
+
+
 def ravel_argument(last_dim=False):
     """Wrap function operating on 1-D numpy array to allow arbitrary shapes.
 
@@ -46,10 +78,12 @@ _REAL_KINDS = "biuf"
 def check_reduced_matsubara(n, zeta=None):
     """Checks that ``n`` is a reduced Matsubara frequency.
 
-    Check that the argument is a reduced Matsubara frequency, which is an
-    integer obtained by scaling the freqency `w[n]` as follows::
+    Check that the argument is a reduced Matsubara frequency, which is the
+    integer ``n`` obtained by scaling the frequency ``nu`` as follows::
+
+        beta / np.pi * nu == n == 2 * m + zeta
 
-        beta / np.pi * w[n] == 2 * n + zeta
+    where ``m`` is the ordinary Matsubara index.
 
     Note that this means that instead of a fermionic frequency (``zeta == 1``),
     we expect an odd integer, while for a bosonic frequency (``zeta == 0``),
@@ -74,6 +108,11 @@ def check_reduced_matsubara(n, zeta=None):
             raise ValueError(
                 "reduced Matsubara frequency must be finite, got "
                 f"{nfloat[~np.isfinite(nfloat)][0]!r}")
+        beyond = np.abs(nfloat) >= 2.0**63
+        if beyond.any():
+            raise ValueError(
+                "reduced Matsubara frequency is out of the int64 range, got "
+                f"{np.atleast_1d(nfloat)[np.atleast_1d(beyond)][0]!r}")
         n = np.rint(nfloat).astype(np.int64)
         bad = n != nfloat
         if bad.any():
@@ -142,11 +181,52 @@ def as_boundary_complex(a, name="array", check_finite=True):
     return out
 
 
+def check_domain(x, xmin, xmax, name="evaluation points"):
+    """Check that every element of ``x`` is real, finite and in ``[xmin, xmax]``.
+
+    Returns ``x`` unchanged.  Called before evaluation points are handed to
+    the C library, which would otherwise panic on an out-of-domain point
+    (SpM-lab/sparse-ir-rs#266) and report an internal error.
+
+    Raises:
+        TypeError: if ``x`` is complex or of a non-numeric element type.
+        ValueError: naming the first offending value otherwise.
+    """
+    arr = np.asarray(x)
+    if arr.dtype.kind == 'c':
+        raise TypeError(f"{name} must be real-valued, got dtype {arr.dtype}")
+    if arr.dtype.kind not in _REAL_KINDS:
+        raise TypeError(f"{name} has unsupported dtype {arr.dtype}")
+    xf = np.asarray(arr, dtype=np.float64)
+    bad = ~np.isfinite(xf) | (xf < xmin) | (xf > xmax)
+    if bad.any():
+        offending = np.atleast_1d(xf)[np.atleast_1d(bad)][0]
+        raise ValueError(f"{name} must be finite and lie in [{xmin}, {xmax}], "
+                         f"got {offending!r}")
+    return x
+
+
+def check_unique(points, name="sampling_points"):
+    """Raise ValueError if the one-dimensional ``points`` contain a duplicate.
+
+    Duplicated sampling points make the sampling matrix rank-deficient, which
+    the C library accepts silently.
+    """
+    arr = np.asarray(points)
+    values, counts = np.unique(arr, return_counts=True)
+    if (counts > 1).any():
+        dup = values[counts > 1][0]
+        first, second = np.flatnonzero(arr == dup)[:2]
+        raise ValueError(f"{name} contains the duplicate value {dup!r} at "
+                         f"indices {first} and {second}; sampling points must "
+                         "be pairwise distinct")
+
+
 def as_boundary_matsubara(n, name="Matsubara indices", zeta=None):
-    """Normalize reduced Matsubara indices into a C-contiguous ``int64`` array.
+    """Normalize reduced Matsubara frequencies into a C-contiguous ``int64`` array.
 
     Validates integrality (and, if ``zeta`` is given, parity) *before* the
-    conversion, so a non-integral index raises instead of being truncated.
+    conversion, so a non-integral value raises instead of being truncated.
     """
     checked = check_reduced_matsubara(n, zeta=zeta)
     return np.ascontiguousarray(checked, dtype=np.int64)
@@ -242,11 +322,14 @@ def normalize_tau(statistics, tau, beta):
     Raises:
         ValueError: If tau is outside [-β, β] or statistics is invalid.
         
-    Special cases:
-        - Negative zero (τ = -0.0) is treated as τ = β with appropriate sign
-        - For τ in [0, β]: returns (τ, +1)
-        - For τ in [-β, 0): returns (τ + β, sign) where sign depends on statistics
-        
+    Special cases, with (-1)^ζ = -1 for fermions and +1 for bosons:
+        - For τ = +0.0 and τ in (0, β]: returns (τ, +1); +0.0 is read as 0⁺
+          and β as β⁻
+        - Negative zero (τ = -0.0) is read as 0⁻: returns (β, (-1)^ζ), since
+          f(0⁻) = (-1)^ζ f(β⁻)
+        - For τ in [-β, 0): returns (τ + β, (-1)^ζ); in particular -β, read
+          as (-β)⁺, gives (0, (-1)^ζ)
+
     .. versionadded:: 1.2
     """
     tau = np.asarray(tau, dtype=np.float64)
@@ -296,3 +379,27 @@ def check_svd_result(svd_result, matrix_shape=None):
             raise ValueError(f"shape mismatch between SVD ({m_u}, {n_v}) "
                              f"and matrix ({m}, {n})")
     return u, s, vH
+
+def slice_to_size(index, size):
+    """Return the number of basis functions selected by ``index``.
+
+    Only ``basis[:stop]``-style truncation is supported, mirroring
+    :py:meth:`FiniteTempBasis.__getitem__`.
+    """
+    if not isinstance(index, slice):
+        raise TypeError(
+            f"only slice truncation is supported, got {index!r}")
+    if index.start not in (None, 0):
+        raise ValueError(
+            f"basis truncation must start at 0, got {index.start!r}")
+    if index.step not in (None, 1):
+        raise ValueError(
+            f"basis truncation must have unit step, got {index.step!r}")
+    if index.stop is None:
+        return size
+    stop = int(index.stop)
+    if not 0 < stop <= size:
+        raise IndexError(
+            f"truncation to {stop} functions is out of range for a basis of "
+            f"size {size}")
+    return stop

{sparse_ir-2.1.4 → sparse_ir-2.1.6}/src/sparse_ir/abstract.py

@@ -9,7 +9,12 @@ This module provides the abstract interface that all basis types should implemen
 from abc import ABC, abstractmethod
 
 class AbstractKernel(ABC):
-    """Abstract base class for kernels."""
+    """Abstract base class for kernels.
+
+    It defines no interface of its own: the supported kernels are
+    :class:`~sparse_ir.LogisticKernel` and the deprecated
+    :class:`~sparse_ir.RegularizedBoseKernel`.
+    """
     pass
 
 class AbstractBasis(ABC):
@@ -18,20 +23,34 @@ class AbstractBasis(ABC):
     This class stores a set of basis functions. We can then expand a two-point
     propagator G(τ), where τ is imaginary time:
 
-        G(τ) ≈ Σ_{l=0}^{L-1} g_l U_l(τ)
+    .. math::
+
+        G(\tau) \approx \sum_{l=0}^{L-1} G_l U_l(\tau),
+
+    where :math:`U_l` is the l-th basis function, stored in :py:attr:`u`, and
+    the :math:`G_l` are the expansion coefficients.  Similarly, the Fourier
+    transform G(iν) at the Matsubara frequency ν = nπ/β, where n is a reduced
+    Matsubara frequency, can be expanded as follows:
 
-    where U is now the l-th basis function, stored in u and g denote the
-    expansion coefficients. Similarly, the Fourier transform Ĝ(n), where n
-    is a reduced Matsubara frequency, can be expanded as follows:
+    .. math::
 
-        Ĝ(n) ≈ Σ_{l=0}^{L-1} g_l Û_l(n)
+        G(\mathrm{i}\nu) \approx \sum_{l=0}^{L-1} G_l \hat U_l(\mathrm{i}\nu),
 
-    where Û is the Fourier transform of the l-th basis function, stored
-    in uhat.
+    where :math:`\hat U_l` is the Fourier transform of the l-th basis
+    function, stored in :py:attr:`uhat`.  The Fourier transform and its
+    inverse are
 
-    Assuming that basis is an instance of some abstract basis, g is a vector
-    of expansion coefficients, tau is some imaginary time and n some frequency,
-    we can write this in the library as follows:
+    .. math::
+
+        G(\mathrm{i}\nu) = \int_0^\beta d\tau\, e^{\mathrm{i}\nu\tau} G(\tau),
+        \qquad
+        G(\tau) = \frac{1}{\beta} \sum_\nu e^{-\mathrm{i}\nu\tau}
+        G(\mathrm{i}\nu).
+
+    Assuming that ``basis`` is an instance of some abstract basis, ``gl`` is
+    a vector of expansion coefficients G_l, ``tau`` is some imaginary time and
+    ``n`` some reduced frequency, we can write this in the library as
+    follows::
 
         G_tau = basis.u(tau).T @ gl
         G_n = basis.uhat(n).T @ gl
@@ -42,9 +61,13 @@ class AbstractBasis(ABC):
     def u(self):
         r"""Basis functions on the imaginary time axis.
 
-        Set of IR basis functions on the imaginary time (tau) axis, where tau
-        is a real number between zero and beta. To get the l-th basis function
-        at imaginary time tau of some basis, use:
+        Set of basis functions :math:`U_l(\tau)` on the imaginary time (tau)
+        axis, where tau is a real number in [-beta, beta].  Negative times
+        follow :math:`U_l(\tau) = (-1)^\zeta U_l(\tau + \beta)`, where
+        :math:`(-1)^\zeta` is -1 for fermions and +1 for bosons, and the
+        endpoints are one-sided limits: ``+0.0`` is 0⁺, ``beta`` is β⁻,
+        ``-0.0`` is 0⁻ and ``-beta`` is (-β)⁺.  To get the l-th basis function
+        at imaginary time tau of some basis, use::
 
             ultau = basis.u[l](tau)        # l-th basis function at time tau
 
@@ -55,24 +78,30 @@ class AbstractBasis(ABC):
     @property
     @abstractmethod
     def uhat(self):
-        r"""Basis functions on the reduced Matsubara frequency (wn) axis.
+        r"""Basis functions on the reduced Matsubara frequency axis.
+
+        Set of basis functions :math:`\hat U_l(\mathrm{i}\nu)` at the
+        Matsubara frequencies ν = nπ/β, where the reduced frequency n is an
+        integer.  These are related to u by the following Fourier transform:
 
-        Set of IR basis functions reduced Matsubara frequency (wn) axis, where
-        wn is an integer. These are related to u by the following Fourier transform:
+        .. math::
 
-           û(n) = ∫₀^β dτ exp(iπnτ/β) u(τ)
+            \hat U_l(\mathrm{i}\nu) = \int_0^\beta d\tau\,
+            e^{\mathrm{i}\nu\tau} U_l(\tau).
 
-        To get the l-th basis function at some reduced frequency wn of
-        some basis, use:
+        To get the l-th basis function at some reduced frequency n of
+        some basis, use::
 
-            uln = basis.uhat[l](wn)        # l-th basis function at freq wn
+            uln = basis.uhat[l](n)        # l-th basis function at iν, ν = nπ/β
 
         Note:
             Instead of the value of the Matsubara frequency, these functions
-            expect integers corresponding to the prefactor of pi over beta.
-            For example, the first few positive fermionic frequencies would
-            be specified as [1, 3, 5, 7], and the first bosonic frequencies
-            are [0, 2, 4, 6]. This is also distinct to an index!
+            expect the reduced frequency n = βν/π, the integer prefactor of
+            π/β.  For example, the first few positive fermionic frequencies
+            would be specified as [1, 3, 5, 7], and the first bosonic
+            frequencies are [0, 2, 4, 6]: n is odd for fermions and even for
+            bosons.  It is not the ordinary Matsubara index m, which gives
+            n = 2m + ζ (ζ = 1 for fermions, 0 for bosons).
         """
         raise NotImplementedError()
 
@@ -117,7 +146,11 @@ class AbstractBasis(ABC):
         """Accuracy of the basis.
 
         Upper bound to the relative error of representing a propagator with
-        the given number of basis functions (number between 0 and 1).
+        the given number of basis functions (number between 0 and 1).  This
+        default returns the smallest significance, ``significance[-1]``;
+        :class:`~sparse_ir.FiniteTempBasis` overrides it with S_L/S_0 of the
+        first discarded singular value, and the DLR and augmented bases
+        return the accuracy of their underlying basis.
         """
         return self.significance[-1]
 
@@ -161,10 +194,9 @@ class AbstractBasis(ABC):
         npoints : int, optional
             Minimum number of sampling points to return.
         positive_only : bool
-            Only return non-negative frequencies. This is useful if the
-            object to be fitted is symmetric in Matsubara frequency,
-            ghat(w) == ghat(-w).conj(), or, equivalently, real in
-            imaginary time.
+            Only return non-negative frequencies, n >= 0. This is useful if
+            the object to be fitted is symmetric in Matsubara frequency,
+            G(-iν) = G(iν)*, or, equivalently, real in imaginary time.
         """
         raise NotImplementedError()