sdos 0.1.0__tar.gz

sdos-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, David A. Drabold
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

sdos-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: sdos
+Version: 0.1.0
+Summary: Order-N spectral density of states (KPM, Maxent, shift-invert) for large sparse Hermitian problems
+Author-email: "David A. Drabold" <drabold@ohio.edu>
+License-Expression: BSD-3-Clause
+Keywords: density of states,kernel polynomial method,maximum entropy,sparse eigenvalue,tight binding,vibrational spectra
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: scipy>=1.8
+Provides-Extra: plot
+Requires-Dist: matplotlib; extra == "plot"
+Provides-Extra: amg
+Requires-Dist: pyamg; extra == "amg"
+Provides-Extra: sisl
+Requires-Dist: sisl; extra == "sisl"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# sdos
+
+The density of states of a big sparse matrix, in one call.  Order-N stochastic trace estimation with the kernel polynomial
+method (KPM) or maximum entropy; real symmetric or complex Hermitian; explicit or matrix-free; standard `A x = λ x` or
+generalized `A x = λ B x`; electrons or phonons.
+
+Status: **0.1.0, first public release.**  The method, its tests against dense diagonalization and an independent code, benchmarks up to
+millions of atoms, and the limits of the approach (what does not scale) are described in the report in `paper/` (REVTeX source and bibliography).
+Docs: `docs/guide.md`, `docs/theory.md`.  Tests: `pip install -e ".[test]" && pytest`.
+
+**In short.**  `sdos` estimates the density of states of a large sparse Hermitian matrix (or a generalized problem with an overlap or mass matrix)
+from Chebyshev moments computed with random vectors, so the cost grows linearly with the matrix size.  The density is reconstructed by the kernel
+polynomial method or by maximum entropy, and the same moments give band energies, Fermi levels, local and projected densities and harmonic
+thermodynamics.  Interfaces: tight-binding and DFTB Hamiltonians, SIESTA through sisl, and matrix-free LAMMPS Hessians for phonons.
+The underlying methods are due to Silver, Röder, Kress, Voter, Drabold, Sankey and collaborators; the report states what is added.
+
+## Install
+
+    pip install -e ".[test]"        # from a clone; add [plot] for matplotlib, [amg] for the AMG preconditioner
+
+## The simple way
+
+```python
+import sdos
+res = sdos.dos("H.npz")            # a file (triplets, Matrix Market, .npz), a SciPy sparse matrix, an array, or a LinearOperator
+res.plot()                         # DOS with error bars
+E, rho = res.E, res.rho            # rho: per orbital, integrates to 1 (multiply by N for states per unit energy)
+res.save("dos.txt")
+```
+
+Real or complex is detected, defaults are sensible (256 moments, 10 random vectors, first 4 moments exact), and nothing else is
+needed.  From the shell:  `sdos H.npz -o dos.dat --plot dos.png`.
+
+**Input.**  The simplest matrix file is plain text, one entry per line, `i j a_ij` (a fourth column is the imaginary part).
+Give one triangle or both; 0- or 1-based indices and the storage are detected automatically, and the other triangle is
+generated by conjugation.  Matrix Market and SciPy `.npz` also work.
+
+**Save, then analyse later.**  The DOS stage needs only the matrix.  Save everything it produced (DOS, error bars, moments,
+spectral window, settings) and analyse it afterwards, with no matrix:
+
+    sdos H.dat -o result.npz                          # a .npz name saves the full result
+    sdos analyze result.npz --valence-file Z.txt      # electrons: E_F and band energy (Z of each atom, one per line)
+    sdos analyze result.npz --electrons 4096 --spin 2
+    sdos analyze phonons.npz --thermo 10 1000 50      # vibrations: ZPE, U, F, S, Cv (result made with --omega)
+    sdos analyze result.npz --moments 60 --method maxent -o dos.txt   # re-reconstruct from the saved moments
+
+In Python: `res.save("result.npz")`, `res = sdos.load("result.npz")`.  The DOS is generic; electron counts, spin and
+temperature enter only in the analysis step.
+
+```python
+sdos.dos(H, resolution=0.05)       # choose the energy resolution instead of the number of moments
+sdos.dos(H, quick=True)            # fast look: 128 moments, 4 vectors
+sdos.dos(H, B=S)                   # generalized problem: overlap S (sparse), or masses (1-D array)
+res = sdos.vdos(Phi, mass=m)       # phonons: res.omega, res.g (= 2 w rho(w^2)); negative lambda are reported, never clipped
+```
+
+## All the extras, when you need them
+
+Every option below is a keyword of `sdos.dos` / `sdos.estimate_dos` (and a flag of the `sdos` command).
+
+| you want | use |
+|---|---|
+| sharper features from few moments | `method="maxent"` (with moment uncertainties and jackknife errors) |
+| damping kernel | `kernel="jackson"` (default) or `"lorentz"` (a Green-function kernel: it spikes at the window edges for a DOS) |
+| lower noise in band energy / Fermi level | `exact_moments=K` (local O(N) method, unbiased; standard or diagonal B), or `vectors="impartial"` (Drabold-Sankey, first 3 moments exact per vector) |
+| variance reduction by probing | `probe=d` (distance-d coloring: moments n ≤ d exact) |
+| other random vectors | `vectors="phase" / "rademacher" / "gaussian" / "impartial"` |
+| generalized problem `A x = λ B x` | `B=...`; `binv="pcg"` (default; `precond="block-jacobi"`, `"ic"` incomplete Cholesky, `"amg"`, `"none"`, experimental `"ilu"`) or `binv="chebyshev"` (fixed polynomial B⁻¹) |
+| per-site blocks | `block_size=4` (orbitals per atom) for block-Jacobi / scaling |
+| a window with sharp levels | `sdos.shift_invert_dos(A, (E1, E2))` — **not O(N)** |
+| Fermi level and band energy | `sdos.fermi_and_band_energy(res, n_electrons)` |
+| eigenstates in a window + IPR | `sdos.window_eigs(A, B, (E1, E2), method="filter")` (scalable) or `"shift-invert"` (exact, not O(N)) |
+| local / projected DOS (Mulliken for B != 1) | `sdos.pdos(A, B, groups=...)`, `sdos.ldos(A, B, orbitals=...)` |
+| phonon thermodynamics | `sdos.vdos(Phi, mass=m, zero_modes=3)` then `sdos.harmonic_thermo(res, T)` |
+| DOS from forces only (e.g. LAMMPS) | `sdos.interfaces.lmp.HessianOperator` + `sdos.vdos(op, hermitian_tol=1e-3)` |
+| H(k), S(k) from SIESTA/sisl | `sdos.interfaces.sisl_if.from_sisl(H, k)` |
+
+## What to know
+
+* The Lanczos spectral bounds are estimates inside the spectrum; the default 1% margin covers the usual error and a warning is
+  issued if a moment exceeds 1 (bounds too tight).  Pass `bounds=(Emin, Emax)` for guaranteed values (Gershgorin: `sdos.spectral_bounds(A, "gershgorin")`).
+* Generalized problems: exact local moments and impartial vectors need a local operator and are refused for a non-diagonal B.
+  Probing is not available for them.  A diagonal B (masses) is mass-weighted once and no solves are done.
+* Shift-invert windows factorize `A - σ`; the fill grows superlinearly in 3D, so they are not O(N).
+* License: BSD-3-Clause.
+
+## Citation
+
+Archived on Zenodo, concept DOI [10.5281/zenodo.24023874](https://doi.org/10.5281/zenodo.24023874) (always the latest version); see `CITATION.cff`.
+

sdos-0.1.0/README.md

@@ -0,0 +1,90 @@
+# sdos
+
+The density of states of a big sparse matrix, in one call.  Order-N stochastic trace estimation with the kernel polynomial
+method (KPM) or maximum entropy; real symmetric or complex Hermitian; explicit or matrix-free; standard `A x = λ x` or
+generalized `A x = λ B x`; electrons or phonons.
+
+Status: **0.1.0, first public release.**  The method, its tests against dense diagonalization and an independent code, benchmarks up to
+millions of atoms, and the limits of the approach (what does not scale) are described in the report in `paper/` (REVTeX source and bibliography).
+Docs: `docs/guide.md`, `docs/theory.md`.  Tests: `pip install -e ".[test]" && pytest`.
+
+**In short.**  `sdos` estimates the density of states of a large sparse Hermitian matrix (or a generalized problem with an overlap or mass matrix)
+from Chebyshev moments computed with random vectors, so the cost grows linearly with the matrix size.  The density is reconstructed by the kernel
+polynomial method or by maximum entropy, and the same moments give band energies, Fermi levels, local and projected densities and harmonic
+thermodynamics.  Interfaces: tight-binding and DFTB Hamiltonians, SIESTA through sisl, and matrix-free LAMMPS Hessians for phonons.
+The underlying methods are due to Silver, Röder, Kress, Voter, Drabold, Sankey and collaborators; the report states what is added.
+
+## Install
+
+    pip install -e ".[test]"        # from a clone; add [plot] for matplotlib, [amg] for the AMG preconditioner
+
+## The simple way
+
+```python
+import sdos
+res = sdos.dos("H.npz")            # a file (triplets, Matrix Market, .npz), a SciPy sparse matrix, an array, or a LinearOperator
+res.plot()                         # DOS with error bars
+E, rho = res.E, res.rho            # rho: per orbital, integrates to 1 (multiply by N for states per unit energy)
+res.save("dos.txt")
+```
+
+Real or complex is detected, defaults are sensible (256 moments, 10 random vectors, first 4 moments exact), and nothing else is
+needed.  From the shell:  `sdos H.npz -o dos.dat --plot dos.png`.
+
+**Input.**  The simplest matrix file is plain text, one entry per line, `i j a_ij` (a fourth column is the imaginary part).
+Give one triangle or both; 0- or 1-based indices and the storage are detected automatically, and the other triangle is
+generated by conjugation.  Matrix Market and SciPy `.npz` also work.
+
+**Save, then analyse later.**  The DOS stage needs only the matrix.  Save everything it produced (DOS, error bars, moments,
+spectral window, settings) and analyse it afterwards, with no matrix:
+
+    sdos H.dat -o result.npz                          # a .npz name saves the full result
+    sdos analyze result.npz --valence-file Z.txt      # electrons: E_F and band energy (Z of each atom, one per line)
+    sdos analyze result.npz --electrons 4096 --spin 2
+    sdos analyze phonons.npz --thermo 10 1000 50      # vibrations: ZPE, U, F, S, Cv (result made with --omega)
+    sdos analyze result.npz --moments 60 --method maxent -o dos.txt   # re-reconstruct from the saved moments
+
+In Python: `res.save("result.npz")`, `res = sdos.load("result.npz")`.  The DOS is generic; electron counts, spin and
+temperature enter only in the analysis step.
+
+```python
+sdos.dos(H, resolution=0.05)       # choose the energy resolution instead of the number of moments
+sdos.dos(H, quick=True)            # fast look: 128 moments, 4 vectors
+sdos.dos(H, B=S)                   # generalized problem: overlap S (sparse), or masses (1-D array)
+res = sdos.vdos(Phi, mass=m)       # phonons: res.omega, res.g (= 2 w rho(w^2)); negative lambda are reported, never clipped
+```
+
+## All the extras, when you need them
+
+Every option below is a keyword of `sdos.dos` / `sdos.estimate_dos` (and a flag of the `sdos` command).
+
+| you want | use |
+|---|---|
+| sharper features from few moments | `method="maxent"` (with moment uncertainties and jackknife errors) |
+| damping kernel | `kernel="jackson"` (default) or `"lorentz"` (a Green-function kernel: it spikes at the window edges for a DOS) |
+| lower noise in band energy / Fermi level | `exact_moments=K` (local O(N) method, unbiased; standard or diagonal B), or `vectors="impartial"` (Drabold-Sankey, first 3 moments exact per vector) |
+| variance reduction by probing | `probe=d` (distance-d coloring: moments n ≤ d exact) |
+| other random vectors | `vectors="phase" / "rademacher" / "gaussian" / "impartial"` |
+| generalized problem `A x = λ B x` | `B=...`; `binv="pcg"` (default; `precond="block-jacobi"`, `"ic"` incomplete Cholesky, `"amg"`, `"none"`, experimental `"ilu"`) or `binv="chebyshev"` (fixed polynomial B⁻¹) |
+| per-site blocks | `block_size=4` (orbitals per atom) for block-Jacobi / scaling |
+| a window with sharp levels | `sdos.shift_invert_dos(A, (E1, E2))` — **not O(N)** |
+| Fermi level and band energy | `sdos.fermi_and_band_energy(res, n_electrons)` |
+| eigenstates in a window + IPR | `sdos.window_eigs(A, B, (E1, E2), method="filter")` (scalable) or `"shift-invert"` (exact, not O(N)) |
+| local / projected DOS (Mulliken for B != 1) | `sdos.pdos(A, B, groups=...)`, `sdos.ldos(A, B, orbitals=...)` |
+| phonon thermodynamics | `sdos.vdos(Phi, mass=m, zero_modes=3)` then `sdos.harmonic_thermo(res, T)` |
+| DOS from forces only (e.g. LAMMPS) | `sdos.interfaces.lmp.HessianOperator` + `sdos.vdos(op, hermitian_tol=1e-3)` |
+| H(k), S(k) from SIESTA/sisl | `sdos.interfaces.sisl_if.from_sisl(H, k)` |
+
+## What to know
+
+* The Lanczos spectral bounds are estimates inside the spectrum; the default 1% margin covers the usual error and a warning is
+  issued if a moment exceeds 1 (bounds too tight).  Pass `bounds=(Emin, Emax)` for guaranteed values (Gershgorin: `sdos.spectral_bounds(A, "gershgorin")`).
+* Generalized problems: exact local moments and impartial vectors need a local operator and are refused for a non-diagonal B.
+  Probing is not available for them.  A diagonal B (masses) is mass-weighted once and no solves are done.
+* Shift-invert windows factorize `A - σ`; the fill grows superlinearly in 3D, so they are not O(N).
+* License: BSD-3-Clause.
+
+## Citation
+
+Archived on Zenodo, concept DOI [10.5281/zenodo.24023874](https://doi.org/10.5281/zenodo.24023874) (always the latest version); see `CITATION.cff`.
+

sdos-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sdos"
+version = "0.1.0"
+description = "Order-N spectral density of states (KPM, Maxent, shift-invert) for large sparse Hermitian problems"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [{ name = "David A. Drabold", email = "drabold@ohio.edu" }]
+keywords = ["density of states", "kernel polynomial method", "maximum entropy", "sparse eigenvalue", "tight binding", "vibrational spectra"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = ["numpy>=1.22", "scipy>=1.8"]
+
+[project.optional-dependencies]
+plot = ["matplotlib"]
+amg = ["pyamg"]
+sisl = ["sisl"]
+test = ["pytest"]
+
+[project.scripts]
+sdos = "sdos.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["slow: slower tests excluded from CI (run with -m slow)"]

sdos-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sdos-0.1.0/src/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-0.1.0/src/sdos/__main__.py

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

sdos-0.1.0/src/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-0.1.0/src/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