Skip to content

API Reference

This reference has one page per source file. Each page explains the logic of that file — and the math, where there is any — above its generated signatures. For the end-to-end story, read the worked examples first: Triple Quantum Dot and Minimal Kitaev Chain.

The curated public surface

Most scripts only need the top-level imports:

from tempura import (
    Device,
    Dielectric,
    Gate,
    QuantumRegion,
    prepare_layout,
    build_device,
    build_problem,
    solve_gate_potentials,
)
from tempura.electrostatics import extract_quantum_region_basis, extract_quantum_region_plane

A few conventions worth knowing:

  • Device(grid=...) is the public spelling for the in-plane lattice.
  • build_problem(...) resolves each layer's resolution=[dx, dy, dz] from the finalized device; the QuantumRegion sets the finest master lattice.
  • build_device(...) expands one source_layer into one or more Gate objects, suffixing the names _0, _1, and so on.

The reference is split in two:

  • Core API documents the public modules — the names you import and call directly, listed above.
  • Extensive API documents the internal modules behind them (mesh planning, problem assembly, the linear solve, IO, and formatting), so the logic behind each public name stays traceable. You do not import these directly, but they are documented for contributors and for anyone debugging the pipeline.

(A couple of public helpers, such as extract_quantum_region_plane(...), live in an internal _-prefixed module but are re-exported from tempura.electrostatics; their page sits under Core API where the public methods are.)

The physical model

Tempura solves the Poisson equation for the electrostatic potential \(\phi(\mathbf r)\),

\[ -\nabla\cdot\bigl(\varepsilon(\mathbf r)\,\nabla\phi(\mathbf r)\bigr) = \rho(\mathbf r), \]

where the layer stack defines the geometry and the permittivity map \(\varepsilon(\mathbf r)\), and pescado discretizes it into a sparse linear system \(A\,x = b\). For a fixed device \(A\) is built once; different gate voltages change only \(b\). Tempura assigns one of four boundary models to each region:

Model Condition Used for
Dirichlet \(\phi = \phi_0\) grounded shell, metal gates
Neumann \(\hat{\mathbf n}\cdot(\varepsilon\nabla\phi) = g\) dielectrics
Helmholtz \(\hat{\mathbf n}\cdot(\varepsilon\nabla\phi) + \alpha\phi = \beta\) quantum region (default)
Flexible geometry only; response set later quantum region handed to a self-consistent solve

solve_gate_potentials(...) computes one basis field \(\phi_i\) per gate (gate \(i\) at \(1\,\mathrm V\), all others and the boundary at \(0\,\mathrm V\)). Because the problem is linear, any voltage configuration is the superposition

\[ \phi(\mathbf r) = \sum_i V_i\,\phi_i(\mathbf r), \]

so the one-time factorization is reused for every new voltage setting. The math specific to each step is detailed on the module pages: the Dirichlet elimination on electrostatics.solver, the commensurate mesh on electrostatics._mesh_plan, and the overhang model on electrostatics.height_fields.

For a nonlinear or voltage-dependent quantum-region response the basis fields no longer suffice; hand the finalized problem to Pescado's self-consistent tools directly (see electrostatics.pescado_wrapper).

Core API

The public modules — the names you import and call directly.

Extensive API

The internal modules behind the public surface — implementation detail, not imports. Documented so the pipeline stays traceable.