sdos 0.1.0__py3-none-any.whl

sdos/__init__.py

@@ -0,0 +1,34 @@
+"""sdos: order-N spectral density of states for large sparse Hermitian problems.
+
+Stochastic trace estimation (Drabold-Sankey) with the kernel polynomial method or maximum entropy,
+plus shift-invert windows.  Works for real symmetric and complex Hermitian matrices, explicit or
+matrix-free.  See ``sdos.estimate_dos`` and the ``sdos`` command.
+"""
+
+__version__ = "0.1.0"
+
+from .api import dos
+from .bounds import distance_coloring, spectral_bounds
+from .dos import DOSResult, estimate_dos, fermi_and_band_energy, fermi_interval
+from .results import load, save_result
+from .io import read_matrix, write_dos, write_triplets
+from .maxent import band_quantities_grid, maxent, maxent_bootstrap, maxent_density, maxent_fit
+from .moments import chebyshev_moments, chebyshev_moments_plain, impartial_vector, make_vectors, moment_errors, stochastic_moments
+from .operators import HermitianError, ScaledOperator, check_hermitian
+from .reconstruct import band_quantities, jackson, lorentz, reconstruct
+from .eigwin import WindowResult, count_states_below, homo_lumo, ipr, mulliken_weights, window_eigs
+from .exact import exact_chebyshev_moments
+from .generalized import GeneralizedOperator, generalized_bounds, pcg
+from .phonon import vdos
+from .projections import ProjectedResult, ldos, pdos, site_groups
+from .thermo import HBAR_OMEGA_METAL, ThermoResult, harmonic_thermo
+from .windows import shift_invert_dos, si_nodes
+
+__all__ = [
+    "__version__", "dos", "load", "save_result", "vdos", "DOSResult", "estimate_dos", "fermi_and_band_energy", "fermi_interval", "read_matrix", "write_dos",
+    "write_triplets", "spectral_bounds", "distance_coloring", "chebyshev_moments", "make_vectors",
+    "stochastic_moments", "moment_errors", "impartial_vector", "jackson", "lorentz", "reconstruct", "band_quantities",
+    "maxent", "maxent_bootstrap", "maxent_fit", "maxent_density", "band_quantities_grid", "shift_invert_dos", "si_nodes",
+    "check_hermitian", "HermitianError", "ScaledOperator", "exact_chebyshev_moments", "GeneralizedOperator",
+    "generalized_bounds", "pcg", "window_eigs", "WindowResult", "count_states_below", "homo_lumo", "harmonic_thermo", "ThermoResult", "HBAR_OMEGA_METAL", "pdos", "ldos", "site_groups", "ProjectedResult", "ipr", "mulliken_weights", "chebyshev_moments_plain",
+]

sdos/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

sdos/api.py

@@ -0,0 +1,80 @@
+"""The simple front door: ``sdos.dos(A)`` gives the density of states of a big sparse matrix with sensible defaults;
+every advanced option of :func:`sdos.estimate_dos` is available as a keyword when needed."""
+
+import os
+
+import warnings
+import numpy as np
+import scipy.sparse as sp
+import scipy.sparse.linalg as spla
+
+from .bounds import spectral_bounds
+from .dos import estimate_dos
+from .generalized import GeneralizedOperator, generalized_bounds, is_diagonal
+from .io import read_matrix
+from .operators import is_complex
+
+
+def _as_matrix(A, name):
+    if isinstance(A, (str, os.PathLike)):
+        return read_matrix(A, verbose=False)
+    if isinstance(A, np.ndarray) and A.ndim == 2:
+        return sp.csr_matrix(A)
+    if sp.issparse(A):
+        return A.tocsr()
+    if isinstance(A, spla.LinearOperator):
+        return A
+    raise TypeError(f"{name}: expected a file path, a 2-D array, a SciPy sparse matrix or a LinearOperator")
+
+
+def dos(A, B=None, *, M=None, R=None, resolution=None, quick=False, exact_moments="auto", method="kpm", seed=None,
+        verbose=False, **options):
+    """Density of states of a large sparse Hermitian matrix A (or of A x = lambda B x).
+
+    ``A`` and ``B`` can be a file name (triplets, Matrix Market or .npz), a dense/sparse matrix, or (A only) a matrix-free
+    ``LinearOperator``; a 1-D ``B`` is a diagonal B (e.g. masses).  Real or complex Hermitian is detected automatically.
+
+    Defaults: 256 moments and 10 random vectors (``quick=True``: 128 and 4), Jackson kernel, the first 4 moments exact (cheap local
+    method; set ``exact_moments=0`` to turn it off; the default is 0 for method="maxent" with R = 1), PCG with block-Jacobi for a generalized B.  Give an energy ``resolution`` instead
+    of ``M`` to choose the number of moments from it.  Anything else of :func:`sdos.estimate_dos` can be passed as a keyword
+    (``method='maxent'``, ``vectors='impartial'``, ``binv='chebyshev'``, ``probe=2`` ...).
+
+    Returns a :class:`~sdos.DOSResult`: ``res.E``, ``res.rho`` (per orbital, integrates to 1), ``res.rho_err``, ``res.idos``,
+    ``res.plot()``, ``res.save(path)``.  Multiply ``rho`` by N for states per unit energy.
+    """
+    A = _as_matrix(A, "A")
+    if B is not None and not (isinstance(B, np.ndarray) and B.ndim == 1):
+        B = _as_matrix(B, "B")
+    if R is None:
+        R = 4 if quick else 10
+    explicit = sp.issparse(A)
+    diag_B = B is None or (isinstance(B, np.ndarray) and B.ndim == 1) or (sp.issparse(B) and is_diagonal(B))
+    if exact_moments == "auto":
+        exact_moments = 4 if (explicit and diag_B and method == "kpm" or explicit and diag_B and method == "maxent") else 0
+        if method == "maxent" and R < 2:
+            exact_moments = 0              # Maxent with one vector and spliced moments does not converge (see estimate_dos); no substitution by default
+    if M is None and resolution is not None:
+        # window width from the bounds, then M ~ pi a / resolution
+        if B is None or diag_B:
+            if B is not None:
+                d = np.real(B.diagonal()) if sp.issparse(B) else np.asarray(B, float)
+                Aw = sp.diags(1 / np.sqrt(d)) @ A @ sp.diags(1 / np.sqrt(d))
+            else:
+                Aw = A
+            lo, hi = spectral_bounds(Aw, verbose=False)
+        else:
+            op = GeneralizedOperator(A, B, binv=options.get("binv", "pcg"), tol=options.get("binv_tol", 1e-12),
+                                     block_size=options.get("block_size", 1), check=False)
+            lo, hi, rs = generalized_bounds(op.apply, op.B, A.shape[0], seed=0, is_cplx=bool(is_complex(A)))
+            lo, hi = lo - rs, hi + rs
+        M = int(np.ceil(np.pi * 0.5 * (hi - lo) * 1.02 / resolution))
+    if M is None:
+        M = 128 if quick else 256
+    if method == "maxent":
+        options.setdefault("maxent_default", "flat")          # uniform default model; measured equal in accuracy and conditioning to the alternatives (docs/theory.md)
+    if M >= A.shape[0]:
+        warnings.warn(f"M={M} >= N={A.shape[0]}: the resolution pi*a/M is finer than the mean level spacing, the density resolves individual levels and sampling speckle; "
+                      "for such a small matrix dense diagonalization (numpy.linalg.eigvalsh) is cheaper and exact.", stacklevel=2)
+    if exact_moments and exact_moments >= M:
+        exact_moments = max(0, M - 1)
+    return estimate_dos(A, B=B, M=M, R=R, method=method, seed=seed, verbose=verbose, exact_moments=exact_moments, **options)

sdos/bounds.py

@@ -0,0 +1,67 @@
+"""Spectral bounds and probing colorings."""
+
+import sys
+
+import numpy as np
+import scipy.sparse as sp
+import scipy.sparse.linalg as spla
+
+
+def spectral_bounds(H, method="lanczos", verbose=True, v0_seed=12345):
+    """Return (Emin, Emax): guaranteed (Gershgorin, explicit matrices only) or estimated (Lanczos).
+
+    Lanczos extremal Ritz values lie *inside* the spectrum, so callers add a safety margin
+    (``estimate_dos(margin=...)``); for matrix-free operators only the Lanczos route exists.
+    The ARPACK start vector is generated from ``v0_seed`` so the bounds (and hence the whole DOS for a given ``seed``) are
+    reproducible; the original sdos.py let ARPACK pick a random start, so repeated runs differed at the 1e-4 level in the bounds.
+    """
+    n = H.shape[0]
+    explicit = sp.issparse(H)
+    if explicit:
+        absH = abs(H)
+        d = np.real(H.diagonal())
+        radius = np.asarray(absH.sum(axis=1)).ravel() - np.abs(d)
+        gmin, gmax = float((d - radius).min()), float((d + radius).max())
+        if method == "gershgorin" or n < 3:
+            return gmin, gmax
+    elif method == "gershgorin":
+        raise ValueError("Gershgorin bounds need an explicit sparse matrix")
+    try:
+        v0 = np.random.default_rng(v0_seed).normal(size=n)
+        if np.issubdtype(H.dtype, np.complexfloating):
+            v0 = v0 + 1j * np.random.default_rng(v0_seed + 1).normal(size=n)
+        kw = dict(k=1, tol=1e-3, maxiter=max(300, 10 * int(np.sqrt(n))), v0=v0)
+        emax = float(np.real(spla.eigsh(H, which="LA", return_eigenvectors=False, **kw)[0]))
+        emin = float(np.real(spla.eigsh(H, which="SA", return_eigenvectors=False, **kw)[0]))
+        return emin, emax
+    except Exception as exc:  # fall back to the safe bounds when they exist
+        if not explicit:
+            raise
+        if verbose:
+            print(f"Lanczos bounds failed ({exc}); using Gershgorin", file=sys.stderr)
+        return gmin, gmax
+
+
+def distance_coloring(H, d):
+    """Greedy coloring such that same-colored sites are > d hops apart (explicit matrices only)."""
+    n = H.shape[0]
+    G = H.copy().tocsr()
+    G.data = np.ones_like(G.data, dtype=np.int8)
+    G = (G + sp.identity(n, dtype=np.int8, format="csr")).astype(bool).astype(np.int8)
+    P = G.copy()
+    for _ in range(d - 1):
+        P = (P @ G).astype(bool).astype(np.int8)
+    P = P.tocsr()
+    indptr, indices = P.indptr, P.indices
+    colors = -np.ones(n, dtype=np.int64)
+    mark = -np.ones(n + 1, dtype=np.int64)   # mark[c] = node that saw color c
+    order = np.argsort(-np.diff(indptr), kind="stable")  # high degree first
+    for i in order:
+        nb = indices[indptr[i]:indptr[i + 1]]
+        cs = colors[nb]
+        mark[cs[cs >= 0]] = i
+        c = 0
+        while mark[c] == i:
+            c += 1
+        colors[i] = c
+    return colors, int(colors.max()) + 1

sdos/cli.py

@@ -0,0 +1,186 @@
+"""Command-line interface: ``sdos H.dat -M 512 -R 10 --probe 2 -o dos.dat --electrons 4096``."""
+
+import argparse
+import sys
+
+import numpy as np
+
+from . import __version__
+from .api import dos as dos_api
+from .dos import fermi_and_band_energy
+from .phonon import vdos
+from .io import read_matrix, write_dos
+from .windows import shift_invert_dos
+
+__doc__ += """
+
+Run ``sdos -h`` for all options.  Input: triplets ``i j Re(A_ij) [Im(A_ij)]`` (0/1-based, one
+triangle or both), Matrix Market, or SciPy ``.npz``.
+"""
+
+def main(argv=None):
+    if (argv if argv is not None else sys.argv[1:])[:1] == ["analyze"]:
+        from .results import analyze
+        return analyze((argv if argv is not None else sys.argv[1:])[1:])
+    p = argparse.ArgumentParser(prog="sdos", description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--version", action="version", version=f"sdos {__version__}")
+    p.add_argument("matrix", help="triplet file: i j Re [Im]  (or Matrix Market)")
+    p.add_argument("-M", "--moments", type=int, default=256,
+                   help="number of Chebyshev moments (resolution ~ pi*halfwidth/M)")
+    p.add_argument("-R", "--samples", type=int, default=10,
+                   help="number of independent random samples (for averaging and error bars)")
+    p.add_argument("--probe", type=int, default=0,
+                   help="distance-d coloring for probing (0 = plain random vectors)")
+    p.add_argument("--B", default=None, help="second matrix B of A x = lambda B x (same formats as the matrix; Hermitian positive definite)")
+    p.add_argument("--mass", default=None, help="text file with one mass (diagonal B) per degree of freedom: mass-weights once, no solves")
+    p.add_argument("--binv", choices=["pcg", "chebyshev"], default="pcg", help="how B^-1 is applied: PCG, or a fixed Chebyshev polynomial")
+    p.add_argument("--precond", choices=["block-jacobi", "ilu", "amg", "none"], default="block-jacobi", help="PCG preconditioner")
+    p.add_argument("--block-size", type=int, default=1, help="per-site block size for block-Jacobi / scaling (e.g. orbitals per atom)")
+    p.add_argument("--binv-tol", type=float, default=1e-12, help="PCG relative tolerance / polynomial accuracy")
+    p.add_argument("--exact-moments", default="auto", help="'auto' (first 4 moments exact when cheap), 0 (off) or K")
+    p.add_argument("--thermo", type=float, nargs=3, metavar=("TMIN", "TMAX", "NT"), help="with --omega: harmonic thermodynamics (U, F, S, Cv per atom) on a T grid, "
+                   "written to <output>.thermo (lambda in eV/(A^2 amu); use --zero-modes 3 for crystals/molecules)")
+    p.add_argument("--zero-modes", type=int, default=0, help="number of known zero modes (rigid translations: 3) to remove from the moments exactly")
+    p.add_argument("--omega", action="store_true", help="phonon output: write omega, g(omega)=2 omega rho(omega^2), error (lambda = omega^2)")
+    p.add_argument("--window", type=float, nargs=2, metavar=("E1", "E2"), help="eigenpairs inside [E1, E2] with the IPR of each state (see --window-method)")
+    p.add_argument("--window-method", choices=["auto", "shift-invert", "filter"], default="auto",
+                   help="shift-invert (exact, NOT O(N)) or Chebyshev-filtered subspace iteration (scalable)")
+    p.add_argument("--window-degree", type=int, default=300, help="filter polynomial degree")
+    p.add_argument("--vectors-out", default=None, help="save the window eigenvectors (npz) as well")
+    p.add_argument("--base", choices=["auto", "0", "1"], default="auto")
+    p.add_argument("--format", choices=["auto", "triplet", "mm", "npz"], default="auto", help="input format")
+    p.add_argument("--kernel", choices=["jackson", "lorentz"], default="jackson", help="KPM damping kernel")
+    p.add_argument("--lorentz-lambda", type=float, default=4.0, help="lambda of the Lorentz kernel")
+    p.add_argument("--vectors", choices=["auto", "phase", "rademacher", "gaussian", "impartial"], default="auto", help="random-vector ensemble; impartial = Drabold-Sankey penalty-function vectors (Maxent-friendly, first 3 moments exact)")
+    p.add_argument("--storage", choices=["auto", "triangle", "full"], default="auto")
+    p.add_argument("--emin", type=float, help="lower spectral bound (skip estimation)")
+    p.add_argument("--emax", type=float, help="upper spectral bound (skip estimation)")
+    p.add_argument("--complex-phases", action="store_true",
+                   help="use exp(i phi) vectors even for real H (half the variance, 2x cost)")
+    p.add_argument("--seed", type=int, default=None)
+    p.add_argument("--npts", type=int, default=None, help="energy grid points")
+    p.add_argument("--method", choices=["kpm", "maxent", "si"], default="kpm",
+                   help="kpm (Jackson kernel, default), maxent, or si (shift-and-invert "
+                        "Lanczos in a window; needs --si-range)")
+    p.add_argument("--si-range", type=float, nargs=2, metavar=("E1", "E2"),
+                   help="energy window for --method si (e.g. a gap/tail/defect region)")
+    p.add_argument("--si-shifts", type=int, default=1,
+                   help="number of shifts (LU factorizations) spread over the window")
+    p.add_argument("--si-steps", type=int, default=150,
+                   help="Lanczos steps per vector at each shift")
+    p.add_argument("--si-eta", type=float, default=None,
+                   help="Gaussian broadening of Ritz nodes (default: mean node spacing)")
+    p.add_argument("--maxent-default", choices=["chebyshev", "flat", "kpm"], default="chebyshev",
+                   help="Maxent default model: 1/(pi sqrt(1-x^2)) (default), flat, or kpm (the Jackson density; robust to a too-wide spectral window)")
+    p.add_argument("--maxent-noise", type=float, default=1.0,
+                   help="scale on moment standard errors in the Maxent dual (0 = fit moments exactly)")
+    p.add_argument("--electrons", type=float, default=None,
+                   help="number of electrons: report Fermi level and band energy")
+    p.add_argument("--spin", type=float, default=2.0, help="spin degeneracy (default 2)")
+    p.add_argument("-o", "--output", default="dos.dat",
+                   help="output file; a name ending in .npz saves a full result file (moments, settings) for `sdos analyze`")
+    p.add_argument("--moments-out", default=None, help="write averaged moments to file")
+    p.add_argument("--plot", default=None, help="save a plot (png/pdf)")
+    args = p.parse_args(argv)
+
+    H = read_matrix(args.matrix, base=args.base, storage=args.storage, fmt=args.format)
+    bounds = None
+    if args.emin is not None and args.emax is not None:
+        bounds = (args.emin, args.emax)
+    if args.window is not None:
+        from .eigwin import window_eigs
+        Bw = None
+        if args.B:
+            Bw = read_matrix(args.B, base=args.base, storage=args.storage, fmt=args.format)
+        elif args.mass:
+            Bw = np.loadtxt(args.mass).ravel()
+        w = window_eigs(H, Bw, tuple(args.window), method=args.window_method, degree=args.window_degree,
+                        block_size=args.block_size, precond=args.precond)
+        np.savetxt(args.output, np.column_stack([w["E"], w["ipr"], w["residual"]]),
+                   header=f"sdos window [{args.window[0]}, {args.window[1]}] method={w['info']['method']} n_found={len(w['E'])} "
+                          f"(KPM estimate {w['info']['n_estimated']:.1f})\nE   IPR   residual", fmt="%.10e")
+        if args.vectors_out:
+            np.savez(args.vectors_out, E=w["E"], V=w["V"], ipr=w["ipr"])
+        print(f"{len(w['E'])} states in the window ({w['info']['method']}); wrote {args.output}")
+        return
+    if args.method == "si":
+        if args.si_range is None:
+            p.error("--method si requires --si-range E1 E2")
+        res = shift_invert_dos(H, args.si_range, nshift=args.si_shifts, m=args.si_steps,
+                               R=args.samples, eta=args.si_eta, npts=args.npts,
+                               seed=args.seed, complex_phases=args.complex_phases or None)
+        if args.electrons is not None:
+            print("note: --electrons ignored for --method si (window DOS only)", file=sys.stderr)
+            args.electrons = None
+    else:
+        Bobj = None
+        if args.B:
+            Bobj = read_matrix(args.B, base=args.base, storage=args.storage, fmt=args.format)
+        elif args.mass:
+            Bobj = np.loadtxt(args.mass).ravel()
+        exact = "auto" if args.exact_moments == "auto" else int(args.exact_moments)
+        kw = dict(M=args.moments, R=args.samples, probe=args.probe, bounds=bounds, complex_phases=args.complex_phases or None,
+                  seed=args.seed, npts=args.npts, method=args.method, maxent_default=args.maxent_default,
+                  maxent_noise=args.maxent_noise, kernel=args.kernel, lorentz_lambda=args.lorentz_lambda, vectors=args.vectors,
+                  exact_moments=exact, binv=args.binv, precond=args.precond, block_size=args.block_size, binv_tol=args.binv_tol,
+                  verbose=True)
+        res = vdos(H, B=Bobj, zero_modes=args.zero_modes, **kw) if args.omega else dos_api(H, B=Bobj, **kw)
+
+    N = res["N"]
+    if res["method"] == "kpm":
+        recon = f"Jackson resolution ~ {res['resolution']:.4g}"
+    elif res["method"] == "si":
+        recon = f"shift-invert Lanczos, window {res['erange']}, eta ~ {res['resolution']:.4g}"
+    else:
+        recon = f"Maxent, {res['maxent_default']} default"
+    header = (f"sdos {__version__}  N={N}  M={res['M']}  samples={res['R']}  colors={res['ncolors']}  "
+              f"{recon}\n"
+              "E   rho(E) [per orbital, integrates to 1]   err   IDOS(E) [fraction]   err")
+    if args.output.endswith(".npz"):
+        from .results import save_result
+        save_result(args.output, res, {"command": " ".join(sys.argv[1:]) if argv is None else " ".join(argv), "matrix": args.matrix})
+    elif args.omega and "omega" in res:
+        np.savetxt(args.output, np.column_stack([res["omega"], res["g"], res["g_err"]]),
+                   header=header + "\nomega  g(omega)=2 omega rho(omega^2) [integrates to 1 - neg. weight]  err", fmt="%.10e")
+    else:
+        np.savetxt(args.output, np.column_stack([res["E"], res["rho"], res["rho_err"],
+                                                 res["idos"], res["idos_err"]]),
+                   header=header, fmt="%.10e")
+    print(f"wrote {args.output}")
+    if args.thermo and args.omega:
+        from .thermo import harmonic_thermo
+        Tg = np.linspace(args.thermo[0], args.thermo[1], int(args.thermo[2]))
+        th = harmonic_thermo(res, Tg)
+        np.savetxt(args.output + ".thermo", np.column_stack([Tg, th["U"], th["F"], th["S"], th["Cv"]]),
+                   header=f"harmonic thermodynamics per atom; zero-point energy {th['zpe']:.6g} eV; reliable for T >~ {th['info']['T_reliable']:.0f} K\nT[K]  U[eV]  F[eV]  S[kB]  Cv[kB]", fmt="%.8e")
+        print(f"wrote {args.output}.thermo (zero-point energy {th['zpe']:.5g} eV/atom; reliable for T >~ {th['info']['T_reliable']:.0f} K)")
+    if args.moments_out:
+        np.savetxt(args.moments_out, res["mu"], header="mu_n = Tr T_n(Ht)/N", fmt="%.12e")
+
+    if args.electrons is not None:
+        EF, Ebs, dEF, dEbs = fermi_and_band_energy(res, args.electrons, args.spin)
+        if res["R"] > 1:
+            print(f"E_F = {EF:.6f} +- {dEF:.2g}    E_BS = {Ebs:.6f} +- {dEbs:.2g}  "
+                  f"({Ebs / args.electrons:.6f} per electron)")
+        else:
+            print(f"E_F = {EF:.6f}    E_BS = {Ebs:.6f}  ({Ebs / args.electrons:.6f} per electron)")
+
+    if args.plot:
+        import matplotlib
+        matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+        fig, ax = plt.subplots(figsize=(7, 4))
+        ax.plot(res["E"], res["rho"], lw=1)
+        if res["R"] > 1:
+            ax.fill_between(res["E"], res["rho"] - 2 * res["rho_err"],
+                            res["rho"] + 2 * res["rho_err"], alpha=0.3, lw=0)
+        ax.set_xlabel("E")
+        ax.set_ylabel("DOS per orbital")
+        ax.set_title(f"N = {N}, M = {res['M']}, {res['R']} sample(s), {res['method'].upper()}")
+        fig.tight_layout()
+        fig.savefig(args.plot, dpi=150)
+        print(f"wrote {args.plot}")
+
+if __name__ == "__main__":
+    main()