FLOOXS » TclLib » Device

Device — TclLib Procs

235 documented proc(s) in TclLib/Device/.

2Bound · 2BoundSide · 2Defect · 311Eqn · ::AlGaN::PolarizationCharge · ::Elastic::bond_transform · ::Elastic::miller_rotation · ::Elastic::parse_miller_digits · ::Hamiltonians::Barrier · ::Hamiltonians::Expr::is_num · ::Hamiltonians::Expr::lit · ::Hamiltonians::Expr::neg · ::Hamiltonians::Expr::scale · ::Hamiltonians::Form::schema · ::Hamiltonians::Pull::__AnisoCore · ::Hamiltonians::Pull::__Congruence · ::Hamiltonians::Pull::__ConsumesStrain · ::Hamiltonians::Pull::__CrystalStrainExpr · ::Hamiltonians::Pull::__dget · ::Hamiltonians::Pull::__HNames · ::Hamiltonians::Pull::__IsoCore · ::Hamiltonians::Pull::__MatAdd · ::Hamiltonians::Pull::__RotVec · ::Hamiltonians::Pull::__ShearComp · ::Hamiltonians::Pull::__StressPresent · ::Hamiltonians::Pull::__Validate · ::Hamiltonians::Pull::__ValleyFrame · ::Hamiltonians::Pull::__WarpDminv · ::Hamiltonians::Pull::__XKPCore · ::Hamiltonians::Pull::dispatch · ::Matrix::invNxN · ::Matrix::multAx · ::Matrix::multNxN · ::Matrix::transpose · ::QBulk::__view · ::QBulk::ComplianceMatrix · ::QBulk::Get · ::QBulk::SiGeValleyOffsets · ::Strain::Generic::CrystalStrain · ::Strain::Generic::GammaValleyShifts · ::Strain::Generic::LValleyShifts · ::Strain::Generic::ValleyShift · ::Strain::Generic::XValleyShifts · __CompareBands · __DirectStatistics · __DOS1D · __DOS2D · __EllipsoidalDimMap · __EllipsoidalMassTensor · __GeCrystalStrain · __IndirectStatistics · __interpolate_linear_vec · __KdepBuildSubbandPsi2 · __KdepEffectiveMass · __KdepExtractBandList · __mult_sweep · __RotateTensor · __RotateTensorDiag · __SiCrystalStrain · __SiliconCompliance · __Stats1D · __Stats2D · __ValleyMatInQReg · _tb_ensure_field · _tb_erfinv · _tb_find_anions · _tb_find_cations · _tb_get_lattice_constant · _tb_hopping · _tb_onsite · _tb_parse_material · AddSolution · assert_close · BandGap · BandGapGamma · BandGapL · BandGapX · BandOverlapLoop · BuildGAAMesh · BuildGAAMeshHalf · BuildInterfaceCharges · BulkGeStrainShiftsGamma · BulkGeStrainShiftsL · BulkGeStrainShiftsX · BulkSiStrainShifts · ClusterEqn · ComputeDispersionDOS · ComputeDOSFields · ComputeModes · ComputeXPointDispersion · CplxMult · Cubic::CubicSpline · Cubic::SolveTridiag · d-d · DeclareSiGeMoleFrac · DefectBound · DefectBoundSide · DefectBulk · DeltaBandProcs · DeltaDescriptorsFromQReg · DGEquation · DirectTunnelEnergy · dopant_has · dopant_has2 · DopantBulk · DopantConstant · DopantDefectPair · DopantDefectReact · DopantFermi · DopantPair · DopantReact · EllipsoidalMassTensor · EqnsVerySimple · GetdU · GetMobilityTensor · GetPCosDir · Hamiltonians::BuildGeDeltaHams · Hamiltonians::BuildGeGammaHam · Hamiltonians::BuildGeXPointHams · Hamiltonians::BuildLPointHams · Hamiltonians::BuildXPointHams · Hamiltonians::DescriptorRitzRQIBandsProc · Hamiltonians::Generic::__BuildLKMatrix · Hamiltonians::Generic::__DiscretizeLinear · Hamiltonians::Generic::__LKPeqn · Hamiltonians::Generic::__LKQeqn · Hamiltonians::Generic::__LKReqn · Hamiltonians::Generic::__LKSeqn · Hamiltonians::Generic::__SplitTopPlus · Hamiltonians::Generic::AssignBandClasses · Hamiltonians::Generic::ComputeMdosFromMinv · Hamiltonians::Generic::CopyFFAcrossTRPairs · Hamiltonians::Generic::DeltaValley · Hamiltonians::Generic::DiscretizeTerm · Hamiltonians::Generic::Isotropic · Hamiltonians::Generic::KDiscretize · Hamiltonians::Generic::KKDiscretize · Hamiltonians::Generic::LK · Hamiltonians::Generic::LKFromMaterial · Hamiltonians::Generic::LValley · Hamiltonians::Generic::MapTerm · Hamiltonians::Generic::SolveDeltaDescriptors · Hamiltonians::Generic::XValley · Hamiltonians::RitzRQIBandsProc · Hamiltonians::Valley::__SigFmt · Hamiltonians::Valley::ClearRegistry · Hamiltonians::Valley::Lookup · Hamiltonians::Valley::Make · Hamiltonians::Valley::ReduceEmpirical · Hamiltonians::Valley::ReduceStructural · Hamiltonians::Valley::Register · Hamiltonians::Valley::RegisterFromDescriptors · Hamiltonians::Valley::Relation · Hamiltonians::Valley::StructSig · Init · InitDopant · InterpBowing · InterpLinear · IntNumIntegral · JancuAlP · JancuSi · LK_KGrid · LKBandProcs · LKElectrostatics · logN · LoopBulkDall · LoopBulkNall · LoopEng · Ltun · Masetti · Nc · NcGamma · NcL · NcX · p-d · p-p · PoissonSchrodinger · PoissonSchrodingerKdep · PoissonSchrodingerKdepPC · QGrid · QSolve::__pick · QSolve::__tunnelDosScale · QSolve::__tunnelTdos · QSolve::BandEnergies · QSolve::ComputeOmegaMsq · QSolve::DirectTunnelCurrent · QSolve::DirectTunnelCurrentKP · QSolve::IndirectTunnelCurrent · QSolve::MatData · QSolve::NonParabolicityCorrection · QSolve::QuantumLocals · QSolve::Schrodinger100Solve · QSolve::Schrodinger100SolveKP · QSolve::SchrodingerSolveElec · quantum · RotMExpr · s-d · s-p · s-s · Schenk · SchrodingerDirectCurrent · SchrodingerDirectCurrentKPMeff · SchrodingerIndirectUnscaledTransmission · SchrodingerSolveEllipsoidal · SchrodingerSolveLVal · SchrodingerSolveXVal · Segregation · SetupGAAOxide · SG · SmicEqn · Solve · SolveEllipsoidalStrained · SolveIMinusA · SolveLPointValleys · SolveSiEllipsoidalStrained · SolveSiEllipsoidalValleyStrained · SolveXPointValleys · SoRBulk · SortLowHigh · sp3d5s* · SRH · StressDriftTest · TB_a0 · tb_random_alloy · tb_set_a · tb_slab · tb_strain_z · test_dd_symmetry · Transpose · Trapezoidal · VacNumIntegral · VoxelVolumeTest · XKPBandProcs · XptK · XptKK

Interface dispatcher for dimers.

Per-side interface equation for dimers (I2 / V2 at Oxide/Silicon).

Di-defect (I2 / V2) self-equation + cross-coupling into Base, RecombDefect,
BiMolecular partners.

311Eqn manages D311 AND C311 self equations, plus cross-coupling into Int
and I2.  Registered on C311 (per master Params/Silicon/C311); $Sol = C311.

Polarization sheet charge at a III-N heterointerface (e.g. AlGaN/GaN
2DEG).  Unchanged from the pre-port implementation — operates on the
named interface, not on AlGaN bulk state.

Build 6x6 Bond matrix from a 3x3 rotation matrix.
Converts first-order (vector) rotation to second-order (Voigt tensor) rotation.

Build a 3x3 rotation matrix from Miller indices.

Syntax:
  (hkl)<uvw>             — default: () → column 2 (z), <> → column 0 (x)
  (axis:hkl)<axis:uvw>   — explicit axis assignment

Examples:
  (001)<100>             — (001) surface, [100] channel. Normal→z, channel→x
  (x:001)<y:100>         — (001) surface normal along x, [100] along y
  (x:110)<z:1-10>        — (110) normal along x (1D quantum), [-110] along z

The third direction is always the cross product of the other two,
placed in whichever column remains.

The rotation matrix rows are crystal [100],[010],[001] directions.
The columns are device x,y,z directions.

Parse a signed Miller index string (e.g., "001", "-110", "1-10") into a list of 3 integers.

::Hamiltonians::Barrier <m> <carrier_slice> — barrier-material slice
mirroring every instance of a carrier slice as a decoupled IsoMeff on
the SAME sols/H names (oxide penetration: flooxs `solution add const`
is material-scoped, so the same name carries a per-region expression
and the deck flips only the Schrodinger mask).  This is the old
QuantumPackage pass-2, demoted to a data helper.

  m             — isotropic barrier mass in m₀ (SiO2 standard: 0.5)
  carrier_slice — the carrier material's slice (CommonParameters
                  ignored); each instance contributes one IsoMeff
                  instance named <iname>b with its sols/H/potential.

True if v is a strict Tcl number (so native `expr` arithmetic is safe).

Pass v through as an alagator-safe sub-expression.
  number → returned untouched (Tcl auto-stringifies on splice; matches
           the legacy `[expr {...}]` byte representation exactly so
           pure-Si/Ge expression strings stay bit-identical)
  string → wrapped in parens so precedence at the splice site is preserved

Negate v.  Numbers fold via `expr` (raw-double pass-through); strings
are wrapped.

c * v where c is a Tcl number and v is number-or-expression.
Constant-folds via native `expr` when v is numeric (preserves the
raw-double string repr legacy code emitted).  Splices into a
parenthesised string when v is an expression.

============================================================================
Form schema — ncomp is the required sols length ("any" = N decoupled
copies).  `known` lists the form's own keys; the engine-common instance
keys {model sols H potential mirror} are allowed on every form.
============================================================================

__AnisoCore — one ellipsoidal-valley descriptor.

spec keys:
  sol h Potential ml mt axis            required (axis: signed unit 3-vec)
  dE       diagonal shift: "" (none) | number | expression       ("")
  sh       legacy Bir-Pikus shear value, with `alpha`            (0.0)
  alpha    legacy Cartesian-axis warp coefficient                (0.0)
  dminv    3×3 crystal-frame Δ(1/m) additions (numbers/exprs)    (zeros)
  k0       scalar Bloch offset along axis, 1/cm; 0 = envelope    (0.0)
  complex  append the i*kz complex-storage dummy                 (0)
  mirror   TR metadata                                            (same)
  sig_k0   StructSig k0 slot value                               ($k0)

Expression-tolerant congruence transform: crystal tensor M → device
frame under rotation R, matching RotMExpr's convention
(device[a][b] = Σ_ij R[a][i]·R[b][j]·M[i][j], i.e. R·M·Rᵀ).
All-numeric input is delegated to RotMExpr so the numeric path stays
byte-identical to the legacy builders.

Does this instance build strain terms when stress fields are present?

Crystal-frame strain dict as EXPRESSIONS in the stress.* fields.

ε_cry_voigt = S · (α6 · σ_dev) where α6 is the device→crystal stress
rotation (same math CrystalStrain does numerically) — so each strain
component is a numeric-weighted linear combination of the stress.*
field symbols.  Missing component fields contribute zero.  Returns
{exx eyy ezz eyz exz exy}; a component with no surviving terms is "0".

dict-get-with-default

H names for an instance: explicit `H` list or the ${sol}H default.

__IsoCore — one isotropic-mass diagonal expression.
  dE "" (legacy Isotropic shape, byte-identical) | number | expression.

Sum a numeric 3×3 with a (possibly expression-valued) 3×3.

R · v for a 3-vector (numeric).

Engineering transverse-shear component ε_t1t2 in the valley frame of
`axis`:  2·(t1·ε_tensor·t2) = Σ_i 2·t1_i·t2_i·ε_ii
                             + Σ_{i<j} (t1_i·t2_j + t1_j·t2_i)·ε_ij_eng.
For Cartesian axes this reduces exactly to the legacy per-axis shear
pick (ε_yz / ε_xz / ε_xy).  Numbers fold; expressions splice.

Unified stress-field surface (device-frame Voigt order, the same set
`stress pull` stamps).  Returns 1 if ANY component field exists.

Strict-consumption validation of one instance against the form schema.

Deterministic valley frame {t1 t2} for a longitudinal axis n̂.
Cartesian axes (exactly one nonzero component) get the other two
Cartesian axes in index order — this reproduces the legacy Δ/X
transverse-pair convention ([100]→(y,z), [010]→(x,z), [001]→(x,y)).
General axes get a Gram-Schmidt pair seeded from the Cartesian axis
least aligned with n̂.

Declared warp rows → 3×3 Δ(1/m) matrix in the crystal frame.
Row vocabulary (v1): {t1t2 eps_t1t2 <coeff>} — Δ(1/m) gets
coeff·ε_t1t2 on the (t1,t2) off-diagonal pair of the valley frame,
mapped back to crystal axes via the frame outer product
t1⊗t2 + t2⊗t1.  Entries are numbers or expression strings.

__XKPCore — one X-point 2×2 pair (two descriptors).

spec keys:
  s1 s2 h1 h2 Potential ml mt Mxpt axis   required (axis: unit 3-vec)
  dE sh alpha dminv                       as __AnisoCore; dE is emitted
                                          UNCONDITIONALLY (legacy X shape:
                                          "...+0*XA1" at zero stress)
  k0       scalar Bloch offset (1/cm); 0 = envelope                (0.0)
  sig_k0   StructSig k0 slot (legacy wrappers pass k0_frac)        ($k0)
  mirror                                                            (new)

============================================================================
Dispatcher
============================================================================

Generic NxN inverse via Gauss-Jordan elimination with partial pivoting.

Matrix A times vector x multiplication
Returns a vector

multiplies two NxN matricies

Returns the transpose of matrix A

__view <mat> — the full bulk-shaped dict for a material, from QuantumKP.

::QBulk::ComplianceMatrix <mat> <x> — 6×6 crystal-frame compliance from the
QuantumKP CommonParameters {s11 s12 s44} (rules resolved against x).

::QBulk::Get <mat> <key> ?<key> ...? — dotted-path read into the bulk view.
Drop-in for the retired `::QBulk::Get <mat> <key>...`.

::QBulk::SiGeValleyOffsets <x> — Δ/L/Γ CB-min offsets (eV, ≥0) at composition
x, from the SiGe QuantumKP Bulk ValleyOffsets difference rules + min clamp.

Strain::Generic::CrystalStrain

  stress     — device-frame stress 6-vec {σxx σyy σzz σyz σxz σxy} in Pa
  miller     — Miller-orientation string ("(001)<100>" = no rotation)
  compliance — 6×6 compliance matrix in the standard crystal frame
               (Voigt notation, s44 along shear axes), as a list of
               six 6-element lists

Returns the crystal-frame strain dict
  {exx, eyy, ezz, eyz, exz, exy}
where the off-diagonal entries are 2·ε_ij (engineering strain),
matching the compliance-matrix convention used throughout flooxs.

Strain::Generic::GammaValleyShifts

  strain      — crystal-frame strain dict (output of CrystalStrain)
  gval_params — dict with key {ac_g} (absolute hydrostatic DP for Γ).

Γ-CB has no preferred axis (single isotropic valley at k=0), so only
a hydrostatic shift applies:  ΔE_Γ = ac_g · Tr(ε).  Returns {E0s
shear_list} with length-1 lists, mirroring the X/LValleyShifts return
shape for caller-side symmetry.

Strain::Generic::LValleyShifts

  strain      — crystal-frame strain dict (output of CrystalStrain;
                off-diagonals are engineering shear, ε_ij_eng = 2·ε_ij_tensor)
  lval_params — dict with keys {Xid Xiu}.  Xid is the hydrostatic
                deformation potential along L; Xiu is the uniaxial DP
                along the body-diagonal valley axis.

Returns {E0s shear_list}

  E0s        — {dE_1 dE_2 dE_3 dE_4} per-valley diagonal shifts (eV)
               ΔE_a = Ξ_d·Tr(ε) + Ξ_u·(n̂_a·ε·n̂_a)
               where n̂_a are the unit body-diagonals corresponding to
               the Generic::LValley descriptor enumeration:
                 a=1  (+1,+1,+1)/√3
                 a=2  (+1,+1,-1)/√3
                 a=3  (+1,-1,+1)/√3
                 a=4  (-1,+1,+1)/√3
               For an engineering-shear strain tensor (off-diagonals
               are 2·ε_ij_tensor):
                 n̂·ε·n̂ = Σ n_i² ε_ii + Σ_{i<j} n_i n_j ε_ij_eng
               Body-diagonal n̂·ε·n̂ = Tr(ε)/3 + (sign-pattern)·(εxy ± εyz ± εxz)/3.
  shear_list — {0 0 0 0} — L-valley has no Bir-Pikus inverse-mass
               warp in the literature reviewed (see docs/SiGe.md), so
               Generic::LValley does not consume shear.  Placeholder
               kept so the return shape matches XValleyShifts for
               caller-side symmetry.

Strain::Generic::ValleyShift

Generic per-valley deformation-potential shift for an ellipsoidal
valley along an ARBITRARY k-space axis (Δ, L, Λ, Σ — same formula):

  dE = Ξ_d·Tr(ε) + Ξ_u·(n̂·ε·n̂)

  axis   — signed unit 3-vector (k-space longitudinal direction).
           Normalized defensively.
  xid    — Ξ_d hydrostatic deformation potential (eV)
  xiu    — Ξ_u uniaxial deformation potential along axis (eV)
  strain — crystal-frame strain dict {exx eyy ezz eyz exz exy};
           off-diagonals in engineering convention (2·ε_tensor).
           Values may be NUMBERS (folded to a number) or alagator
           EXPRESSIONS (the `quantum pull` stress.* field path —
           result is an expression string with numeric weights).

n̂·ε·n̂ in engineering-shear components:
  Σ n_i² ε_ii + n_x·n_y·ε_xy + n_y·n_z·ε_yz + n_x·n_z·ε_xz

The per-component weight form (W_exx = Ξd + Ξu·n_x², W_exy = Ξu·n_x·n_y,
…) groups float operations differently than the legacy
XValleyShifts/LValleyShifts specializations below, so numeric results
can differ in the last ulp — those procs stay self-contained for the
byte-stable wrapper path; this proc is the engine's generic path.

Returns a number (all-numeric strain) or an expression string; 0 when
every weighted component vanishes.

Strain::Generic::XValleyShifts

  strain      — crystal-frame strain dict (output of CrystalStrain)
  xval_params — dict with keys {Xid Xiu}
                  Xid  hydrostatic deformation potential (eV)
                  Xiu  uniaxial deformation potential along valley axis (eV)

Returns {E0s shear_list}
  E0s        — {dE_100 dE_010 dE_001} per-valley diagonal shifts (eV)
               ΔE_α = Ξ_d·Tr(ε) + Ξ_u·ε_αα
  shear_list — {ε_yz ε_xz ε_xy} raw per-valley transverse shear
               (consumed by the Bir-Pikus inverse-mass-tensor rotation
               path inside Generic::{XValley,DeltaValley}, gated by
               params.alpha)

Valley-direction convention:
  [100] valley → transverse plane (y,z) → ε_yz
  [010] valley → transverse plane (x,z) → ε_xz
  [001] valley → transverse plane (x,y) → ε_xy

Deduplicate equivalent bands

Statistics used in direct band to band tunneling
quantum calculations
Takes an energy, quasi fermis, and temperature

Returns the 1D Density of states value for a given
temperature and effective mass

Returns the 2D Density of states value for a given
temperature and effective mass

__EllipsoidalDimMap — confinement-direction k-product discretizer for the
ellipsoidal effective-mass Hamiltonian, by string substitution on a built
expression (kx*kx*s -> VelX(GradX(s)), etc.).  Relocated verbatim from the
retired ::LK::DimMap (this is its only caller).

Legacy alias — older decks (and the auto-loaded tclIndex) reference the
underscored name.

Crystal-frame strain {exx eyy ezz eyz exz exy} list (engineering strain;
off-diagonals are 2·ε_ij to match the compliance-matrix convention).

Statistics used in indirect band to band tunneling
quantum calculations
Takes an energy, quasi fermis, temperature, and phonon energy

Vectorized linear interpolation for a sorted list of query points.
Single pass O(n+m) where n = len(x), m = len(xv).
Values outside the data range are clamped to the nearest endpoint.

Paint sqrt(Σ_s |ψ_s,b,k_min|²) onto ${ev_prefix}${g} for each global band.
Caller must have fs selected to Main.

Invert the parabolic Fermi-Dirac integral to find the per-subband effective
DOS mass m_eff (in units of m₀) that reproduces `occ` at (E0, Ef).
dim=2 → 1D unconfined direction (use __Stats1D: occ ∝ √m · fn12(arg/kT))
dim=1 → 2D unconfined plane    (use __Stats2D: occ ∝ m · log(1+exp(arg/kT)))
Caller must have fs selected to Main (we need a scratch field for the
alagator intrinsic evaluation).

Build the global sorted band_list across all valleys from the kaschro
E_b<j> kgrid fields.  Each entry is {E0 vidx j wbase v_class}.  Caller must
have fs selected to the kgrid with the __k_at_min delta-mask field present.

Multiplicative (geometric) sweep — same interface as __linear_sweep but
steps by multiplication instead of addition.  step is a factor (e.g. 1.2).

Takes a 3x3 Tensor list and crystal rotation vector
returns a rotated tensor

Same procedure but only outputs Diag

Crystal-frame strain {exx eyy ezz eyz exz exy} list (engineering strain;
off-diagonals are 2·ε_ij to match the compliance-matrix convention).

Resolve Silicon's elastic compliance triple {c11 c12 c44} from the
active device dict's BandStructure StrainParams slice — the dict-read
replacement for the old ::Silicon::c11/c12/c44 namespace vars.  Both
stress helpers below are Silicon-hardcoded global emitters, so they
read Silicon's slice directly from [::Defaults::device].

Returns the 1D Density of states with integral function for a given
temperature, effective mass and potential

Returns the 2D Density of states with integral function for a given
temperature, effective mass and potential

__ValleyMatInQReg — first material in $qreg carrying a valley instance of
the given model with a non-empty descriptors list.

Create a field initialized to zero if it doesn't exist yet

Approximate inverse error function (Winitzki 2008)

Find which anion elements are present (have a nonzero field)

Find which cation elements are present

Get lattice constant in cm from mesh extent along an axis

Helper: define hopping solutions for one anion-cation pair

Helper: define on-site solutions for one atom type

Parse material name into {anion cation}

to do pod we need a set of solutions
this procedure adds a solution as a function of bias

--- Test Helper ---

Effective (minimum) bandgap — for ni calculations
At x<~0.85 the X-valley is lowest; above that, L takes over.
We return a smooth minimum via Alagator ternary.

Gamma-valley (direct gap) — matters for optical transitions and direct tunneling

L-valley — dominant conduction band for Ge-rich alloys

X-valley (Delta minimum) — dominant conduction band for Si-rich alloys

Loop over energies from the bottom of the conduction band to the 
top of the valance band. Only produces values if the bands overlap
fxn is a function that is called at every point in the loop with that energy
dU is the energy step size
mat is the material used

Build a 2D gate-all-around nanowire cross-section mesh

Creates Gas/Oxide/Silicon regions with a single Gate contact
wrapping the entire oxide/gas interface.

Args:
  lnr    - nanowire width in nm
  tsi    - silicon thickness in nm
  tox    - oxide thickness (default 1 nm)
  tga    - gas region thickness (default 1 nm)
  div    - mesh divisions per dimension (default 25)
  donor  - donor concentration (default 1e13 cm^-3)
  accept - acceptor concentration (default 1e12 cm^-3)

Symmetry-cut GAA cross-section: halves the longer dimension.
lnr >= tsi (ribbon): cuts along y, right edge is symmetry plane
tsi > lnr  (fin):    cuts along x, bottom edge is symmetry plane

Build interface Coulomb charge sources for GAA nanowire

Enumerates Si/SiO2 interface nodes and returns a charges list suitable
for FixedChargeRateScr / the LBTE coulomb rate spec.

Two models:
  "delta"    — one charge source per interface node (incoherent scattering,
               rates from independent impurities add). Each delta weighted
               by sqrt(N_it * ds) so that charge^2 = N_it * ds gives the
               correct linear-in-N_it rate sum.
  "constant" — single combined charge source (coherent, potentials
               superpose). Each delta weighted by N_it * ds.

Args:
  W     - nanowire width (lnr) in nm
  H     - silicon thickness (tsi) in nm
  div   - mesh divisions (same as BuildGAAMesh)
  N_it  - interface trap density in cm^-2
  model - "delta" or "constant"
  tox   - oxide thickness, default 1 nm

Returns: Tcl list of charge expression strings

Γ-valley hydrostatic shift for Ge.  Returns {E0s shear_list} with
length-1 lists — Γ is a single isotropic CB minimum with only the
hydrostatic deformation potential entering.

Per-L-valley band-edge shifts for Ge.  Returns {E0s shear_list} — see
::Strain::Generic::LValleyShifts.  Length-4 lists (one per
〈111〉-equivalent body-diagonal) instead of length-3.

Per-X-valley band-edge shifts + transverse shear couplings for Ge Δ.
Returns {E0s shear_list} — see ::Strain::Generic::XValleyShifts.  The
Bir-Pikus shear parameter (alpha) rides in the XValley params dict and
is consumed by Generic::{XValley,DeltaValley} from there — no global.

Per-X-valley band-edge shifts + transverse shear strains.
Returns {E0s shear_list} — see ::Strain::Generic::XValleyShifts.  The
Bir-Pikus shear parameter (alpha) is carried in the XValley params dict
and consumed by Generic::{XValley,DeltaValley} from there — no global.

ClusterEqn manages Smic's bulk equation AND back-propagates to 6 partner
species (Int, I2, Vac, V2, D311, C311).  Pre-resolves DiffLimit via subst
(Alagator does not evaluate `[Tcl]` substitutions in eqn= values).

Populate velocity and DOS on the KSpace fieldspace from actual E(k) dispersion.
Unlike ComputeDOSFields (parabolic analytics), this uses GradX on the actual
dispersion for exact non-parabolic bands.

The dispersion E_j(k) must already be stored as ${EV}${j}Ek fields on the
KSpace fieldspace (populated by sweeping schro/aschro over k-points).

valleys: list of {EV N BandEdge E mdos} band tuples

Populate TransportK and DOS1D fields for each subband on the CURRENT fieldspace.
e_abs: field name or expression for ABSOLUTE energy in eV at each grid point.
On the Energy fieldspace, pass "(x*$kT+$FermiLevel)".
On the KSpace fieldspace, pass "EkField".
For parabolic bands, uses analytical k(E) and g(E).
For general dispersions, replace the body with GradX-based numerics.

only take a subset of modes with this proc for ramping purposes

============================================================
ComputeXPointDispersion: build E(k) / v(k) on KSpace from the 2x2 k.p
============================================================
Sweep the rotated 2x2 Hamiltonians at a sequence of k_model values
along the negative inside-BZ direction (one sweep covers both +X and
-X branches via mirror symmetry of the lower band). For each global
subband, spline-interpolate the resulting (kz_real, E) samples onto
the KSpace kz grid and compute v(k) = Grad(E) · q/(100·hbar) / kmax.

The 2x2 places X at k_model=0; the physical kz_real of each valley's
X projection is X_device_z = (alpha · dir)_z · 2π/a. Each sample at
kz_model produces TWO (kz_real, E) points by mirror:
  kz_real_pos = +X_device_z + kz_model   (inside-BZ from +X)
  kz_real_neg = -X_device_z - kz_model   (inside-BZ from -X)
For Delta-2 (X_device_z = 0) the two collapse to a symmetric pair
around kz_real = 0. For Delta-4 they tile the [-X, +X] window.

Returns the input xbands list augmented with a 6th tuple element
{0 0 X_device_z_cm} so downstream LBTE consumers see the same shape
they get from ComputeElecDispersion.

Multiply complex numbers that are stored as two separate values

#+##########################################################################

CubicSpline - returns the x,y coordinates of the cubic spline using
xy control points.
xy => {{x0 y0} {x1 y1} .... {xn yn}}

XY points MUST BE SORTED by increasing x

#+##########################################################################
SolveTriDiag -- solves the linear system for tridiagoal NxN matrix A
using Gaussian elimination (no pivoting). Since A is sparse, we pass
in three diagonals:
    sub(i)  => a(i,i-1)    diag(i) => a(i,i)    sup(i)  => a(i,i+1)

Result is returned in b[1:n]

o1, o2: d-orbital indices
0:xy, 1:yz, 2:zx, 3:x2-y2, 4:3z2-r2
dv: {l m n}

DeclareSiGeMoleFrac expr= "<alagator-expression>" — paint the SiGeMoleFrac
field the SiGe LK Hamiltonian expressions reference for spatial grading.

Interface bulk-side dispatcher.  Walks both sides and calls
DefectBoundSide for each side where DiffModel is "Numeric" (matched via
matparam_sub).  If the side has no DiffModel set, that side is skipped
(which is the typical case — only the bulk side with the diffusing
species gets a boundary condition).

Per-side interface equation.  Writes to the C++ EqnComplex via a separate
code path than the bulk Equation accumulator — uses the existing
`solution Mat /Other name=Sol side=Side value="…"` shape directly rather
than going through pde_*.

The trapping term that touches Vac's BULK equation does go through
pde_append, because that IS a cross-coupling into the bulk accumulator.

Build the bulk rate equation for $Sol (Int or Vac) in $Mat (Silicon):
  ddt(Sol) - D0 · grad(ScaleSol) + IVRecomb
plus the scratch terms EqSol, ScaleSol, IVRecomb, PressureSol used by it.

DeltaBandProcs $qreg ?-mat M? ?-nev N? ?-k_solver S? ?-mirror_kgrid 0|1?
               ?-interp_skip K? ?-ev_prefix P?

AnisoMeff (Δ / L) electron valleys.  Groups the flattened descriptors by
struct_sig (one kaschro per unique signature), folding ±k₀ TR partners into
degeneracy and labeling each group with a distinct class for f/g-type rate
filtering downstream.

DeltaDescriptorsFromQReg — flatten the AnisoMeff valley descriptors of one
material from a `quantum pull=` registration dict (used by DeltaBandProcs
and by the descriptor-ritz path in production decks).

# Full Density Gradient Correction:

Computes the direct tunneling energy using the effective mass approximation
Takes an conduction band sub band energy Eci
Conduction band effective mass
Takes an valance band sub band energy Evi
Valance band effective mass

Helper: check if a per-(Mat, Sol, Key) parameter is set (returns "" if not).

Same but for the nested Mat/Sol/Def/Key form.  Delegates to matparam_sub3
so the inherit chain is honored: a child material picks up its parent's
per-(dopant, defect) params without redeclaring them.

DopantBulk: top-level dispatcher.  Reads DiffModel / ActiveModel / Charge
switches and routes to the right sub-builder; finally folds the active
species into the global Charge term.

Simple constant-diffusivity model: ddt(Sol) - D * grad(SolActive).

Per-(dopant, defect) flux contribution for the Pair model.  Builds the
DiffDef diffusivity and the FluxSolDef term; subtracts the flux from
the dopant's residual, adds a dopant-defect binding term to the defect's
residual.

Per-(dopant, defect) reaction for the React model.

Fermi-level dependent diffusivity.  Reads D0, optional Dn/Dnn/Dp/Dpp
coefficients for the Fermi-expansion in Noni and Poni.  For charged
species the diffusivity gets a 1/(Poni) or 1/(Noni) factor and the grad
argument picks up a (Poni) or (Noni) factor — same shape as master.

Pair model — substitutional via 1/(1 + Σ Bind*Defect), then per-(Sol,Def)
flux contribution.

React model — substitutional is dopant total minus sum of (dopant, defect)
species; per-(Sol, Def) reactions wire flux + binding.

Build the 3x3 inverse mass tensor for an ellipsoidal valley
with longitudinal mass ml along direction {dx dy dz} and
transverse mass mt perpendicular.

Silicon::EqnsVerySimple — minimal single-band DD equation set
(Masetti-only mobility, no BGN, no DP-tensor, R=G=0).  Replaces
Silicon's multi-valley + Klaassen-Canali + BGN baseline emission
with a simpler form suitable for trap-only physics tests
(InterfaceTraps-Edge / -Mid).  Call AFTER `device pull T= Temp
feqf` to overwrite the dispatcher-emitted multi-valley equations.

Get dU from the number of integration points that you want

takes a mobility vector
returns a tensor 3x3 list

o is the p-orbital index
dv is the normalized cosine vector as a list

============================================================
Hamiltonians::BuildGeDeltaHams — Ge Δ-valley envelope-form.
============================================================
Single-band envelope-form Δ-valley Hamiltonians, registered as
Δ{1,2,3}{p,m}H solutions on Germanium.  Returns the descriptor list
directly (no legacy ham_info tuple — Δ-envelope is single-band, so
the natural consumer iterates descriptors and calls aschro per-valley).

The 6 ±k₀ Δ-valleys map to 3 unique struct_sig groups when no Bloch-
form coupling is enabled (k0_frac=0 default); each ±k₀ pair produces
byte-identical H expressions modulo sol-name and folds via TR
symmetry into the same envelope.

Args:
  miller       Miller-orientation string
  Stress_dev   device-frame stress (Pa, 6-vec)
  Econd        band-edge field name (default: Econd)

============================================================
Hamiltonians::BuildGeGammaHam — Ge Γ-valley isotropic CB.
============================================================
Single-valley isotropic effective-mass Hamiltonian centred at k=0,
with hydrostatic strain shift folded into the diagonal.  Sole Γ-CB
valley registered on Germanium under sol-name "GAMMA" / "GAMMAH".

Returns a 1-element descriptor list (mirrors the L/Δ shape so callers
can iterate uniformly).  k0_crystal = {0 0 0} marks Γ unambiguously.

In Ge this is the direct-gap minimum, ~0.14 eV above L at zero
strain.  Tensile [001] strain pushes Γ down faster than L (because
a_c^Γ is more negative), so the Γ-CB becomes the dominant minimum
under sufficient tensile strain — the standard Ge-on-Si direct-gap
laser story.

Args:
  miller       Miller-orientation string (currently unused — Γ is
               rotation-invariant, but accepted for caller-side
               symmetry with the X/Δ/L wrappers)
  Stress_dev   device-frame stress (Pa, 6-vec)
  Econd        band-edge field name (default: Econd)

============================================================
Hamiltonians::BuildGeXPointHams — Ge X-point 2×2 k.p (Bloch-form).
============================================================
Three rotated 2×2 X-point Hamiltonians, one per cubic axis.  Same
return-tuple shape as BuildXPointHams (Si): list of 5-tuples
{s1 s2 H1_name H2_name dir}, one per axis.

In Ge this is mainly an exploratory/strain probe: the X minima sit
above L by ~0.85 eV at zero strain (Ge X-point is at ~1.2 eV above
Γ-VB top vs L at 0.66 eV).  BuildGeLPointHams is the right entry
point for Ge CB transport at thermal equilibrium.

Args:
  mcl, mct     longitudinal / transverse Δ-valley masses (m₀ units)
  Mxpt         X-point off-diagonal coupling-mass parameter
  miller       Miller-orientation string for crystal→device rotation
  Stress_dev   device-frame stress (Pa, 6-vec); defaults to all zeros
  k0_frac      X-valley centre offset in 2π/a₀; 0 = envelope form,
               ≈0.15 = Bloch form at 0.85·X
  Econd        band-edge field name for the diagonal (default: Econd)

============================================================
Hamiltonians::BuildLPointHams — assemble four rotated single-band
H expressions for the four 〈111〉-equivalent L-valleys of Ge.
============================================================
Pure H-construction (no aschro solve).  Returns a `ham_info` list of
  {sol H dir}
tuples — one per body-diagonal axis (4 entries).  Single-band envelope
form: no s2/H2 slot (compare X-valley's 5-tuple).

Args:
  mcl, mct     longitudinal / transverse L-valley masses (m₀ units;
               e.g. 1.59 / 0.0815 from ::QBulk::Get Germanium LValley)
  miller       Miller-orientation string for crystal→device rotation
  Stress_dev   device-frame stress (Pa, 6-vec); defaults to all zeros
  k0_frac      L-valley centre offset in 2π/a₀; 0 = envelope form,
               >0 reserved for future Bloch-form expansion (not
               exercised by Generic::LValley today)
  Econd        band-edge field name for the diagonal (default: Econd)

============================================================
Hamiltonians::BuildXPointHams — assemble three rotated 2x2 H expressions
============================================================
Pure H-construction (no aschro solve).  Returns a `ham_info` list of
  {s1 s2 H1 H2 dir}
tuples — one per cubic X-axis ({100}, {010}, {001}).  This is the same
format SolveXPointValleys's `ham_info` return slot has, so it drops in
anywhere a deck previously rolled its own inline H-build (bulk decks
that skip the k=0 solve, kaschro-only flows, etc.).

Args:
  mcl, mct     longitudinal / transverse Δ-valley masses (m₀ units)
  Mxpt         X-point off-diagonal coupling-mass parameter
  miller       Miller-orientation string for crystal→device rotation
  Stress_dev   device-frame stress (Pa, 6-vec); defaults to all zeros
  k0_frac      X-valley centre offset in 2π/a₀; 0 = envelope form,
               0.15 (≈ 0.85·X) = Bloch form
  Econd        band-edge field name for the diagonal (default: Econd)

Descriptor-aware ritz+RQI bands_proc for the 6-Δ-valley pipeline.
Counterpart to Hamiltonians::RitzRQIBandsProc but driven by per-valley
descriptors instead of the 3-tuple ritz_basis convention.

Eigenvector basis fields B_${rep_sol}${j} must already exist on the
fine mesh for each unique-struct_sig rep (saved by the deck's coarse
+ refine + RQI bootstrap).

Per PS iteration:
  1. Group descriptors by struct_sig — one ritz+RQI per group.
  2. ritz sol= ${rep_sol}R basis= B_${rep_sol} V= Econd  (project
     saved basis onto current potential)
  3. aschro Hr= rep_expr update  (1-step RQI fix)
  4. Copy fields from rep to TR-partner sol-names so all 6
     descriptors have populated eigenvectors.
  5. Build 6 N=1 band tuples with descriptor sol-names.

Build the symbolic 6×6 LK Hamiltonian matrix in the angular-momentum
basis |3/2,3/2>, |3/2,1/2>, |3/2,-1/2>, |3/2,-3/2>, |1/2,1/2>, |1/2,-1/2>.
Returns a list-of-lists; element [i][j] is the symbolic expression for
H_ij multiplied through by sol_names[j], or "0" for structural zeros.

Helper: discretize a single linear-in-k term coeff*[i*]ka*s with
rotation R applied to ka.  Lifts each rotated component through
KDiscretize.

P-block: kinetic γ1 term + hydrostatic deformation potential a.
  $s — sol name multiplied through every term
  $P — eV·m², equals -C1 * g1   (number or alagator expression)
  $a — eV, hydrostatic deformation potential   (number or expression)

Q-block: γ2 anisotropy + biaxial deformation potential b.
  $Q — eV·m², equals -C1 * g2   (number or expression)
  $b — eV, biaxial deformation potential   (number or expression)

R-block: γ2/γ3 mixing + b/d shear deformation potentials.
  $R  — eV·m², equals C2 * g2   (number or expression)
  $Sv — eV·m², equals -2 * C2 * g3 (passed as $Sv to avoid Tcl 'S' reuse)
  $b  — eV, biaxial deformation potential
  $d  — eV, shear deformation potential

S-block: γ3 mixing + d shear deformation potential.
  $Sv — eV·m², equals -2 * C2 * g3   (number or expression)
  $d  — eV, shear deformation potential   (number or expression)

Paren-aware split on top-level '+' characters.  Mirrors `split $expr +`
for coefficient strings that contain no parentheses (the legacy numeric
Si/Ge code path), but preserves '+' nested inside parentheses — needed
when Expr-wrapped coefficients contain alagator subexpressions like
"(4.22 + 9.13*SiGeMoleFrac)" that must not be split mid-coefficient.

Hamiltonians::Generic::AssignBandClasses bands

Return a `band_classes` list the C++ lbte walker uses to evaluate the
f / g `same_class`-vs-`cross_class` final-state filter against the
descriptor-aware band ordering.

Class assignment: descriptors with matching `struct_sig` share a
class; everything else gets a fresh class.  For Si Δ-valleys with no
strain, this yields 3 classes (Δ1±, Δ2±, Δ3±) — same as the legacy
v_class assignment in PoissonSchrodingerKdep, just driven by the
descriptor structural signature instead of a deck-supplied integer.

`bands` is the flat (valley, subband) list returned by
SolveDeltaDescriptors.  The returned list is built in the same flat
order (valley 0 subbands first, then valley 1, …) — must match
whatever rate-tuple order the caller hands to LBTEMobility via
`dispersion= [dict create band_classes <list> ...]`.

Sol-names not in the registry get class 0; this lets a deck mix
legacy-EV-named tuples and descriptor-aware tuples in the same
LBTE solve without crashing the band.classes lookup.

Hamiltonians::Generic::ComputeMdosFromMinv minv_r dim

Compute the density-of-states mass for the UNCONFINED direction(s)
from a rotated inverse-mass tensor.  This is the mass that
__Stats1D / __Stats2D / KuboGreenwood's parabolic-band paths consume
for carrier-density and DOS integrals.

  dim=2 (2D confined, 1D transport along device-z):
      mdos_1D = m_zz = 1/minv_r[2][2]
  dim=1 (1D confined, 2D transport in device-y/z plane):
      mdos_2D = sqrt(m_yy · m_zz) = sqrt((1/minv_r[1][1])·(1/minv_r[2][2]))
  dim=0 (3D bulk):
      mdos_3D = (m_xx · m_yy · m_zz)^(1/3)

Returns 1.0 as a fallback if the tensor is degenerate.

Hamiltonians::Generic::CopyFFAcrossTRPairs bands prefix nsub_per

After ComputeFormFactorsTable paints the per-valley intra-block
form factors (cross-valley = 0 as block-diagonal), copy those
blocks across TR-partner pairs.  Needed for g-process scattering:
Δ1p ↔ Δ1m has F-factor identical to Δ1p ↔ Δ1p because the envelope
wavefunctions are TR copies (SolveDeltaDescriptors literally
field-copied from rep to partner).

  bands       — list of band tuples in same order as the
                ComputeFormFactorsTable call (slot 0 = descriptor
                sol-name); registry must have those sol-names.
  prefix      — FF field prefix on QGrid (e.g. "PhononFF").
  nsub_per    — subband count per valley (uniform, mirrors the
                ComputeFormFactorsTable offset arithmetic).

After this proc, PhononFF_${gb}_${gbp} for (gb, gbp) belonging to
TR-paired valleys carries the same value as the rep's diagonal
PhononFF_${gb_rep}_${gbp_rep}.  Cross-valley between unrelated
valleys (different struct_sig) stays zero.

Hamiltonians::Generic::DeltaValley

Pure envelope-form (single-band-per-valley) Δ-valley conduction-band
Hamiltonian builder.  Strain code is identical to Generic::XValley —
same per-valley diagonal shift Ξ_d·Tr(ε) + Ξ_u·ε_αα and same Bir-Pikus
inverse-mass tensor warp Ξ_u'·ε_⊥ (driven by params.alpha).  The only
differences from Generic::XValley:
  • no XA/XB 2x2 coupling — Δ-valley is single-band envelope form
  • no Bloch-form k₀ expansion (envelope form absorbs k₀ into the
    basis, leaving k = δk only)

Enumerates all 6 ±k₀ Δ-valleys with sol-names D{x,y,z}{p,m}
('x'/'y'/'z' = crystal axis, 'p' = +k₀, 'm' = -k₀).  Identifier
constraints: alagator's PDE-equation parser rejects UTF-8 Δ in
identifier-position; it also misparses `D1p0` as scientific
notation (`1p0` looks like a number with exponent).  Three letters
before any digit suffix dodges both.  H expressions for D${a}p and
D${a}m on the same crystal axis are byte-identical (envelope form,
mass tensor invariant under TR k → -k); the sign distinction lives
in the descriptor's k0_crystal / k0_dev metadata for downstream
scattering consumers that care about lab-frame momentum.

Same params/strain dict shape as Generic::XValley; Mxpt and k0_frac
entries are tolerated but unused.

Returns: list of 6 valley descriptor dicts (Hamiltonians::Valley::Make).

Hamiltonians::Generic::DiscretizeTerm

Single-pipeline equivalent of MapTerm + valley-center k0 shift.
Expands the crystal-frame k-product around k0_cry (substituting
k_i = k0_i + δk_i), discretizes each resulting δk-piece via KDiscretize
/ KKDiscretize after the Miller rotation R, and returns the list of
expression strings that together give the original term in envelope
form.  k0_cry = {0 0 0} (Γ-valley) reduces to MapTerm.

Signature:
  DiscretizeTerm term s dim R k0_cry k_units

`term` shape mirrors MapTerm: "coeff*[i*]ki*kj*s" or "coeff*s" (constant
/ strain).  Higher-than-quadratic k powers aren't supported (not used
by k.p Hamiltonians beyond Luttinger-Kohn).

Hamiltonians::Generic::Isotropic

  dim       — confined-spatial dimensions (0..3)
  params    — dict with key {miso}.  miso is the isotropic effective
              mass in m₀.
  sol_names — list of N spinor / band field names.  Each gets its
              own decoupled diagonal expression.
  Potential — band-edge field added to the diagonal (default Econd).
  k_units   — m | cm.  cm is the flooqs KGrid convention.

Returns N expression strings, one per sol_name.  Each is:
  H_i = $s_i*$Potential + (C/miso)·(kx²+ky²+kz²)·$s_i

Discretize a single linear-in-k term (ki*s) by index a ∈ {0,1,2}.
Used by DiscretizeTerm when expanding around non-zero k0.
  hasI    — 1 if the original term had an i* prefix (i*ki*s)
  k_units — "m" or "cm" (free-k lift identical to KKDiscretize)

Discretize ka*kb*s by index pair (a,b ∈ {0,1,2} = {x,y,z}).
  dim     — number of confined spatial dimensions; first `dim` axes are
            confined (mapped to GradX/Vel), the rest stay as broadcast
            k-parameters
  hasI    — 1 if the original term had an i* prefix (i*ki*kj*s)
  k_units — "m" (broadcast k in 1/m) or "cm" (broadcast k in 1/cm; each
            free k contributes ×1e2 to lift back to 1/m for the eV·m²
            coefficients)

Hamiltonians::Generic::LK

Pure 6-band Luttinger-Kohn k.p Hamiltonian builder.  No state.  All
material-specific quantities arrive as args.

  dim       — number of confined spatial dimensions (0..3)
  miller    — Miller-orientation string for the crystal→device rotation
  params    — dict with keys: g1 g2 g3 delta a b d
                g1, g2, g3 — Luttinger γs (dimensionless)
                delta      — split-off energy (eV; sign forced negative)
                a, b, d    — Bir-Pikus deformation potentials (eV)
              (a0 is not used here; the caller can carry it elsewhere.)
  strain    — dict with keys: exx eyy ezz exy exz eyz
                Each value is substituted directly into the expression
                string — pass numbers (inlined constants) or alagator
                expressions (e.g. "Material(Silicon)*0.001") for region-
                masked strain.  Pass zeros for unstrained.
  sol_names — list of 6 spinor field names in basis order
                |3/2,3/2>, |3/2,1/2>, |3/2,-1/2>, |3/2,-3/2>, |1/2,1/2>,
                |1/2,-1/2>.  These names are referenced in the returned
                expressions; aschro uses them as the eigenvector basis.
  Potential — band-edge field name added to the diagonal (default: Eval).
  k_units   — "m" or "cm".  "cm" matches flooqs's KGrid (1/cm) convention
              and lifts free-k factors by ×10² per free k inside MapTerm.

Returns the 6-element list of LK Hamiltonian expression strings ready
for aschro / kaschro.

Hamiltonians::Generic::LKFromMaterial

Convenience: read a material's QuantumKP LK slice (the canonical k.p
parameters in the ::Defaults Quantum domain) and build the 6-band LK
Hamiltonian for it.  Returns {H sols a0} — the equation list, the spinor
solution names, and the lattice constant (m) the caller needs for k-grids.
Replaces the legacy `LK::SetParamsFor $mat; LK::BuildH $dim` idiom.

  mat       — material name (Silicon, Germanium, ...)
  dim       — confined spatial dimensions (0..3)
  Potential — band-edge field on the diagonal (default Eval)
  miller    — crystal→device orientation (default unrotated (001)<100>)
  k_units   — "m" (matches the legacy LK::BuildH default) or "cm"

Hamiltonians::Generic::LValley

  dim       — confined-spatial dimensions (0..3)
  miller    — Miller-orientation string for crystal→device rotation
  params    — dict with keys {mcl mct k0_frac}; Mlpt is accepted but
              unused (envelope form only — no Bloch-form 2×2 expansion).
  strain    — dict with keys {dE_list shear_list} (output of
              Strain::Generic::LValleyShifts).  Length-4 lists.
              shear_list is accepted but unused today (no inverse-mass
              tensor warp for L; see file header).
  Potential — band-edge field added to the diagonal (default Econd)
  k_units   — m | cm.  Only "cm" is supported (flooqs KGrid convention).

Returns a list of 4 valley descriptor dicts (Hamiltonians::Valley::Make).

Discretize a single Hamiltonian term, optionally applying rotation R.
Parses coeff*[i*]ki*kj*s patterns; strain/constant terms pass through.
Returns a list of discretized terms (one for unrotated, up to 9 for rotated).

Hamiltonians::Generic::SolveDeltaDescriptors

Solve a list of Δ-valley descriptors at k=0, exploiting structural
signature sharing between TR partners (the +k₀ and -k₀ envelopes on
the same crystal axis are byte-identical envelope-form Hamiltonians,
so one aschro call covers both).  Eigenvector fields for non-rep
descriptors are populated by copying from their representative.

Inputs:
  nbasis      — nev for each aschro call
  descriptors — list of descriptor dicts (output of Generic::DeltaValley)
  mask        — flooxs mask string (e.g. "SchrodingerMask")
  args        — extra positional flags forwarded to aschro
                (e.g. `update`)

Side effects:
  - sets kz=0, ky=0 on the active fieldspace
  - leaves eigenvector fields ${sol}${j} populated for every
    descriptor (rep solves directly, non-rep gets field copies)
  - registers the descriptor list with Hamiltonians::Valley so
    downstream rate code's Relation calls fire on these sol-names

Returns: list of band tuples {sol N=1 Econd E_list mdos}, one per
descriptor in input order.  Spin degeneracy is intentionally NOT
folded into N here — KuboGreenwoodK applies its own spin factor.

Hamiltonians::Generic::XValley

  dim       — confined-spatial dimensions (0..3)
  miller    — Miller-orientation string for crystal→device rotation
  params    — dict with keys mcl mct Mxpt alpha k0_frac a0
                mcl, mct  — Δ-valley longitudinal / transverse mass (m₀)
                Mxpt      — X-point coupling-mass parameter
                alpha     — Bir-Pikus shear inverse-mass split parameter
                k0_frac   — X-valley centre offset in 2π/a₀ (0 = envelope
                            form, ≈0.15 = Bloch form at 0.85·X)
                a0        — lattice constant (m), used by k₀ expression
  strain    — dict with keys {dE_list shear_list} (output of
              Strain::Generic::XValleyShifts).  The Ξ_u' shear coupling
              enters via the Bir-Pikus inverse-mass tensor rotation,
              parameterised by params.alpha (m₀-units form of Ξ_u').
  sol_names — list of 6 spinor field names {XA1 XB1 XA2 XB2 XA3 XB3},
              one A/B pair per cubic Δ-axis
  Potential — band-edge field added to each diagonal entry (default Econd)
  k_units   — m | cm.  Coefficients are eV·cm² inside this proc; cm-mode
              is the flooqs KGrid convention.  m-mode would require
              adjusting the C constant — flagged as TODO if needed.

Returns a list of 6 expression strings, in the same order as sol_names:
  [H(XA1) H(XB1) H(XA2) H(XB2) H(XA3) H(XB3)]

Ritz projection onto a coarse-mesh basis followed by a 1-step RQI fix
at the current PS potential.  Returns the standard PoissonSchrodinger
{elec hole} pair.

Fixed-precision formatting for StructSig inputs.  Numbers format to 6
sig figs (legacy behavior, byte-identical); alagator expression strings
— produced by the `quantum pull` engine when strain enters through the
stress.* fields — pass through verbatim: two valleys share a sig iff
their expressions are byte-identical, which is exactly the dedup
contract.

Hamiltonians::Valley::ClearRegistry

Wipe the EV-name index.  Tests / multi-run decks call this to avoid
stale entries crossing between scenarios.

Hamiltonians::Valley::Lookup

Returns the descriptor for the given EV name, or "" if not found.

Hamiltonians::Valley::Make — build a descriptor dict.

Hamiltonians::Valley::ReduceEmpirical

Post-solve grouping that catches geometric degeneracy across
structurally-distinct valleys (e.g. (001)<110> square wire makes
Δ_x and Δ_y eigenvalue-equal even though their rotated mass tensors
differ in matrix form).

  descriptors — list of representative descriptors (one per
                struct_sig group, output of ReduceStructural)
  E_dict      — dict mapping each representative's sol-name to its
                sorted k=0 eigenvalue list
  tol         — absolute eigenvalue tolerance (eV); two reps are
                considered eigenvalue-equal iff their lists match
                elementwise within tol

Returns a list of {representative members} pairs, where members is
the descriptors collapsed into this representative.  Inputs that
don't appear in E_dict are passed through untouched as their own
group.

Hamiltonians::Valley::ReduceStructural

Group descriptors by struct_sig.  Returns a list of {representative
copies} pairs — one entry per unique signature, with `representative`
being the first descriptor in input order.  The `copies` list always
includes the representative itself (so total descriptor count is
preserved across the partition).

Hamiltonians::Valley::PackKramers

Backward-compatibility helper for rate code that expects band tuples
packed with N=2 for ±k₀ Kramers pairs (today's OpticalPhononRate
g-process logic, etc.).

Given a descriptor list, group descriptors whose k0_crystal vectors
are negatives of one another (and which share struct_sig — they're
always TR partners for envelope-form Hamiltonians, but the check is
cheap insurance against future builders).  Returns a list of
{representative degeneracy} pairs:

  degeneracy = number of descriptors folded onto the representative

Descriptors with a unique k0 (no opposite-sign partner present in
the input list) come back with degeneracy=1 unchanged.
Hamiltonians::Valley::Register

Index a descriptor under a band-tuple EV name.  Same descriptor can
be registered under multiple EV names (useful when a legacy solver
emits "EVS11V"-style names that don't match the descriptor's sol).

Stores: dict { ev_name → descriptor }

Hamiltonians::Valley::RegisterFromDescriptors

Bulk-register a descriptor list under each descriptor's `sol` field.
Convenience wrapper for the common case where rate-code EV names
match the descriptor sol-names.

Hamiltonians::Valley::Relation ev1 ev2

Classify a pair of valleys for scattering purposes.  Returns:
  self    — same valley (no scattering channel)
  g       — same crystal axis, opposite k₀ sign (g-process intervalley)
  f       — different crystal axes (f-process intervalley)
  unknown — at least one EV name has no descriptor registered

Callers handle "unknown" by falling back to legacy semantics
(today's 3-Δ N=2-packed band tuples don't carry descriptor metadata
under their flooxs-derived "EVS${v}1V" / "EVX${v}V" sol-names).

Hamiltonians::Valley::StructSig

Stable hash from the structural inputs that drive an H expression.
The expression is built from these alone (plus the sol-name, which
we want to ignore for dedup), so two descriptors with the same sig
produce byte-identical operators.

  minv_r    — 3x3 rotated inverse-mass tensor (list of lists)
  dE        — diagonal strain shift (eV)
  sh        — Bir-Pikus shear coupling
  k0_frac   — Bloch-form k0 fraction (0 for envelope)
  extras    — optional dict of additional structural inputs
              (e.g. off-diagonal B tensor for X-valley 2x2)

Returns a fixed-precision string representation.  6 sig figs is
tighter than the 1e-30 tolerance the builders already use for
matrix elements and looser than floating-point noise on rotation
matrix multiplications.

lastly we can make guesses using the POD equations for each solution

Initialize dopant-defect product solutions.  For React model, these are
real solve variables (XInt, XVac for dopant X).  For other models they are
const placeholders.

Quadratic interpolation with bowing parameter for alloy properties.
Returns an Alagator expression: (1-x)*valA + x*valB - bow*x*(1-x)
x can be a numeric constant or an Alagator field name.

Linear interpolation returning an Alagator expression.
x can be a numeric constant or an Alagator field name.

Trapezoidal integration over loop sizes for interstitial-flavored loops.

Remaining parameters were parsed by AI.. verify at a different date if someone cares
--- III-V Semiconductors ---

Helper: Jancu 1998 sp3d5s* tight-binding parameter sets (PRB 57, 6493)
packaged as auto-loadable procs JancuSi, JancuC, JancuGe, JancuAlP, JancuGaP,
JancuInP, JancuAlAs, JancuGaAs, JancuInAs, JancuAlSb, JancuGaSb, JancuInSb.
Each returns a Tcl-eval'able body of `set <param> <value>` lines: call as
`eval [JancuSi]` to bind the params in the caller's scope, or pass `[JancuSi]`
to spds-general.tcl's `sp3d5s*` builder. Energies in eV, lattice constants in
Å. SOC parameter is lambda_p (diamond) or lambda_p_{a,c} (zincblende).
Jancu 1998 Parameters (eV)

LK_KGrid H kmax dk nev dim sols a0 — sweep a polar k-grid, solve the LK
ladder at each point, and return a list of {ky kz Eig EVnames polarizations}
(in-plane / transport polarization factors from the |3/2,±> weights).

============================================================================
Band solver dict — LK 6-band k.p (kaschro/kcharge schema)
============================================================================
Returns a band_procs dict for the new PoissonSchrodingerKdep. LK is one
valley with 6 spinor components; kaschro sweeps the Hamiltonian over the
kgrid and persists wavefunctions for kcharge to integrate.

Pure dict builder: the deck registers the Hamiltonians FIRST via
`quantum pull= $dict` (Models/QuantumWrapper.tcl); this proc only names
the standardized LK solution set.

  set q [::Hamiltonians::Baseline Silicon]
  dict set q Silicon CommonParameters Miller "(x:100)<z:011>"
  quantum pull= $q
  set bp [LKBandProcs $nev]

LKElectrostatics H nev dim sols a0 — solve the confined LK ladder at k=0 and
return a band tuple {LKV 1.0 Eval Eig mdos} with velocity-based DOS masses
from a finite-difference dispersion (1D: geometric mean of y/z; 2D: z only).

Log-normal size distribution kernel.  Alagator doesn't parse `^` so the
squaring is expanded to `(diff)*(diff)`.

Loop average size Dall.  Alagator-`^` is expanded to `*`.

Loop density Nall — accumulates the local self equation incrementally
(because of nested foreach control flow) and flushes via pde_set_self at
the end.  Cross-coupling is appended inline through pde_append.

Loop elastic energy factor at radius $AvgRad.  Read the elastic moduli
(mu, b, ohm, kerg, nu) preferentially from the per-defect namespace
(::Mat::Sol::Key) but fall back to material-level (::Mat::Key) — this
mirrors master's pdb chain walk that auto-falls-back when the per-(mat,
sol) slot is missing.

In practice LoopEng is called with $Sol = Nall (the loop density species)
inside IntNumIntegral; Nall doesn't carry its own elastic moduli, so the
fall-back to material-level is load-bearing.

Compute the tunneling length in 1D
all parameters are optional
units are nm or um
Econd_o is an offset value for the conduction band
Eval is the name of the valance band
Econd is the name of the conduction band

Masetti Mobility Model from Sentaurus, P at end of parameter is Phospherous, B at end of parameter is Boron
See paper titled Electrical TCAD Simulations of a Germanium pMOSFET Technology

Aggregate electron DOS for ohmic contact calculations.
Returns X-valley Nc, which is the dominant valley in Si-rich compositions
and provides the correct contact boundary condition.

Gamma-valley electron DOS (1-fold degeneracy)
Si: mGamma ≈ 0.036 (very light, high in the band structure)
Ge: mGamma ≈ 0.041

L-valley electron DOS (4-fold degeneracy)
Ge: ml=1.59, mt=0.0815
Si: L-valley masses ml=1.42, mt=0.13
Computed inline (same method as Germanium::Nc) to match endpoint exactly.

X-valley electron DOS (6-fold degeneracy)
Si: ml=0.9161, mt=0.1905 → md = 6^(2/3)*(ml*mt^2)^(1/3) ≈ 1.084
Ge: X-valley masses ml=1.35, mt=0.29 → md = 6^(2/3)*(ml*mt^2)^(1/3) ≈ 1.42

o1: p-orbital index (0=x, 1=y, 2=z)
o2: d-orbital index (0=xy, 1=yz, 2=zx, 3=x2-y2, 4=3z2-r2)
dv: normalized cosine vector {l m n}

o1 is the first p-orbital index
o2 is the second p-orbital index
dv is the normalized cosine vector as a list

Silicon Electron and Hole Poisson-Schrodinger loop with predictor corrector
T is temperature, er is the oxide relative permittivity

============================================================================
Band-agnostic Poisson-Schrodinger with k-dependent charge (kaschro/kcharge)
============================================================================
Self-consistent PS loop using the flooxs C++ commands kaschro and kcharge.
kaschro sweeps the eigenvalue problem over every kgrid node (RQI from a
single full-solve at the band-minimum k-node); kcharge integrates
  ρ(r) = (spin / 2π) Σ_b ∫ |ψ_b(r,k)|² f(E_b(k); Ef, T) J(k) dk
in C++. After PS convergence, dispersion fields lbte_comb_Ek_<g> /
lbte_comb_Vk_<g> are populated for downstream LBTE mobility consumers.

band_procs dict keys (top-level):
  valleys           — list of per-valley dicts (see below)
  ev_prefix         — combined energy-sorted eigenvector prefix
  band_edge         — band-edge alagator expr (re-evaluated each iter)
  carrier           — "electron" | "hole"
  fermi_qf          — quasi-Fermi field; Ef = mean of this
  classical_carrier — classical carrier field swapped in Poisson PDE
  spin_factor       — extra (band, k) weight (LK Kramers=1; spinless 2x2=2)
  kgrid_name        — kgrid FieldServer name (default "KSpace")

Per valley dict:
  sols         — kaschro solutions= list (component prefixes)
  H            — kaschro H= list (one entry per sols)
  nev          — eigenvalues per valley
  wavebase     — kaschro wavebase= for unique kgrid output names
  charge_field — kcharge out= for this valley (kcharge zeros each call)
  degeneracy   — optional; default 1.  Multiplier for this valley's
                 kcharge contribution and for downstream form-factor /
                 dispersion expansion.  Set to 2 (or higher) to merge
                 symmetry-equivalent valleys into a single kaschro
                 call instead of computing each separately.  E.g.,
                 (x:100)<z:011> Si has crystal [010] ≡ [001] X-valleys
                 (y↔−y mirror); compute one, set degeneracy=2, drop
                 the other.

Note: KSpace resolution drives the inner Newton kaschro cost. Coarsen via
the caller's KGrid <kmax> <dk> by raising dk if PS becomes slow.

Returns: [list $valleys $disp]
  valleys = [list {ev_prefix 1 band_edge E_sorted precomputed}]
  E(k), v(k) on KSpace as ${ev_prefix}${g}Ek / Velocity.
  disp = dict {nsub <n> v_conv <vc> lk_occ <list> psi_meta <dict>
               band_classes <list>}  — thread into LBTEMobility /
               KuboGreenwoodK / ComputeElecDispersion via the
               `dispersion= $disp` keyword arg.

============================================================================
Predictor-corrector variant of PoissonSchrodingerKdep
============================================================================
Same band_procs schema and return shape as PoissonSchrodingerKdep.  The
difference is the inner-loop body:

  1. Predictor — kaschro + kcharge per valley (identical to Kdep).
  2. Per-subband effective-DOS extraction — invert the parabolic 1D / 2D
     Fermi-Dirac integral to find m_eff,g such that
       lk_occ[g] = __Stats{1,2}D(m_eff,g, T, (E0[g] - Ef))   (holes)
     reproduces the kaschro-derived occupation at the current Ef.
  3. Closed-form quantum charge — assemble HoleSchro (or ElecSchro) as a
     DevPsi-dependent alagator string via __PSAddHoleStats /
     __PSAddElecStats:
       Σ_g |ψ_g|² · __Stats{1,2}D(m_eff,g, T, -Qfp + (Eval-EvalPrev) + E0[g])
     The (Eval-EvalPrev) factor is the predictor-corrector hook — Poisson
     Newton sees the FD integral shift with DevPsi during the corrector
     solve, so each outer (kaschro) iteration converges over a much wider
     basin of attraction than Kdep's frozen-charge step.
  4. Corrector — `device init silent` re-solves Poisson with the
     DevPsi-responsive quantum charge.
  5. Anderson mixing on DevPsi (identical to Kdep), optionally preceded by
     linear damping `pc_damp` (default 1.0 = off).

Extra band_procs keys (with defaults):
  pc_damp        1.0    linear damp on post-corrector DevPsi (before Anderson)
  pc_int_err     1e-10  subband-significance threshold passed to __PSAddHoleStats
  pc_meff_floor  1e-4   clamp on per-subband m_eff (in m₀ units)
  pc_meff_ceil   100.   clamp on per-subband m_eff

Test target: LK 6-band holes on a confined geometry (dim=2 simulation, 1D
KGrid).  Also supports electron decks (X-valley) on dim=2 or dim=1.

QGrid: 1D fieldserver for form-factor / momentum-transfer lookup.

Nodes live on normalized [0, +1]; physical |q| (1/cm) is stored as the
`q` field with value x·qmax. Always 1D — form factors for 1D-k nanowire,
2D-k planar, and 3D-k bulk transport all depend only on the scalar |q|
(transverse-plane rotational invariance of the screened Coulomb kernel +
|ψ|² confinement envelopes), so QGrid has no dim-dispatch.

Form factor fields on QGrid follow the convention `${prefix}_${b}_${bp}`
(e.g. `PhononFF_2_3`) and are read by the C++ `lbte` command via
`ff.bindings= {symbol prefix ...}` at rate registration. Writers:
  ComputeFormFactorsTable PhononFF $valleys
  ComputeSRFormFactorsOnQGrid AndoSRFF $valleys
  CoulombScatteringOnQGrid CoulFF_$tag $charge $screening

__pick qd ref — resolve a {Sub Key} mass reference into qd, e.g.
{XValley mct} -> [dict get $qd XValley mct].

__tunnelDosScale dim degen mass — per-dimensionality DOS prefactor for
the indirect-tunnel conduction/valence scale factors (2D: sqrt(2 m E)
surface DOS; 1D: line DOS; 0D: degeneracy count only).

__tunnelTdos qd {form valley} — confinement transverse-DOS mass for a
conduction valley: sqrt_lt -> sqrt(mct*mcl); long -> mct;
ge_l -> sqrt(mct*(mct+2*mcl)/3).

QSolve::BandEnergies bands -> dict {bandname -> eigenvalue-list}.
`bands` is a flat list of band tuples {name degen pot E mdos ...};
pulls the 4th element (E) per name.  Replaces the deprecated
::<Mat>::E* side-effect globals — consumers read energies from here
(or straight from the returned tuples) instead of the namespace var.

QSolve::ComputeOmegaMsq qd — phonon-assisted coupling term |OmegaM|^2
for indirect (phonon-assisted) tunneling.  Reproduces the unit lifts
from the old ::Silicon::QuantumParams / ::Germanium::IndirectTunnelingParams
inline blocks: Dk0 eV/cm -> J/m (x100 then x q_e), rho g/cm^3 -> kg/m^3
(x1000), omega = hw*q/hbar.  Returns J^3*m/(kg*rad) (SI), matching the
scal factor in the tunnel-current procs.

QSolve::DirectTunnelCurrent qd bands T — direct band-to-band tunneling
current.  Pull form of ::<Mat>::DirectTunnelCurrent: the conduction
band, two valence bands, and direct gap come from qd `DirectTunnel`;
eigenvalues from the band tuples.  Thin wrapper over the generic
SchrodingerDirectCurrent engine (no namespace var / E* global).

QSolve::DirectTunnelCurrentKP qd bands T — direct tunneling into the Γ
valley against an LK valence band (Ge).  Pull form of
Germanium::DirectTunnelCurrentKP: mc/Eg from qd `DirectTunnel`, the Γ
eigenvalue and the LK hole tuple from `bands` (no ::<Mat>:: globals);
the LK k-grid is built with the material's Luttinger params.

QSolve::IndirectTunnelCurrent qd bands T — phonon-assisted indirect
band-to-band tunneling current.  Pull form of ::<Mat>::
IndirectTunnelCurrent: conduction valleys (degeneracy + transverse-DOS
mass) and valence bands come from qd `Tunnel`; the FGR coupling is
ComputeOmegaMsq(qd) and the phonon energy qd Phonon hw; eigenvalues from
the band tuples.  Sums every (conduction, valence) crossing through the
generic SchrodingerIndirectUnscaledTransmission engine.  Returns
"<integral_abs> <integral_em> <per-transition abs/em debug...>".

QSolve::MatData mat — per-material quantum-solver data dict.

These are the Schrodinger/tunneling solver's own tuned constants (the
values formerly inlined in ::Silicon::QuantumParams /
::Germanium::{Indirect,}TunnelingParams).  They are deliberately
DISTINCT from the device-pull BandStructure masses (e.g. Si quantum
mcl 0.9163 vs CommonParameters Xml 0.916 vs Valleys ml
0.97) — the confined-subband solver was tuned independently, so the
values must be preserved verbatim.  Kept as a literal table here (the
same on-the-object pattern as flooqs ::Materials) rather than under a
device-pull family: the `Quantum` family name is taken by the
Density-Gradient composer, and these solvers never run through
`device pull`.

Non-parabolicity correction for an ellipsoidal subband ladder.
  E         - list of subband eigenvalues (eV)
  EV        - eigenvector solution-name prefix (EV0, EV1, ... must exist)
  BandEdge  - band-edge potential field name
  alpha     - non-parabolicity parameter (1/eV)
reference doi: 10.1063/1.3500553

QSolve::QuantumLocals mat — returns a script (for `eval`) that sets the
legacy ::<Mat>::QuantumParams / IndirectTunnelingParams locals
(mct mcl mvlh mvhh hbar q me pi hw OmegaMsq) from MatData — a drop-in for
the deleted per-material param-var blocks, used by the band-solve /
generation procs that haven't been fully restructured into pull form.

QSolve::Schrodinger100Solve qd ?dooxide? — confined band solve along
[100], data-driven off the qd `Bands` descriptor (was the per-material
::<Mat>::Schrodinger100Solve).  Each band entry:
  kind  elec|hole         pot   band-edge field
  meff  {Sub Key} ref     degen tuple degeneracy
  mdos  DOS mass          np    (optional) non-parabolicity alpha
  conv_mcl (optional)     transport->DOS confinement-mass conversion
                          m -> 3*m*mct/(2*m+mct)  (L-valley)
Solve method: when the material declares `ConfineOxideMask <mat>` and
dooxide==0, the confined eigenproblem is the oxide-penetrating aschro
(band edge masked by a large oxide potential); otherwise the plain
`schro` effective-mass solve.  Returns {elec hole} band-tuple lists;
does NOT set any ::<Mat>:: global (see BandEnergies).

QSolve::Schrodinger100SolveKP qd ?dooxide? — confined band solve with
LK (k.p) valence holes instead of the effective-mass holes of
Schrodinger100Solve.  Pull form of ::<Mat>::Schrodinger100SolveKP.
Electrons come from the qd `KP elec` descriptor (per-band solve =
schro | aschro_plain, optional non-parabolicity / L-valley mass
conversion); holes are the LK ladder (LK::BuildH on the material's
Luttinger params -> LKElectrostatics).  Returns {elec hole}; no E* global.

QSolve::SchrodingerSolveElec qd nev ... — confined electron Δ/X-valley
solve.  Generic body (was ::Silicon::SchrodingerSolveElec); the only
material input is the X-valley mass pair from `qd`.  The rest is the
already-generic SchrodingerSolveEllipsoidal / SchrodingerSolveXVal
engine.  Preserves the full band tuple incl. the 6th device-frame
inverse-mass element appended by SchrodingerSolveEllipsoidal.

============================================================================
`quantum` command
============================================================================

RotMExpr — numeric tensor congruence  Ten' = α · Ten · αᵀ
(Ten'[i][j] = Σ_mn α[i][m]·α[j][n]·Ten[m][n]).

o is the d-orbital index
dv is the normalized cosine vector as a list

o is the p-orbital index
dv is the normalized cosine vector as a list

Helper: Slater-Koster two-center integral procs (s-s, s-p, p-p, s-d, p-d,
d-d) for the sp3d5s* basis, plus a built-in self-check (assert_close
block + 10x randomized d-d symmetry test) that runs at source time. Used
by spds-general.tcl to construct the Tcl-side tight-binding Hamiltonian.

Slater integral convienence procs

The driving force, SRH, band gap, and thermal voltage are arguments
This expression modifies an SRH like expression

Computes direct tunnel current using the Bigelow method
Ec is the gamma electron sub band energies
EVc is the gamma electron eigen vector base names
mc is the gamma electron effective mass
Evlh is the light hole sub band energies
EVvlh is the light hole eigen vector base names
mvlh is the light hole effective mass
Evhh is the heavy hole sub band energies
EVvhh is the heavy hole eigen vector base names
mvhh is the heavy hole effective mass
Eg is the direct band gap
T is the temperature

Computes direct tunnel current using the Bigelow method assuming kp
Ec is the gamma electron sub band energies
EVc is the gamma electron eigen vector base names
mc is the gamma electron effective mass
Ev is the hole sub band energies
EV is the hole eigen vector base names
mv is the hole effective mass
Eg is the direct band gap
T is the temperature

Computes indirect tunneling transmission for a given conduction and valance band
Ev is list of eigenvalues for the valance band
EVv is the valance band eigenvector base name
Ec is list of eigenvalues for the conduction band
EVc is the conduction band eigenvector base name
hw is the phonon energy
T is the temperature value or field
N is the Number of integration points
Returns units of inverse cm

Solve the Schrodinger equation for a set of ellipsoidal valleys.

Arguments:
  Econd       - band edge potential name (Alagator field)
  ml          - longitudinal effective mass (m0 units)
  mt          - transverse effective mass (m0 units)
  directions  - list of valley direction vectors, e.g., {{1 0 0} {0 1 0} {0 0 1}}
  dotransport - compute transport mass if true
  nev         - number of eigenvalues
  prefix      - solution variable prefix (e.g., "EVX" or "EVL")
  alpha       - 3x3 crystal-to-device rotation matrix
  shear_alpha - shear deformation potential (Ξu' rotation coeff) used by
                the `shear_list` term; default 53.0 (Silicon).
  a0          - lattice constant (m) used only as the finite-difference
                step scale for the transport-mass k-derivative; default
                5.43e-10 (Silicon).

L-valley solver: 4 valleys along <111> directions

X-valley solver: 6 valleys along <100> directions

Interface segregation — uses the slash form for side-qualified Sol
references (see src/BasePDE/lexical.cc for the lexer patch).

Common oxide and gate equations for the GAA nanowire
Args:
  er_ox - oxide permittivity (default 5.8 for HfO2/AlOx, use 3.9 for SiO2)
  wfn   - gate work function (default 4.408)

Silicon::SG — SG-mode entry point: sources the SG-specific Silicon
baseline (Masetti + Canali mobility, Flat single-band, Transport=SG,
SRH+Auger recombination) and runs `device pull T= $T sg` to register
the full SG infrastructure (Elec/Hole PDE, Qfn/Qfp const, per-axis
Emfn{x,y,z}/Emfp{x,y,z}, SGOhmic contacts).  Replaces the legacy
SGDevicePackage proc.

Small interstitial cluster (Smic) — formation from Int + I2; recombination
with V2 → base.

Run a Galerkin POD-projected Newton solve using the per-variable
bases stored in this namespace.  Returns the iteration count.  The
caller is expected to have already set up an initial guess (e.g. via
POD::Init) so the warm start lives in the column space of V.

============================================================
SolveEllipsoidalStrained: reference single-band ellipsoidal solve
with per-valley strain shift (for comparison against the 2x2 result)
============================================================

SolveIMinusA — solve (I - A) x = b by Gaussian elimination with partial
pivoting. A is N×N (list of lists), b is N-vector. Used in tensor Lindhard
for the self-consistent intra-subband response equation (Ferry eq. 2.85).

============================================================
SolveLPointValleys: BuildLPointHams + k=0 aschro + transport mass
============================================================
Returns [list $all_bands $ham_info]
  $all_bands: list of KuboGreenwood-compatible band tuples
              {EV N BandEdge E_list mdos_list}, one per L-valley.
              N=2 (Kramers degeneracy at k=0; envelope form folds
              ±L body-diagonal partners into one valley with spin
              degeneracy carried in N — same convention as the
              legacy single-band ellipsoidal solve).
  $ham_info:  list of {sol H dir} tuples (3-tuple, single-band).

Full ellipsoidal solve (all three Δ-valleys) with strain folded in.
Two-step: (1) registers Δ${v}H const solutions via Generic::DeltaValley
so any quantum-pull-style consumer can read them by name, (2) defers
the actual build+solve to flooxs's QSolve::SchrodingerSolveElec — its
output band tuples include rate-code-required side fields (TransportK,
subband-resolved velocities) that the pure-aschro path doesn't yet
emit.  Once those are reproduced in flooqs, this can drop step 2.

Per-valley ellipsoidal solve with strain folded in.  Used inside
Hamiltonians::RitzRQIBandsProc.  Defers to flooxs's
SchrodingerSolveEllipsoidal for the same TransportK reason as the
full-strained variant above.

============================================================
SolveXPointValleys: Hamiltonians::BuildXPointHams + k=0 aschro + transport mass
============================================================
Returns [list $all_bands $ham_info]
  $all_bands: list of KuboGreenwood-compatible band tuples
              {EV N BandEdge E_list mdos_list}, one per valley
  $ham_info:  list of {s1 s2 H1 H2 dir} tuples — same shape
              BuildXPointHams returns directly.

k0_frac = 0.0 (default): envelope form. k0_frac > 0: Bloch form
centered at ±k0 along the valley longitudinal axis.

Super-saturation ratio bulk equation.  Sets SoR's self equation directly.

Sort a tcl list of numbers low to high

Helper: builds the sp3d5s* tight-binding Hamiltonian (Jancu et al., PRB 57,
6493, 1998) as alagator Hr/Hi strings for the aschro solver. Defines
`sp3d5s* {params use_soc}` which returns {sols Hr Hi} from a Tcl-formatted
parameter set (e.g. `[JancuSi]`, `[JancuInSb]` from params.tcl). The
Slater-Koster two-centre procs (s-s, s-p, p-p, ...) auto-load from slater.tcl
on first use. The proc emits `solution add` consts, so the CALLER must set up
the device first (`options nm !constdatafields !storenodes; init zerod`) —
this library file is side-effect-free on load.
Default use_soc to 1 (True) if not specified

SRH recombination

StressDriftTest — per-component stress regression check.

Used by voxel process decks that compute `averagestress3d` over a
fixed sub-region after stress solves and want to gate on the result.
Designed to coexist with VoxelVolumeTest: volume catches geometry-
construction bugs; stress catches PDE / elasticity / Newton solver
bugs.

Drift model:
  - When |gold| > abs_floor, use RELATIVE drift: |cur - gold| / |gold|.
  - When |gold| <= abs_floor, the component is near the noise floor;
    use ABSOLUTE drift: |cur - gold|, bounded by abs_floor.
Two-mode handling so a near-zero component (szz ~ 1e7 Pa next to a
sxx of ~5 GPa) doesn't fail a 15% relative check on noise.

Args:
  cur=      {sxx syy szz}  three-element list from averagestress3d
  gold=     {sxx syy szz}  reference values
  rel=      relative drift bound (default 0.15 = 15%)
  abs=      absolute floor in Pa (default 1e8 = 0.1 GPa)
  label=    descriptive prefix for log lines (default "")

=====================================================================
Lattice constants (Angstroms) for strain calculations
=====================================================================

tb_random_alloy atom1 atom2 fraction axis cell_lo cell_hi
Randomly assign atom1 vs atom2 on cation (or anion) sites within a slab.
fraction: probability of atom1 (0 to 1)
Only affects sites where atom1 or atom2 is currently present.

Example: tb_random_alloy In Ga 0.53 z 1 2
  Within z=[a,2a], set 53% of group-III sites to In, 47% to Ga

Set the lattice constant (call after lattice command)

tb_slab material axis cell_lo cell_hi
Set atoms in a slab region to a different material.
axis: x, y, or z
cell_lo, cell_hi: slab boundaries in units of lattice constants
material: e.g., GaAs, AlAs, InAs — must match the element naming

Example: tb_slab GaAs z 1 2
  Swaps atoms in z=[a, 2a] from the substrate material to GaAs

tb_strain_z a_sub a0_layer axis cell_lo cell_hi C12_over_C11
Apply tetragonal strain to atoms in a slab along the growth direction.
Modifies z-coordinates using updatecoordinates.
a_sub: substrate lattice constant (in-plane, Angstroms)
a0_layer: natural lattice constant of the strained layer (Angstroms)
C12_over_C11: elastic constant ratio (e.g., 0.534 for GaAs)

Example: tb_strain_z 5.8687 6.0583 z 1 2 0.534

--- Symmetry Test for d-d Block ---

Transpose a tcl list that is holding numeric matrix data

Simple trapezoidal integration formula
U is a list of evenly spaced values
dU is the separation of the values

Trapezoidal integration over loop sizes for vacancy-flavored loops.

VoxelVolumeTest — volume-integration regression check for voxel decks.

Loops over the FieldServer's currently-meshed bulk materials, integrates
each material's volume (`integrate eqn=Material($mat)`), and compares
against a stored gold-value dict. Drift > `bound` percent on any single
material fails the test. Platform-independent metric — replaces the
old structure-to-structure CompareStruct gating in voxel test decks.

Requires the deck to have called `meshvoxel` first (integrate operates
on the tet mesh, not the voxel brick).

XKPBandProcs $qreg ?-mat M? ?-nev N? ?-k_solver S? ?-mirror_kgrid 0|1?
             ?-interp_skip K? ?-ev_prefix P?

XKP2x2 (X-point 2×2 Bloch) electron valleys — one band_procs valley per
X-point instance (its two spinor components solved together).  No geometric
degeneracy folding (each instance is computed; deck-specific miller symmetry
folding is out of scope here — see ReduceEmpirical).

Discretise  coeff * k_a * s   (linear in k; coeff in eV·cm, k in 1/cm)
coeff: number (legacy, byte-identical) or expression string (see XptKK).

Discretise  coeff * k_a * k_b * s   (coeff in eV·cm², k in 1/cm)

coeff is a Tcl number (legacy path — formatted via %.10g, byte-identical
output) or an alagator expression string (spliced in parens; used by the
`quantum pull` engine when strain enters through the stress.* fields).