uniqc.simulator.torchquantum_simulator module#

TorchQuantum-based simulator with native PyTorch autograd.

This module provides a quantum circuit simulator backed by TorchQuantum, enabling differentiable statevector simulation where gradients flow through PyTorch autograd natively (no parameter-shift rule needed).

Unlike BaseSimulator subclasses that consume OriginIR/QASM strings, this simulator reads Circuit.opcode_list directly.

Note: TorchQuantum uses qubit-0-as-MSB convention (the first dimension in the state tensor is qubit 0). UnifiedQuantum uses qubit-0-as-LSB convention (standard in most quantum computing frameworks). This simulator handles the endianness conversion automatically.

class uniqc.simulator.torchquantum_simulator.TorchQuantumSimulator(n_wires=0, device='cpu')[source]#

Bases: object

TorchQuantum-based simulator with native PyTorch autograd.

Operates on Circuit.opcode_list directly (no string serialization). All operations are differentiable through PyTorch autograd.

The n_wires parameter is optional — if not set, it is auto-detected from the opcodes.

Parameters:
execute_opcodes(opcode_list, param_overrides=None, n_qubits=None, bsz=1)[source]#

Execute opcodes on a fresh QuantumDevice.

Parameters:

  • opcode_list (list[OpCode]) – Circuit.opcode_list.

  • param_overrides (dict[int, torch.Tensor] | None) – Map opcode index → torch.Tensor to inject differentiable parameters.

  • n_qubits (int | None) – Override number of qubits (auto-detected if None).

  • bsz (int) – Batch size for the QuantumDevice.

Returns:

The QuantumDevice after executing all gates.

Return type:

tq.QuantumDevice

expectation(opcode_list, hamiltonian, param_overrides=None, n_qubits=None)[source]#

Compute <psi|H|psi> for a Pauli Hamiltonian.

Parameters:

  • opcode_list (list[OpCode]) – Circuit.opcode_list.

  • hamiltonian (list[tuple[str, float]]) – List of (pauli_string, coefficient).

  • param_overrides (dict[int, torch.Tensor] | None) – Differentiable parameter injection.

  • n_qubits (int | None) – Override number of qubits.

Returns:

Scalar tensor with the expectation value (differentiable).

Return type:

torch.Tensor

simulate_statevector(opcode_list, param_overrides=None, n_qubits=None)[source]#

Execute circuit and return statevector (LSB convention).

Returns:

Complex tensor of shape (2^n_qubits,) with the final statevector.

Parameters:
Return type:

torch.Tensor