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.7.0 (alpha). Implemented and tested (47 tests, Python 3.9-3.13):

• 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.

Every item of the v0.5 roadmap is now implemented (v0.6): Bir-Pikus strain terms (strain_blocks, wired through every assembly, validated by the structural identity with the kinetic template at eps_ij = k_i k_j and by closed-form eigenvalues -- no deformation-potential values shipped, on purpose: supply cited D1..D6); full k-grid non-parabolic filling (fill_subbands_kgrid, agreeing with the closed-form parabolic filler on an exactly parabolic model and refusing an undersized k-window); spin-splitting analysis (spin_splitting, splitting_vs_k: exactly zero where Kramers and inversion symmetry demand, finite Rashba-type splitting of the 2DHG under an asymmetric potential); the finite-barrier self-consistent loop (solve_self_consistent_hetero, reproducing the hard-wall loop exactly on a uniform stack); and the transport groundwork (group_velocity, dos_from_dispersion, both pinned to parabolic closed forms).

Intersubband optics (new in v0.7): dipole_matrix computes the intersubband dipole matrix elements z_mn = <m|z|n> from any solver's envelopes (trapezoidal inner products on the solver's own grid, all spinor components summed, Hermiticity enforced by construction), and oscillator_strengths converts the ground-subband dipole column into dimensionless oscillator strengths f_(1->n) = (m*/m0) (E_1 - E_n) |z_1n|^2 / (hbar^2/2m0) (hole convention, energies descending) -- the quantities that set intersubband absorption spectra and the design of QWIPs and polaritonic devices. Anchors, asserted not stated: on a hard-wall well the multiplet-summed dipole and oscillator strength reproduce the textbook closed forms z12 = 16 L / (9 pi^2) and f12 = 256 / (27 pi^2); the Thomas-Reiche-Kuhn f-sum rule sum_n f_1n = 1 is verified to a fraction of a percent with basis-size convergence; parity forbids z13 on a symmetric well (found at 1e-12); and shifting the coordinate origin changes no off-diagonal element (gauge identity, checked on the coupled Rinke 2008 GaN well). For the shipped six-fold-degenerate demo set the invariant quantities are the multiplet-summed ones, and the docstrings say so rather than letting a user read meaning into basis-dependent individual elements.

Deliberate scope, stated plainly -- designed-out, not overlooked: scattering-mechanism transport lifetimes (interface roughness, ionized impurities, phonons) need cited screening and roughness parameters per structure, and this package ships no number it cannot source -- the DOS and velocity factors every lifetime integral needs are provided instead; the Poisson solve is single-medium (one cited permittivity; a spatially varying permittivity is not smuggled in); and k-linear bulk-inversion-asymmetry terms beyond the six-band Chuang-Chang form are not included.

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