kpenvelope 0.2.1__tar.gz

kpenvelope-0.2.1/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

kpenvelope-0.2.1/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: kpenvelope
+Version: 0.2.1
+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"
+Dynamic: license-file
+
+# 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.
+
+## Status
+
+v0.2.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)
+
+Not yet implemented, stated plainly because they matter physically:
+
+- **finite barriers.** Hard walls one grid spacing outside the grid ends.
+  A hard wall forces the envelope to vanish at the interface and pushes
+  the gas outward, which shifts subband energies and masses; a finite AlN
+  barrier treated as position-dependent material parameters is the v0.3
+  gate before research-grade use.
+- strain terms, full k-grid (non-parabolic) filling, spin splitting
+  analysis, transport lifetimes.
+
+## 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 -e .
+```
+
+```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. Together with the hard-wall boundary this is why the same
+warning stands: do not use these numbers in publications before the
+finite-barrier, dispersion-filled v0.3.
+
+## 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 finite-barrier physics that this
+package does not yet have.
+
+## License
+
+Apache-2.0

kpenvelope-0.2.1/README.md

@@ -0,0 +1,117 @@
+# 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.
+
+## Status
+
+v0.2.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)
+
+Not yet implemented, stated plainly because they matter physically:
+
+- **finite barriers.** Hard walls one grid spacing outside the grid ends.
+  A hard wall forces the envelope to vanish at the interface and pushes
+  the gas outward, which shifts subband energies and masses; a finite AlN
+  barrier treated as position-dependent material parameters is the v0.3
+  gate before research-grade use.
+- strain terms, full k-grid (non-parabolic) filling, spin splitting
+  analysis, transport lifetimes.
+
+## 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 -e .
+```
+
+```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. Together with the hard-wall boundary this is why the same
+warning stands: do not use these numbers in publications before the
+finite-barrier, dispersion-filled v0.3.
+
+## 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 finite-barrier physics that this
+package does not yet have.
+
+## License
+
+Apache-2.0

kpenvelope-0.2.1/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kpenvelope"
+version = "0.2.1"
+description = "Six-band k.p envelope-function solver for wurtzite heterostructures, self-consistent with Poisson"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Tanvir M. Mahim", email = "tanvir.mahim@bracu.ac.bd" }]
+requires-python = ">=3.9"
+keywords = ["k.p", "envelope function", "wurtzite", "GaN", "2DHG", "subband", "semiconductor"]
+dependencies = ["numpy>=1.22"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Physics",
+]
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[project.urls]
+Homepage = "https://tanvir-mahmud-mahim.github.io/software/"
+Repository = "https://github.com/TaN-MM-Org/kpenvelope"
+Issues = "https://github.com/TaN-MM-Org/kpenvelope/issues"
+Changelog = "https://github.com/TaN-MM-Org/kpenvelope/releases"
+
+[tool.setuptools.packages.find]
+where = ["src"]

kpenvelope-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kpenvelope-0.2.1/src/kpenvelope/__init__.py

@@ -0,0 +1,23 @@
+"""kpenvelope: multiband k.p envelope-function solver for wurtzite heterostructures.
+
+Solves the six-band valence envelope-function problem on a 1D grid,
+self-consistently with Poisson's equation, for polarization-induced
+two-dimensional hole gases and related wurtzite heterostructures.
+
+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), and the standard wurtzite k.p formulation of
+Chuang and Chang, Phys. Rev. B 54, 2491 (1996).
+"""
+from .params import (WurtziteParameters, aln_rinke2008, demo_single_band,
+                     gan_rinke2008)
+from .hamiltonian import assemble_hamiltonian, HBAR2_OVER_2M0
+from .solver import solve_subbands
+from .selfconsistent import solve_self_consistent, SelfConsistentResult
+
+__version__ = "0.2.1"
+__all__ = [
+    "WurtziteParameters", "demo_single_band", "gan_rinke2008",
+    "aln_rinke2008", "assemble_hamiltonian", "solve_subbands",
+    "solve_self_consistent", "SelfConsistentResult", "HBAR2_OVER_2M0",
+]

kpenvelope-0.2.1/src/kpenvelope/hamiltonian.py

@@ -0,0 +1,105 @@
+"""Assembly of the six-band wurtzite envelope Hamiltonian on a 1D grid.
+
+The bulk Hamiltonian follows the standard wurtzite six-band form (Chuang
+and Chang, Phys. Rev. B 54, 2491 (1996)), written here as
+
+    H(k) = H0(kx, ky) + H1(kx, ky) * kz + H2 * kz^2
+
+The envelope operator is obtained by kz -> -i d/dz with the symmetrized
+(Ben Daniel-Duke) discretization for the kz^2 terms and the symmetrized
+first-difference for terms linear in kz, which keeps the discrete matrix
+exactly Hermitian, including for position-dependent parameters.
+
+Off-diagonal phase conventions differ between papers; eigenvalues are
+invariant under those phase choices.
+
+Energies in eV, lengths in nm. Valence-electron energy convention: holes
+occupy the HIGHEST eigenvalues.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+# hbar^2 / (2 m0) in eV nm^2
+HBAR2_OVER_2M0 = 0.0380998
+
+
+def bulk_blocks(p, kx: float, ky: float):
+    """Return (H0, H1, H2): 6x6 complex blocks for the given in-plane k.
+
+    H(k) = H0 + H1*kz + H2*kz^2, with kz in nm^-1 and energies in eV.
+    """
+    c = HBAR2_OVER_2M0
+    kt2 = kx * kx + ky * ky
+    kplus = kx + 1j * ky
+
+    lam0 = c * p.A2 * kt2                 # kz-independent part of lambda
+    th0 = c * p.A4 * kt2                  # kz-independent part of theta
+    F0 = p.delta1 + p.delta2 + lam0 + th0
+    G0 = p.delta1 - p.delta2 + lam0 + th0
+    K0 = c * p.A5 * kplus * kplus         # K term, no kz dependence
+    D = np.sqrt(2.0) * p.delta3
+
+    H0 = np.array([
+        [F0, -np.conj(K0), 0, 0, 0, 0],
+        [-K0, G0, 0, 0, 0, D],
+        [0, 0, lam0, 0, D, 0],
+        [0, 0, 0, F0, -K0, 0],
+        [0, 0, D, -np.conj(K0), G0, 0],
+        [0, D, 0, 0, 0, lam0],
+    ], dtype=complex)
+
+    # terms linear in kz: Ht = A6 k+ kz enters the (1,3)/(2,3) pattern
+    Ht = c * p.A6 * kplus
+    H1 = np.zeros((6, 6), dtype=complex)
+    H1[0, 2] = -np.conj(Ht)
+    H1[2, 0] = -Ht
+    H1[1, 2] = Ht
+    H1[2, 1] = np.conj(Ht)
+    H1[3, 5] = np.conj(Ht)
+    H1[5, 3] = Ht
+    H1[4, 5] = -Ht
+    H1[5, 4] = -np.conj(Ht)
+
+    # kz^2 coefficients: lambda gains A1 kz^2, theta gains A3 kz^2
+    lam2 = c * p.A1
+    th2 = c * p.A3
+    H2 = np.diag([lam2 + th2, lam2 + th2, lam2, lam2 + th2, lam2 + th2, lam2]).astype(complex)
+    return H0, H1, H2
+
+
+def assemble_hamiltonian(p, z, kx: float = 0.0, ky: float = 0.0, potential=None):
+    """Dense 6N x 6N envelope Hamiltonian on grid z (uniform, nm).
+
+    potential : optional array of the HOLE potential energy V_h(z) in eV;
+        it enters the valence-electron Hamiltonian as -V_h on the diagonal.
+    Hard-wall boundaries at both ends of the grid (v0.1 limitation; a
+    finite barrier treated as a position-dependent material is the v0.2
+    gate, and matters: a hard wall pushes the gas away from the interface).
+    """
+    z = np.asarray(z, dtype=float)
+    n = z.size
+    dz = z[1] - z[0]
+    if not np.allclose(np.diff(z), dz):
+        raise ValueError("z grid must be uniform")
+
+    H0, H1, H2 = bulk_blocks(p, kx, ky)
+    H = np.zeros((6 * n, 6 * n), dtype=complex)
+
+    idx = lambda i: slice(6 * i, 6 * i + 6)
+    inv_dz2 = 1.0 / (dz * dz)
+    inv_2dz = 1.0 / (2.0 * dz)
+
+    for i in range(n):
+        diag = H0.copy()
+        # kz^2 term: -d/dz H2 d/dz -> +2 H2 / dz^2 on the diagonal
+        diag += 2.0 * H2 * inv_dz2
+        if potential is not None:
+            diag -= potential[i] * np.eye(6)
+        H[idx(i), idx(i)] = diag
+        if i + 1 < n:
+            # kz^2 off-diagonal: -H2/dz^2 ; kz linear: -i H1 * (D_central)
+            off = -H2 * inv_dz2 + (-1j) * H1 * inv_2dz
+            H[idx(i), idx(i + 1)] = off
+            H[idx(i + 1), idx(i)] = off.conj().T
+    return H

kpenvelope-0.2.1/src/kpenvelope/params.py

@@ -0,0 +1,143 @@
+"""Band-structure parameter sets.
+
+This module ships two CITED parameter sets, gan_rinke2008() and
+aln_rinke2008(), plus a synthetic set for the test-suite. Every number in
+the cited sets is traceable to the source given in its `reference` field,
+and the test-suite checks the GaN set against closed-form quasi-cubic
+results (zone-center splittings of 5.20 and 21.80 meV; asymptotic in-plane
+masses m0/|A2+A4-A5| and m0/|A2+A4+A5|).
+
+The general warning stands: A parameters and splittings differ between
+first-principles parameterizations, and the choice materially affects
+computed masses. 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.
+
+demo_single_band() returns a degenerate, decoupled parameter set used by
+the test-suite; it is numerically convenient and physically meaningless.
+"""
+from __future__ import annotations
+
+import dataclasses
+
+
+@dataclasses.dataclass
+class WurtziteParameters:
+    """Six-band wurtzite valence parameters (Chuang-Chang convention).
+
+    A1..A6 : dimensionless valence-band effective-mass parameters.
+    delta1 : crystal-field splitting (eV).
+    delta2, delta3 : spin-orbit parameters (eV); for the common isotropic
+        approximation delta2 = delta3 = Delta_so / 3.
+    eps_r : static relative permittivity (used by the Poisson solver).
+        May be NaN for a set intended only as a barrier material; the
+        self-consistent solver refuses to run on a NaN permittivity.
+    reference : provenance of the numbers. Required, on purpose.
+    """
+
+    A1: float
+    A2: float
+    A3: float
+    A4: float
+    A5: float
+    A6: float
+    delta1: float
+    delta2: float
+    delta3: float
+    eps_r: float
+    reference: str
+
+
+def demo_single_band(A: float = -2.0) -> WurtziteParameters:
+    """A decoupled, NON-PHYSICAL parameter set for tests.
+
+    With A1 = A2 = A and every other coupling zero, the six-band
+    Hamiltonian reduces to six identical parabolic bands with
+    E = A * (hbar^2/2m0) * k^2, which has closed-form well solutions.
+    """
+    return WurtziteParameters(
+        A1=A, A2=A, A3=0.0, A4=0.0, A5=0.0, A6=0.0,
+        delta1=0.0, delta2=0.0, delta3=0.0,
+        eps_r=10.0,
+        reference="synthetic single-band demonstration values; not physical",
+    )
+
+
+def gan_rinke2008() -> WurtziteParameters:
+    """GaN valence parameters of Rinke et al., Phys. Rev. B 77, 075202 (2008).
+
+    A1..A6 and the crystal-field splitting Delta_CR = 10 meV and spin-orbit
+    splitting Delta_SO = 17 meV are the consistent GW-based set of Rinke
+    et al., as tabulated in Extended Data Table 1 of Chang et al., Nature
+    Electronics 9, 346 (2026), and as used in the self-consistent analysis
+    of Mahim, Mohsin and Rahman (gan-2dhg-masses-lifetimes). The isotropic
+    quasi-cubic convention delta2 = delta3 = Delta_SO / 3 is applied.
+
+    With these numbers the k = 0 splittings of the six-band Hamiltonian
+    are 5.20 and 21.80 meV (against accepted experimental values near
+    5 to 6 and 22 meV), and the asymptotic in-plane masses are
+    m0/|A2+A4-A5| = 1.89 m0 and m0/|A2+A4+A5| = 0.18 m0; the test-suite
+    checks both from the assembled Hamiltonian.
+
+    eps_r = 10.4 is the static dielectric constant of GaN for fields along
+    the c axis (the growth axis of a c-plane heterostructure), from the
+    infrared oscillator fit of Barker and Ilegems, Phys. Rev. B 7, 743
+    (1973); it is the value used by the analysis of Mahim et al.
+    """
+    return WurtziteParameters(
+        A1=-5.947, A2=-0.528, A3=5.414,
+        A4=-2.512, A5=-2.510, A6=-3.202,
+        delta1=0.010,
+        delta2=0.017 / 3.0,
+        delta3=0.017 / 3.0,
+        eps_r=10.4,
+        reference=(
+            "A1-A6, Delta_CR = 0.010 eV, Delta_SO = 0.017 eV: P. Rinke "
+            "et al., Phys. Rev. B 77, 075202 (2008), as tabulated in "
+            "Extended Data Table 1 of C. F. C. Chang et al., Nature "
+            "Electronics 9, 346 (2026) and used in T. M. Mahim, "
+            "A. S. M. Mohsin and M. M. Rahman (under review; code: "
+            "github.com/Tanvir-Mahmud-Mahim/gan-2dhg-masses-lifetimes, "
+            "doi:10.5281/zenodo.21798022). delta2 = delta3 = Delta_SO/3. "
+            "eps_r = 10.4 (E parallel c): A. S. Barker and M. Ilegems, "
+            "Phys. Rev. B 7, 743 (1973)."
+        ),
+    )
+
+
+def aln_rinke2008() -> WurtziteParameters:
+    """AlN valence parameters, intended as a BARRIER material.
+
+    A1..A6 and Delta_CR = -295 meV are from Rinke et al., Phys. Rev. B 77,
+    075202 (2008), the same source from which the GaN set descends. Rinke
+    et al. do not tabulate the spin-orbit splitting of AlN; Delta_SO =
+    22 meV is the midpoint of the values computed by de Carvalho et al.,
+    Appl. Phys. Lett. 97, 232101 (2010) (21.7 meV parallel, 23.5 meV
+    perpendicular), following the treatment of Mahim, Mohsin and Rahman,
+    who verify that changing it from 22 to 19 meV changes nothing at four
+    figures in their barrier-sensitive results.
+
+    eps_r is deliberately NaN: this set is meant for barrier regions,
+    where the states are evanescent and the permittivity never enters the
+    supported calculations. The self-consistent solver refuses a NaN
+    permittivity rather than running with an unvetted number; supply your
+    own cited value if you need an AlN Poisson solve.
+    """
+    return WurtziteParameters(
+        A1=-3.991, A2=-0.311, A3=3.671,
+        A4=-1.147, A5=-1.329, A6=-1.952,
+        delta1=-0.295,
+        delta2=0.022 / 3.0,
+        delta3=0.022 / 3.0,
+        eps_r=float("nan"),
+        reference=(
+            "A1-A6, Delta_CR = -0.295 eV: P. Rinke et al., Phys. Rev. B "
+            "77, 075202 (2008). Delta_SO = 0.022 eV: midpoint of L. C. "
+            "de Carvalho et al., Appl. Phys. Lett. 97, 232101 (2010). "
+            "delta2 = delta3 = Delta_SO/3. As used in T. M. Mahim, "
+            "A. S. M. Mohsin and M. M. Rahman (under review; "
+            "doi:10.5281/zenodo.21798022). eps_r intentionally NaN: "
+            "barrier-only set, no vetted permittivity shipped."
+        ),
+    )

kpenvelope-0.2.1/src/kpenvelope/poisson.py

@@ -0,0 +1,33 @@
+"""Electrostatics of a polarization-bound hole gas.
+
+The confining potential is not imposed: the gas is balanced by the fixed
+polarization bound charge at the interface (z = 0), and Gauss's law gives
+the hole potential energy
+
+    dV_h/dz = (e^2 / (eps_r eps_0)) * ( ps - integral_0^z p(z') dz' )
+
+which is positive at the interface (holes are held against it) and
+vanishes once the whole gas lies below z. Units: eV, nm, densities nm^-2
+(sheet) and nm^-3 (volume).
+"""
+from __future__ import annotations
+
+import numpy as np
+
+# e^2 / (4 pi eps0) = 1.4399645 eV nm  ->  e^2/eps0 = 4*pi*that
+E2_OVER_EPS0 = 4.0 * np.pi * 1.4399645
+
+
+def hole_potential(z, p_density, ps, eps_r):
+    """Integrate the hole potential energy V_h(z) from the density profile.
+
+    z : uniform grid (nm), starting at the interface z=0.
+    p_density : hole volume density on the grid (nm^-3).
+    ps : total sheet density (nm^-2).
+    """
+    z = np.asarray(z, dtype=float)
+    dz = z[1] - z[0]
+    cum = np.cumsum(p_density) * dz          # integral_0^z p
+    field = (E2_OVER_EPS0 / eps_r) * (ps - cum)
+    vh = np.concatenate([[0.0], np.cumsum(0.5 * (field[1:] + field[:-1]) * dz)])
+    return vh

kpenvelope-0.2.1/src/kpenvelope/selfconsistent.py

@@ -0,0 +1,118 @@
+"""Self-consistent solution of the coupled k.p and Poisson problem."""
+from __future__ import annotations
+
+import dataclasses
+
+import numpy as np
+
+from .poisson import hole_potential
+from .solver import solve_subbands
+from .hamiltonian import HBAR2_OVER_2M0
+
+
+@dataclasses.dataclass
+class SelfConsistentResult:
+    z: np.ndarray
+    potential: np.ndarray          # hole potential energy V_h(z), eV
+    energies: np.ndarray           # subband edges at k_t = 0 (valence eV, descending)
+    envelopes: np.ndarray          # (n, 6, N)
+    density: np.ndarray            # hole volume density (nm^-3)
+    occupations: np.ndarray        # sheet density per subband (nm^-2)
+    masses: np.ndarray             # numeric in-plane edge masses (units of m0)
+    iterations: int
+    residual: float
+
+
+def _inplane_masses(p, z, potential, energies0, n_states, dk=0.02):
+    """Numeric in-plane effective masses at the subband edge along kx.
+
+    m*/m0 = (hbar^2/2m0) * (2 dk^2) / (E(0) - E(dk)) for a band curving
+    downward from the valence edge (hole mass positive).
+    """
+    e_k, _ = solve_subbands(p, z, kx=dk, ky=0.0, potential=potential,
+                            n_states=n_states)
+    masses = []
+    for i in range(n_states):
+        curv = energies0[i] - e_k[i]
+        if curv <= 1e-12:
+            masses.append(np.inf)
+        else:
+            masses.append(HBAR2_OVER_2M0 * dk * dk / curv)
+    return np.asarray(masses)
+
+
+def _fill_subbands(energies, masses, ps):
+    """T = 0 filling of hole subbands with parabolic in-plane dispersion.
+
+    Holes fill from the highest valence energy downward. Each state is a
+    single spin-resolved branch with 2D DOS m/(2 pi hbar^2) = m/(m0) /
+    (4 pi (hbar^2/2m0)). Solves for E_F by bisection so occupations sum
+    to ps. Returns per-subband sheet densities (nm^-2).
+    """
+    dos = (masses / HBAR2_OVER_2M0) / (4.0 * np.pi)   # states nm^-2 eV^-1
+    finite = np.isfinite(dos)
+
+    def total(ef):
+        occ = np.where(finite, dos * np.clip(energies - ef, 0.0, None), 0.0)
+        return occ.sum()
+
+    lo, hi = energies.min() - 5.0, energies.max()
+    for _ in range(200):
+        mid = 0.5 * (lo + hi)
+        if total(mid) > ps:
+            lo = mid
+        else:
+            hi = mid
+    ef = 0.5 * (lo + hi)
+    occ = np.where(finite, dos * np.clip(energies - ef, 0.0, None), 0.0)
+    if occ.sum() > 0:
+        occ = occ * (ps / occ.sum())      # exact neutrality after bisection
+    return occ
+
+
+def solve_self_consistent(p, z, ps, n_states=6, mixing=0.3, tol=1e-5,
+                          max_iter=80):
+    """Iterate k.p and Poisson to self-consistency at sheet density ps.
+
+    p : WurtziteParameters.  z : uniform grid from the interface (nm).
+    ps : hole sheet density (nm^-2). Note 1e13 cm^-2 = 0.1 nm^-2.
+
+    Returns SelfConsistentResult. Convergence is measured as the maximum
+    absolute change of V_h between iterations (eV).
+    """
+    if not (p.eps_r == p.eps_r):   # NaN check without importing math
+        raise ValueError(
+            "this parameter set carries no vetted permittivity (eps_r is "
+            "NaN; barrier-only set). Supply a cited eps_r before running "
+            "a self-consistent Poisson solve."
+        )
+    z = np.asarray(z, dtype=float)
+    vh = np.zeros_like(z)
+    density = np.zeros_like(z)
+    residual = np.inf
+    for it in range(1, max_iter + 1):
+        energies, envelopes = solve_subbands(p, z, potential=vh,
+                                             n_states=n_states)
+        masses = _inplane_masses(p, z, vh, energies, n_states)
+        occ = _fill_subbands(energies, masses, ps)
+        new_density = np.zeros_like(z)
+        for i in range(n_states):
+            prob = (np.abs(envelopes[i]) ** 2).sum(axis=0)
+            new_density += occ[i] * prob
+        density = (1 - mixing) * density + mixing * new_density
+        new_vh = hole_potential(z, density, ps, p.eps_r)
+        residual = float(np.max(np.abs(new_vh - vh)))
+        vh = (1 - mixing) * vh + mixing * new_vh
+        if residual < tol:
+            break
+    # final consistent (unmixed) state at the converged potential
+    energies, envelopes = solve_subbands(p, z, potential=vh, n_states=n_states)
+    masses = _inplane_masses(p, z, vh, energies, n_states)
+    occ = _fill_subbands(energies, masses, ps)
+    density = np.zeros_like(z)
+    for i in range(n_states):
+        density += occ[i] * (np.abs(envelopes[i]) ** 2).sum(axis=0)
+    return SelfConsistentResult(z=z, potential=vh, energies=energies,
+                                envelopes=envelopes, density=density,
+                                occupations=occ, masses=masses,
+                                iterations=it, residual=residual)

kpenvelope-0.2.1/src/kpenvelope/solver.py

@@ -0,0 +1,28 @@
+"""Eigen-solution of the assembled envelope Hamiltonian."""
+from __future__ import annotations
+
+import numpy as np
+
+from .hamiltonian import assemble_hamiltonian
+
+
+def solve_subbands(p, z, kx=0.0, ky=0.0, potential=None, n_states=8):
+    """Solve for the top valence states (the ones holes occupy).
+
+    Returns (energies, envelopes):
+      energies : (n_states,) eV, sorted descending (highest first).
+      envelopes : (n_states, 6, N) complex envelope functions, normalized
+          such that sum_m integral |F_m|^2 dz = 1.
+    """
+    z = np.asarray(z, dtype=float)
+    H = assemble_hamiltonian(p, z, kx, ky, potential)
+    vals, vecs = np.linalg.eigh(H)
+    order = np.argsort(vals)[::-1][:n_states]
+    dz = z[1] - z[0]
+    energies = vals[order]
+    envelopes = np.empty((len(order), 6, z.size), dtype=complex)
+    for j, o in enumerate(order):
+        v = vecs[:, o].reshape(z.size, 6).T  # (6, N)
+        norm = np.sqrt((np.abs(v) ** 2).sum() * dz)
+        envelopes[j] = v / norm
+    return energies, envelopes

kpenvelope-0.2.1/src/kpenvelope.egg-info/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: kpenvelope
+Version: 0.2.1
+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"
+Dynamic: license-file
+
+# 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.
+
+## Status
+
+v0.2.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)
+
+Not yet implemented, stated plainly because they matter physically:
+
+- **finite barriers.** Hard walls one grid spacing outside the grid ends.
+  A hard wall forces the envelope to vanish at the interface and pushes
+  the gas outward, which shifts subband energies and masses; a finite AlN
+  barrier treated as position-dependent material parameters is the v0.3
+  gate before research-grade use.
+- strain terms, full k-grid (non-parabolic) filling, spin splitting
+  analysis, transport lifetimes.
+
+## 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 -e .
+```
+
+```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. Together with the hard-wall boundary this is why the same
+warning stands: do not use these numbers in publications before the
+finite-barrier, dispersion-filled v0.3.
+
+## 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 finite-barrier physics that this
+package does not yet have.
+
+## License
+
+Apache-2.0

kpenvelope-0.2.1/src/kpenvelope.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/kpenvelope/__init__.py
+src/kpenvelope/hamiltonian.py
+src/kpenvelope/params.py
+src/kpenvelope/poisson.py
+src/kpenvelope/selfconsistent.py
+src/kpenvelope/solver.py
+src/kpenvelope.egg-info/PKG-INFO
+src/kpenvelope.egg-info/SOURCES.txt
+src/kpenvelope.egg-info/dependency_links.txt
+src/kpenvelope.egg-info/requires.txt
+src/kpenvelope.egg-info/top_level.txt
+tests/test_cited_params.py
+tests/test_kpenvelope.py

kpenvelope-0.2.1/src/kpenvelope.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kpenvelope-0.2.1/src/kpenvelope.egg-info/requires.txt

@@ -0,0 +1,4 @@
+numpy>=1.22
+
+[test]
+pytest

kpenvelope-0.2.1/src/kpenvelope.egg-info/top_level.txt

@@ -0,0 +1 @@
+kpenvelope

kpenvelope-0.2.1/tests/test_cited_params.py

@@ -0,0 +1,119 @@
+"""Tests of the cited GaN and AlN parameter sets.
+
+The closed-form anchors come from the quasi-cubic limits of the six-band
+Hamiltonian and are quoted in the Supplemental Material (Sec. S9) of
+Mahim, Mohsin and Rahman, "Origin of the conflicting hole masses in the
+GaN/AlN two-dimensional hole gas" (under review):
+
+  * zone-center splittings 5.20 and 21.80 meV for the GaN set
+    (closed form: E1 = d1+d2 against the eigenvalues of [[d1-d2, sqrt2 d3],
+    [sqrt2 d3, 0]]), against accepted experimental values near 5-6 and
+    22 meV;
+  * asymptotic in-plane masses m0/|A2+A4-A5| = 1.89 m0 and
+    m0/|A2+A4+A5| = 0.18 m0.
+
+If a transcription error ever enters the parameter tables, these tests
+fail against the closed forms.
+"""
+import math
+
+import numpy as np
+import pytest
+
+from kpenvelope import (HBAR2_OVER_2M0, aln_rinke2008, gan_rinke2008,
+                        solve_self_consistent)
+from kpenvelope.hamiltonian import bulk_blocks
+
+
+def _trapz(y, x):
+    """Trapezoidal integral on a uniform grid (works on NumPy 1 and 2)."""
+    dz = x[1] - x[0]
+    return dz * (y.sum() - 0.5 * (y[0] + y[-1]))
+
+
+def test_gan_values_locked():
+    p = gan_rinke2008()
+    assert (p.A1, p.A2, p.A3) == (-5.947, -0.528, 5.414)
+    assert (p.A4, p.A5, p.A6) == (-2.512, -2.510, -3.202)
+    assert p.delta1 == 0.010
+    assert p.delta2 == p.delta3 == pytest.approx(0.017 / 3.0)
+    assert p.eps_r == 10.4
+    assert "Rinke" in p.reference and "Barker" in p.reference
+
+
+def test_aln_values_locked():
+    p = aln_rinke2008()
+    assert (p.A1, p.A2, p.A3) == (-3.991, -0.311, 3.671)
+    assert (p.A4, p.A5, p.A6) == (-1.147, -1.329, -1.952)
+    assert p.delta1 == -0.295
+    assert p.delta2 == p.delta3 == pytest.approx(0.022 / 3.0)
+    assert math.isnan(p.eps_r)
+    assert "Rinke" in p.reference and "Carvalho" in p.reference
+
+
+def test_gan_zone_center_splittings():
+    p = gan_rinke2008()
+    H0, _, _ = bulk_blocks(p, 0.0, 0.0)
+    e = np.sort(np.linalg.eigvalsh(H0))[::-1]
+    # Kramers degeneracy at k = 0
+    assert e[0] == pytest.approx(e[1], abs=1e-12)
+    assert e[2] == pytest.approx(e[3], abs=1e-12)
+    # closed-form quasi-cubic eigenvalues
+    d1, d2, d3 = p.delta1, p.delta2, p.delta3
+    top = d1 + d2
+    g = d1 - d2
+    pair_hi = 0.5 * (g + math.sqrt(g * g + 8 * d3 * d3))
+    pair_lo = 0.5 * (g - math.sqrt(g * g + 8 * d3 * d3))
+    assert e[0] == pytest.approx(top, abs=1e-12)
+    assert e[2] == pytest.approx(pair_hi, abs=1e-12)
+    assert e[4] == pytest.approx(pair_lo, abs=1e-12)
+    # the published values (Supplemental Material, Sec. S9)
+    assert (e[0] - e[2]) * 1e3 == pytest.approx(5.20, abs=0.01)
+    assert (e[0] - e[4]) * 1e3 == pytest.approx(21.80, abs=0.01)
+
+
+def test_gan_asymptotic_inplane_masses():
+    p = gan_rinke2008()
+    c = HBAR2_OVER_2M0
+    k1, k2 = 4.0, 4.4
+    E1 = np.sort(np.linalg.eigvalsh(bulk_blocks(p, k1, 0.0)[0]))[::-1]
+    E2 = np.sort(np.linalg.eigvalsh(bulk_blocks(p, k2, 0.0)[0]))[::-1]
+    slope_top = (E1[0] - E2[0]) / (c * (k2 ** 2 - k1 ** 2))
+    slope_bot = (E1[5] - E2[5]) / (c * (k2 ** 2 - k1 ** 2))
+    # heavy branch -> m0/|A2+A4-A5| = 1.89 m0 (slope 0.53); at these
+    # wavevectors the top sorted band interleaves with the A2-only band
+    # (slope 0.528), which lies within the tolerance
+    assert 1.0 / slope_top == pytest.approx(1.89, abs=0.03)
+    # light branch -> m0/|A2+A4+A5| = 0.18 m0
+    assert 1.0 / slope_bot == pytest.approx(0.180, abs=0.003)
+
+
+def test_aln_refuses_poisson_without_permittivity():
+    z = np.linspace(0.0, 4.0, 33)
+    with pytest.raises(ValueError, match="permittivity"):
+        solve_self_consistent(aln_rinke2008(), z, ps=0.1)
+
+
+def test_gan_self_consistent_hard_wall():
+    """Hard-wall self-consistent GaN gas at the measured sheet density.
+
+    Compared against the hard-wall row of Table S1 of the source paper
+    (centroid 0.568 nm, light-pair sheet density 0.46e13 cm^-2). The
+    tolerances are loose on purpose: kpenvelope fills subbands with
+    parabolic edge masses (a documented approximation), while the source
+    fills the computed non-parabolic dispersions.
+    """
+    p = gan_rinke2008()
+    z = np.linspace(0.0, 6.0, 97)
+    res = solve_self_consistent(p, z, ps=0.46, n_states=4, mixing=0.5,
+                                tol=2e-5)
+    # charge neutrality, exact by construction and preserved to the end
+    sheet = _trapz(res.density, z)
+    assert sheet == pytest.approx(0.46, rel=5e-3)
+    # the gas sits within a nanometer of the interface
+    centroid = _trapz(z * res.density, z) / sheet
+    assert 0.4 < centroid < 0.8
+    # two heavy branches dominate; the light branch is a minority
+    occ = np.sort(res.occupations)[::-1]
+    assert occ[0] + occ[1] > 3.0 * occ[2]
+    assert res.residual < 2e-5

kpenvelope-0.2.1/tests/test_kpenvelope.py

@@ -0,0 +1,60 @@
+import numpy as np
+
+from kpenvelope import (assemble_hamiltonian, demo_single_band,
+                        solve_subbands, solve_self_consistent,
+                        HBAR2_OVER_2M0)
+from kpenvelope.poisson import hole_potential, E2_OVER_EPS0
+
+
+def test_hamiltonian_is_hermitian():
+    p = demo_single_band()
+    # switch on every coupling to test the discretization, not the demo
+    p.A3, p.A4, p.A5, p.A6 = 0.5, -0.3, 0.4, 0.7
+    p.delta1, p.delta2, p.delta3 = 0.02, 0.005, 0.005
+    z = np.linspace(0.0, 5.0, 40)
+    H = assemble_hamiltonian(p, z, kx=0.3, ky=0.2)
+    assert np.allclose(H, H.conj().T)
+
+
+def test_square_well_matches_analytic():
+    # decoupled bands: E_n = A * (hbar^2/2m0) * (n pi / L)^2, A < 0 so the
+    # HIGHEST states are n = 1, 2, ... from the top.
+    A = -2.0
+    L = 8.0
+    p = demo_single_band(A)
+    z = np.linspace(0.0, L, 400)
+    energies, _ = solve_subbands(p, z, n_states=12)
+    # the discrete Dirichlet walls sit one grid spacing outside the
+    # endpoints, so the effective well width is L + 2 dz
+    dz = z[1] - z[0]
+    Leff = L + 2 * dz
+    analytic = [A * HBAR2_OVER_2M0 * (n * np.pi / Leff) ** 2 for n in (1, 2)]
+    # each level is 6-fold degenerate in the decoupled limit
+    np.testing.assert_allclose(energies[:6], analytic[0], rtol=1e-4)
+    np.testing.assert_allclose(energies[6:12], analytic[1], rtol=1e-4)
+
+
+def test_poisson_uniform_slab():
+    # uniform density filling 0..L exactly cancels ps: field decreases
+    # linearly to zero, potential is parabolic with V'(0) set by ps
+    L, ps, eps_r = 4.0, 0.1, 10.0
+    z = np.linspace(0.0, L, 2001)
+    density = np.full_like(z, ps / L)
+    vh = hole_potential(z, density, ps, eps_r)
+    slope0 = (vh[1] - vh[0]) / (z[1] - z[0])
+    assert np.isclose(slope0, E2_OVER_EPS0 / eps_r * ps, rtol=1e-3)
+    # analytic: V(L) = (e^2 ps L / (2 eps)) for the uniform slab
+    assert np.isclose(vh[-1], E2_OVER_EPS0 / eps_r * ps * L / 2.0, rtol=1e-3)
+
+
+def test_self_consistent_converges_and_is_neutral():
+    p = demo_single_band()
+    z = np.linspace(0.0, 6.0, 120)
+    ps = 0.046  # nm^-2, i.e. 4.6e12 cm^-2
+    res = solve_self_consistent(p, z, ps, n_states=4, tol=1e-5)
+    assert res.residual < 1e-5
+    dz = z[1] - z[0]
+    assert np.isclose(res.density.sum() * dz, ps, rtol=1e-6)
+    # the gas must be held toward the interface, not centered in the well
+    centroid = (res.z * res.density).sum() / res.density.sum()
+    assert centroid < 0.5 * z[-1]