Metadata-Version: 2.4
Name: pennylane-metal
Version: 0.2.1
Summary: GPU-accelerated PennyLane simulator for Apple silicon, built on Metal 4
Keywords: pennylane,quantum,simulation,metal,gpu,apple-silicon
Author-Email: Derek Lei <leiderek12@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: GPU
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Physics
Project-URL: Homepage, https://github.com/dereklei12/pennylane-metal
Project-URL: Documentation, https://github.com/dereklei12/pennylane-metal#readme
Project-URL: Repository, https://github.com/dereklei12/pennylane-metal
Project-URL: Issues, https://github.com/dereklei12/pennylane-metal/issues
Requires-Python: >=3.10
Requires-Dist: pennylane>=0.42
Requires-Dist: numpy>=1.21
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-benchmark; extra == "dev"
Requires-Dist: pennylane-lightning>=0.42; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Description-Content-Type: text/markdown

# PennyLane Metal

<p align="center">
  <!-- CI (GitHub Actions) -->
  <a href="https://github.com/dereklei12/pennylane-metal/actions/workflows/ci.yml">
    <img src="https://img.shields.io/github/actions/workflow/status/dereklei12/pennylane-metal/ci.yml?branch=main&style=flat-square" />
  </a>
  <!-- PyPI -->
  <a href="https://pypi.org/project/pennylane-metal/">
    <img src="https://img.shields.io/pypi/v/pennylane-metal.svg?style=flat-square" />
  </a>
  <!-- Python versions -->
  <a href="https://pypi.org/project/pennylane-metal/">
    <img src="https://img.shields.io/pypi/pyversions/pennylane-metal.svg?logo=python&logoColor=white&style=flat-square" />
  </a>
  <!-- Platform -->
  <img src="https://img.shields.io/badge/platform-macOS_26%2B_arm64-lightgrey?logo=apple&style=flat-square" />
  <!-- License -->
  <a href="https://www.apache.org/licenses/LICENSE-2.0">
    <img src="https://img.shields.io/pypi/l/pennylane-metal.svg?logo=apache&style=flat-square" />
  </a>
</p>

PennyLane Metal is a [PennyLane](https://pennylane.ai) quantum simulator for
Apple silicon, built exclusively on Metal 4. It provides the `metal.qubit`
device, where state evolution, noise channels, measurements, sampling, and
adjoint gradients all run on the GPU.

- Pure circuits use a state vector; noisy circuits use a density-matrix
  execution model, selected automatically.
- Native Metal adjoint Jacobians and VJPs for the parameterized gate set.
- Broad native gate, measurement, and noise-channel coverage — see
  [supported operations](docs/SUPPORTED_OPERATIONS.md).
- Device-aware memory admission with a queryable resource planner — see
  [memory and resources](docs/RESOURCES.md).

## Requirements

- macOS 26.0 or newer on Apple silicon
- A Metal 4-capable Apple GPU (M1 or newer)
- Python 3.10–3.14

## Installation

```bash
pip install pennylane-metal
```

Binary wheels are published for macOS 26+ (arm64) and CPython 3.10–3.14.

Building from the sdist or a git checkout additionally requires Xcode 26 with
the Metal Toolchain component (`xcodebuild -downloadComponent MetalToolchain`)
and CMake 3.24+; then `pip install .`. See
[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for the full workflow.

## Quickstart

```python
import pennylane as qml

dev = qml.device("metal.qubit", wires=2)

@qml.qnode(dev)
def bell_state():
    qml.H(0)
    qml.CNOT([0, 1])
    return qml.probs(wires=[0, 1])

print(bell_state())  # [0.5, 0.0, 0.0, 0.5]
```

Gradients use the native Metal adjoint method:

```python
@qml.qnode(dev, diff_method="adjoint")
def expectation(angle):
    qml.RX(angle, 0)
    qml.CNOT([0, 1])
    return qml.expval(qml.Z(0))

angle = qml.numpy.array(0.37, requires_grad=True)
print(qml.grad(expectation)(angle))  # -sin(0.37)
```

## Performance

A 22-qubit, depth-10 RY/CNOT circuit with an analytic expectation value
(Apple M1 Max, macOS 26, pennylane-metal 0.2.0):

| Device            | Time per execution |
| ----------------- | ------------------ |
| `default.qubit`   | 5808 ms            |
| `lightning.qubit` | 973 ms             |
| `metal.qubit`     | **98 ms**          |

Each execution carries a fixed ~1 ms GPU dispatch cost, so CPU simulators
remain faster for very small circuits; the GPU advantage grows with qubit
count and depth. Reproduce with `benchmarks/benchmark_metal.py` — see
[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md#benchmarks).

## Capabilities and limits

| Area            | Summary                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------ |
| Gates           | Native one/two/multi-qubit set incl. excitation families, arbitrary unitaries              |
| Measurements    | State, probs, expval, var, purity, entropies (analytic); shots via Metal sampling          |
| Noise           | Standard channels plus arbitrary multi-wire Kraus maps, all on GPU                         |
| Gradients       | Native adjoint/VJP (pure states); parameter-shift for noisy circuits                       |
| Precision       | `complex64`; capacity is device-memory-bound (`2**n` state vector, `4**n` density matrix)  |
| Not supported   | Mid-circuit measurements, reset, postselection, classical conditionals                     |

Full details: [docs/SUPPORTED_OPERATIONS.md](docs/SUPPORTED_OPERATIONS.md) and
[docs/RESOURCES.md](docs/RESOURCES.md).

## Documentation

- [Supported operations](docs/SUPPORTED_OPERATIONS.md) — gates, measurements,
  channels, differentiation, batching
- [Memory and resources](docs/RESOURCES.md) — memory budgets, capacity
  queries, resource estimation
- [Architecture](docs/ARCHITECTURE.md) — layer ownership and data-flow rules
- [Development](docs/DEVELOPMENT.md) — building, testing, benchmarks,
  releasing

## Development

```bash
python -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
```

See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for CMake iteration builds,
Metal API validation runs, and the release process.

## License

[Apache 2.0](LICENSE)
