Skip to main content

Getting Started

Documentation note (single source of truth): The canonical documentation is being consolidated under memories/. Start here: memories/readme.md.

Getting Started with QCOS

This guide will help you get started with QCOS (Quantum Circuit Orchestration System) for quantum circuit optimization.

Installation​

Requirements​

  • Python 3.10 or higher
  • pip (Python package manager)

Basic Installation​

pip install softqcos

Optional Dependencies​

QCOS supports multiple quantum backends and features through optional dependencies:

# CLI tools (typer, rich)
pip install softqcos[cli]

# REST API server (fastapi, uvicorn)
pip install softqcos[api]

# Cirq backend
pip install softqcos[cirq]

# PennyLane backend
pip install softqcos[pennylane]

# Amazon Braket backend
pip install softqcos[braket]

# All backends
pip install softqcos[backends]

# Everything (full installation)
pip install softqcos[all]

Your First Optimization​

Step 1: Create a Backend​

QCOS needs a quantum backend to execute circuits. The simplest option is the Aer backend from Qiskit:

from softqcosimport AerBackend

# Create a statevector backend for 10 qubits
backend = AerBackend(num_qubits=10, method="statevector")

Step 2: Create an Optimizer​

The Optimizer class is the main entry point for QCOS:

from softqcosimport Optimizer

optimizer = Optimizer(
    backend=backend,
    num_qubits=10,
    seed=42  # Optional: for reproducibility
)

Step 3: Run Optimization​

For GHZ state preparation:

result = optimizer.optimize_ghz(
    max_iters=100,    # Maximum iterations
    neighbors=8       # Neighbors to evaluate per iteration
)

print(f"Final Fidelity: {result.fidelity:.4f}")
print(f"Total Evaluations: {result.total_evaluations}")

Complete Example​

"""
QCOS Quick Start Example
Optimize a 10-qubit GHZ state preparation circuit
"""

from softqcosimport Optimizer, AerBackend

def main():
    # 1. Create backend
    backend = AerBackend(num_qubits=10, method="statevector")

    # 2. Create optimizer
    optimizer = Optimizer(backend, num_qubits=10, seed=42)

    # 3. Define progress callback (optional)
    def on_progress(iteration, cost, fidelity, params):
        if iteration % 10 == 0:
            print(f"Iteration {iteration}: cost={cost:.6f}, fidelity={fidelity:.4f}")

    # 4. Run optimization
    result = optimizer.optimize_ghz(
        max_iters=100,
        neighbors=8,
        callback=on_progress
    )

    # 5. Print results
    print("\n" + "="*50)
    print("OPTIMIZATION COMPLETE")
    print("="*50)
    print(f"Final Fidelity:     {result.fidelity:.4f}")
    print(f"Final Cost:         {result.final_cost:.6f}")
    print(f"Total Evaluations:  {result.total_evaluations}")
    print(f"Converged:          {result.converged}")

if __name__ == "__main__":
    main()

Save this as quickstart.py and run:

python quickstart.py

Understanding the Results​

The OptimizationResult object contains:

FieldDescription
fidelityFinal state fidelity (0-1, higher is better)
final_costFinal cost function value
total_evaluationsNumber of circuit evaluations performed
iterationsNumber of optimization iterations
convergedWhether the optimization converged
optimal_paramsOptimal parameter values found
historyList of (cost, fidelity) tuples per iteration

Scaling to Large Circuits​

For circuits with more than ~25 qubits, use the MPS (Matrix Product State) backend:

from softqcosimport AerMPSBackend, Optimizer

# 50-qubit optimization with MPS
backend = AerMPSBackend(
    num_qubits=50,
    bond_dimension=64  # Higher = more accurate but slower
)

optimizer = Optimizer(backend, num_qubits=50)
result = optimizer.optimize_ghz(max_iters=200)

Using the CLI​

If you installed softqcos[cli], you can use the command-line interface:

# Run GHZ optimization
softqcosrun ghz --qubits 10 --max-iters 100

# Run benchmark suite
softqcosbenchmark --qubits 5 10 20

# Show system info
softqcosinfo

Using the REST API​

If you installed softqcos[api], you can start the API server:

# Start server
uvicorn softqcos.api.server:app --host 0.0.0.0 --port 8000

# Or use the CLI
softqcos-server

Then make requests:

# Health check
curl http://localhost:8000/health

# Run optimization
curl -X POST http://localhost:8000/optimize \
  -H "Content-Type: application/json" \
  -d '{"num_qubits": 10, "problem_type": "ghz", "max_iters": 100}'

Next Steps​

Troubleshooting​

Import Errors​

If you get import errors, make sure all dependencies are installed:

pip install softqcos[all]

Performance Issues​

For large circuits:

  1. Use AerMPSBackend instead of AerBackend
  2. Reduce bond_dimension if memory is limited
  3. Reduce neighbors parameter for faster iterations

GPU Acceleration​

For GPU-accelerated simulation, ensure you have:

  1. NVIDIA GPU with CUDA support
  2. qiskit-aer-gpu installed
pip install qiskit-aer-gpu

Then use:

backend = AerBackend(num_qubits=10, method="statevector", device="GPU")