MerLin brings quantum computing capabilities to AI practitioners through easy-to-use PyTorch integrations. Named after the legendary wizard, MerLin adds quantum wizardry to your AI toolkit with no quantum expertise required.
Built for AI/ML practitioners: MerLin is designed to feel familiar to PyTorch users while unlocking the potential of quantum computing. Under the hood, it leverages photonic quantum computing - a cutting-edge approach using single-photons that's hardware-aware and prepares your models for real quantum processors.
Simulation-first with hardware bridges: Optimized for classical simulation today, with connections to currently available photonic QPUs and pathways to next-generation quantum hardware.
Key Goals:
- Paper Reproduction: Simple tools to reproduce published quantum ML papers and benchmark algorithms - see our reproduced papers list.
- Quantum Architecture Bridge: Access to latest and next-gen quantum photonic architectures as a bridge between AI and quantum worlds - see our quantum architectures.
- GPU-Optimized Performance: Fast simulation scaling up to 500+ mode chips with 10-20 photons near the simulability threshold - see performance benchmarks.
Together, these provide researchers with comprehensive tools for exploring and developing new quantum-classical hybrid algorithms.
Why Quantum Layers? Enable non-conventional operations in hybrid workflows that can help classical ML models improve performance, learn faster, or use fewer parameters.
Advanced users can leverage the underlying Perceval framework for custom models or advanced functionality.
- AI/ML Practitioners: Add quantum layers to existing PyTorch models
- Quantum Researchers: Experiment with photonic quantum computing
- Enterprise Teams: Build future-proof quantum-AI applications
Production installation:
pip install merlinquantumDevelopment (includes tests, benchmarks, lint & mypy):
git clone https://github.com/merlinquantum/merlin.git
cd merlin
pip install -e '.[dev]'Examples environment (notebooks & plots):
pip install -e '.[examples]'Build documentation locally:
pip install -e '.[docs]'
cd docs
make html # or: make livehtml (if sphinx-autobuild added manually)Run the full test suite (excluding tests on remote platform):
pytest -qCloud (remote) tests:
- For most contributions, it's fine to run the suite as-is; tests that require a cloud token are skipped by default.
- If your development involves tests that run against a remote platform (Quandela Cloud or another Perceval provider), please:
- Have an active account on https://cloud.quandela.com (or the other supported Perceval provider), and
- Configure Perceval remote access by following the official guide: https://perceval.quandela.net/docs/reference/runtime/remote_config.html#remoteconfig
To run tests that require a cloud token, enable them with:
pytest -q --run-cloud-tests -r s tests/core/cloudNotes:
- Without
--run-cloud-tests, only the token-requiring tests are skipped; other cloud-related tests still run. - If you pass
--run-cloud-testsbut no token is configured, those tests will still be skipped at runtime with a clear reason. - Use
-r s(or-r a) to display skip reasons.
Run only benchmarks (pytest-benchmark):
pytest --benchmark-onlyCompare two branches (example):
pytest tests/test_sampling.py --benchmark-save current
# ... switch branch ...
pytest tests/test_sampling.py --benchmark-compare currentQuick quality checks:
ruff check .
ruff format --check .
mypy merlinTip: run pytest -k <keyword> to target a subset.
The following shows how to create a very simple quantum layer using MerLin's high-level API. This layer can be integrated into any PyTorch model, and supports usual PyTorch operations like training and inference.
import merlin as ML # Package: merlinquantum, import: merlin
import torch
# Create a simple quantum layer
quantum_layer = ML.QuantumLayer.simple(
input_size=3,
)
# Use it like any PyTorch layer
x = torch.rand(10, 3)
output = quantum_layer(x)
print(f"Input shape: {x.shape}, Output shape: {output.shape}")Under the hood, this simple interface wraps complex photonic quantum operations — including architecture selection, ansatz design, input encoding, and photon number configuration. Learn more in our User Guide.
- Examples: Check the
examples/directory for tutorials - Notebooks: Explore
docs/source/notebooks/for interactive examples
-
v0.1: Initial release with core features
-
In development:
- More circuit types and ansatz configurations
- Improved documentation and examples
- Integration with Quandela's photonic hardware
- additional machine learning models
We welcome contributions! Here's how to get started:
- Fork the repository
- Create a feature branch:
git checkout -b feature-name - Test your changes:
pytest tests/ - Submit a pull request
See our Contributing Guide for detailed guidelines.
MIT License - see LICENSE for details.
- Issues: GitHub Issues
- Discussions: GitHub Discussions
MerLin uses automated test coverage tracking to maintain code quality:
Coverage Reports:
- 🎯 Target Coverage: 80% (warning threshold)
- 📊 Reports Generated: On every PR and commit
- 🚫 Non-blocking: Coverage checks don't prevent merges
- 📈 Diff Coverage: Shows coverage for changed files only
Running Coverage Locally:
# Quick coverage check
pytest tests/ --cov=merlin --cov-report=term | grep TOTAL
# Detailed coverage with missing lines
pytest tests/ --cov=merlin --cov-report=term-missing
# Generate HTML report
pytest tests/ --cov=merlin --cov-report=html
# Then open htmlcov/index.html in browser
# Test specific module
pytest tests/test_layer.py --cov=merlin.core --cov-report=termCoverage Configuration:
- Exclusions: Tests, migrations, virtual environments
- Formats: Terminal, HTML, XML reports
- Thresholds: 80% target (informational only)
Coverage data is automatically collected and reported in PRs without blocking development workflow.
⚡ Ready to add quantum power to your AI models? Get started with MerLin! ⚡
