PyTorch Autograd Engine & QuantumLayer Interface for QML

[Rao-Adarsh]

This PR introduces native PyTorch integration, it uses the torch.autograd.Function to implement the Paramater Shift Rule, allowing users to optimize parameterized quantum circuits using standard PyTorch optimizers (like Adam or SGD).

ParameterShiftFunction: A custom PyTorch autograd engine. Because the parameter-shift rule requires $2N$ independent circuit evaluations, this function utilizes concurrent.futures.ThreadPoolExecutor to evaluate the forward and backward shifted circuits concurrently.

QuantumLayer (torch.nn.Module): A high-level wrapper:
1. Dynamically binds PyTorch weight tensors to the IntermediateCircuitRepresentation (ICR).
2. Hardware-Ready: Natively computes exact mathematical expectation values via the QpiAI-QSV-Local simulator. If a user sets device_name to real hardware, it automatically falls back to an empirical counts-based measurement logic.

Verification Tests: Added comprehensive tests in test_torch_interface.py verifying the computed parameter-shift gradients against exact analytical gradients and PyTorch's native gradcheck.

Usage example:

import torch
from qpiai_quantum.circuit import Circuit
from qpiai_quantum.interfaces.torch_integration import QuantumLayer

# 1. Define a parameterized QpiAI Circuit
circuit = Circuit(1)
circuit.rx(0, 0.0)  # Parametric gate (parameter bound dynamically)

# 2. Define observables (e.g., measure Pauli-Z on Qubit 0)
observables = [(0, 'Z')]

# 3. Create the PyTorch Quantum Layer (can run on local simulator or real hardware)
q_layer = QuantumLayer(circuit, observables, num_params=1, device_name="QpiAI-QSV-Local")

# 4. Forward pass & backpropagation
expectation = q_layer()
expectation.backward()

# Gradients are computed exactly via the parameter-shift rule!
print(q_layer.q_params.grad) 

Future Prospects ?:
Currently, parameter binding and parameter batching are managed at the Python wrapper layer (QuantumLayer dynamically rebuilds the circuit for each shift).
The parameter-shift rule requires you to run $2N$ different circuits (because you are shifting the parameters forward and backward $N$ times). Currently, circuit.run() only accepts one circuit configuration at a time. It cannot accept a 2D matrix containing $2N$ different parameter vectors. Because of this limitation, the torch_integration.py uses Python's concurrent.futures to spawn $2N$ separate Python threads. If the core SDK is updated such that you could pass the circuit to the simulator exactly once, along with a 2D matrix of all $2N$ parameter shifts and everything is done using Numba/ C++ instead of python by the StatevectorSimulator, it could decrease the runtimes.

Disclaimer: This PR has been developed with generous use of Generative AI.