Metadata-Version: 2.4
Name: c2q-framework
Version: 0.1.2
Summary: C2|Q: Classical-to-Quantum software development framework
Author: C2Q Team
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/C2-Q/C2Q
Project-URL: Repository, https://github.com/C2-Q/C2Q
Project-URL: Documentation, https://github.com/C2-Q/C2Q#readme
Project-URL: Issues, https://github.com/C2-Q/C2Q/issues
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy==1.26.4
Requires-Dist: scipy==1.13.1
Requires-Dist: networkx==3.3
Requires-Dist: matplotlib==3.9.0
Requires-Dist: seaborn==0.13.2
Requires-Dist: PyLaTeX==1.4.2
Requires-Dist: fpdf==1.7.2
Requires-Dist: qiskit==1.4.3
Requires-Dist: qiskit-aer==0.16.0
Requires-Dist: python-sat==1.8.dev13
Provides-Extra: parser
Requires-Dist: torch==2.4.1; extra == "parser"
Requires-Dist: transformers==4.44.2; extra == "parser"
Requires-Dist: safetensors==0.5.3; extra == "parser"
Provides-Extra: recommender
Requires-Dist: pandas==2.2.2; extra == "recommender"
Provides-Extra: cloud
Requires-Dist: qiskit-ibm-runtime==0.34.0; extra == "cloud"
Requires-Dist: qiskit-ionq==0.5.12; extra == "cloud"
Requires-Dist: pytket==2.6.0; extra == "cloud"
Requires-Dist: pytket-qiskit==0.64.0; extra == "cloud"
Requires-Dist: pytket-quantinuum==0.45.0; extra == "cloud"
Requires-Dist: amazon-braket-sdk==1.97.0; extra == "cloud"
Provides-Extra: artifact
Requires-Dist: pandas==2.2.2; extra == "artifact"
Requires-Dist: torch==2.4.1; extra == "artifact"
Requires-Dist: transformers==4.44.2; extra == "artifact"
Requires-Dist: safetensors==0.5.3; extra == "artifact"
Provides-Extra: dev
Requires-Dist: pandas==2.2.2; extra == "dev"
Requires-Dist: torch==2.4.1; extra == "dev"
Requires-Dist: transformers==4.44.2; extra == "dev"
Requires-Dist: safetensors==0.5.3; extra == "dev"
Requires-Dist: pytest==8.4.1; extra == "dev"
Dynamic: license-file

# C2|Q>: Classical-to-Quantum Software Development Framework

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python 3.10-3.12](https://img.shields.io/badge/Python-3.10--3.12-blue.svg)](https://www.python.org/downloads/)
[![Status: Research Prototype](https://img.shields.io/badge/status-research--prototype-orange)]()

## Overview

**C2|Q>** is a modular framework for moving from classical problem specifications to quantum-ready problem representations, circuit generation, execution, and report generation.

This repository accompanies the article:

> **"C2|Q>: A Robust Framework for Bridging Classical and Quantum Software Development"**  
> Accepted at *ACM Transactions on Software Engineering and Methodology (TOSEM)* (in press).  
> Preprint: [arXiv:2510.02854](https://arxiv.org/abs/2510.02854)

Artifact-review companion documents:
- [INSTALL](/Users/mac/Documents/GitHub/C2Q/INSTALL.md)
- [REQUIREMENTS](/Users/mac/Documents/GitHub/C2Q/REQUIREMENTS.md)
- [STATUS](/Users/mac/Documents/GitHub/C2Q/STATUS.md)
- [Claims Map](/Users/mac/Documents/GitHub/C2Q/docs/CLAIMS_MAP.md)
- [RCR Draft](/Users/mac/Documents/GitHub/C2Q/docs/RCR_DRAFT.md)

## What To Run

Use these commands as the main entry points for the paper-backed artifact paths:

| Purpose | Command | Main output |
|---|---|---|
| Optional Docker image build | `make docker-build` | Docker image `c2q:latest` |
| Experiment 1: parser training assets | notebook/manual assets | `src/parser/` |
| Experiment 2: recommender multi-device variation | `make recommender-maxcut` | `artifacts/recommender_maxcut/` |
| Experiment 3: smoke reproduction | `make reproduce-smoke` | `artifacts/reproduce/smoke/` |
| Experiment 3: full paper reproduction | `make reproduce-paper` | `artifacts/reproduce/paper/` |
| Experiment 4: dataset validation | `make validate-dataset` | `artifacts/parser_validation/` |

All generated outputs from the `make`-based experiment paths are written under `artifacts/`.

## Repository Layout

- `src/` – framework source code
- `src/parser/` – parser code, training notebook, checkpoints, model helpers
- `src/c2q-dataset/` – JSON inputs and dataset assets
- `tools/` – reproducibility and environment helpers
- `scripts/` – experiment orchestration scripts
- `artifacts/` – generated outputs from reproducibility commands

## Primary Reviewer Path

The primary reviewer path is a normal source checkout with a local virtual environment.

```bash
git clone https://github.com/C2-Q/C2Q.git
cd C2Q
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
```

Environment sanity check:

```bash
make doctor
```

## Parser Model Setup

The parser model is not bundled in GitHub or PyPI because of file size.

Published model archive:
- [saved_models_2025_12.zip (Zenodo)](https://zenodo.org/records/19061126/files/saved_models_2025_12.zip?download=1)

Recommended installation path:
1. Download the archive in a browser from the Zenodo link above.
2. Install it with:

```bash
python tools/setup_model.py --archive /path/to/saved_models_2025_12.zip --model-path src/parser/saved_models_2025_12
```

3. Verify it:

```bash
make model-check
```

Optional helper:

```bash
make model-download
```

Use `make model-download` only as a convenience path. Manual archive download plus `--archive` is the most robust installation route across environments.

Required files inside the model directory:
- `config.json`
- `tokenizer_config.json`
- one weight file: `model.safetensors` or `pytorch_model.bin`

## Optional Docker Path

Use Docker only if you want a clean path that does **not** touch your current `.venv`.

Build the Docker image:

```bash
make docker-build
```

Run the main artifact commands in Docker:

```bash
make docker-smoke
make docker-recommender-maxcut
make docker-validate-dataset
make docker-paper
```

Notes:
- Docker commands use a separate virtual environment path: `/tmp/c2q-venv` inside the container
- Your existing `.venv` is not reused
- Outputs still appear in the repository under `artifacts/`
- The parser model is still required; see the next section
- `make docker-smoke` is the recommended first Docker check; longer Docker targets are available but slower

## Experiments Used In The Paper

### Experiment 1: Parser Training and Saved Model

This experiment is represented by the parser training notebook and its training outputs.

Main assets:
- notebook: `src/parser/parser_train_results_12_1.ipynb`
- intermediate checkpoints: `src/parser/results/`
- released trained model archive: [Zenodo model zip](https://zenodo.org/records/19061126/files/saved_models_2025_12.zip?download=1)

This experiment is notebook-driven rather than make-driven.

### Experiment 2: Recommender Multi-Device Variation

Run:

```bash
make recommender-maxcut
```

Outputs:
- raw recommender CSVs and plots: `artifacts/recommender_maxcut/raw_csv/`
- post-processed Algorithm 1 outputs: `artifacts/recommender_maxcut/algorithm1/`

Key files:
- `artifacts/recommender_maxcut/raw_csv/errors_wide.csv`
- `artifacts/recommender_maxcut/raw_csv/times_wide.csv`
- `artifacts/recommender_maxcut/raw_csv/prices_wide.csv`
- `artifacts/recommender_maxcut/raw_csv/recommender_output_errors.pdf`
- `artifacts/recommender_maxcut/raw_csv/recommender_output_prices.pdf`
- `artifacts/recommender_maxcut/raw_csv/recommender_output_times.pdf`
- `artifacts/recommender_maxcut/algorithm1/winners.csv`
- `artifacts/recommender_maxcut/algorithm1/details.csv`

### Experiment 3: Report Reproduction

Smoke run:

```bash
make reproduce-smoke
```

Full paper run:

```bash
make reproduce-paper
```

The full paper run is time-consuming and takes roughly **10 hours**.

Outputs:
- smoke path: `artifacts/reproduce/smoke/`
- paper path: `artifacts/reproduce/paper/`

This path reproduces the artifacts corresponding to the [C2Q data record](https://zenodo.org/records/18780001) used in paper evaluation.

### Experiment 4: Dataset Validation

Run:

```bash
make validate-dataset
```

Outputs:
- implementation-level validation: `artifacts/parser_validation/implementation/`
- algorithmic/structural validation: `artifacts/parser_validation/diversity/`

Key files:
- `artifacts/parser_validation/implementation/snippet_metrics.csv`
- `artifacts/parser_validation/implementation/family_summary.csv`
- `artifacts/parser_validation/implementation/syntax_failures.csv`
- `artifacts/parser_validation/diversity/summary_by_tag.csv`
- `artifacts/parser_validation/diversity/algorithm_diversity_summary.csv`
- `artifacts/parser_validation/diversity/algorithm_signals_per_instance.csv`

## Tests

Fast default tests:

```bash
PYTHONPATH=. pytest
```

Model-backed tests:

```bash
make verify-model
```

## PyPI Installation

For lightweight CLI/API use without cloning the repo:

```bash
python -m pip install --upgrade pip
python -m pip install --upgrade c2q-framework
```

Optional extras:

```bash
python -m pip install --upgrade "c2q-framework[parser]"
python -m pip install --upgrade "c2q-framework[recommender]"
python -m pip install --upgrade "c2q-framework[artifact]"
python -m pip install --upgrade "c2q-framework[cloud]"
```

Use them as follows:
- `parser`: local parser model support
- `recommender`: CSV export and experiment helpers
- `artifact`: paper-backed local artifact path from a source checkout
- `cloud`: optional live-provider SDK integrations

Check the installed version:

```bash
python -m pip show c2q-framework
```

CLI help:

```bash
c2q-json -h
```

## Programming Interface

Current import namespace is `src.*`.

JSON DSL from Python:

```python
from src.json_engine import load_input, normalise_task

task = load_input("min_add.json")
family, instance, params, goal = normalise_task(task)
print(family, instance)
```

Parser usage:

```python
from src.parser.parser import Parser

parser = Parser(model_path="/path/to/saved_models_2025_12")
family, data = parser.parse("def add(a,b):\n    return a+b\n")
print(family, type(data).__name__)
```

The parser API requires the `parser` extra in PyPI installs.

Generate a report via Python API:

```python
from src.graph import Graph
from src.problems.maximal_independent_set import MIS

edges = [[0, 1], [1, 2], [2, 3], [0, 3], [0, 2]]
problem = MIS(Graph(edges).G)
problem.report_latex(output_path="API_demo_report")
```

## JSON DSL CLI Example

Repository example:

```bash
c2q-json --input src/c2q-dataset/inputs/json/mis/mis_04.json
```

This command parses the JSON problem, generates the quantum workflow, and writes a PDF report.

Regenerate the maintained JSON DSL example set under `src/c2q-dataset/inputs/json_dsl/`:

```bash
make json-dsl-examples
```

Generate PDF reports for a curated smoke subset of those JSON DSL examples:

```bash
make reproduce-json-smoke
```

The curated smoke subset currently includes one example each for `ADD`, `Factor`, `MaxCut`, and `MIS`.

Generate PDF reports for the full JSON DSL example set:

```bash
make reproduce-json-full
```

Outputs are written to:
- smoke: `artifacts/reproduce/json/smoke/`
- full: `artifacts/reproduce/json/full/`

The full JSON reproduction path is intentionally not run by default here because it is slow and takes roughly 2 hours.

## Architecture

![Framework Overview](./src/assets/workflow_editted-1.png)

Detailed component diagrams are available in `src/assets/classiq_flow.pdf`.

## Contact

For research collaboration or substantial contributions:

- boshuai.ye@oulu.fi
- Teemu.Pihkakoski@oulu.fi
- arif.khan@oulu.fi (Project Principal Investigator, PI)
- matti.silveri@oulu.fi (Project Principal Investigator, PI)
- liangp@whu.edu.cn (Outside Collaborator, Peng Liang)

## License

This project is licensed under the [Apache 2.0 License](LICENSE).
