compile_state

GateCompiler.compile_state(target_state, initial_state=None)

Compile the circuit preparing a state on the device.

A preparation asks less than a unitary: the circuit has to act correctly on the one state the experiment starts from, not on every basis state. The backend searches in that smaller space, so a preparation reaches register widths a unitary of the same circuit does not.

Runs under AdaptiveConfig and ErrorAwareAdaptiveConfig. Under the second the circuit carries its error-aware diagnostics on metadata["error_aware"], and the search stops where the compilation and physical errors are smallest together rather than at tolerance_error.

Parameters:

  • target_state (Any) – State to prepare, as a Statevector or an amplitude array.

  • initial_state (Any) – State the register starts in, as a basis-state index or a Statevector. None means the all-zero state. A device starting elsewhere is brought to it by a leading rotation on each excited qubit.

Return type:

QuantumCircuit

Returns:

Native circuit preparing target_state from initial_state.

Raises:

  • ConfigError – If the configuration has no state-preparation path.

  • ValidationError – If a state’s width does not match the gate set, its norm is not 1, or initial_state is not a basis state.