bztetra 0.1.0__tar.gz

bztetra-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+libtetra_original/
+.internal/
+
+# Python
+__pycache__/
+*.py[cod]
+*.so
+.python-version
+.pkg-venv/
+.venv/
+venv/
+
+# Packaging
+build/
+dist/
+*.egg-info/
+site/
+
+# Tool caches
+.coverage
+.hypothesis/
+.mypy_cache/
+.nox/
+.pytest_cache/
+.ruff_cache/
+htmlcov/

bztetra-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bztetra contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bztetra-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: bztetra
+Version: 0.1.0
+Summary: Python and Numba port of libtetrabz-style tetrahedron integration routines.
+Project-URL: Homepage, https://github.com/skilledwolf/bztetra
+Project-URL: Documentation, https://skilledwolf.github.io/bztetra/
+Project-URL: Repository, https://github.com/skilledwolf/bztetra
+Project-URL: Issues, https://github.com/skilledwolf/bztetra/issues
+Author: bztetra contributors
+License: MIT License
+        
+        Copyright (c) 2026 bztetra contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: brillouin-zone,density-of-states,electronic-structure,numba,tetrahedron-method
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.11
+Requires-Dist: numba>=0.61
+Requires-Dist: numpy>=2.0
+Provides-Extra: dev
+Requires-Dist: matplotlib>=3.9; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.28; extra == 'docs'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.9; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# bztetra
+
+`bztetra` is a Python + Numba package for tetrahedron integration on regular
+k-grids.
+
+This is the public `0.x` preview series. Validate important production results
+against the original
+[`libtetrabz`](https://github.com/mitsuaki1987/libtetrabz) implementation or
+the parity guidance in the
+[validation docs](https://skilledwolf.github.io/bztetra/validation/).
+
+## Install
+
+```bash
+pip install bztetra
+```
+
+Plot-backed examples use Matplotlib:
+
+```bash
+pip install "bztetra[plot]"
+```
+
+## What It Provides
+
+- Occupation, DOS, and integrated DOS weights on regular 3D k-grids.
+- Static overlap, nesting, and polarization weights.
+- Real- and complex-frequency Lindhard-style response functions.
+- A separate `bztetra.twod` namespace for genuine 2D triangle-method problems.
+
+## Documentation
+
+- Documentation: <https://skilledwolf.github.io/bztetra/>
+- Quickstart: <https://skilledwolf.github.io/bztetra/quickstart/>
+- Physics guide: <https://skilledwolf.github.io/bztetra/physics/>
+- Examples: <https://skilledwolf.github.io/bztetra/examples/>
+- Validation: <https://skilledwolf.github.io/bztetra/validation/>
+- Repository: <https://github.com/skilledwolf/bztetra>
+- Issues: <https://github.com/skilledwolf/bztetra/issues>

bztetra-0.1.0/README.md

@@ -0,0 +1,176 @@
+# bztetra
+
+`bztetra` is a Python + Numba package for single-process tetrahedron
+integration on regular k-grids.
+
+It is aimed at users who already have band energies on a regular mesh and want
+k-resolved weights for occupations, DOS, and Lindhard-style response functions
+without going through the legacy `libtetrabz` wrapper.
+
+The top-level `bztetra` API remains strictly 3D. A parallel 2D linear
+triangle-method implementation now lives under `bztetra.twod` for the
+occupation, DOS, and response families. Do not fake a flat third axis with
+`nz=1`; see
+[docs/two_dimensional_plan.md](docs/two_dimensional_plan.md).
+
+> [!IMPORTANT]
+> `bztetra` is a public preview in the `0.x` series. The package is usable, but
+> the API and validation envelope may still evolve before `1.0`. Validate
+> important production results against the original
+> [`libtetrabz`](https://github.com/mitsuaki1987/libtetrabz) implementation or
+> run the parity checks described in [docs/validation.md](docs/validation.md).
+
+- NumPy arrays in, NumPy arrays out.
+- Optimized and legacy-linear tetrahedron schemes.
+- Validation against legacy shell outputs, the legacy Python wrapper, and
+  analytic free-electron reference cases.
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+pip install bztetra
+```
+
+Project docs live at [skilledwolf.github.io/bztetra](https://skilledwolf.github.io/bztetra/).
+
+Plotting examples use Matplotlib:
+
+```bash
+pip install "bztetra[plot]"
+```
+
+From a source checkout:
+
+```bash
+pip install .
+```
+
+## First Calculation
+
+```python
+import numpy as np
+from bztetra import density_of_states_weights
+
+bvec = 2.0 * np.pi * np.eye(3)
+nx = ny = nz = 16
+energies = np.linspace(-1.0, 1.0, 200, dtype=np.float64)
+
+eigenvalues = np.empty((nx, ny, nz, 1), dtype=np.float64)
+for ix in range(nx):
+    for iy in range(ny):
+        for iz in range(nz):
+            kfrac = np.array([ix / nx, iy / ny, iz / nz], dtype=np.float64) - 0.5
+            kcart = bvec @ kfrac
+            eigenvalues[ix, iy, iz, 0] = 0.5 * np.dot(kcart, kcart)
+
+weights = density_of_states_weights(bvec, eigenvalues, energies)
+total_dos = weights.sum(axis=(1, 2, 3, 4)) * np.linalg.det(bvec)
+```
+
+`weights` has shape `(nenergy, nx, ny, nz, nbands)`. For band-resolved DOS,
+sum only over the k-grid axes.
+
+## Core Conventions
+
+- `reciprocal_vectors` is a `(3, 3)` matrix with reciprocal basis vectors in
+  columns.
+- `eigenvalues` always has shape `(nx, ny, nz, nbands)`.
+- `weight_grid_shape` is optional. Leave it unset unless you intentionally want
+  weights interpolated onto another regular grid.
+- Response outputs use the last axes `(target_band, source_band)`.
+- To integrate over the Brillouin zone, sum over the explicit k-grid axes and
+  multiply by `np.linalg.det(bvec)` for a right-handed basis.
+
+## Choose The Right Routine
+
+| Need | Call |
+| --- | --- |
+| Occupations at a known Fermi level | `occupation_weights` |
+| Fermi level search plus occupations | `solve_fermi_energy` |
+| DOS or integrated DOS on a sampled energy grid | `density_of_states_weights`, `integrated_density_of_states_weights` |
+| Static overlap, nesting, or polarization between two band manifolds | `phase_space_overlap_weights`, `nesting_function_weights`, `static_polarization_weights` |
+| Repeated real- or complex-frequency response sweeps | `prepare_response_evaluator`, then `fermi_golden_rule_weights` or `complex_frequency_polarization_weights` |
+
+See [docs/physics.md](docs/physics.md) for the key formulas and
+[docs/examples.md](docs/examples.md) for worked examples with output plots.
+
+## 2D Triangle Method
+
+For genuinely 2D problems, switch namespaces and use `bztetra.twod`.
+`bztetra.twod` keeps the same physics-facing routine names for occupations,
+DOS, overlap, Lindhard-style polarization, and real- or complex-frequency
+response, but on `(nx, ny, nbands)` arrays with Brillouin-zone **area**
+normalization and the linear triangle method.
+
+Start with [docs/two_dimensional_plan.md](docs/two_dimensional_plan.md) for
+the current 2D surface, then run one of the plot-backed example scripts:
+
+- [examples/plot_twod_square_lattice_dos.py](examples/plot_twod_square_lattice_dos.py)
+- [examples/plot_twod_phase_space_overlap.py](examples/plot_twod_phase_space_overlap.py)
+- [examples/plot_twod_lindhard.py](examples/plot_twod_lindhard.py)
+
+## Examples
+
+- [docs/quickstart.md](docs/quickstart.md): the shortest path from eigenvalues
+  on a regular grid to a correct `bztetra` call.
+- [examples/plot_tight_binding_dos.py](examples/plot_tight_binding_dos.py):
+  cubic tight-binding DOS figure.
+- [examples/review_occupancy.py](examples/review_occupancy.py): occupation
+  weights and Fermi-level search on a small reference problem.
+- [examples/plot_lindhard.py](examples/plot_lindhard.py): static Lindhard
+  response figure.
+- [examples/plot_twod_square_lattice_dos.py](examples/plot_twod_square_lattice_dos.py):
+  2D square-lattice DOS and integrated DOS via `bztetra.twod`.
+- [examples/plot_twod_phase_space_overlap.py](examples/plot_twod_phase_space_overlap.py):
+  2D free-electron `dblstep` phase-space overlap with the exact circular-segment curve.
+- [examples/plot_twod_lindhard.py](examples/plot_twod_lindhard.py):
+  2D free-electron static Lindhard plateau and Kohn cusp.
+
+## Validation
+
+`bztetra` is checked against tracked legacy shell/example fixtures, optional
+direct parity with the legacy `libtetrabz` Python wrapper, and analytic
+reference cases. See
+[docs/validation.md](docs/validation.md) for the exact coverage and
+reproduction commands.
+
+## Acknowledgement
+
+`bztetra` is a clean-room Python + Numba port informed by the original
+[`libtetrabz`](https://github.com/mitsuaki1987/libtetrabz) project by Mitsuaki
+Kawamura and collaborators. If `bztetra` is useful in research, users should
+also acknowledge the original method and implementation:
+
+- M. Kawamura, Y. Gohda, and S. Tsuneyuki, "Improved tetrahedron method for the
+  Brillouin-zone integration applicable to response functions,"
+  [Phys. Rev. B 89, 094515 (2014)](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.89.094515)
+- Original repository:
+  [github.com/mitsuaki1987/libtetrabz](https://github.com/mitsuaki1987/libtetrabz)
+
+## Development
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -e '.[dev]'
+python -m pytest -q
+```
+
+For local docs work:
+
+```bash
+pip install -e '.[dev,docs]'
+mkdocs serve
+```
+
+Benchmark entry points live under `benchmarks/`:
+
+```bash
+PYTHONPATH=src python benchmarks/benchmark_hotpaths.py
+PYTHONPATH=src python benchmarks/benchmark_twod_hotpaths.py --profile --profile-task complex_frequency_polarization_weights
+PYTHONPATH=src python benchmarks/benchmark_twod_response_multiband.py --profile --profile-task all
+```
+
+Package versions are derived from git tags at build and install time.

bztetra-0.1.0/README.pypi.md

@@ -0,0 +1,39 @@
+# bztetra
+
+`bztetra` is a Python + Numba package for tetrahedron integration on regular
+k-grids.
+
+This is the public `0.x` preview series. Validate important production results
+against the original
+[`libtetrabz`](https://github.com/mitsuaki1987/libtetrabz) implementation or
+the parity guidance in the
+[validation docs](https://skilledwolf.github.io/bztetra/validation/).
+
+## Install
+
+```bash
+pip install bztetra
+```
+
+Plot-backed examples use Matplotlib:
+
+```bash
+pip install "bztetra[plot]"
+```
+
+## What It Provides
+
+- Occupation, DOS, and integrated DOS weights on regular 3D k-grids.
+- Static overlap, nesting, and polarization weights.
+- Real- and complex-frequency Lindhard-style response functions.
+- A separate `bztetra.twod` namespace for genuine 2D triangle-method problems.
+
+## Documentation
+
+- Documentation: <https://skilledwolf.github.io/bztetra/>
+- Quickstart: <https://skilledwolf.github.io/bztetra/quickstart/>
+- Physics guide: <https://skilledwolf.github.io/bztetra/physics/>
+- Examples: <https://skilledwolf.github.io/bztetra/examples/>
+- Validation: <https://skilledwolf.github.io/bztetra/validation/>
+- Repository: <https://github.com/skilledwolf/bztetra>
+- Issues: <https://github.com/skilledwolf/bztetra/issues>

bztetra-0.1.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["hatch-vcs>=0.4", "hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bztetra"
+dynamic = ["version"]
+description = "Python and Numba port of libtetrabz-style tetrahedron integration routines."
+readme = {file = "README.pypi.md", content-type = "text/markdown"}
+requires-python = ">=3.11"
+license = {file = "LICENSE"}
+license-files = ["LICENSE"]
+authors = [
+  {name = "bztetra contributors"},
+]
+keywords = [
+  "brillouin-zone",
+  "density-of-states",
+  "electronic-structure",
+  "numba",
+  "tetrahedron-method",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+  "numba>=0.61",
+  "numpy>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/skilledwolf/bztetra"
+Documentation = "https://skilledwolf.github.io/bztetra/"
+Repository = "https://github.com/skilledwolf/bztetra"
+Issues = "https://github.com/skilledwolf/bztetra/issues"
+
+[project.optional-dependencies]
+plot = [
+  "matplotlib>=3.9",
+]
+docs = [
+  "mkdocs>=1.6",
+  "mkdocs-material>=9.5",
+  "mkdocstrings[python]>=0.28",
+]
+dev = [
+  "matplotlib>=3.9",
+  "pytest>=8.0",
+  "ruff>=0.11",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bztetra"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/LICENSE",
+  "/README.md",
+  "/README.pypi.md",
+  "/pyproject.toml",
+  "/src",
+]
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+fallback_version = "0.0.0"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

bztetra-0.1.0/src/bztetra/__init__.py

@@ -0,0 +1,56 @@
+"""Modern 3D Python port of the legacy libtetrabz tetrahedron routines."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as package_version
+
+from .dos import density_of_states_weights
+from .dos import integrated_density_of_states_weights
+from .occupancy import FermiEnergySolution
+from .response import complex_frequency_polarization_weights
+from .response import fermi_golden_rule_weights
+from .response import nesting_function_weights
+from .response import phase_space_overlap_weights
+from .response import prepare_response_evaluator
+from .response import PreparedResponseEvaluator
+from .response import static_polarization_weights
+from .formulas import SimplexCut
+from .geometry import IntegrationMesh
+from .geometry import build_integration_mesh
+from .occupancy import occupation_weights
+from .occupancy import solve_fermi_energy
+from .formulas import simplex_affine_coefficients
+from .formulas import small_tetrahedron_cut
+from .geometry import tetrahedron_offsets
+from .geometry import tetrahedron_weight_matrix
+from .formulas import triangle_cut
+from .geometry import trilinear_interpolation_indices
+
+try:
+    __version__ = package_version("bztetra")
+except PackageNotFoundError:
+    __version__ = "0+unknown"
+
+__all__ = [
+    "complex_frequency_polarization_weights",
+    "density_of_states_weights",
+    "FermiEnergySolution",
+    "fermi_golden_rule_weights",
+    "integrated_density_of_states_weights",
+    "IntegrationMesh",
+    "nesting_function_weights",
+    "occupation_weights",
+    "phase_space_overlap_weights",
+    "PreparedResponseEvaluator",
+    "prepare_response_evaluator",
+    "SimplexCut",
+    "solve_fermi_energy",
+    "static_polarization_weights",
+    "__version__",
+    "build_integration_mesh",
+    "simplex_affine_coefficients",
+    "small_tetrahedron_cut",
+    "tetrahedron_offsets",
+    "tetrahedron_weight_matrix",
+    "triangle_cut",
+    "trilinear_interpolation_indices",
+]