Quasiparticle (QP) expansion and density-matrix renormalization group (DMRG) solvers for superconducting quantum impurities.
Authors: Teodor Iličin and Rok Žitko. License: BSD-3-Clause.
qdjj_solver calculates low-lying many-body energies, impurity charge and spin,
Josephson currents, and transition matrix elements for interacting impurities
coupled to superconducting reservoirs. Models can contain one or more impurity
orbitals and several superconducting leads.
Both numerical methods solve the same finite-bath Hamiltonian:
| Method | Approximation and convergence parameter |
|---|---|
| Quasiparticle expansion | Retains all impurity configurations and limits the number of bath QPs. Increase the QP cutoff to check convergence; removing it gives exact diagonalization (ED) of the finite-bath model in the selected symmetry sector. |
| DMRG | Represents the state as a matrix-product state (MPS). Increase the MPS bond dimension and check the optimization to establish convergence for the finite bath. |
Bath discretization is a separate approximation. Small finite models allow direct comparisons between the two methods and unrestricted ED.
The QP method references describe our Andreev spin-qubit (ASQ) variational theory and its earlier single-impurity and quantum-dot Josephson-junction formulations.
The Python modules qdjj_solver.common, qdjj_solver.qp_solver, and
qdjj_solver.dmrg_solver provide the common model definitions and the two solvers.
Try the QD Josephson Junction Explorer for interactive QP-expansion calculations of a quantum dot coupled to one or two superconducting leads. Explore many-body spectra, inspect state composition and physical observables, run parameter sweeps, and export data and plots.
The numerical solver runs locally in your browser using WebAssembly, with no installation required.
Install the current version from source. Building the native extension requires Python 3.11+, a C++17-capable compiler, and Python development headers for the interpreter being used. Install them before running pip:
- Linux: GCC or Clang; on Debian/Ubuntu, for example, install
build-essentialandpython3-dev(or the development package matching your Python version). - macOS: Xcode Command Line Tools (
xcode-select --install). - Windows: Visual Studio C++ Build Tools with the C++ workload and Windows SDK.
Pip obtains CMake and pybind11 as needed, but does not install a C++ compiler or Python development headers.
git clone https://github.com/rokzitko/qdjj_solver.git
cd qdjj_solverChoose one of these installation alternatives. The [dmrg] extra is
required for every DMRG example below, including continuation and
examples/00_first_calculation/run.py --profile full; it installs TeNPy and HDF5 support for saved
MPS states. The base installation supports models and the QP solver without TeNPy.
python -m pip install . # models and QP solver
python -m pip install '.[dmrg]' # add DMRG and saving of MPS states (recommended)
python -m pip install -e '.[dmrg,dev]' # development installationfrom qdjj_solver import Sector, cosh_grid, reference_model, solve
bath = cosh_grid(pairs=1, delta=1.0, bandwidth=5.0)
h = reference_model(bath, u=1.6, gamma=0.3, phi=0.8, compress=False)
sector = Sector(parity=1, twice_sz=1) # odd parity, S_z = 1/2
qp = solve(h, cutoff=2, sector=sector, backend="qp")
print(qp.energies, qp.qp_weights)
assert abs(qp.energies[0] - (-0.2950595967187083)) < 1e-10
assert max(qp.residuals) < 1e-9
assert abs(qp.qp_weights[0].sum() - 1) < 1e-12From the main source directory, the same QP-only example runs with
python -B examples/quickstart.py.
It computes the lowest state in the selected sector of a small finite model.
Here energies are in units of the gap, gamma=0.3 is the total hybridization
of both leads, and phi=0.8 is their phase difference in radians. To identify
the global ground state, compare the relevant even and odd sectors.
The bath and many-body settings are:
-
pairs=1: one mirrored pair of normal-state bath energies, at$+\xi$ and$-\xi$ , per lead. Increasingpairsrefines the bath discretization; it does not count leads or spin directions. -
compress=False: retain all bath modes. In this symmetric model, some linear combinations of degenerate bath QP modes have tunnelling amplitudes to the impurity that cancel exactly. These "dark" combinations decouple from the impurity, although occupying them still costs excitation energy.compress=Trueretains the coupled ("bright") combinations and freezes the discarded dark modes in their vacuum, omitting states with dark-mode excitations. UseFalsewhen the full finite-bath spectrum is needed. -
parity=1: select odd total fermion parity;0selects even parity. This includes the impurity and both reservoirs, not only the impurity. -
twice_sz=1: select total spin projection$S_z=+1/2$ , in units where$\hbar=1$ . This also includes both impurity and reservoir spins. -
cutoff=2: allow at most two bath QPs in total across both leads and spins. All impurity configurations remain available, subject to the selected total sector.cutoff=Noneremoves this bath-QP truncation.
The printed output is approximately:
[-0.2950596] [[0.89270561 0.10104019 0.00625420]]
qp.energies contains the computed many-body energies in the selected sector,
not excitation gaps. By default, solve returns only the lowest state.
qp.qp_weights[i, n] is the probability of exactly n bath QPs in eigenstate
i, obtained by summing squared amplitudes of the corresponding configurations;
impurity occupation is not counted. Here the single row gives probabilities
of approximately 89.27%, 10.10%, and 0.63% for zero, one, and two bath QPs.
Each row sums to one. Odd total parity does not require odd bath-QP number,
because the impurity also contributes to parity.
The assertions check the reference energy, the eigenvalue-equation residual
qp.residuals, and normalization of the QP weights. The residual measures
eigensolver accuracy within the truncated space; neither a small residual nor
normalized weights establishes convergence with QP cutoff or bath size.
To continue with DMRG, the [dmrg] extra must be installed. If you chose the base
installation, first run python -m pip install '.[dmrg]' from the main source
directory, then continue in the same Python session:
import numpy as np
mps = solve(h, sector=sector, backend="dmrg",
options={"eigenpairs": 2, "chi_max": 32, "require_convergence": True})
exact = solve(h, cutoff=None, sector=sector, options={"eigenpairs": 2})
np.testing.assert_allclose(mps.energies, exact.energies, rtol=0, atol=1e-9)
print(mps.energies, mps.residuals)
print(mps.matrix_elements(h.observables["impurity_spin_z"]))Both methods use the same finite Hamiltonian and energy zero. The first
QP calculation, qp, uses cutoff two; exact includes every configuration
allowed by the selected symmetry sector. DMRG includes the same modes and
approximates the state through its MPS bond dimension. Eigensolver accuracy,
QP/MPS convergence, and bath convergence must be assessed separately.
To save a result and its wavefunctions, then load them for further analysis:
from qdjj_solver import save_result, load_result
save_result(qp, "results/state.json", save_states=True)
restored = load_result("results/state.json")Python solve includes all configurations of the specified finite bath by
default; the qdjj-solver terminal command defaults to QP cutoff two.
Set compress=False explicitly when constructing a full reference
model in Python. See the
defaults table
and convergence guidance
before increasing problem sizes.
Tutorial 00
provides JSON inputs and reference outputs for these calculations.
Run python -B examples/00_first_calculation/run.py for QP with the base installation.
With the [dmrg] extra installed, add --profile full for all three
calculations (QP expansion, DMRG and exact diagonalization).
To specify a calculation in an input file, save the following text as
model.json in your working directory. This example requires only the base
installation:
{
"format_version": 1,
"backend": "qp",
"model": {"kind": "reference", "u": 1.6, "gamma": 0.3, "phi": 0.8, "compress": false},
"bath": {"kind": "cosh-grid", "pairs": 1, "bandwidth": 5.0},
"cutoff": 2,
"sector": {"parity": 1, "twice_sz": 1},
"solver": {"eigenpairs": 2}
}qdjj-solver solve model.json --output results/qp.json --save-statesThe command creates the output directory and prints a lowest energy near
-0.2950595967. It saves the energies and calculation settings in JSON, and the
wavefunction coefficients in a companion NumPy file (NPZ). Load the result with
load_result("results/qp.json").
The following commands use input files supplied with the source code; run them
from the main source directory. The DMRG solve and --resume commands require
the [dmrg] extra: install it first with python -m pip install '.[dmrg]'.
qdjj-solver solve examples/qp.json --output results/qp.json --save-states
qdjj-solver solve examples/dmrg.json --output results/dmrg.json --save-states
qdjj-solver solve examples/dmrg_refined.json --resume results/dmrg.json --output results/refined.json --save-statesdmrg_refined.json raises chi_max from 32 to 64, permits more sweeps, and tightens
energy and residual tolerances. --resume starts a new optimization from the
saved, completed MPS states using the new settings. This small example normally
already converges at bond dimension 32; the same procedure is useful for larger models.
qdjj-solver saves both methods' results in a common JSON format. Wavefunctions
are saved separately as NPZ files for QP calculations and TeNPy HDF5 files for
DMRG. Keep the JSON and its named wavefunction file together when copying a
calculation.
The documentation has three parts, each with its own purpose. The release workflow also publishes the user/reference handbook and physics manual as versioned PDFs; see PDF editions and local builds.
- User and developer manual: how to run, check, save and extend calculations. Its pages are
the Markdown files listed below; they can be read on GitHub or built into a website with
python -m pip install '.[dmrg,docs]'andpython -m sphinx -c docs -b html . build/docs. The separate PDF uses the same canonical guide and reference sources, with complete calculation workflows and selected convergence evidence. - Physics manual (LaTeX, PDF): the models, equations, methods and physical interpretation, with worked examples.
- Tutorials: runnable, checked calculations that accompany the physics manual.
- Installation and a first checked calculation
- Static states, observables and transitions
- Parameter scans and reproducible saved results
- DMRG refinement and custom models
- Tutorial 00: the first calculation with inputs and reference outputs
- Models, units, sectors, and observables
- Python functions, input files, and saved results
- Floquet calculations, matrix elements, and spectra
- Bath representations: parameters, convergence, and precision/time benchmarks
- Padé chain-expansion reservoirs
- Numerical methods and convergence, including a worked parity, excitation, and current calculation
- QP-cutoff convergence: energy, local moment, charge probabilities, and dot–lead spin correlation
- Troubleshooting
- Model/drive constructors, JSON configuration and saved records and artifacts
- API, options, results, command line, observables and probes, conventions and from the equations to the code
- Citation and method references
- Research applications and literature reproductions
- Large-hybridization study: 2QP, 4QP, 6QP and DMRG through Gamma/Delta = 10
- NRG comparison results and test1 results
- Contributing, architecture and extension guide and documentation policy
- Validation and development
- Release guide for maintainers and developers
Before opening a GitHub issue,
consult the troubleshooting and issue-report checklist.
See CONTRIBUTING.md
for development setup and the test, style-check (ruff), and packaging commands used by
the continuous-integration (CI) checks on GitHub.
Reinstall after changing the native C++ implementation or build configuration.