FermiSimplex 0.1.0__tar.gz

fermisimplex-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+.pixi/
+__pycache__/
+*.py[cod]
+*$py.class
+
+.pytest_cache/
+.ipynb_checkpoints/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+artifacts/
+docs/generated/
+
+build/
+dist/
+*.egg-info/
+_skbuild/
+CMakeCache.txt
+CMakeFiles/
+cmake-build-*/
+compile_commands.json
+
+*.so
+*.dylib
+*.dll

fermisimplex-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to FermiSimplex are documented in this file.
+
+## Unreleased
+
+## 0.1.0 - 2026-07-28
+
+- Added adaptive Fermi-surface extraction, charge integration, and density
+  matrices through a shared Python and C++ numerical core.
+- Added occupation certification, projected charge-error estimation, and
+  reusable eigensystem caching on adaptive simplex meshes.
+- Added production tests, performance benchmarks, examples, and visual
+  documentation.

fermisimplex-0.1.0/CITATION.cff

@@ -0,0 +1,10 @@
+cff-version: 1.2.0
+message: "If you use FermiSimplex, please cite it using this metadata."
+title: "FermiSimplex"
+version: "0.1.0"
+date-released: "2026-07-28"
+authors:
+  - family-names: "Vilkelis"
+    given-names: "Kostas"
+license: "BSD-3-Clause"
+repository-code: "https://gitlab.kwant-project.org/qt/lineartetrahedron"

fermisimplex-0.1.0/CMakeLists.txt

@@ -0,0 +1,31 @@
+cmake_minimum_required(VERSION 3.28...3.30)
+
+project(
+  FermiSimplex
+  VERSION 0.1.0
+  LANGUAGES CXX
+)
+
+if(CMAKE_SOURCE_DIR STREQUAL PROJECT_SOURCE_DIR)
+  set(FERMISIMPLEX_TOP_LEVEL_DEFAULT ON)
+  include(CTest)
+else()
+  set(FERMISIMPLEX_TOP_LEVEL_DEFAULT OFF)
+endif()
+
+option(
+  FERMISIMPLEX_BUILD_PYTHON
+  "Build the FermiSimplex Python extension"
+  "${FERMISIMPLEX_TOP_LEVEL_DEFAULT}"
+)
+option(
+  FERMISIMPLEX_BUILD_TESTING
+  "Build the FermiSimplex C++ tests"
+  "${FERMISIMPLEX_TOP_LEVEL_DEFAULT}"
+)
+
+add_subdirectory(cpp)
+
+if(FERMISIMPLEX_BUILD_PYTHON)
+  add_subdirectory(python)
+endif()

fermisimplex-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Kostas Vilkelis
+
+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.

fermisimplex-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: FermiSimplex
+Version: 0.1.0
+Summary: Adaptive spectral calculations with simplex occupation certification
+Keywords: adaptive mesh,electronic structure,Fermi surface,scientific computing
+Author: Kostas Vilkelis
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Project-URL: Repository, https://gitlab.kwant-project.org/qt/lineartetrahedron
+Project-URL: Mirror, https://github.com/Kostusas/FermiSimplex
+Project-URL: Documentation, https://github.com/Kostusas/FermiSimplex/blob/main/docs/showcase.md
+Project-URL: Changelog, https://github.com/Kostusas/FermiSimplex/blob/main/CHANGELOG.md
+Requires-Python: <3.14,>=3.11
+Requires-Dist: numpy>=2.0
+Provides-Extra: examples
+Requires-Dist: matplotlib>=3.8; extra == "examples"
+Description-Content-Type: text/markdown
+
+# FermiSimplex
+
+**Adaptive, occupation-certified spectral calculations on simplex meshes.**
+
+FermiSimplex finds Fermi surfaces and computes zero-temperature charge and
+density matrices without paying for a dense momentum grid. Its central object
+is the local occupation
+
+$$
+N(k; \mu) = \mathrm{Tr}\left[\Theta\left(\mu I - H(k)\right)\right],
+$$
+
+and its central question is simple: *can the occupation be proved constant on
+this simplex, or should we look more closely?*
+
+The upstream development repository is
+[GitLab](https://gitlab.kwant-project.org/qt/lineartetrahedron); the
+[GitHub repository](https://github.com/Kostusas/FermiSimplex) is a public
+mirror.
+
+![Adaptive Fermi-surface refinement](https://raw.githubusercontent.com/Kostusas/FermiSimplex/main/docs/assets/fermi_surface_refinement.gif)
+
+See the [visual Python tour][visual-tour] for a presentation-ready
+introduction with real adaptive sampling traces, multiband examples, and a
+rotating noble-metal-inspired three-dimensional surface.
+
+- 🛡️ **Gapped-region proofs** combine cached eigensystems with rigorous spectral
+  bounds to exclude a Fermi-level crossing throughout a simplex and to bound
+  the remaining charge.
+- ⚡ **Adaptive sampling**, built on
+  [AdaptiveSimplex](https://gitlab.kwant-project.org/qt/adaptivesimplex),
+  concentrates diagonalizations near unresolved Fermi surfaces instead of
+  refining the entire Brillouin zone uniformly.
+- 🚀 **Numerical efficiency by design:** adaptive refinement, shared spectral
+  caching, and the compiled numerical core avoid repeated work as the Fermi
+  surface becomes progressively sharper.
+- 🎯 **Projected charge estimates** compare sampled projected eigenvalues with
+  vertex-linear interpolation only in the bands whose occupation is still
+  ambiguous.
+- 🧩 **Python and C++** share one numerical core; models can be dense callables
+  or translation-invariant tight-binding Hamiltonians.
+
+## Quick start
+
+From a source checkout with a C++20 compiler and BLAS/LAPACK available:
+
+```bash
+pip install .
+```
+
+The model below produces the three-dimensional surface shown above:
+
+```python
+import numpy as np
+
+from fermisimplex import SpectralMesh
+
+
+def hamiltonian(kx, ky, kz):
+    phase = 2 * np.pi * np.array([kx, ky, kz])
+    return np.array([[np.cos(phase).sum()]], dtype=complex)
+
+
+mesh = SpectralMesh(hamiltonian)
+surface = mesh.fermi_surface(
+    mu=0.17,
+    min_feature_size=0.07,
+    curvature_bound=(2 * np.pi) ** 2,
+)
+
+surface.points      # (npoints, 3)
+surface.cells       # (ntriangles, 3)
+surface.cell_bands  # band index for every triangle
+```
+
+The coordinates are reduced coordinates in $[0,1]^d$. Here
+$M=(2\pi)^2$ bounds every directional second derivative of the scalar
+Hamiltonian. `SpectralMesh` infers the momentum-space dimension from the
+callable arguments and the matrix dimension by evaluating it at the origin.
+Callables receive separate coordinates: `hamiltonian(kx, ky, ...)`.
+
+![Two- and three-dimensional Fermi surfaces](https://raw.githubusercontent.com/Kostusas/FermiSimplex/main/docs/assets/fermi_surface_gallery.png)
+
+The same `SpectralMesh` can drive the other observables and reuse every
+eigensystem it has already computed:
+
+```python
+charge = mesh.integrate_charge(
+    mu=0.17,
+    target_error=1e-2,
+    max_refinements=10_000,
+    curvature_bound=(2 * np.pi) ** 2,
+)
+density = mesh.integrate_density_matrix(
+    mu=0.17,
+    lattice_vectors=[(0, 0, 0), (1, 0, 0)],
+    target_error=1e-2,
+    max_refinements=10_000,
+)
+
+charge.value
+charge.stopping_error
+charge.certified_error_bound
+density.matrices  # (number of lattice vectors, ndof, ndof)
+```
+
+For a tight-binding model,
+
+$$
+H(k)=\sum_R H_R e^{-2\pi i k\cdot R},
+$$
+
+pass `{R: H_R, ...}` directly to `SpectralMesh`. Opposite hoppings are checked
+for $H_{-R}=H_R^\dagger$.
+
+## What does the certificate prove?
+
+At each simplex, FermiSimplex asks: **can the occupation change between the
+sampled vertices?** It combines their eigensystems with `curvature_bound`,
+which limits how much the Hamiltonian can bend in between. If occupied and
+unoccupied trial subspaces remain on opposite sides of $\mu$, the occupation
+is fixed everywhere—without sampling the interior.
+
+- **Certified:** no Fermi surface crosses the simplex.
+- **Partially certified:** rigorous lower and upper occupation bounds remain.
+- **Inconclusive:** this is not a gapless verdict; FermiSimplex refines and
+  tries again.
+
+Every charge and Fermi-surface simplex is checked. The remaining uncertainty
+becomes `charge.certified_error_bound`; `surface.coverage_certified` concerns
+classification down to `min_feature_size`, not topology or geometric accuracy.
+Density matrices currently use adaptive estimates instead.
+
+The guarantee assumes a valid `curvature_bound`. Omitting it, `None`, and
+`0.0` all assert zero curvature; none disables certification. See the
+[mathematics guide][mathematics] for the proof and error bounds.
+
+## API at a glance
+
+- `SpectralMesh`: accept a callable or tight-binding dictionary and own the
+  adaptive geometry and cached eigensystems.
+- `certify_simplex`: certify supplied vertex eigenpairs directly; eigenvalues
+  must be finite and ascending, and eigenvector columns must be finite and
+  orthonormal. These performance-sensitive numerical preconditions are not
+  rechecked.
+- `mesh.integrate_charge`: adaptive filling and $dQ/d\mu$.
+- `mesh.integrate_density_matrix`: real-space density-matrix components.
+- `mesh.fermi_surface`: band-labelled points and cells in reduced coordinates.
+
+Adaptive controls such as `target_error`, `max_refinements`, and
+`preview_depth` are ordinary keyword arguments on the calculation that uses
+them—there is no separate options object. Charge calculations default to
+`preview_depth=0` because their sampled projected-error estimate drives
+refinement intrinsically; positive depths are intended for explicit
+diagnostic comparisons.
+
+See the [visual Python tour][visual-tour], runnable
+[quick start][quick-start], and
+[two-band plotting example][fermi-example], the
+[visual-generation notes][visuals], and the
+[build and architecture guide][development].
+
+## Development
+
+AdaptiveSimplex provides the mesh geometry, refinement, vertex caching, and
+cut-simplex integration; FermiSimplex adds the spectral models, certificates,
+and observable-specific algorithms.
+
+```bash
+pixi run test
+```
+
+This builds the standalone C++ library, verifies an installed downstream CMake
+consumer, rebuilds the Python extension, and runs the Python tests. The dense
+60-band stress case lives in [benchmarks/fermi_surface_60.py][stress-benchmark].
+
+FermiSimplex is licensed under the BSD 3-Clause license. If you use it in
+research, please cite the metadata in [CITATION.cff][citation].
+
+
+[visual-tour]: https://github.com/Kostusas/FermiSimplex/blob/main/docs/showcase.md
+[mathematics]: https://github.com/Kostusas/FermiSimplex/blob/main/docs/mathematics.md
+[quick-start]: https://github.com/Kostusas/FermiSimplex/blob/main/examples/quick_start.py
+[fermi-example]: https://github.com/Kostusas/FermiSimplex/blob/main/examples/fermi_surface.py
+[visuals]: https://github.com/Kostusas/FermiSimplex/blob/main/docs/visuals.md
+[development]: https://github.com/Kostusas/FermiSimplex/blob/main/docs/development.md
+[stress-benchmark]: https://github.com/Kostusas/FermiSimplex/blob/main/benchmarks/fermi_surface_60.py
+[citation]: https://github.com/Kostusas/FermiSimplex/blob/main/CITATION.cff

fermisimplex-0.1.0/README.md

@@ -0,0 +1,188 @@
+# FermiSimplex
+
+**Adaptive, occupation-certified spectral calculations on simplex meshes.**
+
+FermiSimplex finds Fermi surfaces and computes zero-temperature charge and
+density matrices without paying for a dense momentum grid. Its central object
+is the local occupation
+
+$$
+N(k; \mu) = \mathrm{Tr}\left[\Theta\left(\mu I - H(k)\right)\right],
+$$
+
+and its central question is simple: *can the occupation be proved constant on
+this simplex, or should we look more closely?*
+
+The upstream development repository is
+[GitLab](https://gitlab.kwant-project.org/qt/lineartetrahedron); the
+[GitHub repository](https://github.com/Kostusas/FermiSimplex) is a public
+mirror.
+
+![Adaptive Fermi-surface refinement](https://raw.githubusercontent.com/Kostusas/FermiSimplex/main/docs/assets/fermi_surface_refinement.gif)
+
+See the [visual Python tour][visual-tour] for a presentation-ready
+introduction with real adaptive sampling traces, multiband examples, and a
+rotating noble-metal-inspired three-dimensional surface.
+
+- 🛡️ **Gapped-region proofs** combine cached eigensystems with rigorous spectral
+  bounds to exclude a Fermi-level crossing throughout a simplex and to bound
+  the remaining charge.
+- ⚡ **Adaptive sampling**, built on
+  [AdaptiveSimplex](https://gitlab.kwant-project.org/qt/adaptivesimplex),
+  concentrates diagonalizations near unresolved Fermi surfaces instead of
+  refining the entire Brillouin zone uniformly.
+- 🚀 **Numerical efficiency by design:** adaptive refinement, shared spectral
+  caching, and the compiled numerical core avoid repeated work as the Fermi
+  surface becomes progressively sharper.
+- 🎯 **Projected charge estimates** compare sampled projected eigenvalues with
+  vertex-linear interpolation only in the bands whose occupation is still
+  ambiguous.
+- 🧩 **Python and C++** share one numerical core; models can be dense callables
+  or translation-invariant tight-binding Hamiltonians.
+
+## Quick start
+
+From a source checkout with a C++20 compiler and BLAS/LAPACK available:
+
+```bash
+pip install .
+```
+
+The model below produces the three-dimensional surface shown above:
+
+```python
+import numpy as np
+
+from fermisimplex import SpectralMesh
+
+
+def hamiltonian(kx, ky, kz):
+    phase = 2 * np.pi * np.array([kx, ky, kz])
+    return np.array([[np.cos(phase).sum()]], dtype=complex)
+
+
+mesh = SpectralMesh(hamiltonian)
+surface = mesh.fermi_surface(
+    mu=0.17,
+    min_feature_size=0.07,
+    curvature_bound=(2 * np.pi) ** 2,
+)
+
+surface.points      # (npoints, 3)
+surface.cells       # (ntriangles, 3)
+surface.cell_bands  # band index for every triangle
+```
+
+The coordinates are reduced coordinates in $[0,1]^d$. Here
+$M=(2\pi)^2$ bounds every directional second derivative of the scalar
+Hamiltonian. `SpectralMesh` infers the momentum-space dimension from the
+callable arguments and the matrix dimension by evaluating it at the origin.
+Callables receive separate coordinates: `hamiltonian(kx, ky, ...)`.
+
+![Two- and three-dimensional Fermi surfaces](https://raw.githubusercontent.com/Kostusas/FermiSimplex/main/docs/assets/fermi_surface_gallery.png)
+
+The same `SpectralMesh` can drive the other observables and reuse every
+eigensystem it has already computed:
+
+```python
+charge = mesh.integrate_charge(
+    mu=0.17,
+    target_error=1e-2,
+    max_refinements=10_000,
+    curvature_bound=(2 * np.pi) ** 2,
+)
+density = mesh.integrate_density_matrix(
+    mu=0.17,
+    lattice_vectors=[(0, 0, 0), (1, 0, 0)],
+    target_error=1e-2,
+    max_refinements=10_000,
+)
+
+charge.value
+charge.stopping_error
+charge.certified_error_bound
+density.matrices  # (number of lattice vectors, ndof, ndof)
+```
+
+For a tight-binding model,
+
+$$
+H(k)=\sum_R H_R e^{-2\pi i k\cdot R},
+$$
+
+pass `{R: H_R, ...}` directly to `SpectralMesh`. Opposite hoppings are checked
+for $H_{-R}=H_R^\dagger$.
+
+## What does the certificate prove?
+
+At each simplex, FermiSimplex asks: **can the occupation change between the
+sampled vertices?** It combines their eigensystems with `curvature_bound`,
+which limits how much the Hamiltonian can bend in between. If occupied and
+unoccupied trial subspaces remain on opposite sides of $\mu$, the occupation
+is fixed everywhere—without sampling the interior.
+
+- **Certified:** no Fermi surface crosses the simplex.
+- **Partially certified:** rigorous lower and upper occupation bounds remain.
+- **Inconclusive:** this is not a gapless verdict; FermiSimplex refines and
+  tries again.
+
+Every charge and Fermi-surface simplex is checked. The remaining uncertainty
+becomes `charge.certified_error_bound`; `surface.coverage_certified` concerns
+classification down to `min_feature_size`, not topology or geometric accuracy.
+Density matrices currently use adaptive estimates instead.
+
+The guarantee assumes a valid `curvature_bound`. Omitting it, `None`, and
+`0.0` all assert zero curvature; none disables certification. See the
+[mathematics guide][mathematics] for the proof and error bounds.
+
+## API at a glance
+
+- `SpectralMesh`: accept a callable or tight-binding dictionary and own the
+  adaptive geometry and cached eigensystems.
+- `certify_simplex`: certify supplied vertex eigenpairs directly; eigenvalues
+  must be finite and ascending, and eigenvector columns must be finite and
+  orthonormal. These performance-sensitive numerical preconditions are not
+  rechecked.
+- `mesh.integrate_charge`: adaptive filling and $dQ/d\mu$.
+- `mesh.integrate_density_matrix`: real-space density-matrix components.
+- `mesh.fermi_surface`: band-labelled points and cells in reduced coordinates.
+
+Adaptive controls such as `target_error`, `max_refinements`, and
+`preview_depth` are ordinary keyword arguments on the calculation that uses
+them—there is no separate options object. Charge calculations default to
+`preview_depth=0` because their sampled projected-error estimate drives
+refinement intrinsically; positive depths are intended for explicit
+diagnostic comparisons.
+
+See the [visual Python tour][visual-tour], runnable
+[quick start][quick-start], and
+[two-band plotting example][fermi-example], the
+[visual-generation notes][visuals], and the
+[build and architecture guide][development].
+
+## Development
+
+AdaptiveSimplex provides the mesh geometry, refinement, vertex caching, and
+cut-simplex integration; FermiSimplex adds the spectral models, certificates,
+and observable-specific algorithms.
+
+```bash
+pixi run test
+```
+
+This builds the standalone C++ library, verifies an installed downstream CMake
+consumer, rebuilds the Python extension, and runs the Python tests. The dense
+60-band stress case lives in [benchmarks/fermi_surface_60.py][stress-benchmark].
+
+FermiSimplex is licensed under the BSD 3-Clause license. If you use it in
+research, please cite the metadata in [CITATION.cff][citation].
+
+
+[visual-tour]: https://github.com/Kostusas/FermiSimplex/blob/main/docs/showcase.md
+[mathematics]: https://github.com/Kostusas/FermiSimplex/blob/main/docs/mathematics.md
+[quick-start]: https://github.com/Kostusas/FermiSimplex/blob/main/examples/quick_start.py
+[fermi-example]: https://github.com/Kostusas/FermiSimplex/blob/main/examples/fermi_surface.py
+[visuals]: https://github.com/Kostusas/FermiSimplex/blob/main/docs/visuals.md
+[development]: https://github.com/Kostusas/FermiSimplex/blob/main/docs/development.md
+[stress-benchmark]: https://github.com/Kostusas/FermiSimplex/blob/main/benchmarks/fermi_surface_60.py
+[citation]: https://github.com/Kostusas/FermiSimplex/blob/main/CITATION.cff

fermisimplex-0.1.0/ci/test_wheel.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import sys
+from importlib.metadata import version
+from pathlib import Path
+
+import numpy as np
+
+import fermisimplex
+from fermisimplex import SpectralMesh
+
+
+def test_installed_distribution_runs_a_native_surface_calculation():
+    def hamiltonian(kx, ky):
+        coordinate_sum = kx + ky
+        return np.diag(
+            [coordinate_sum - 1.5, coordinate_sum - 0.5]
+        ).astype(complex)
+
+    surface = SpectralMesh(hamiltonian).fermi_surface(
+        mu=0.0,
+        min_feature_size=0.2,
+        curvature_bound=0.0,
+    )
+
+    assert version("FermiSimplex")
+    assert surface.completed
+    assert surface.coverage_certified
+    assert set(surface.cell_bands.tolist()) == {0, 1}
+
+
+def test_bundled_openblas_notice_matches_platform_backend():
+    package_dir = Path(fermisimplex.__file__).resolve().parent
+    notice = package_dir / "licenses" / "scipy-openblas32.txt"
+
+    if sys.platform == "darwin":
+        assert not notice.exists()
+        return
+
+    assert notice.is_file()
+    assert "OpenBLAS" in notice.read_text()