c2q-framework 0.1.1

C2|Q: Classical-to-Quantum software development framework

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

---

Overview

C2|Q> is a modular quantum software development framework that automates the full pipeline from classical problem specifications to quantum circuit generation and execution.

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 available on arXiv: https://arxiv.org/abs/2510.02854

---

Table of Contents

• Features
• Architecture
• Modular Reuse
• Getting Started
• PyPI Usage
• Programming Interface
• Running Tests
• Reproducibility
• Contributing
• License
• Contact

Features

• Submit standard Python code describing a problem.
• Automatically parse, the problem into Quantum-Compatible Formats (QCFs).
• Select suitable quantum algorithms (e.g., QAOA, VQE, Grover).
• Recommend appropriate quantum devices across platforms (e.g., IBM, IonQ, Rigetti).
• Transpile and execute on hardware or simulators.

---

Architecture

Refer to src/assets/workflow_editted-1.png for detailed component diagrams and workflow explanations.

---

Modular Reuse

For modular reuse, individual components of C2|Q> can be accessed independently:

• Encoder Module

  • Parser (parser.py)
  • QCF translation logic embedded within problem functions (in the problems/ directory)
  • Circuit generator (generator.py)
  • Transpilation layer built on existing SDK interfaces

• Deployment Module

  • Hardware recommender (recommender_engine.py)
  • Execution interfaces provided by external quantum vendors

• Decoder Module

  • Result interpretation logic embedded within each problem-specific function (in the problems/ directory)

Getting Started

Prerequisites

• Python 3.10+
• Git

Quickstart

git clone https://github.com/C2-Q/C2Q.git
cd C2Q
pip install -r requirements-lock.txt
pip install -e .

PyPI Usage

Install from PyPI:

python -m pip install c2q-framework

Check the installed CLI:

c2q-json -h

Minimal JSON smoke case:

{
  "family": "ADD",
  "instance": {
    "operands": [1, 1],
    "bits": 2
  }
}

Run it:

c2q-json --input min_add.json

Programming Interface

Use JSON DSL helpers from 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)

Use parser API for Python-code classification:

from src.parser.parser import Parser

# Requires downloaded model files (saved_models_2025_12)
parser = Parser(model_path="src/parser/saved_models_2025_12")
family, data = parser.parse("def add(a,b):\n    return a+b\n\nprint(add(1,2))")
print(family, type(data).__name__)

Parser model note:

• The parser model is not stored in GitHub/PyPI due to size.
• Download it from Google Drive and set C2Q_MODEL_PATH when needed.

Running Tests

Test tiers are separated for contributor usability:

• unit (default): fast tests, no model required.
• model: parser model required.
• paper: long-running paper-scale tests.

Default fast tier:

PYTHONPATH=. pytest

Model tier (opt-in):

C2Q_MODEL_PATH=src/parser/saved_models_2025_12 PYTHONPATH=. pytest -m model -p no:warnings
# or use helper target:
make verify-model

One-command diagnostics before testing/reproduction:

make doctor

Reproducibility

Use the reproducibility pipeline to run key experiments and export final artifacts.

Quick smoke run (small scale, around 4 reports):

make reproduce-smoke

Full paper run (up to 434 reports, time-consuming, roughly 10 hours):

make reproduce-paper

What this pipeline does:

• Creates/updates a local virtual environment and installs dependencies.
• Runs implementation-level validation (src/validation/implementation_validation.py).
• Runs algorithmic/structural validation (src/validation/diversity_validation.py).
• Generates report artifacts via src/tests/tests_reports.py.
• Exports metadata and artifact index under artifacts/reproduce/{smoke|paper}.

Input policy:

• Primary CSV: src/parser/python_programs.csv
• Backup CSV: src/parser/data.csv
• JSON inputs are kept under src/c2q-dataset/inputs/json/
• Dataset archive uploaded to Zenodo: C2Q data record

Model requirement:

• The parser model is not committed to GitHub because of file size.
• Download the model from Google Drive: saved_models_2025_12
• Place it at src/parser/saved_models_2025_12/ (default path), or pass:
  • MODEL_PATH=/path/to/saved_models_2025_12 for make reproduce-*
  • C2Q_MODEL_PATH=/path/to/saved_models_2025_12 for direct pytest / script runs
• Expected model files: config.json, tokenizer_config.json, and one weight file (model.safetensors or pytorch_model.bin).
• Integrity checks: tools/model_checksums.json stores SHA256 checksums for the distributed model files.
• Collaboration helpers:
  • make model-check verifies model files exist and are complete.
  • make model-download downloads model archive from Google Drive via gdown and installs it (pip install gdown if missing).
  • make doctor checks Python/LaTeX/model/checksum readiness in one command.
  • Manual mode: python tools/setup_model.py --archive /path/to/model_archive.zip

Quick verification commands:

PYTHONPATH=. pytest
C2Q_MODEL_PATH=src/parser/saved_models_2025_12 PYTHONPATH=. pytest -m model -p no:warnings
MODEL_PATH=src/parser/saved_models_2025_12 make reproduce-smoke

---

Using JSON DSL Input

In addition to Python code snippets, C2|Q> supports a lightweight JSON-based Domain-Specific Language (DSL) that allows developers to describe quantum problem instances without writing any quantum code.

📄 Example Format

Each JSON file must contain two fields:

• "problem_type": the problem class (e.g., "maxcut", "add", "factor")
• "data": problem-specific parameters

Example — MaxCut on a 4-node graph:

{
  "problem_type": "maxcut",
  "data": {
    "nodes": 4,
    "edges": [[0, 1], [1, 2], [2, 3], [3, 0], [0, 2]]
  }
}

Supported problem types:

• maxcut
• mis (Maximum Independent Set)
• tsp
• clique
• kcolor
• vc (Minimum Vertex Cover)
• factor (Integer Factorization)
• add (Integer Addition)
• mul (Integer Multiplication)
• sub (Integer Subtraction)

Sample files are available in: src/c2q-dataset/inputs/json/

---

🚀 Running JSON Inputs via CLI

To execute a JSON-defined problem instance using the full C2|Q> workflow, run:

python -m src.json_engine --input src/c2q-dataset/inputs/json/mis/mis_04.json

This command:

• Parses and validates the input
• Classifies the problem and extracts relevant data
• Generates a quantum circuit using the correct algorithm
• Selects the best-fit backend (simulator or hardware)
• Transpiles, executes, and generates reports

---

📁 Output

A detailed PDF report will be saved in:

./MIS_report.pdf

Each report includes:

• Problem summary and visualization
• Quantum circuit diagram
• Device recommendation and parameters
• Execution results (e.g., bitstring outcomes, optimal solution)
• Runtime, fidelity, and cost breakdown

---

Contributing

We welcome contributions from researchers, developers, and practitioners interested in quantum software engineering.

Development Workflow

1. Fork the repository on GitHub.
2. Clone your fork and install dependencies:

   git clone https://github.com/YOUR_USERNAME/C2Q.git
   cd C2Q
   python -m venv venv
   source venv/bin/activate  # On Windows use venv\Scripts\activate
   pip install -r requirements-lock.txt
   make doctor
   make verify
   

3. Create a feature branch:

   git checkout -b feature/my-feature
   

4. Commit your changes:

   git add .
   git commit -m "Add explanation / fix bug / implement feature"
   

5. Push and open a pull request:

   git push origin feature/my-feature
   

Guidelines

• Follow PEP8 coding conventions.
• Document public functions and modules clearly.
• Keep commits focused and descriptive.
• Be respectful in discussions and code reviews.

---

License

This project is licensed under the Apache 2.0 License.

Contact

For research collaboration or substantial contributions, contact the maintainer:

📧 [e-mail]

📧 [e-mail]

📧 [e-mail] (Project Principal Investigator (PI))

📧 [e-mail] (Project Principal Investigator (PI))