necstar.state

Classes

QuantumState

Represents a simulated quantum state using the stabilizer decomposition method.

Module Contents

class necstar.state.QuantumState

Represents a simulated quantum state using the stabilizer decomposition method.

property num_qubits: int: The number of qubits in the quantum state.

property stabilizer_rank: int: The stabilizer rank χ (number of stabilizer states in the decomposition).

static from_circuit(circuit: necstar.circuit.QuantumCircuit) → QuantumState

Creates a new QuantumState by compiling a QuantumCircuit.

Parameters:

circuit (QuantumCircuit) – The quantum circuit to be simulated.

Returns:

The compiled quantum state ready for simulation.

Return type:

QuantumState

Raises:

ValueError – If the circuit compilation fails (e.g., contains unsupported
gates). –

to_statevector() → List[complex]

Returns the statevector as a list of complex number tuples (real, imag).

Note

This function computes the full, dense statevector of size \(2^n\), which can be computationally expensive and memory-intensive for a large number of qubits (\(n\)). It is primarily intended for testing and debugging. The indexing follows the little-endian convention (like Qiskit).

Returns:: The statevector represented as a list of complex numbers.
Return type:: List[complex]
Raises:: ValueError – If the statevector calculation fails (e.g., too many qubits).

inner_product(other: QuantumState) → complex

Computes the inner product <self|other> between this state and another.

Parameters:: other (QuantumState) – The other quantum state. Must have the same number of qubits.
Returns:: The inner product value as a complex number.
Return type:: complex
Raises:: ValueError – If the inner product calculation fails (e.g., qubit count mismatch).

measure(qargs: List[int], seed: int | None = None) → List[bool]

Measures the specified qubits in the computational basis. The state collapses according to the measurement results.

Parameters:

qargs (List[int]) – A list of qubit indices to measure.
seed (Optional[int]) – An optional seed for the random number generator to ensure reproducibility. Defaults to None.

Returns:

A list of boolean measurement outcomes (False for \(|0\rangle\), True for \(|1\rangle\)).

Return type:

List[bool]

Raises:

ValueError – If measurement fails (e.g., invalid qubit index).

measure_all(seed: int | None = None) → List[bool]

Measures all qubits in the computational basis.

The state collapses according to the measurement results.

Parameters:

seed (Optional[int]) – An optional seed for the random number generator
None. (to ensure reproducibility. Defaults to)

Returns:

A list of boolean measurement outcomes for all qubits.

Return type:

List[bool]

Raises:

ValueError – If measurement fails.

sample(qargs: List[int], shots: int, seed: int | None = None) → Dict[str, int]

Samples measurement outcomes for the specified qubits without collapsing the state.

This method efficiently gathers measurement statistics without modifying the internal state, making it suitable for repeated analysis. It uses a recursive approach with binomial sampling for efficiency with large shot counts.

Parameters:

qargs (List[int]) – A list of qubit indices to sample.
shots (int) – The number of measurement samples to generate.
seed (Optional[int]) – An optional seed for the random number generator for reproducibility. Defaults to None.

Returns:

A dictionary mapping outcome bitstrings (e.g., “010”) to the number of times that outcome was observed.

Return type:

Dict[str, int]

Raises:

ValueError – If sampling fails (e.g., invalid qubit index).

exp_value(pauli_string: necstar.pauli_string.PauliString) → float

Calculates the expectation value of a given Pauli observable.

Parameters:: pauli_string (PauliString) – The Pauli string representing the observable.
Returns:: The expectation value \(\langle\psi|P|\psi\rangle\), where P is the Pauli operator.
Return type:: float
Raises:: ValueError – If the Pauli string is invalid or the calculation fails.

project_normalized(qubit: int, outcome: bool) → None

Projects the state onto a computational basis state for a specific qubit and normalizes.

This is equivalent to a projective measurement in the Z-basis. The state is modified in place.

Parameters:

qubit (int) – The index of the qubit to project.
outcome (bool) – The desired basis state (False for \(|0\rangle\), True for \(|1\rangle\)).

Raises:

ValueError – If the projection is impossible (e.g., projecting \(|0\rangle\) onto \(|1\rangle\)).

project_unnormalized(qubit: int, outcome: bool) → None

Projects the state onto a computational basis state without normalizing.

The state is modified in place. The total norm after this operation may not be 1. Useful for intermediate steps in algorithms like sampling.

Parameters:

qubit (int) – The index of the qubit to project.
outcome (bool) – The desired basis state (False for \(|0\rangle\), True for \(|1\rangle\)).

Raises:

ValueError – If the projection operation encounters an internal error, though it won’t raise an error for impossible projections resulting in a zero-norm state.

discard(qubit: int) → None

Discards a qubit from the quantum state by tracing it out.

Reduces the total number of qubits by one and modifies the state in place.

### Important: This function MUST only be called on a qubit that has been projected to the \(|0\rangle\) state and is disentangled from all others. Failure to meet this precondition will lead to incorrect results. No verification is performed for performance reasons. Use project_normalized(qubit, False) first if needed.

Parameters:: qubit (int) – The index of the qubit to discard.
Raises:: ValueError – If the qubit index is out of bounds or an internal error occurs.

apply_gate(gate: necstar.gate.QuantumGate) → None

Applies a QuantumGate directly to the quantum state.

Note

Only Clifford gates are supported for direct application. Attempting to apply non-Clifford gates (e.g., T or T-dagger) will raise an error.

Parameters:: gate (QuantumGate) – The quantum gate to apply.
Raises:: ValueError – If the gate application fails (e.g., unsupported gate).

apply_gates(gates: List[necstar.gate.QuantumGate]) → None

Applies a list of QuantumGate s directly to the quantum state.

### Note: Only Clifford gates are supported for direct application. Attempting to apply non-Clifford gates (e.g., T or T-dagger) will raise an error.

Parameters:: gates (List[QuantumGate]) – The list of quantum gates to apply in sequence.
Raises:: ValueError – If any gate application fails (e.g., unsupported gate).

apply_x(qubit: int) → None

Applies a Pauli-X gate directly to the state.

Parameters:: qubit (int) – The target qubit index.
Raises:: ValueError – If the gate application fails (e.g., invalid index).

apply_y(qubit: int) → None

Applies a Pauli-Y gate directly to the state.

Parameters:: qubit (int) – The target qubit index.
Raises:: ValueError – If the gate application fails.

apply_z(qubit: int) → None

Applies a Pauli-Z gate directly to the state.

Parameters:: qubit (int) – The target qubit index.
Raises:: ValueError – If the gate application fails.

apply_h(qubit: int) → None

Applies a Hadamard gate directly to the state.

Parameters:: qubit (int) – The target qubit index.
Raises:: ValueError – If the gate application fails.

apply_s(qubit: int) → None

Applies an S gate directly to the state.

Parameters:: qubit (int) – The target qubit index.
Raises:: ValueError – If the gate application fails.

apply_sdg(qubit: int) → None

Applies an S-dagger gate directly to the state.

Parameters:: qubit (int) – The target qubit index.
Raises:: ValueError – If the gate application fails.

apply_sqrt_x(qubit: int) → None

Applies a Sqrt(X) gate directly to the state.

Parameters:: qubit (int) – The target qubit index.
Raises:: ValueError – If the gate application fails.

apply_sqrt_xdg(qubit: int) → None

Applies a Sqrt(X)-dagger gate directly to the state.

Parameters:: qubit (int) – The target qubit index.
Raises:: ValueError – If the gate application fails.

apply_cx(control: int, target: int) → None

Applies a CNOT (CX) gate directly to the state.

Parameters:

control (int) – The control qubit index.
target (int) – The target qubit index.

Raises:

ValueError – If the gate application fails.

apply_cz(qarg1: int, qarg2: int) → None

Applies a CZ gate directly to the state.

Parameters:

qarg1 (int) – The index of the first qubit.
qarg2 (int) – The index of the second qubit.

Raises:

ValueError – If the gate application fails.

apply_swap(qarg1: int, qarg2: int) → None

Applies a SWAP gate directly to the state.

Parameters:

qarg1 (int) – The index of the first qubit.
qarg2 (int) – The index of the second qubit.

Raises:

ValueError – If the gate application fails.

norm() → float

Calculates the norm (magnitude) of the quantum state.

For a valid, normalized state, this should be close to 1.0.

Returns:: The norm of the state.
Return type:: float
Raises:: ValueError – If the norm calculation fails.

__str__() → str: Returns a string representation of the quantum state summary.