kpenvelope

A six-band k.p envelope-function solver for wurtzite heterostructures, solved self-consistently with Poisson's equation on a 1D grid. Built for polarization-induced two-dimensional hole gases (GaN/AlN and related systems), where the confining potential is not imposed but emerges from the balance between the fixed polarization charge and the gas itself.

Finite barriers (new in v0.5)

The gate this README used to name is closed: assemble_heterostructure makes the material parameters and the valence band edge functions of z with the symmetrized Ben Daniel-Duke discretization, so the matrix stays exactly Hermitian for arbitrary layer stacks and reduces exactly to the uniform assembly when every point carries the same material (asserted at machine precision). layered_profile builds per-point profiles from a layer stack; solve_heterostructure returns subbands and envelopes with the usual conventions. No default band offset is shipped on purpose: alignments are material- and strain-specific and must be supplied with a citation, like every other number in this package.

Validated against closed forms: the decoupled single-band well reproduces the textbook finite-square-well transcendental levels with second-order grid convergence, the envelope decays in the barrier with the analytic decay constant to better than a percent, and the deep-barrier limit approaches the hard-wall solver.

from kpenvelope import (gan_rinke2008, aln_rinke2008, layered_profile,
                        solve_heterostructure)
import numpy as np
z = np.linspace(0.0, 30.0, 301)
params, edge = layered_profile(z, [(10.0, aln_rinke2008(), -vbo),
                                   (10.0, gan_rinke2008(), 0.0),
                                   (10.0, aln_rinke2008(), -vbo)])
energies, envelopes = solve_heterostructure(z, params, edge)

Status

v0.5.0 (alpha). Implemented and tested:

• six-band wurtzite valence Hamiltonian (standard Chuang-Chang form), discretized with symmetrized operator ordering so the matrix is exactly Hermitian for position-dependent parameters

• envelope eigen-solution at arbitrary in-plane k

• Gauss-law hole potential from the density profile

• self-consistent loop with T = 0 subband filling using numeric in-plane edge masses, converging to charge neutrality

• cited GaN and AlN parameter sets with closed-form verification (new in v0.2, see below)

• dispersion and mass utilities (new in v0.3): subband dispersions along an in-plane path (subband_dispersion) and the local finite-difference effective mass of any dispersion (local_mass), because a hole mass is not one number. Asserted in the test suite: the decoupled demo set returns exactly 1/|A| m0 at every momentum; applied to the bulk Rinke 2008 GaN bands the utility reproduces the quasi-cubic asymptotic masses 1.89 and 0.180 m0; and a locally flat branch reports an infinite mass rather than an error, because a diverging mass is physics.

• finite barriers (new in v0.5): position-dependent material parameters and band edge with the symmetrized Ben Daniel-Duke discretization (see above). The bare solve_subbands/ solve_self_consistent path still uses hard walls at the grid ends; use solve_heterostructure when the barrier matters.

Not yet implemented, stated plainly because they matter physically:

• strain terms, full k-grid (non-parabolic) filling, spin splitting analysis, transport lifetimes, and a self-consistent loop on the finite-barrier assembly (the current self-consistent solver remains hard-wall).

Cited parameter sets (new in v0.2)

• gan_rinke2008(): the consistent GW-based GaN valence set of Rinke et al., Phys. Rev. B 77, 075202 (2008) (A1..A6, Delta_CR = 10 meV, Delta_SO = 17 meV, delta2 = delta3 = Delta_SO/3), as tabulated in Extended Data Table 1 of Chang et al., Nature Electronics 9, 346 (2026) and used in the source paper below. eps_r = 10.4 (E parallel to c) from Barker and Ilegems, Phys. Rev. B 7, 743 (1973).
• aln_rinke2008(): the matching AlN set (Delta_CR = -295 meV from Rinke et al.; Delta_SO = 22 meV from de Carvalho et al., Appl. Phys. Lett. 97, 232101 (2010)), intended as a barrier material. Its permittivity is deliberately NaN, and the self-consistent solver refuses to run on it, because no vetted value is shipped and none is needed for a barrier.

The test-suite locks every number and checks the GaN set against closed forms: the zone-center splittings come out at 5.20 and 21.80 meV (against accepted experimental values near 5-6 and 22 meV), and the asymptotic in-plane masses at m0/|A2+A4-A5| = 1.89 m0 and m0/|A2+A4+A5| = 0.18 m0, the quasi-cubic values quoted in the source paper's Supplemental Material.

For any other material or parameterization, populate WurtziteParameters from the literature (e.g. Vurgaftman and Meyer, J. Appl. Phys. 94, 3675 (2003)) and record the source in the mandatory reference field. The shipped demo_single_band() set is a decoupled, non-physical configuration used by the test-suite, chosen because it has closed-form well solutions to test against.

Install and use

pip install kpenvelope

For development, clone the repository and pip install -e .[test].

import numpy as np
from kpenvelope import gan_rinke2008, solve_self_consistent

p = gan_rinke2008()                      # cited set; or your own WurtziteParameters
z = np.linspace(0.0, 6.0, 97)            # nm, from the interface
res = solve_self_consistent(p, z, ps=0.46)   # ps in nm^-2; 4.6e13 cm^-2 = 0.46
# res.energies, res.masses, res.density, res.potential, res.occupations

Convention: valence-electron energies, holes occupy the highest eigenvalues; energies in eV, lengths in nm, sheet densities in nm^-2.

Verification

The test-suite checks Hermiticity with every coupling switched on, the decoupled square-well limit against the analytic spectrum, the uniform slab against the analytic Gauss-law potential, convergence plus exact charge neutrality of the self-consistent loop, and (new in v0.2) the cited GaN set against the closed-form quasi-cubic splittings and masses above.

One comparison against the source paper is on record and stated honestly: a hard-wall self-consistent run at the measured sheet density (4.6e13 cm^-2, 97 points over 6 nm) puts the gas centroid at 0.62 nm against 0.568 nm for the hard-wall row of the paper's Table S1, with the same subband structure (two heavy branches filled, the light branch a minority). The difference comes from the filling model: this package fills parabolic edge-mass subbands, while the paper fills the computed non-parabolic dispersions, and the light branch is strongly non-parabolic. The finite-barrier assembly (v0.5) removes the hard-wall half of that caveat for fixed-potential runs; the self-consistent loop is still hard-wall and parabolic-filled, so the warning stands for self-consistent numbers: do not publish them without checking the barrier and filling model against your system.

Subband character (new in v0.4)

band_character resolves each envelope state into its heavy-hole, light-hole and crystal-field split-off fractions (basis populations in the Chuang-Chang basis), and character_vs_k tracks the composition along an in-plane path. Band mixing is the physics behind the "one subband, many masses" problem this package makes explicit: the top subband is pure HH at the zone center, and its mass moves as LH and CH weight grows with in-plane momentum.

from kpenvelope import band_character, gan_rinke2008, solve_subbands

energies, envelopes = solve_subbands(gan_rinke2008(), z, kx=0.3)
fractions = band_character(envelopes, z)   # (n_states, 3): HH, LH, CH

The tests assert the exact zone-center block structure rather than an approximation: at kt = 0 the six-band Hamiltonian couples only LH and CH (through delta3), so every zone-center state has HH fraction exactly 1 or exactly 0, and the LH states carry the small CH admixture the delta3 coupling demands.

Methodological basis

T. M. Mahim, A. S. M. Mohsin and M. M. Rahman, "Origin of the conflicting hole masses in the GaN/AlN two-dimensional hole gas" (under review); code for the paper: https://github.com/Tanvir-Mahmud-Mahim/gan-2dhg-masses-lifetimes

and S. L. Chuang and C. S. Chang, Phys. Rev. B 54, 2491 (1996). This package is the general-purpose tool; the paper repository reproduces the specific published study, including the dispersion-filled self-consistent finite-barrier calculation that this package does not yet run end to end.

Support and governance

The package is written and maintained by Tanvir Mahmud Mahim (Department of Electrical and Electronic Engineering, BRAC University), who reviews every change and takes the final decision on scope and releases. There is no separate governance body; design questions are discussed in the open in issues and pull requests, and the standing rule of CONTRIBUTING.md binds the maintainer exactly as it binds contributors: a change that touches physics arrives with a test, and a constant arrives with its source.

Support runs through the issue tracker at https://github.com/TaN-MM-Org/kpenvelope/issues. Usage questions are welcome there alongside bug reports; a docstring that left a unit or a sign convention unclear is treated as a documentation bug, not as user error. The maintainer aims to respond within a week.

While the version is below 1.0 the API may still move between minor versions; such changes are called out in the release notes. The limitations named under Status are deliberate scope, recorded there precisely so that a user can tell a designed-out feature from an oversight.

License

Apache-2.0