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; the GitHub repository is a public mirror.

Adaptive Fermi-surface refinement

See the visual Python 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, 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:

pip install .

The model below produces the three-dimensional surface shown above:

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

The same SpectralMesh can drive the other observables and reuse every eigensystem it has already computed:

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 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, runnable quick start, and two-band plotting example, the visual-generation notes, and the build and architecture guide.

Development

AdaptiveSimplex provides the mesh geometry, refinement, vertex caching, and cut-simplex integration; FermiSimplex adds the spectral models, certificates, and observable-specific algorithms.

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.

FermiSimplex is licensed under the BSD 3-Clause license. If you use it in research, please cite the metadata in CITATION.cff.

Project links

Data verified by PyPI on Jul 28, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Kostusas from gravatar.com Kostusas

Credits

Author: Kostas Vilkelis

GitHub Statistics

Data verified by PyPI on Jul 28, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

BSD-3-Clause
View SPDX License List

Requires

Python <3.14, >=3.11

Provides Extra

examples

Tags

adaptive mesh electronic structure Fermi surface scientific computing

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

fermisimplex-0.1.0.tar.gz (46.8 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

fermisimplex-0.1.0-cp313-cp313-win_amd64.whl (6.9 MB view details)

Uploaded CPython 3.13Windows x86-64

fermisimplex-0.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (8.9 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

fermisimplex-0.1.0-cp313-cp313-macosx_11_0_x86_64.whl (176.0 kB view details)

Uploaded CPython 3.13macOS 11.0+ x86-64

fermisimplex-0.1.0-cp313-cp313-macosx_11_0_arm64.whl (161.3 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

fermisimplex-0.1.0-cp312-cp312-win_amd64.whl (6.9 MB view details)

Uploaded CPython 3.12Windows x86-64

fermisimplex-0.1.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (8.9 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

fermisimplex-0.1.0-cp312-cp312-macosx_11_0_x86_64.whl (176.0 kB view details)

Uploaded CPython 3.12macOS 11.0+ x86-64

fermisimplex-0.1.0-cp312-cp312-macosx_11_0_arm64.whl (161.3 kB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

fermisimplex-0.1.0-cp311-cp311-win_amd64.whl (6.9 MB view details)

Uploaded CPython 3.11Windows x86-64

fermisimplex-0.1.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (8.9 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

fermisimplex-0.1.0-cp311-cp311-macosx_11_0_x86_64.whl (176.4 kB view details)

Uploaded CPython 3.11macOS 11.0+ x86-64

fermisimplex-0.1.0-cp311-cp311-macosx_11_0_arm64.whl (162.1 kB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

File details

Details for the file fermisimplex-0.1.0.tar.gz.

File metadata

  • Download URL: fermisimplex-0.1.0.tar.gz
  • Upload date:
  • Size: 46.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for fermisimplex-0.1.0.tar.gz
Algorithm Hash digest
SHA256 845506ee3d224d59d1b401bd86a4d49f04034ad964bdb540d33a0bb81966e2a8
MD5 19a33e8bb63b02f90126065a2f907eee
BLAKE2b-256 c3ee50eb113f79cf14709e605c1862705c7da4ddfb561f3ad5778b9a9093feea

See more details on using hashes here.

Provenance

The following attestation bundles were made for fermisimplex-0.1.0.tar.gz:

Publisher: release.yml on Kostusas/FermiSimplex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fermisimplex-0.1.0-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for fermisimplex-0.1.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 629b4062346eec5a61dae7464a4269e05181642e4d881f66ab3a4c6c06f4635d
MD5 3c372d52ce07dc7f5c495efaf5b8a40d
BLAKE2b-256 c4a4fb365e63fd0c3a4332bd6dacd43f582ca3740b42bd2c549914cb02fdcf55

See more details on using hashes here.

Provenance

The following attestation bundles were made for fermisimplex-0.1.0-cp313-cp313-win_amd64.whl:

Publisher: release.yml on Kostusas/FermiSimplex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fermisimplex-0.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for fermisimplex-0.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 3d57ef2d15bdf18ad9d80bb75651e618f53598edff6e52d3a77860e387b072d2
MD5 7f9f910cf3a8d61ae542ab3e06a9129e
BLAKE2b-256 1dd0821f8dac23f3b6a73e1737068175076990891c9b5eb72763ced02a897777

See more details on using hashes here.

Provenance

The following attestation bundles were made for fermisimplex-0.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on Kostusas/FermiSimplex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fermisimplex-0.1.0-cp313-cp313-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for fermisimplex-0.1.0-cp313-cp313-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 b451eeda95b017fb25f32522a1a69036111c163264163a5f4d37d613594d2677
MD5 d2d3742207c28ae04f5b08194e5dc5f9
BLAKE2b-256 d72043df78057edb3963d6142e0b17572423fbf96e0d7c21ef9363e201edfcc6

See more details on using hashes here.

Provenance

The following attestation bundles were made for fermisimplex-0.1.0-cp313-cp313-macosx_11_0_x86_64.whl:

Publisher: release.yml on Kostusas/FermiSimplex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fermisimplex-0.1.0-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for fermisimplex-0.1.0-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 9f33f199de862acc21ea12869aa560b93d0e64bfd5ef8d31525adbeb8d581c41
MD5 8da678cfdf8dd30d9fe361a96761cb9a
BLAKE2b-256 b1a79f3f5a3f15eee22c539d3a275082b9d42d491cd361c09ccf0a8b04316df9

See more details on using hashes here.

Provenance

The following attestation bundles were made for fermisimplex-0.1.0-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: release.yml on Kostusas/FermiSimplex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fermisimplex-0.1.0-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for fermisimplex-0.1.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 574fc5f7e604796790e605447ceed441ba0e5378170242b15003ae084fa0dd66
MD5 86e026cbb26fa2e16f53dc9a75ce3d22
BLAKE2b-256 0521c413833f1f08232708aa3b84cd664bc0cf7b6c426e03ae9004768ee01e86

See more details on using hashes here.

Provenance

The following attestation bundles were made for fermisimplex-0.1.0-cp312-cp312-win_amd64.whl:

Publisher: release.yml on Kostusas/FermiSimplex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fermisimplex-0.1.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for fermisimplex-0.1.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 a37491b8877ab9ad8054108b05c0bd0eb495f65857d9d050ecdffb53e138cf74
MD5 24631e03fcdbaa826577203519782e77
BLAKE2b-256 75a36fe02bddc1232fdc90d5a8027ade8d8c87ec51475d49140c06e093927c36

See more details on using hashes here.

Provenance

The following attestation bundles were made for fermisimplex-0.1.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on Kostusas/FermiSimplex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fermisimplex-0.1.0-cp312-cp312-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for fermisimplex-0.1.0-cp312-cp312-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 e957eb55c5993c50193568fbd829cb03ab3d6cd54ab0083ac5df5c96e467aec2
MD5 2ebd8b461749e260e3537d1f387d7f5d
BLAKE2b-256 b8401b0795a51d8bc2ec69f160253509b299060b185eef598181d3c48b49b273

See more details on using hashes here.

Provenance

The following attestation bundles were made for fermisimplex-0.1.0-cp312-cp312-macosx_11_0_x86_64.whl:

Publisher: release.yml on Kostusas/FermiSimplex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fermisimplex-0.1.0-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for fermisimplex-0.1.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f6afe3323c8741b0f3ef057bf3a16ca2dbcae6a15e6c8c98f9dcfbb192ab8988
MD5 fc15e5998c2cea7c85fcb5019dc0d88f
BLAKE2b-256 943bcdda90e6d5290b0fdbb14d12c407760238bc18aae23ab87fc9184ba1bb95

See more details on using hashes here.

Provenance

The following attestation bundles were made for fermisimplex-0.1.0-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: release.yml on Kostusas/FermiSimplex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fermisimplex-0.1.0-cp311-cp311-win_amd64.whl.

File metadata

File hashes

Hashes for fermisimplex-0.1.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 6ee3b1aedb786accb0840eb03f92d442fefe5517a411538e6a45d5a2c90de64c
MD5 e475f3f42f9987631545c70c3f79cc1c
BLAKE2b-256 bc293b56b16cea251d5f1dae2de224b5006c2e837cfa2eebfd7be72e654e4eb3

See more details on using hashes here.

Provenance

The following attestation bundles were made for fermisimplex-0.1.0-cp311-cp311-win_amd64.whl:

Publisher: release.yml on Kostusas/FermiSimplex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fermisimplex-0.1.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for fermisimplex-0.1.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 e471c02e297bea38836091ecc6fa2f244e61ca5c3cbc608c000c560d2c933929
MD5 c665302900e45edb58ccf8c715ee3f01
BLAKE2b-256 d88e77d5323500a4ac9cb8e55fabafd26f43308db3c760d2fd06a4775f06f4e4

See more details on using hashes here.

Provenance

The following attestation bundles were made for fermisimplex-0.1.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on Kostusas/FermiSimplex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fermisimplex-0.1.0-cp311-cp311-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for fermisimplex-0.1.0-cp311-cp311-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 b4fcfbe6bc0e28e7eaaf33273cbf55792b4c115c16f1c2c201eb5e187cd2c16e
MD5 b347c158a3cba8c651c93384f6bfdc5a
BLAKE2b-256 354aaebac30702a0c41f4025e84d748049e8a2de42af72bc6ed1dd0b4d29d80d

See more details on using hashes here.

Provenance

The following attestation bundles were made for fermisimplex-0.1.0-cp311-cp311-macosx_11_0_x86_64.whl:

Publisher: release.yml on Kostusas/FermiSimplex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fermisimplex-0.1.0-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for fermisimplex-0.1.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 4270f6300d05b8a472c08916a5d42612096e834f26965c5a4a70ecb763da6aef
MD5 49ff8b735f1a88bf7bc4c689af926bb5
BLAKE2b-256 2f4490b6b22beb2627365843c5b5a9c43533b5ef9529e1ff4ba2d18e87f8a69f

See more details on using hashes here.

Provenance

The following attestation bundles were made for fermisimplex-0.1.0-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: release.yml on Kostusas/FermiSimplex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.0 This release

13 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page