Metadata-Version: 2.4
Name: fastqsim
Version: 0.1.0
Summary: FastQSim SDK — submit and manage quantum simulation jobs via OpenQASM 3.0
Author-email: Aneeq Malik <i221167@nu.edu.pk>, Abeer Noor <i221122@nu.edu.pk>, Abdullah Mehmood <i220978@nu.edu.pk>
Maintainer-email: Imran Ashraf <imran.ashraf@isb.nu.edu.pk>
License-Expression: MIT
Project-URL: Documentation, https://aneeq-ahmed-malik.github.io/QSim/
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Dynamic: license-file

# fastqsim

**FastQSim SDK** — submit and manage quantum simulation jobs on the FastQubit platform using OpenQASM 3.0.

## Installation

```bash
pip install fastqsim
```

## Quick Start

```python
import fastqsim

# Initialise with your pod token (starts with fqp_)
fastqsim.init("fqp_your_pod_token_here")

from fastqsim import FastQSimClient, RunArgs, SimulationType

client = FastQSimClient()

qasm = """
OPENQASM 3.0;
qubit[2] q;
h q[0];
cx q[0], q[1];
measure q;
"""

# Submit a job
job = client.run(RunArgs(
    qasm_input=qasm,
    shots=1024,
    simulation_type=SimulationType.STATEVECTOR,
))

# Poll until done, then fetch result
result = client.get_result(job.id)
print(result.counts)   # e.g. {'00': 512, '11': 512}
```

## Simulation Types

| Type | Description |
|------|-------------|
| `statevector` | Full state-vector (default) |
| `density_matrix` | Noisy / open-system simulation |
| `mps` | Matrix Product State (low-entanglement) |
| `chp` | Clifford / stabilizer (Clifford gates only) |

## API

```python
from fastqsim import (
    init, reset,              # module-level helpers
    FastQSimClient,           # main client class
    Job, Result, Session,     # data types
    JobStatus, SimulationType, RunArgs,
    # exceptions:
    FastQSimError, AuthenticationError, JobFailedError,
    JobTimeoutError, ValidationError, QuotaExceededError,
    # ... (15 exception types total)
)
```

### `FastQSimClient` methods

| Method | Description |
|--------|-------------|
| `client.run(args)` | Submit a job, returns `Job` |
| `client.get_result(job_id)` | Fetch result (polls until complete) |
| `client.cancel(job_id)` | Cancel a queued/running job |
| `client.get_session()` | Get current session info |

## Requirements

- Python >= 3.8
- `requests >= 2.28`

## Documentation

Full docs at https://aneeq-ahmed-malik.github.io/QSim/

## License

MIT
