https://github.com/qubit-os/qubit-os-hardware
Hardware Abstraction Layer (HAL) for QubitOS - Rust+PyO3 backend implementations for QuTiP and IQM
https://github.com/qubit-os/qubit-os-hardware
hal pyo3 quantum quantum-computing qutip rust
Last synced: about 1 month ago
JSON representation
Hardware Abstraction Layer (HAL) for QubitOS - Rust+PyO3 backend implementations for QuTiP and IQM
- Host: GitHub
- URL: https://github.com/qubit-os/qubit-os-hardware
- Owner: qubit-os
- License: apache-2.0
- Created: 2026-01-26T00:12:35.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-02-07T19:05:59.000Z (about 2 months ago)
- Last Synced: 2026-02-08T03:13:42.714Z (about 2 months ago)
- Topics: hal, pyo3, quantum, quantum-computing, qutip, rust
- Language: Rust
- Homepage: https://qubit-os.github.io
- Size: 119 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# QubitOS Hardware Abstraction Layer (HAL)
[](https://github.com/qubit-os/qubit-os-hardware/actions/workflows/ci.yaml)
[](https://opensource.org/licenses/Apache-2.0)
Rust implementation of the QubitOS Hardware Abstraction Layer - the bridge between pulse optimization and quantum backends.
## Overview
The HAL provides:
- **gRPC Server** - Protocol buffer interface for pulse execution
- **REST API** - HTTP/JSON facade for the gRPC service
- **Backend Registry** - Pluggable backend system for simulators and hardware
- **QuTiP Backend** - Local quantum simulator (via PyO3)
- **IQM Backend** - Cloud access to IQM quantum processors
## Quick Start
### Running the HAL
```bash
# Development mode
cargo run -- --config config.yaml
# Or with environment variables
QUBITOS_LOG_LEVEL=debug cargo run
# Production (release build)
cargo build --release
./target/release/qubit-os-hal --config config.yaml
```
### Docker
```bash
# Build
docker build -t qubit-os-hardware .
# Run
docker run -p 50051:50051 -p 8080:8080 qubit-os-hardware
```
### Configuration
```yaml
# config.yaml
server:
host: "127.0.0.1" # Default - use 0.0.0.0 for external access
grpc_port: 50051
rest_port: 8080
shutdown_timeout_sec: 30
rate_limit:
enabled: true
requests_per_second: 100
backends:
qutip_simulator:
enabled: true
default: true
iqm_garnet:
enabled: false
gateway_url: "${IQM_GATEWAY_URL}"
auth_token: "${IQM_AUTH_TOKEN}"
logging:
level: "info"
format: "json"
```
## Security
The HAL includes several security features:
- **Input Validation**: All requests are validated at the API boundary (envelope sizes, qubit bounds, amplitude limits). See [qubit-os-proto/LIMITS.md](../qubit-os-proto/LIMITS.md).
- **Timeout Protection**: Python/QuTiP execution has a 300s timeout to prevent hangs.
- **Error Sanitization**: Production builds return generic error messages to prevent information leakage.
- **Rate Limiting**: Configurable rate limits (enforced at infrastructure layer).
- **Secure Defaults**: Binds to localhost by default, restrictive CORS.
- **Secret Handling**: IQM tokens use SecretString (optional `iqm` feature).
## Architecture
```
┌─────────────────────────────────────────┐
│ HAL Server │
├──────────────────┬──────────────────────┤
│ gRPC Service │ REST Service │
│ (tonic) │ (axum) │
├──────────────────┴──────────────────────┤
│ Backend Registry │
├────────────────┬────────────────────────┤
│ QuTiP Backend │ IQM Backend │
│ (PyO3) │ (reqwest) │
└────────────────┴────────────────────────┘
```
## Development
### Prerequisites
- Rust 1.83+
- Python 3.11+ (for QuTiP backend)
- Protocol Buffers compiler (protoc)
### Building
```bash
# Debug build
cargo build
# Release build
cargo build --release
# Run tests
cargo test
# Run with logging
RUST_LOG=debug cargo run
```
### Code Structure
```
src/
├── main.rs # Entry point
├── lib.rs # Library exports
├── config.rs # Configuration handling
├── server/
│ ├── mod.rs
│ ├── grpc.rs # gRPC service implementation
│ └── rest.rs # REST API facade
├── backend/
│ ├── mod.rs
│ ├── trait.rs # QuantumBackend trait
│ ├── registry.rs # Backend registration
│ ├── qutip/ # QuTiP simulator backend
│ └── iqm/ # IQM hardware backend
├── validation/
│ ├── mod.rs
│ ├── pulse.rs # Pulse validation
│ └── hamiltonian.rs
└── error.rs # Error types
```
## Adding a New Backend
1. Implement the `QuantumBackend` trait:
```rust
#[async_trait]
impl QuantumBackend for MyBackend {
fn name(&self) -> &str { "my_backend" }
fn backend_type(&self) -> BackendType { BackendType::Hardware }
async fn execute_pulse(&self, request: ExecutePulseRequest)
-> Result {
// Implementation
}
// ... other methods
}
```
2. Register in `backend/mod.rs`
3. Add configuration in `config.rs`
4. Write tests in `tests/`
## License
Apache 2.0 - See [LICENSE](LICENSE) for details.