qSSL/README.md

# Quantum Self-Supervised Learning (qSSL)

This directory gathers the pretrained checkpoints produced while reproducing “Quantum Self-Supervised Learning” (Jaderberg et al., 2021) — https://arxiv.org/abs/2103.14653.  
Each backend (photonic MerLin, Qiskit gate-based, and the classical MLP baseline) lives in its own subfolder and contains the per-epoch `.pth` weights, the resolved training arguments (`args.json`), and the saved metrics for the corresponding run timestamp.

## Where to fetch the weights
- Hugging Face repository: `Quandela/ReproducedPapersQML`
- Layout on the Hub: `qSSL/<backend>/<timestamp>/...`
  - Example: `qSSL/merlin/20250827_181840/model-cl-5-epoch-5.pth`
  - The Qiskit checkpoints were obtained with the authors’ original gate-model workflow from https://arxiv.org/abs/2103.14653.

You can inspect the latest timestamps and files directly on the Hub page or by calling the Hub API.

## Loading a checkpoint in Python

Install the tooling (if not already available):

```bash
pip install huggingface_hub torch
```

Download the artifacts for a given run and load the state dictionary:

```python
from argparse import Namespace
from pathlib import Path
import json
import torch
from huggingface_hub import snapshot_download

run_id = "qSSL/merlin/20250827_181840"
local_root = Path(
    snapshot_download(
        repo_id="Quandela/ReproducedPapersQML",
        repo_type="model",
        allow_patterns=[f"{run_id}/*"],
    )
)

args_path = local_root / run_id / "args.json"
state_path = local_root / run_id / "model-cl-5-epoch-5.pth"

args = Namespace(**json.loads(args_path.read_text()))
state_dict = torch.load(state_path, map_location="cpu")
```

Rebuild the PyTorch model before loading the weights. If you are using the reproduction codebase (see below), instantiate the `QSSL` model with the `args` namespace and load the weights:

```python
import sys

repo_root = Path("/path/to/reproduced_papers")  # adjust to your clone
sys.path.append(str(repo_root / "qSSL"))

from lib.model import QSSL

model = QSSL(args)
model.load_state_dict(state_dict)
model.eval()
```

- For MerLin runs you will need `merlin` and `perceval`.
- For Qiskit runs install the dependencies from the paper’s reference implementation (`qiskit`, `qiskit-aer`, etc.). These checkpoints were generated with the same circuit and training recipe as the authors’ code: https://arxiv.org/abs/2103.14653.

## More background

You can find a full description of the experiments, configuration options, and evaluation protocol in `reproduced_papers/qSSL/README.md` of the main reproduction repository (`fork_reproduced_papers`). It documents dataset preparation, training/linear-probing scripts, and the differences between the MerLin, Qiskit, and classical variants.