Metadata-Version: 2.4
Name: merlinquantum
Version: 0.4.0
Summary: Quantum neural network models using photonic circuits - Preview
Author: MerLin Team
Author-email: MerLin <MerLin@quandela.com>
License-Expression: MIT
Project-URL: homepage, https://merlinquantum.ai
Project-URL: documentation, https://merlinquantum.ai
Project-URL: source, https://github.com/merlinquantum/merlin
Project-URL: issues, https://github.com/merlinquantum/merlin/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch<2.13,>=2.0.0
Requires-Dist: perceval-quandela>=1.2.1
Requires-Dist: numpy>=2.2.6
Requires-Dist: pandas
Requires-Dist: scikit-learn<1.10,>=1.7.2
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx<7.0.0,>=6.2.1; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.0.0; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex>=2.5.0; extra == "docs"
Requires-Dist: renku-sphinx-theme; extra == "docs"
Requires-Dist: enum-tools[sphinx]; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: nbformat; extra == "docs"
Requires-Dist: ipython; extra == "docs"
Requires-Dist: ipykernel; extra == "docs"
Requires-Dist: gitpython; extra == "docs"
Requires-Dist: python-dotenv; extra == "docs"
Requires-Dist: jinja2==3.0.0; extra == "docs"
Requires-Dist: scikit-learn>=1.7.0; extra == "docs"
Provides-Extra: examples
Requires-Dist: matplotlib>=3.5.0; extra == "examples"
Requires-Dist: scikit-learn>=1.7.0; extra == "examples"
Requires-Dist: jupyter>=1.0.0; extra == "examples"
Dynamic: license-file

# MerLin - Photonic Quantum Machine Learning Framework

![Tests](https://img.shields.io/github/actions/workflow/status/merlinquantum/merlin/ci.yml?branch=main&style=flat-square&logo=github&label=tests)
[![Coverage](https://img.shields.io/github/actions/workflow/status/merlinquantum/merlin/coverage.yml?branch=main&event=pull_request&style=flat-square&logo=github&label=coverage)](https://github.com/merlinquantum/merlin/actions/workflows/coverage.yml)
[![PyPI](https://img.shields.io/pypi/v/merlinquantum?style=flat-square&logo=pypi&label=PyPI)](https://pypi.org/project/merlinquantum/)
[![Docs](https://img.shields.io/badge/docs-merlinquantum.ai-0A7BBB?style=flat-square&logo=readthedocs)](https://merlinquantum.ai)
[![License](https://img.shields.io/github/license/merlinquantum/merlin?style=flat-square&label=license)](https://github.com/merlinquantum/merlin/blob/main/LICENSE)
[![arXiv](https://img.shields.io/badge/arXiv-2602.11092-B31B1B?style=flat-square)](https://arxiv.org/abs/2602.11092)

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](https://merlinquantum.ai/reproduced_papers/index.html) 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](https://merlinquantum.ai/quantum_expert_area/architectures.html).
- **GPU-Optimized Performance**: Fast simulation scaling up to 500+ mode chips with 10-20 photons near the simulability threshold - see [performance benchmarks](https://merlinquantum.ai/performance/index.html).

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](https://perceval.quandela.net) framework for custom models or advanced functionality.

## Who Should Use MerLin?

- **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

## Installation

Production installation:
```bash
pip install merlinquantum
```

Development (includes tests, benchmarks, lint & mypy):
```bash
git clone https://github.com/merlinquantum/merlin.git
cd merlin
pip install -e '.[dev]'
```

Examples environment (notebooks & plots):
```bash
pip install -e '.[examples]'
```

Build documentation locally:
```bash
pip install -r requirements-docs.txt
cd docs
make html  # or: make livehtml (if sphinx-autobuild added manually)
```

### Tests & Benchmarks

Run the full test suite (excluding tests on remote platform):
```bash
pytest -q
```

Cloud (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:
  1) Have an active account on https://cloud.quandela.com (or the other supported Perceval provider), and
  2) 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:
```bash
pytest -q --run-cloud-tests -r s tests/core/cloud
```

Notes:
- Without `--run-cloud-tests`, only the token-requiring tests are skipped; other cloud-related tests still run.
- If you pass `--run-cloud-tests` but 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):
```bash
pytest --benchmark-only
```

Compare two branches (example):
```bash
pytest tests/test_sampling.py --benchmark-save current
# ... switch branch ...
pytest tests/test_sampling.py --benchmark-compare current
```

Quick quality checks:
```bash
ruff check .
ruff format --check .
mypy merlin
```

Tip: run `pytest -k <keyword>` to target a subset.

## Hello Quantum World!

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.

``` python
import merlin as ML  # Package: merlinquantum, import: merlin
import torch

# Create a simple quantum layer
quantum_layer = ML.QuantumLayer.simple(
    input_size=3,
    output_size=2,
)
# 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](https://merlinquantum.ai/user_guide/index.html).

## Learn More

- **Examples**: Check our [examples page](https://merlinquantum.ai/examples/index.html) for tutorials and application examples
- **Notebooks**: Explore ``docs/source/notebooks/`` for interactive examples (also on our [examples page](https://merlinquantum.ai/examples/index.html)!)

## Cite MerLin

If you use MerLin in your research, please cite:

```bibtex
@article{notton2026merlin,
  title={MerLin: A Discovery Engine for Photonic and Hybrid Quantum Machine Learning},
  author={Notton, Cassandre and Stott, Benjamin and Schoeb, Philippe and Walsh, Anthony and Leboucher, Gr{\'e}goire and Espitalier, Vincent and Apostolou, Vassilis and Vigneux, Louis-F{\'e}lix and Salavrakos, Alexia and Senellart, Jean},
  journal={arXiv preprint arXiv:2602.11092},
  year={2026}
}
```

## Roadmap

- **Latest release (`0.3.2`)**: See the [release notes](https://github.com/merlinquantum/merlin/releases) for the full changelog.
- **MerLin 0.4 (in progress)**:
  - Built-in modules to make common algorithms easier to use
  - Differentiation support on the `MerlinProcessor`
  - Easier encoding-space specification
  - Photon indistinguishability support
  - Better sparsity handling in SLOS

## Contributing

We welcome contributions! Here's how to get started:

1. **Fork** the repository
2. **Create** a feature branch: ``git checkout -b feature-name``
3. **Test** your changes: ``pytest tests/``
4. **Submit** a pull request

See our [Contributing Guide](https://github.com/merlinquantum/merlin/blob/main/CONTRIBUTING.md) for detailed guidelines.

## License

MIT License - see [LICENSE](https://github.com/merlinquantum/merlin/blob/main/LICENSE) for details.

## Support

- **Issues**: [GitHub Issues](https://github.com/merlinquantum/merlin/issues)
- **Discussions**: [GitHub Discussions](https://github.com/merlinquantum/merlin/discussions)

## Test Coverage

MerLin uses automated test coverage tracking to maintain code quality:

**Coverage Reports:**
- 🎯 **Target Coverage:** 80% (informational only)
- 🔁 **Workflow Trigger:** Runs automatically on each pull request targeting `main`
- 💬 **PR Feedback:** Posts a coverage summary on pull requests opened from this repository
- 📦 **Artifacts:** Uploads an HTML coverage report for inspection
- 🚫 **No Hard Coverage Gate:** Coverage is reported, but the 80% target does not block merges

**Running Coverage Locally:**
```bash
# 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=term
```

**Coverage 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! ⚡**
