PennyLane-Walrus Plugin

A custom PennyLane plugin for advanced simulation of continuous-variable (CV) quantum circuits using the The Walrus library. This plugin provides a suite of devices for gate-based circuit simulation, direct state preparation, and realistic hardware modeling.

Key Features

• Five Specialized Devices: A suite of simulators for different tasks, from simple forward-pass sampling to advanced, physically realistic modeling.
• State-Based Simulation: Directly inject and sample from quantum states defined by their covariance matrix, enabling powerful workflows for GBS.
• Realistic Hardware Modeling: Simulate experiments with both perfect photon number resolving (PNR) and realistic threshold detectors.
• Advanced Tutorials: Includes examples for non-Gaussian state preparation, analyzing information loss in detectors, and solving graph problems with GBS.

Available Devices

Device Name	Key Feature
walrus.simulator.v1	Foundational gate-based simulator for forward-pass sampling and probabilities.
walrus.differentiable	A gate-based device supporting PennyLane's built-in gradient methods.
walrus.advanced	Experimental JAX-native device for end-to-end differentiable hafnian optimization, bypassing traditional gate-based backpropagation.
walrus.simulator.v4	State-based simulator for injecting states via covariance matrix and sampling with PNR detectors.
walrus.threshold_simulator	The most advanced state-based device, modeling realistic threshold detectors.

Installation

This project and its dependencies can be installed using the provided configuration files. It is highly recommended to use a Conda environment. For more complete installation instructions and important notes about library versions, please see the Main Documentation.

# 1. Clone the repository
git clone https://github.com/Encisco/pennylane-walrus-plugin.git
cd pennylane-walrus-plugin

# 2. Create environment and install dependencies from files
conda env create -f environment.yml
conda activate pl-walrus
pip install -r requirements.txt

# 3. Install The Walrus from source (required for development version). This project requires a specific development version of The Walrus (v0.23.0-dev). Clone its repository and install it in editable mode:
git clone https://github.com/XanaduAI/thewalrus.git
cd thewalrus
pip install -e .
cd ..

# 4. Install the plugin itself
pip install -e .

Quick Start: Find the Densest Subgraph

A key application of this plugin is using Gaussian Boson Sampling (GBS) to solve graph theory problems. This example uses the state-based walrus.simulator.v4 to find the densest subgraph of a simple graph.

import pennylane as qml
import numpy as np
from thewalrus import quantum
from collections import Counter
from pennylane_walrus.features.operations import PrepareGaussianState

# 1. Define and encode the graph's adjacency matrix
adj_matrix = np.array([
    [0, 1, 1, 0, 0], 
    [1, 0, 1, 0, 0], 
    [1, 1, 0, 1, 1],
    [0, 0, 1, 0, 1], 
    [0, 0, 1, 1, 0]
])
cov = quantum.adj_to_qmat(adj_matrix, 0.7)
mu = np.zeros(10)

# 2. Set up the GBS simulation
dev = qml.device("walrus.simulator.v4", wires=5, shots=1000)

@qml.qnode(dev)
def find_subgraph():
    PrepareGaussianState(cov=cov, mu=mu, wires=range(5))
    return qml.sample()

# 3. Run and analyze the results
samples = find_subgraph()
# Find the most common sample among those with the most photons
high_photon_samples = [tuple(s) for s in samples if sum(s) >= 3]
most_common = Counter(high_photon_samples).most_common(1)[0][0]
subgraph_nodes = [i for i, n in enumerate(most_common) if n > 0]

print(f"The densest subgraph is composed of nodes: {subgraph_nodes}")

Expected Output

When you run this script, the simulator will generate 1000 samples. The code filters for "high-photon" events (where the total photon count $N \ge 3$) to identify the most frequent patterns, which correspond to the most connected parts of the graph.

You should see an output similar to this:

Result: The densest subgraph is composed of nodes: [0, 1, 2]

Note: Because GBS is a stochastic process, the specific nodes identified might vary slightly between runs. However, they will consistently represent a highly connected cluster within the graph.

Full Documentation

For a complete guide, including detailed tutorials, a full API reference, and a discussion of the different device capabilities, please see the Main Documentation.

License

This project is licensed under the Apache 2.0 License.