Metadata-Version: 2.4
Name: kpenvelope
Version: 0.5.0
Summary: Six-band k.p envelope-function solver for wurtzite heterostructures, self-consistent with Poisson
Author-email: "Tanvir M. Mahim" <tanvir.mahim@bracu.ac.bd>
License: Apache-2.0
Project-URL: Homepage, https://tanvir-mahmud-mahim.github.io/software/
Project-URL: Repository, https://github.com/TaN-MM-Org/kpenvelope
Project-URL: Issues, https://github.com/TaN-MM-Org/kpenvelope/issues
Project-URL: Changelog, https://github.com/TaN-MM-Org/kpenvelope/releases
Keywords: k.p,envelope function,wurtzite,GaN,2DHG,subband,semiconductor
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: scipy>=1.8; extra == "test"
Dynamic: license-file

# kpenvelope

[![PyPI](https://img.shields.io/pypi/v/kpenvelope)](https://pypi.org/project/kpenvelope/) [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22015269-blue)](https://doi.org/10.5281/zenodo.22015269) [![tests](https://github.com/TaN-MM-Org/kpenvelope/actions/workflows/ci.yml/badge.svg)](https://github.com/TaN-MM-Org/kpenvelope/actions)

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.

```python
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]`.

```python
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.

```python
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](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
