Metadata-Version: 2.4
Name: TorQ-bench
Version: 0.1.3
Summary: Tensor Operations for Research in Quantum systems - Benchmarking.
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torq-quantum>=0.1.3
Provides-Extra: pennylane
Requires-Dist: pennylane>=0.31; extra == "pennylane"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# TorQ-bench

Benchmarks and PennyLane comparisons for TorQ.

TorQ-bench is a small companion package that lets you run the same layer logic in
TorQ and PennyLane to compare outputs and timing. It intentionally keeps PennyLane
out of the core TorQ package.

Developed while writing the paper:
Quantum Physics-Informed Neural Networks for Maxwell’s Equations: Circuit Design, “Black Hole” Barren Plateaus Mitigation, and GPU Acceleration

by Ziv Chen, Gal G. Shaviner, Hemanth Chandravamsi, Shimon Pisnoy, Steven H. Frankel, Uzi Pereg

https://arxiv.org/abs/2506.23246

For the simpler version associated with the following paper, please use the simple_for_PINNACLE branch:
PINNACLE: An Open-Source Computational Framework for Classical and Quantum PINNs

by Shimon Pisnoy, Hemanth Chandravamsi, Ziv Chen, Aaron Goldgewert, Gal Shaviner, Boris Shragner, Steven H. Frankel

https://arxiv.org/abs/2604.15645

It is compatible with TorQ simple_for_PINNACLE branch and PINNACLE repos. Also, the simple_for_PINNACLE branch is the same as torq-bench v0.1.2 on PyPI.

## Install

From source (recommended while developing):

```bash
pip install -e .[pennylane]
```

Or from PyPI:

```bash
pip install torq-bench[pennylane]
```

TorQ-bench depends on `torq-quantum>=0.1.3`. PennyLane is optional and only required for
the comparison wrappers.

Note: the PyPI distribution is `torq-quantum`, while the Python import package remains `torq`.

## Quickstart: compare TorQ vs PennyLane

```python
import torch
from torq.QLayer import QLayer
from torq_bench import PennyLaneQLayer

n_qubits = 4
n_layers = 2
x = torch.rand(8, n_qubits)

torq_layer = QLayer(n_qubits=n_qubits, n_layers=n_layers)
pl_layer = PennyLaneQLayer(
    n_qubits=n_qubits,
    n_layers=n_layers,
    pennylane_dev_name="default.qubit",
)

y_torq = torq_layer(x)
y_pl = pl_layer(x)
```

Notes:
- `PennyLaneQLayer` supports TorQ ansatz names:
  `basic_entangling`, `single_rot_basic_ent`, `strongly_entangling`,
  `cross_mesh`, `cross_mesh_2_rots`, `cross_mesh_cx_rot`, `tile`,
  and `no_entanglement_ansatz`.
- `data_reupload_every` is supported.
- Config-driven ansatz options are forwarded to PennyLane:
  `single_rot_basic_ent` uses `single_rotation_gate`, and `tile` uses
  `tile_rotation_params`, `single_rotation_gate`, `tile_sublayers`, and
  `tile_cyclic`. The `tile_cyclic` wrap-around CNOT is applied only when
  `n_qubits > 2` and even, matching TorQ.
- Output observables follow TorQ's current `config.observables` API:
  `None` for per-qubit `Z`, Pauli strings like `"X"` or `"XI_ZZ"`, or
  Hermitian matrices with shape `[2,2]`, `[n_qubits,2,2]`, `[2**n,2**n]`,
  or `[m,2**n,2**n]`.

## Using PennyLaneComparison directly

```python
import torch
from torq_bench import PennyLaneComparison

n_qubits = 4
n_layers = 2
weights = torch.rand(n_layers, 1, n_qubits, 3)  # current TorQ no-data layout
x = torch.rand(n_qubits)

qc = PennyLaneComparison(n_qubits=n_qubits, n_layers=n_layers, weights=weights)
circuit = qc.circuit_strongly_entangling()
state = circuit(x)
```

`PennyLaneComparison` also accepts the older no-data shape `[n_layers, *per_layer_shape]`
for backward compatibility.

## Run the built-in demo

The comparison module includes a demo that builds and draws the supported TorQ
ansatzes, including `single_rot_basic_ent` and `tile` variants. It uses
`qml.draw_mpl`, so you will need `matplotlib` installed.

```bash
python -m torq_bench.PennyLaneComparison
```

## License

MIT
