QPCA SDK Usage Guide

Complete step-by-step instructions for using the QPCA SDK to run quantum computations.

1 Get API Key (REQUIRED FIRST STEP)

Email Request:

• Email: readytogo@quantumpolycontextural.ai
• Subject: "API Key Request for QPCA SDK"
• Include:
  • Your name
  • Your organization/company
  • Purpose (testing, research, production use)
  • Requested access level (sandbox/test or production)

Wait for Response:

• Check your email (including spam/junk folder)
• QPC team will send you an API key
• Usually responds within hours to 1 business day

2 Install Python (If Needed)

Check if Python is Installed:

python3 --version

Required: Python 3.9 or higher

If Not Installed:

• Download from: https://www.python.org/downloads/
• Make sure to check "Add Python to PATH" during installation

3 Install QPCA SDK

Option A: Install from PyPI (Recommended)

# Create virtual environment (recommended)
python3 -m venv qpca_env

# Activate virtual environment
source qpca_env/bin/activate  # macOS/Linux
# OR
qpca_env\Scripts\activate  # Windows

# Install SDK
pip install qpca-sdk

Option B: Install from Source

If SDK is not on PyPI yet, download the package from the website and install:

# Download SDK package from downloads page
# Extract it, then:

cd path/to/qpca-sdk
python3 -m venv qpca_env
source qpca_env/bin/activate
pip install .

4 Set API Key

Set as Environment Variable:

macOS/Linux:

export QPCA_API_KEY="your-api-key-from-email"

Windows (Command Prompt):

set QPCA_API_KEY=your-api-key-from-email

Windows (PowerShell):

$env:QPCA_API_KEY="your-api-key-from-email"

Verify API Key is Set:

echo $QPCA_API_KEY  # macOS/Linux
echo %QPCA_API_KEY%  # Windows CMD
echo $env:QPCA_API_KEY  # Windows PowerShell

Should show your API key (not empty).

5 Download Test Files

Get Files from Website:

1. Visit: Downloads Page
2. Download:
   • qpca_benchmark_demo.py (test script)
   • benchmark_config.json (configuration file)
3. Save them in a folder (e.g., ~/qpca_test/)

6 Submit Test Job

Run the Test Script:

# Make sure virtual environment is activated
source qpca_env/bin/activate  # macOS/Linux
qpca_env\Scripts\activate  # Windows

# Submit job
qpca-cli submit \
  --script path/to/qpca_benchmark_demo.py \
  --config path/to/benchmark_config.json

{
  "job_id": "qpca-3c89e142",
  "status_url": "..."
}

7 Check Job Status

Monitor Job Progress:

qpca-cli status --job-id qpca-3c89e142

Keep checking until status is "COMPLETED":

# Run multiple times
qpca-cli status --job-id qpca-3c89e142

Possible Statuses:

• "QUEUED" - Waiting to start
• "RUNNING" - Executing on quantum hardware
• "COMPLETED" - Finished successfully ✅
• "FAILED" - Error occurred

8 Get Results

Once Status is "COMPLETED":

qpca-cli results --job-id qpca-3c89e142

You'll Get:

• Metrics (fidelity, energy, execution time, etc.)
• Download links for results files
• State probabilities
• Artifacts (PDF report, JSON data, telemetry)

Quick Reference

Complete Workflow:

# 1. Activate environment
source qpca_env/bin/activate

# 2. Set API key
export QPCA_API_KEY="your-key"

# 3. Submit job
qpca-cli submit --script script.py --config config.json

# 4. Check status
qpca-cli status --job-id JOB_ID

# 5. Get results
qpca-cli results --job-id JOB_ID

Troubleshooting

Error: 401 Unauthorized

• Check API key: echo $QPCA_API_KEY
• Set it again: export QPCA_API_KEY="your-key"
• Make sure you got the key from readytogo@quantumpolycontextural.ai

Error: externally-managed-environment (macOS)

• Use virtual environment: python3 -m venv qpca_env
• Activate it: source qpca_env/bin/activate
• Then install: pip install qpca-sdk

Error: File Not Found

• Use full paths to script and config files
• Check files exist: ls path/to/file.py

Support

If you need help:

• Email: readytogo@quantumpolycontextural.ai
• Include: Job ID, error messages, steps taken