state-preparation

State-preparation method selection depends on target structure: explicit method requests are honored first, supplied MPS tensors route to MPS preparation, sparse computational-basis support routes to Superposition, and a general complex target with no special structure defaults to Möttönen. Work-qubit budget, exactness requirements, and whether variational optimization is acceptable also decide between candidates.

Möttönen uses uniformly controlled RY/RZ ladders with a reflected Gray-code schedule, while multiplexer preparation builds a recursive binary probability tree with RY/CRY/MCRY gates plus basis-selective phase loading. They are not interchangeable merely because both use controlled rotations; each has its own gate schedule and wire-order contract.

MPS preparation fits when the target has low-entanglement structure or supplied MPS tensors with a known bond dimension, since it can reduce preparation cost using work qubits. Low entanglement alone is not a guarantee; compare actual bond dimension, work-wire availability, and allowed truncation error against the deterministic Möttönen route.

No, Pauli-word preparation is a variational method that fits a fixed ansatz by optimizing infidelity with deterministic L-BFGS-B restarts. A valid run can return status "failed" when the ansatz or optimizer does not reach the target error, so it is not the default exact deterministic route.

Although result validators may accept zero, the current UnitaryLab Circuit(0) constructor rejects zero qubits, so the supported public contract requires target_qubits >= 1. The target vector must also be non-empty, finite, nonzero in norm, and no longer than 2**target_qubits.

Each method reports distinct metrics: Möttönen and Multiplexer report phase-invariant state error, MPS separates zero-work projection error, work leakage, and bond truncation, and Pauli optimizes infidelity but reports phase-aligned L2 error. Global-phase comparison uses only a unit-modulus alignment factor from the state overlap.