# Contributing to AbirQu

Welcome — and thank you for your interest in AbirQu! This guide will help you get started testing, using, and contributing to the AbirQu Quantum SDK.

AbirQu is a comprehensive, hardware-independent quantum computing SDK. It provides a single unified API across quantum computing, quantum communication, quantum error correction, hardware control, and a full visual development environment — all implemented in pure NumPy.

Whether you are a quantum researcher, a software developer, a student, or just curious about quantum computing, your contributions are welcome.

---

## Table of Contents

1. [Getting Started](#1-getting-started)
2. [Quick Start](#2-quick-start)
3. [Testing the SDK](#3-testing-the-sdk)
4. [Running on Real Hardware](#4-running-on-real-hardware)
5. [Reporting Issues](#5-reporting-issues)
6. [Contributing Code](#6-contributing-code)
7. [Code Standards](#7-code-standards)
8. [Project Structure](#8-project-structure)
9. [Development Setup](#9-development-setup)
10. [Contact](#10-contact)

---

## 1. Getting Started

### What is AbirQu?

AbirQu is a full-stack quantum computing SDK that eliminates the fragmentation across quantum providers. Instead of learning separate APIs for IBM Qiskit, Google Cirq, Amazon Braket, and others, AbirQu gives you:

- **One unified function** — `QuantumRun` — for sampling, estimation, error mitigation, and ML
- **One circuit library** — works across 12 hardware backends
- **One transpiler pipeline** — decomposes gates for any target architecture
- **5 simulation engines** — GPU, Clifford, MPS, Monte Carlo, NumPy
- **6 domain modules** — Chemistry, OSINT, Cryptanalysis, Space, Q-PINN, Agentic
- **7 quantum communication protocols** — BB84, E91, CV-QKD, and more
- **Fault-tolerant QEC** — Surface, Color, and Stabilizer codes with 5 decoders

### Who is AbirQu for?

- **Quantum Researchers** — single SDK with algorithms from multiple quantum domains
- **Software Developers** — unified API across different hardware backends
- **Students and Educators** — learn quantum computing with a hardware-independent SDK
- **Enterprise Teams** — post-quantum cryptography and job scheduling
- **Pharmaceutical Researchers** — quantum chemistry simulation
- **Cybersecurity Teams** — post-quantum cryptographic algorithms

### System Requirements

| Requirement | Minimum | Recommended |
|------------|---------|-------------|
| Python | 3.9+ | 3.10+ |
| NumPy | 1.21+ | 1.24+ |
| RAM | 4 GB | 16 GB+ |
| Disk | 100 MB | 500 MB |
| OS | Linux, macOS, Windows | Linux (best OpenBLAS support) |

Optional for GPU acceleration: CUDA 11.0+ with CuPy and an NVIDIA GPU (compute capability 3.5+).

---

## 2. Quick Start

### Install from Source

AbirQu is not yet published on PyPI. Install from the GitHub repository:

```bash
git clone https://github.com/Abiress/abirqu.git
cd abirqu
pip install -e .
```

### Install with Optional Features

```bash
# GPU acceleration (requires CUDA + CuPy)
pip install -e ".[gpu]"

# Visualization (matplotlib, pillow)
pip install -e ".[visualization]"

# All optional features
pip install -e ".[gpu,visualization]"

# Development tools (pytest, pytest-cov, hypothesis)
pip install -e ".[dev]"
```

### Verify Installation

```python
import abirqu
print(f"AbirQu version: {abirqu.__version__}")

from abirqu import Circuit, H, CNOT
bell = Circuit(2)
bell.h(0)
bell.cnot(0, 1)

from abirqu.primitives import QuantumRun
result = QuantumRun(bell, shots=1000)
print(f"Bell state counts: {result.counts}")
# Expected: {'00': ~500, '11': ~500}
```

### Run Your First Circuit

Create a file called `my_first_circuit.py`:

```python
from abirqu import Circuit, H, CNOT
from abirqu.primitives import QuantumRun

# Create a Bell state — the "Hello World" of quantum computing
circuit = Circuit(2)
circuit.h(0)       # Put qubit 0 into superposition
circuit.cnot(0, 1) # Entangle qubit 1 with qubit 0
circuit.measure([0, 1])

result = QuantumRun(circuit, shots=1000)
print(result.counts)  # {'00': ~500, '11': ~500}
```

```bash
python my_first_circuit.py
```

### Run More Examples

```bash
# Quick start with state visualization
python examples/quick_start.py

# Grover's search algorithm
python examples/grover_search.py

# QAOA for Max-Cut
python examples/qaoa_maxcut.py

# VQE for H2 molecule
python examples/vqe_h2.py

# Surface code error correction
python examples/qec_surface_code.py
```

### Run Benchmarks

```bash
# Run the full benchmark suite on local simulator
python benchmarks/run_benchmarks.py

# Run with a specific backend
python benchmarks/run_benchmarks.py --backend local

# Save results to JSON
python benchmarks/run_benchmarks.py --output results.json
```

Benchmark results are saved to `benchmark_results.json` in the project root.

---

## 3. Testing the SDK

### Running the Test Suite

AbirQu has **412 tests** covering all modules. Run them with:

```bash
# Run all tests
pytest

# Run with verbose output
pytest -v

# Run with coverage report
pytest --cov=abirqu --cov-report=term-missing

# Run a specific test file
pytest tests/test_comprehensive.py

# Run a specific test class or method
pytest tests/test_comprehensive.py::TestCircuit::test_create_empty
```

### Test Files

| File | What It Tests |
|------|---------------|
| `tests/test_comprehensive.py` | Core circuits, backends, noise, primitives, chemistry, QEC, simulation |
| `tests/test_gui.py` | Quantum IDE/GUI components |
| `tests/test_hardware.py` | Hardware calibration, characterization, noise profiling |
| `tests/test_hybrid_simulator.py` | Hybrid MPS-Clifford simulator |
| `tests/test_novel_contributions.py` | Noise-adaptive compiler, SPAE, circuit cutting |
| `tests/test_properties.py` | Quantum circuit properties |
| `tests/test_qec.py` | Quantum error correction codes and decoders |
| `tests/test_quantum_communication.py` | BB84, E91, CV-QKD, and other protocols |
| `tests/test_tutorials.py` | Tutorial code snippets |

### Running Tutorials

AbirQu includes **205 tutorials** covering quantum computing from basics to advanced applications. Tutorials are in the `tutorials/` directory.

```bash
# View the full tutorial index
cat tutorials/INDEX.md

# Run a specific tutorial (tutorials are markdown with code)
# For example, Tutorial 1 — Bell States:
python -c "
from abirqu import Circuit, H, CNOT
from abirqu.primitives import QuantumRun

circuit = Circuit(2)
circuit.h(0)
circuit.cnot(0, 1)
circuit.measure([0, 1])

result = QuantumRun(circuit, shots=1000)
print(result.counts)
"
```

Tutorial categories:

| Category | Tutorials | Topics |
|----------|-----------|--------|
| Fundamentals | 1–10 | Superposition, entanglement, QFT, QPE, Grover, Shor, VQE |
| Algorithms | 11–20 | QAOA, HHL, quantum walk, amplitude estimation, QNN |
| Machine Learning | 21–30 | Quantum RL, GANs, PCA, clustering, anomaly detection |
| Chemistry & Info | 31–40 | Error mitigation, benchmarking, QRAM, molecular simulation |
| Advanced | 41–50 | Surface codes, fault-tolerant circuits, compilers, sensing |
| Expert | 51–100 | Spin chains, chaos, advanced optimization, QML |
| Cutting-Edge | 111–120 | Novel algorithms, research frontiers |
| Domain Apps | 121–150 | Medical, defense, finance, supply chain, agriculture |
| Industry | 151–170 | Manufacturing, retail, aerospace, telecom, energy |
| Business | 171–200 | R&D, IP, M&A, Web3, DevOps, ML Ops |

### Running Benchmarks

```bash
# Full benchmark suite
python benchmarks/run_benchmarks.py

# Specific backend
python benchmarks/run_benchmarks.py --backend local

# Save to custom output file
python benchmarks/run_benchmarks.py --output my_results.json
```

Benchmarks measure wall-clock time and memory for: QFT, random circuits, VQE, Grover search, state preparation, and full pipeline simulation.

---

## 4. Running on Real Hardware

AbirQu supports 12 hardware backends. IBM Quantum is the most complete integration.

### IBM Quantum Setup

**Step 1: Get an IBM Quantum Token**

1. Go to [quantum.ibm.com](https://quantum.ibm.com)
2. Create a free account (or sign in)
3. Navigate to **Account Settings** → **API Tokens**
4. Click **Create Token** and copy it

**Step 2: Set Your Token as an Environment Variable**

```bash
export IBM_QUANTUM_TOKEN="your_token_here"
```

Or add it to a `.env` file in the project root:

```bash
cp .env.example .env
# Edit .env and set IBM_QUANTUM_TOKEN=your_token_here
```

**Step 3: Install IBM Backend Dependencies**

```bash
pip install -e ".[ibm]"
```

**Step 4: Run on Real Hardware**

```bash
# Dry run (local simulation, no credentials needed)
python examples/real_hardware_execution.py --dry-run

# Real hardware execution
python examples/real_hardware_execution.py --backend ibm_brisbane --shots 1024
```

### Other Hardware Backends

AbirQu also supports (with varying levels of verification):

| Backend | Install | Status |
|---------|---------|--------|
| IBM Quantum | `pip install -e ".[ibm]"` | SDK-wired |
| D-Wave | `pip install -e ".[dwave]"` | Verified |
| SpinQ | `pip install -e ".[spinq]"` | Verified |
| AWS Braket | `pip install -e ".[aws]"` | SDK-wired |
| Azure Quantum | `pip install -e ".[azure]"` | SDK-wired |
| Google Quantum | `pip install -e ".[cirq]"` | SDK-wired |
| IonQ | `pip install -e ".[ionq]"` | SDK-wired |

**Note:** "SDK-wired" means adapter code exists but has not been validated against real hardware. D-Wave and SpinQ have been verified.

### Provider API Keys

Set environment variables or create a `.env` file (see `.env.example` for a template):

```bash
# IBM Quantum
export IBM_QUANTUM_TOKEN="your_token_here"

# AWS Braket
export AWS_ACCESS_KEY_ID="your_key"
export AWS_SECRET_ACCESS_KEY="your_secret"

# Azure Quantum
export AZURE_QUANTUM_RESOURCE_ID="your_resource_id"

# IonQ
export IONQ_API_KEY="your_key"

# Google Quantum
export GOOGLE_CLOUD_PROJECT="your_project_id"
```

AbirQu auto-discovers credentials from environment variables via `CloudManager`.

---

## 5. Reporting Issues

If you find a bug, have a feature request, or run into a problem, please open a GitHub issue:

**[https://github.com/Abiress/abirqu/issues](https://github.com/Abiress/abirqu/issues)**

### What to Include

A good issue report helps us fix the problem faster. Please include:

1. **A clear title** — e.g., "QuantumRun raises IndexError on 3-qubit circuit"
2. **Your environment** — OS, Python version, NumPy version, AbirQu version
3. **Steps to reproduce** — minimal code that triggers the issue
4. **Expected behavior** — what you thought would happen
5. **Actual behavior** — the error message or unexpected output
6. **Full traceback** — if there is an error, paste the complete traceback

### Example Issue Report

```markdown
**Title:** QuantumRun crashes with empty circuit

**Environment:**
- OS: Ubuntu 22.04
- Python: 3.11.5
- NumPy: 2.4.4
- AbirQu: 1.0.0

**Steps to reproduce:**
```python
from abirqu import Circuit
from abirqu.primitives import QuantumRun

circuit = Circuit(0)
result = QuantumRun(circuit, shots=100)
```

**Expected:** Either a clear error message or an empty result.

**Actual:** `IndexError: list index out of range` in `abirqu/primitives/__init__.py:42`

**Full traceback:**
```
Traceback (most recent call last):
  File "test.py", line 6, in <module>
    result = QuantumRun(circuit, shots=100)
  ...
```
```

### Quick Way to Get Your Environment Info

```bash
python -c "import sys, numpy, abirqu; print(f'Python {sys.version}\nNumPy {numpy.__version__}\nAbirQu {abirqu.__version__}')"
```

---

## 6. Contributing Code

### Fork, Branch, Test, PR Workflow

1. **Fork** the repository on GitHub
2. **Clone** your fork locally:
   ```bash
   git clone https://github.com/your-username/abirqu.git
   cd abirqu
   ```
3. **Install** in development mode:
   ```bash
   pip install -e ".[dev]"
   ```
4. **Create a branch** for your change:
   ```bash
   git checkout -b feature/your-feature-name
   ```
   Use a descriptive branch name: `feature/add-pauli-y`, `fix/noise-model-bug`, `docs/update-readme`
5. **Make your changes** and write tests
6. **Run the test suite** to make sure nothing is broken:
   ```bash
   pytest
   ```
7. **Commit** with a clear message:
   ```bash
   git add .
   git commit -m "Add Pauli-Y gate to circuit library"
   ```
8. **Push** to your fork:
   ```bash
   git push origin feature/your-feature-name
   ```
9. **Open a Pull Request** on the [main repository](https://github.com/Abiress/abirqu/pulls)

### Pull Request Guidelines

- Keep PRs focused — one feature or fix per PR
- Include a clear description of what changed and why
- Add tests for new functionality
- Update documentation if your change affects the public API
- Make sure all existing tests pass before submitting
- Reference any related issues (e.g., "Closes #42")

### What Makes a Good Contribution

- **Bug fixes** — anything that makes AbirQu more reliable
- **Tests** — improve coverage for under-tested modules
- **Documentation** — clarify confusing APIs, fix typos, add examples
- **New algorithms** — implement well-known quantum algorithms
- **Performance** — optimize simulation or compilation code
- **Backend improvements** — improve hardware adapter accuracy

---

## 7. Code Standards

### Python Style

AbirQu follows PEP 8 with a line length of 100 characters.

```bash
# Check style with ruff (configured in pyproject.toml)
ruff check abirqu/

# Auto-fix style issues
ruff check --fix abirqu/

# Format code
ruff format abirqu/
```

Key conventions:

- Use `snake_case` for functions and variables
- Use `PascalCase` for classes
- Use `UPPER_SNAKE_CASE` for constants
- Maximum line length: 100 characters
- Import sorting: standard library, third-party, local (enforced by ruff)

### Test Requirements

- Every new feature should include at least one test
- Test functions must start with `test_`
- Test classes must start with `Test`
- Tests should verify behavior, not just absence of errors
- Use `pytest` fixtures for shared setup

```python
# Example test
def test_circuit_create():
    from abirqu import Circuit
    c = Circuit(3, "test")
    assert c.num_qubits == 3
    assert len(c.gates) == 0
    assert c.name == "test"
```

### Documentation Expectations

- All public functions and classes should have docstrings
- Use NumPy-style docstrings when possible
- Include type hints where practical
- Update `README.md` if you add a new feature
- Update `tutorials/INDEX.md` if you add a new tutorial

```python
def my_function(param1: int, param2: str = "default") -> bool:
    """Do something quantum.

    Parameters
    ----------
    param1 : int
        The first parameter.
    param2 : str, optional
        The second parameter. Default is "default".

    Returns
    -------
    bool
        True if successful.
    """
    return True
```

---

## 8. Project Structure

```
abirqu/
├── abirqu/                  # Main package — the SDK itself
│   ├── __init__.py          # Package entry point
│   ├── circuit.py           # Circuit and Gate classes
│   ├── gates.py             # Gate definitions (H, X, CNOT, etc.)
│   ├── primitives/          # QuantumRun, Sampler, Estimator, QNN
│   ├── library/             # Pre-built circuits (QFT, Grover, VQE, etc.)
│   ├── simulation/          # 5 simulation backends (GPU, Clifford, MPS, etc.)
│   ├── numpy_sim.py         # Pure NumPy statevector simulator
│   ├── transpiler/          # Gate decomposition pipeline
│   ├── noise_toolkit.py     # ZNE, readout mitigation, PEC
│   ├── qec/                 # Quantum error correction codes and decoders
│   ├── quantum_communication/  # BB84, E91, CV-QKD, etc.
│   ├── chemistry/           # Molecular Hamiltonian mapping
│   ├── osint/               # Graph optimization → Ising/QUBO
│   ├── crypto/              # Shor, Grover, Kyber, Dilithium
│   ├── space/               # HHL, CFD, structural solvers
│   ├── qpinn.py             # Quantum PDE solvers
│   ├── agentic/             # Task orchestration
│   ├── hardware/            # Calibration, characterization, noise profiling
│   ├── backends/            # Hardware backend adapters (IBM, D-Wave, etc.)
│   ├── cloud/               # Cloud manager, credential management
│   ├── quantum_os/          # Job scheduling, resource management
│   ├── visualization/       # Circuit drawer, Bloch sphere, histograms
│   ├── gui/                 # Full IDE/GUI
│   ├── optimize/            # Noise-adaptive compiler, circuit simplifier
│   ├── addons/              # Trotter, circuit cutting, AQCTensor
│   ├── formats/             # Import/export (Qiskit, Cirq, Braket, etc.)
│   ├── docs/                # Beginner guide
│   └── cli.py               # Command-line interface
├── tests/                   # Test suite (412 tests)
│   ├── test_comprehensive.py
│   ├── test_gui.py
│   ├── test_hardware.py
│   ├── test_hybrid_simulator.py
│   ├── test_novel_contributions.py
│   ├── test_properties.py
│   ├── test_qec.py
│   ├── test_quantum_communication.py
│   └── test_tutorials.py
├── tutorials/               # 205 tutorials (markdown with code)
│   ├── INDEX.md             # Full tutorial index
│   ├── 01_bell_states_and_circuits.md
│   ├── 02_quantum_algorithms.md
│   └── ... (1.md through 200.md)
├── examples/                # Runnable example scripts
│   ├── quick_start.py
│   ├── grover_search.py
│   ├── qaoa_maxcut.py
│   ├── vqe_h2.py
│   ├── qec_surface_code.py
│   ├── real_hardware_execution.py
│   └── ...
├── benchmarks/              # Benchmark suite
│   └── run_benchmarks.py
├── scripts/                 # Utility scripts
├── assets/                  # Logo, architecture diagrams
├── pyproject.toml           # Build config, dependencies, tool settings
├── setup.py                 # Backward-compatible setup script
├── README.md                # Project overview and documentation
├── CONTRIBUTING.md          # This file
├── CODE_OF_CONDUCT.md       # Community standards
├── SECURITY.md              # Security policy
├── LICENSE                  # MIT License
└── .env.example             # Provider credentials template
```

---

## 9. Development Setup

### Full Development Environment

```bash
# Clone and install
git clone https://github.com/Abiress/abirqu.git
cd abirqu
pip install -e ".[dev,visualization]"

# Verify everything works
pytest -v
```

### Running Tests

```bash
# All tests
pytest

# Verbose output
pytest -v

# With coverage
pytest --cov=abirqu --cov-report=term-missing

# Specific file
pytest tests/test_comprehensive.py

# Specific test
pytest tests/test_comprehensive.py::TestCircuit::test_create_empty

# Stop on first failure
pytest -x
```

### Linting and Formatting

```bash
# Check for style issues
ruff check abirqu/

# Auto-fix style issues
ruff check --fix abirqu/

# Format code
ruff format abirqu/

# Type checking (if you set it up)
mypy abirqu/
```

### Pre-commit Checks

Before submitting a PR, run this full check:

```bash
ruff check abirqu/ && ruff format --check abirqu/ && pytest
```

If any of these fail, fix the issues before pushing.

### Git Configuration (Optional)

```bash
# Set up a pre-commit hook to run tests automatically
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
echo "Running tests before commit..."
pytest --tb=short -q
if [ $? -ne 0 ]; then
    echo "Tests failed. Commit aborted."
    exit 1
fi
EOF
chmod +x .git/hooks/pre-commit
```

---

## 10. Contact

- **GitHub Issues:** [https://github.com/Abiress/abirqu/issues](https://github.com/Abiress/abirqu/issues) — for bug reports, feature requests, and questions
- **Email:** abhirsxn@gmail.com — for private inquiries
- **Website:** [aqdi.world](https://aqdi.world) — Artificial Quantum Dyson Intelligence

### Getting Help

- Read the [Beginner Guide](abirqu/docs/beginner_guide.md)
- Browse the [Tutorial Index](tutorials/INDEX.md)
- Check the [README](README.md) for a full feature overview
- Search [existing issues](https://github.com/Abiress/abirqu/issues) before opening a new one

---

## License

By contributing to AbirQu, you agree that your contributions will be licensed under the [MIT License](LICENSE).

**Copyright 2026 Abir Maheshwari.**

---

Thank you for contributing to AbirQu! Every improvement — no matter how small — helps make quantum computing more accessible.
