qthermo

Heat, work and efficiency for quantum machines, with the physics checked for you.

Tiny machines built from a few qubits can act as engines and refrigerators. Working out how much heat they move, and whether the model you used is even allowed by the laws of thermodynamics, usually means hand-writing hundreds of lines of simulation code for every paper. qthermo does that part. You describe the machine; it gives you the heat flows, the efficiency, and a warning when the model breaks physics.

pip install "qthermo[plot]"        # Python 3.10 or newer

Try it: reproduce a published result

Pick a paper and run it. Each one rebuilds the paper's setup from scratch and prints qthermo's numbers next to the paper's.

python -m qthermo                  # list the papers
python -m qthermo fridge           # run one
python -m qthermo all              # run all five (~15 s)

What "reproduced" means here: the first four papers state their result as a formula, and qthermo matches it to machine precision. For the last one, qthermo computes the exact answer independently and reproduces the paper's finding (which approximation fails, and where), not its plotted figure.

The same thing from Python, with a figure:

import qthermo as qt

r = qt.papers.local_vs_global(detuning=0.1)
print(r.report())
r.plot()

Each of the two textbook approximations fails somewhere: the global one for resonant oscillators at weak coupling (top, off by up to 25×), the local one for detuned oscillators (bottom, 10% off). The Redfield model is within 0.1% of exact in both.

Build your own machine

Describe the parts, how they are coupled, and which heat bath touches which part:

machine = qt.build_model(
    local_H=[qt.qubit_hamiltonian(1.0), qt.qubit_hamiltonian(0.6)],   # two qubits
    interactions={(0, 1): (0.3 * qt.sigma_x, qt.sigma_x)},            # coupled
    baths=[dict(name="hot", site=0, coupling=qt.sigma_x, T=2.0, gamma=0.1),
           dict(name="cold", site=1, coupling=qt.sigma_x, T=1.0, gamma=0.1)])

steady = machine.analyze()        # heat flow from every bath, efficiency, entropy
print(steady.report())
print(qt.audit(machine))          # does the model break any law of thermodynamics?
qt.plot_machine(steady)           # where the heat goes

Then, depending on what you need:

Every function is listed in the API reference, the guide walks through all of them with figures, and the tutorial notebook takes one research question from a Hamiltonian to publishable numbers.

Proof that it works

python -m qthermo.benchmarks      # 44 checks against published results, ~40 s

• 44 benchmarks, each comparing a computed number with a published or exact result, with the source named next to it.
• About 270 automated tests, run on every change, including randomised checks that the laws of thermodynamics hold for random machines.
• Agrees with QuTiP, the standard quantum simulation library, to 1e-16 for steady states and 1e-10 for time evolution.
• Every code example in this README and the guide is run automatically, so none of them can silently go stale.

The exact definitions behind every number are in docs/physics.md.

Limits

• Weak coupling to the environment by default (Markovian master equations); strong coupling only through the reaction-coordinate mapping.
• Up to about 8 qubits (a few hundred energy levels) on a laptop.
• The Redfield model gives steady states only, and is not guaranteed to stay physical at strong bath coupling.
• Simulation only: nothing here has been compared with experimental data yet.

Feedback and where this could go

qthermo is new and built by one person, and the most useful thing you can do is tell me where it falls short: a result it gets wrong, a paper it should reproduce, or a feature that would make it useful in your work. Please open an issue.

Directions under consideration:

• more reproduced papers, each graded against an exact or published result
• a multi-parameter optimiser ("find the settings that maximise cooling")
• stronger coupling to the environment (HEOM or TEMPO backends)
• presets for specific hardware (superconducting qubits, trapped ions)

Citing and license

If you use qthermo in research, please cite it using CITATION.cff. MIT license. Changes are listed in the changelog.