superposition

Prepares sparse quantum superposition states using compact coefficient preparation and support permutation.

18|3|Updated Aug 14, 2026
One-click install
npx skills add https://github.com/unitarylab/quantum-practices --skill superposition-unitarylab
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: superposition
Source: https://github.com/unitarylab/quantum-practices/tree/main/algorithms/state-preparation/superposition
Command: npx skills add https://github.com/unitarylab/quantum-practices --skill superposition-unitarylab

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires numpy, unitarylab, unitarylab_algorithms, and includes scripts (resource) components.

What problem does it solve? Preparing a quantum state with only a few nonzero computational-basis amplitudes is wasteful with generic dense state initialization. This Skill explains, runs, debugs, and reimplements the UnitaryLab sparse Superposition state-preparation algorithm, which prepares coefficients on a compact index register and permutes prefix basis states onto the target support. ## Core Features & Use Cases - Sparse state preparation: Extracts support above a strict 1e-12 threshold, builds a QR-completed coefficient stage, and applies a prefix-to-support permutation forming the dense unitary P @ Uc. - Circuit decomposition: Emits a UnitaryLab Circuit using MCX/CX permutation gates with one non-overlapping work wire, plus dense-matrix validation with global-phase-invariant error. - Debugging and reimplementation guidance: Documents normalization-before-padding, MSB-first basis tuples, coefficient reordering, permutation orientation, and return-field contracts, with a minimal manual implementation. - Use Case: Given a target vector like [1, 0, 1j, 0]/sqrt(2) on 2 qubits, run SuperpositionAlgorithm to obtain the prepared state, support size of 2, and total error below 1e-6. ## Quick Start Ask the assistant to run the sparse superposition state preparation on a normalized sparse vector with a given number of target qubits and report the support size and total error.

Frequently Asked Questions about superposition

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I prepare a sparse superposition state in Python?

Import SuperpositionAlgorithm from unitarylab_algorithms and call run with your normalized vector Psi, target_qubits, and target_error. The result includes the prepared state, support size, index register qubits, and a status of ok when total error stays within tolerance.

How does sparse superposition state preparation work?

The algorithm extracts amplitudes above a strict 1e-12 threshold, prepares those coefficients on a compact index register via QR completion, then applies a permutation mapping prefix basis states onto the target support. The dense unitary is the product P @ Uc.

Why does superposition state preparation return failed status?

A failed status means total error exceeded max(target_error, 1e-10). This commonly happens when thresholding at 1e-12 discards nonzero amplitude weight, since the error is measured against the original normalized padded target and target_error cannot recover omitted amplitudes.

What are the limitations of the sparse superposition algorithm?

The implementation materializes dense 2^n by 2^n matrices, so sparse support does not reduce memory or gate complexity. The zero-qubit path fails during matrix composition, and the emitted circuit requires one extra non-overlapping work wire.

Can I use a state vector shorter than 2^target_qubits?

Yes, shorter vectors are trailing-zero padded to the full dimension with a RuntimeWarning after normalization. Vectors longer than 2^target_qubits raise a ValueError, and the norm must exceed 1e-12.