qtcad.device.electron_kp module

Utilities for defining and resolving general \(\mathbf{k} \cdot \mathbf{p}\) Hamiltonian models.

This module is used to build user-defined \(\mathbf{k} \cdot \mathbf{p}\) models for the Schrödinger solver. An \(n\)-band \(\mathbf{k} \cdot \mathbf{p}\) model represents a Hamiltonian of the form

\[H = \sum_{i, j \in \{1,x,y,z\}} k_i Q_{ij} k_j + V_\mathrm{conf}(\mathbf r) \mathbb{I},\]

where \(V_\mathrm{conf}(\mathbf r)\) is the confinement potential, \(\mathbb{I}\) is the \(n \times n\) identity matrix, \(k_1 = 1\) is a bookkeeping convention, and \(Q_{ij}\) are \(n \times n\) Hamiltonian coefficients. In this notation:

\(Q_{11}\) is a constant coefficient,
\(Q_{1x}\) and \(Q_{x1}\) are first-order coefficients,
\(Q_{xy}\) is a second-order coefficient.

We stress that the coefficients \(Q_{1x}\) and \(Q_{x1}\) are distinct; the former parametrizes a left-ordered contribution, while the latter parametrizes a right-ordered contribution.

Coefficients may be specified either directly or indirectly. Direct inputs may be uniform or spatially varying, for example as scalars, band matrices, NumPy arrays, or callables of position. Indirect inputs are represented by ElectronKPParameter objects, which describe how coefficient values should be obtained from device attributes, material parameters, or defaults.

By default, ElectronKPParameter lookup proceeds in the following order:

Device values:

device.<name>

device.electron_kp_params[<name>]

Values obtained from region materials. Region materials are the materials passed to device.new_region when creating device regions.

material.<name>

material.electron_kp_params[<name>]

The parameter default, if one is defined.

Terminology

coefficient input: Any user-provided object used to define a Hamiltonian coefficient. This includes direct values, callables, and ElectronKPParameter references.
resolved coefficient: A concrete coefficient value obtained after resolution on a specific device.
direction label: An element of ("1", "x", "y", "z").
canonical ordered-pair representation: Internal representation of coefficients using ordered pairs of direction labels. For example, ("1", "1") denotes a constant term and ("1", "x") denotes a left-ordered first-order term.
resolution: The process of converting coefficient inputs into concrete coefficients on a specific device.

Examples

Create a single-band model with one quadratic term:

>>> model = ElectronKPModel(
...     bands=1,
...     quadratic={("x", "x"): 1.0},
... )

Reference a coefficient from the device or its materials:

>>> model = ElectronKPModel(
...     bands=1,
...     quadratic={("x", "x"): ElectronKPParameter("Qxx")},
... )

Type Aliases

Below are a list of type aliases used by the classes and methods defined in this file.

ParameterTransform

Callable that takes a looked-up parameter value and returns a transformed value to be used as a coefficient input. Position-dependent parameters are transformed pointwise.

CanonicalCoefficientTerm

Two-tuple of the form ((i, j), value), where:

(i, j) is an ordered pair of direction labels identifying the coefficient term \(Q_{ij}\),
value is the associated coefficient input.

ConstantInput

Input accepted by the constant argument of ElectronKPModel. Either:

a single coefficient input,
a tuple of coefficient inputs,
or None.

LinearInput

Input accepted by the linear argument of ElectronKPModel. Either:

a mapping from direction labels to coefficient inputs,
an iterable of (label, coefficient) pairs,
or None.

QuadraticInput

Input accepted by the quadratic argument of ElectronKPModel. Either:

a mapping from ordered pairs of direction labels to coefficient inputs,
an iterable of ((label_1, label_2), coefficient) pairs,
or None.

class ElectronKPCoefficients(bands: int, canonical_terms: tuple[ResolvedCoefficientTerm, ...])

Bases: ElectronKPCoefficients

Fully resolved coefficients for an electron k·p model.

This class stores the resolved coefficients of an ElectronKPModel for a specific device. At this stage, all coefficient inputs have already been processed: parameter references have been resolved, spatial callables have been evaluated, and uniform inputs have been converted to band matrices.

Resolved coefficient values are represented either as uniform band matrices with shape (bands, bands) or as mesh-resolved matrices with shape (n_positions, bands, bands), where n_positions is the number of elements or global nodes in the device mesh.

Attributes:

bands – Number of bands in the model.
canonical_terms – Tuple of resolved coefficient terms in canonical ordered-pair form. Each entry is a ((i, j), value) pair, where (i, j) identifies the coefficient slot Q_ij and value is the resolved coefficient value.

get_coefficients_for_pair(requested_pair: tuple[str, str]) → tuple[ndarray[tuple[Any, ...], dtype[_ScalarT]], ...]

Return resolved coefficients matching an ordered pair.

Multiple canonical terms may contribute to the same coefficient Q_ij. This method returns every resolved coefficient whose ordered pair matches requested_pair, preserving the order stored in canonical_terms.

Parameters:: requested_pair – Ordered pair (i, j) identifying the coefficient Q_ij. Valid labels are "1", "x", "y", and "z".
Returns:: Tuple of resolved coefficient values matching requested_pair. If no terms match, returns an empty tuple.

class ElectronKPModel(bands: int, constant: ConstantInput = None, linear: LinearInput = None, quadratic: QuadraticInput = None)

Bases: ElectronKPModel

Electron \(\mathbf{k} \cdot \mathbf{p}\) model with coefficients up to quadratic order.

Mathematically, the model represents Hamiltonians of the form

\[H = \sum_{i, j \in \{1,x,y,z\}} k_i Q_{ij} k_j + V_\mathrm{conf}(\mathbf r) \mathbb{I},\]

where \(V_\mathrm{conf}(\mathbf r)\) is the confinement potential, \(\mathbb{I}\) is the \(n \times n\) identity matrix (\(n\) is the number of bands in the model), and \(k_1 = 1\).

Coefficients may be provided through three input groups:

constant for k-independent terms,
linear for first-order terms of the type \(Q_{1j}\), where \(j \in \{1,x,y,z\}\),
quadratic for explicit ordered-pair inputs.

Internally, all inputs are converted to a canonical ordered-pair representation.

Attributes:

bands – Number of bands in the model, corresponding to \(n\) above.
canonical_terms – Tuple of coefficient terms stored in canonical ordered-pair representation. Each entry is a ((i, j), value) pair, where (i, j) identifies \(Q_{ij}\) and value is the unresolved input for that coefficient (e.g., scalar, matrix, callable, or ElectronKPParameter).
parameter_names – Tuple of unique parameter names referenced by ElectronKPParameter inputs.

__init__(bands: int, constant: ConstantInput = None, linear: LinearInput = None, quadratic: QuadraticInput = None) → None

Constructor for the ElectronKPModel class.

Parameters:

bands – Number of bands in the model.
constant – Optional constant-term inputs. This may be a single coefficient input, an ordered collection of coefficient inputs, or None. Use a tuple to represent multiple constant contributions. Use an ndarray for one matrix-valued coefficient rather than a nested tuple. Each term is converted internally to the canonical ordered-pair representation ("1", "1"). When omitted, no ("1", "1") terms are added.
linear – Optional first-order inputs. This may be a mapping from directions to coefficient inputs, or an ordered iterable of (direction, coefficient) entries. Each direction is converted internally to the canonical pair ("1", direction). Possible values for direction are "x", "y", and "z".
quadratic – Optional explicit ordered-pair inputs. This may be a mapping from ordered pairs to coefficient inputs, or an ordered iterable of ((direction_1, direction_2), coefficient) entries. Explicit pairs may use the internal identity label "1", for example ("1", "1"), ("1", "x"), or ("x", "1").

Raises:

ValueError – If bands is not positive or if any uniform numeric coefficient fails Hermiticity validation.

property canonical_terms: tuple[CanonicalCoefficientTerm, ...]

Return the model terms in canonical ordered-pair form.

Each entry is a ((i, j), value) pair, where value is the unresolved coefficient input associated with the coefficient block Q_ij.

property parameter_names: tuple[str, ...]

Return the parameter names referenced by the model.

Returns:: Tuple of unique model parameter names.

print(device: Device | None = None) → None

Print a human-readable representation of the model.

This method displays the contents of the ElectronKPModel in a structured, readable format.

When no device is provided, the method prints the unresolved model, showing the canonical coefficient inputs stored internally. When a device is provided, the model is first resolved on that device and the resulting coefficients are printed instead.

Parameters:: device – Optional Device. If provided, print the resolved coefficients for this device. Otherwise, print the unresolved model definition.

resolve_device_coefficients(device: Device) → ElectronKPCoefficients

Resolve all model coefficients for a specific device.

This method converts the model’s coefficient inputs into concrete values defined on the device mesh.

Resolution includes:

resolving parameter references through device and material lookup,
evaluating spatial callables on the mesh,
converting scalar coefficients into diagonal band matrices of dimension (bands, bands) where bands is the number of bands of the model unde consideration.

Parameters:

device – Device providing mesh, region, and parameter information. For each ElectronKPParameter, lookup proceeds in the order device.<name>, then device.electron_kp_params[<name>], then region materials, which are the materials passed to device.new_region when creating device regions, and finally the parameter default when available.

Returns:

ElectronKPCoefficients representing the fully resolved k·p model on this device.

Raises:

KeyError – If a parameter cannot be resolved from the device, region materials, or a default.
ValueError – If a coefficient fails Hermiticity validation.

class ElectronKPParameter(name: str, device_attr: str | None = None, material_attr: str | None = None, default: object = <object object>, transform: ParameterTransform | None = None)

Bases: ElectronKPParameter

Indirect coefficient input for an electron \(\mathbf{k} \cdot \mathbf{p}\) model.

An ElectronKPParameter does not store a coefficient value directly. Instead, it describes how a coefficient should be obtained when the model is resolved on a specific device.

By default, lookup proceeds in the following order:

Device values:
1. device.<name>
2. device.electron_kp_params[<name>]
Values obtained from region materials. Region materials are the materials passed to device.new_region when creating device regions.
1. material.<name>
2. material.electron_kp_params[<name>]
The parameter default, if one is defined.

The lookup paths may be overridden with device_attr and material_attr. When one of these is provided, only that dotted path is tried on the corresponding side.

If transform is provided, it is applied to the looked-up parameter value before that value is interpreted as a coefficient. For position-dependent parameters, the transform is applied pointwise: for scalar parameters, it acts on the scalar value at each point in space; for tensor parameters, it acts on the tensor value at each point in space. This is useful when a model coefficient should be derived from an existing device or material parameter rather than stored separately under a dedicated electron \(\mathbf{k} \cdot \mathbf{p}\) name.

Attributes:

name – Parameter name used for default device- and material-side lookup.
device_attr – Optional dotted device path overriding the default device-side lookup.
material_attr – Optional dotted material path overriding the default material-side lookup.
default – Optional fallback value used when neither the device nor the region materials define the parameter. If left unset, failed lookup raises KeyError.
transform – Optional callable applied to the looked-up parameter value before it is used as a coefficient.

Note

Transforms are useful when a \(\mathbf{k} \cdot \mathbf{p}\) parameter depends on a standard material parameter. For example, in an effective-mass-style electron \(\mathbf{k} \cdot \mathbf{p}\) model, a transform may extract one component of Me_inv, divide it by 2, and multiply it by hbar ** 2 before using it as the resolved coefficient.

__init__(name: str, device_attr: str | None = None, material_attr: str | None = None, default: object = <object object>, transform: ParameterTransform | None = None) → None

Constructor for the ElectronKPParameter class

Parameters:

name – Parameter name used for default lookup.
device_attr – Optional dotted device path overriding the default device-side lookup. When omitted, lookup tries device.<name> first and then device.electron_kp_params[<name>].
material_attr – Optional dotted material path overriding the default material-side lookup. When omitted, lookup tries material.<name> first and then material.electron_kp_params[<name>] for each region material.
default – Optional fallback value used when neither the device nor the material defines the parameter.
transform – Optional callable applied to the looked-up parameter value before it is interpreted as a coefficient.