Tuning a run

An MPS simulation is an approximation you steer. The state is stored as a chain of tensors joined by bonds, and the width of those bonds is what a run pays for in memory and time. Every setting on this page is, in the end, about the same question: how much of the state do you keep, and how carefully do you choose what to drop.

There are three families of control, and they act at different points in a run.

Family	Settings	What it decides
How much you keep	bonddim, sv_cutoff, mpo_cutoff, entdim	The ceiling on the state's width, and the thresholds below which weight is discarded.
How the operator is applied	algorithm	How the simulator chooses which weight to drop when the ceiling binds.
How the problem is laid out	reorderqubits	Where the entanglement sits on the chain in the first place.

The order to reach for them

Start with the layout. Reordering changes nothing physical and costs one pass over the gate list, but on a circuit whose interacting qubits are numbered far apart it can lower the bond dimension the run needs at all. It is the only control here that can make a problem cheaper without making it less accurate.

Then set the ceiling. bonddim is the main dial. Raise it until the observable you care about stops moving; that sweep, not any single number the run reports, is what tells you the answer has converged.

Then pick the algorithm, if the ceiling binds. While the state fits under bonddim, every algorithm is exact and the choice is only about speed. Once it does not fit, weight has to be discarded, and the algorithms differ in how well they choose. That is the point at which the choice starts to matter.

Leave the cutoffs alone unless you have a reason. sv_cutoff and mpo_cutoff are already set well below where they normally bind. They are worth touching when you need tighter accuracy at a bonddim you are not saturating, or when you want to trade accuracy for speed deliberately.

How to tell which control is the one biting

Three symptoms, and what each points at.

The state sits at the ceiling. If the largest bond in use equals bonddim, truncation is happening on every application and accuracy is being paid away. Raise bonddim, improve the layout, or move to an algorithm that chooses its truncations more carefully.

import tensorweaver as tw

sim = tw.TwSimulator(bonddim=64)
state = sim.evolve(sim.zerostate(n), sim.compile(circuit))[0]
print(state.mps.max_used_bond_dim, "of", 64)

The state stays well below the ceiling. Raising bonddim buys nothing. If the result is still wrong, the limit is elsewhere: a cutoff, or a genuine bug.

The reported fidelity looks healthy but the answer moves. The fidelity accounts for discarded weight and nothing else. Treat it as a screen, not a certificate, and confirm with a bonddim sweep or a mirror circuit. See Reading the reported fidelity.

What none of these can fix

A circuit whose entanglement genuinely grows with depth will exceed any ceiling you can afford, on any setting. No layout hides all-to-all interaction, and no algorithm keeps weight that was never affordable to keep. When a bonddim sweep shows the observable still moving at the largest bonddim that fits in memory, the honest conclusion is that the circuit is beyond the method, not that the settings need more tuning.