QuASAr

A proof-of-concept implementation for bounded runtime self-adaptation in hybrid quantum-classical software systems

Overview · Running Scenario · HQC Execution Abstraction · Adaptation Workflow · Getting Started · Limitations

Note

This repository is based on FMweb-K-Quantum, originally developed by Sebastián Candia as part of his undergraduate thesis. The prototype was adapted and extended to support the QuASAr proof-of-concept implementation.

---

Overview

QuASAr (Quantum Adaptive Software Architecture) is a Dynamic Software Product Line (DSPL) architecture for model-governed runtime self-adaptation in Hybrid Quantum-Classical Software Systems (HSS). This repository provides a proof-of-concept implementation of its bounded runtime adaptation mechanisms.

The prototype connects runtime observations with explicit adaptation decisions through a MAPE-K feedback loop. An LLM supports contextual reasoning by proposing candidate adaptations, while deterministic guardrails validate their conformance with the implemented variability, compatibility, policy, and parameter constraints before enactment.

Important

This artifact is a partial research prototype intended to assess architectural feasibility. It should not be interpreted as an industrial runtime platform.

Running Scenario

The prototype represents an HSS in which classical services coordinate an optimization workflow with an optional hybrid quantum-classical capability. The application functionality, optimization goal, and workflow structure remain fixed, while runtime adaptation is restricted to three explicitly controllable decisions:

• C1 — Backend rebinding: infrastructure degradation may trigger the selection of another admissible execution backend (D1).
• C2 — Shot adjustment: simulated noise or execution-quality degradation may trigger a bounded change in the number of shots (D4).
• C3 — HQC activation or bypass: application context and domain policies may determine whether the HQC capability remains enabled or is bypassed (D6).

Together, these cases exercise infrastructure-, parameter-, and capability-level adaptation without synthesizing a new workflow at runtime.

Domain Context and Operational Scenarios

The smart-tourism platform adapts its services as environmental and computational conditions change. It manages tourism, outdoor sports, entertainment, air-quality information, and an optional optimization capability supported by hybrid quantum-classical execution. Decisions consider the visitor profile, Air Quality Index (AQI), problem complexity, Service Level Agreement (SLA) priority, and simulated infrastructure conditions.

These operational scenarios are distinct from cases C1–C3:

• Routine Operations (Variable Conditions): clean-to-moderate air quality and changing user demand. AQI 20–110; complexity 50–120; SLA: latency.
• High Demand (Computational Uncertainty): complexity peaks that prompt a decision on whether hybrid quantum-classical execution is warranted. AQI 40–80; complexity 90–300; SLA: accuracy.
• Environmental Crisis: hazardous air quality requiring restrictions despite conflicting user preferences. AQI 150–300; complexity 50–150; SLA: latency.
• Infrastructure Degradation: unstable cloud infrastructure and variable queue times requiring adaptive backend selection. AQI 50–90; complexity 200–400; SLA: accuracy.

HQC Execution Abstraction

The prototype encapsulates SDK-specific quantum execution behind a common abstraction, preventing the MAPE-K controller from depending directly on Qiskit or Cirq. Instead, the controller delegates backend resolution to HQCModule, which implements the Factory Method pattern.

HQCModule monitors the available backends and creates an implementation of the QuantumBackend interface according to the selected configuration. This interface defines a common execution contract through execute_job(), while QiskitAdapter and CirqAdapter encapsulate the operations required by their respective SDKs.

This design separates adaptation control from SDK-specific implementation details. Consequently, an accepted backend-selection decision can redirect execution by changing the selected adapter without modifying the MAPE-K controller or the application logic.

Note

The current adapters encapsulate different optimization workloads: QiskitAdapter implements a TSP-oriented QAOA workload, whereas CirqAdapter implements a Max-Cut-oriented VQE workload. Backend rebinding therefore demonstrates software-level execution redirection, not semantic-preserving migration of an identical workload between SDKs.

Adaptation Workflow

Each adaptation cycle follows the same bounded workflow:

1. Monitor collects the relevant runtime observations.
2. Analyze determines whether adaptation is required and identifies the affected runtime decision.
3. Plan constructs a bounded decision context, from which Gemini proposes a candidate adaptation and rationale.
4. Validate checks the candidate against the implemented variability, compatibility, policy, and parameter constraints.
5. Execute enacts only an accepted configuration through the managed HSS or HQC execution layer.
6. Knowledge retains the current configuration, observations, candidate, validation outcome, execution evidence, and resulting state.

Note

The LLM has no enactment authority. It proposes a bounded candidate, while deterministic guardrails control whether that candidate may reach execution.

Each cycle records the following adaptation provenance:

Observation → Affected Decision → Candidate → Validation → Enactment or Rejection

Getting Started

Prerequisites

• Docker Compose: Docker with the Compose plugin and a Google API key for models/gemini-2.5-flash.
• Manual setup: uv, Node.js ^20.19.0 or >=22.12.0, npm, Graphviz, a Google API key, and Linux x86_64.

Docker Compose

1. Create Backend/.env and set GOOGLE_API_KEY:

   cp Backend/.env.example Backend/.env

2. Build and start both services:

   docker compose up --build

3. Open http://localhost:5173. Stop the services with docker compose down.

Warning

The Compose configuration mounts /var/run/docker.sock so that the executor can inspect, start, and stop matching containers. This grants the backend control over the host Docker daemon; run only trusted backend code with this configuration.

Manual Setup

1. Configure Backend/.env, set GOOGLE_API_KEY, and start the backend:

   cd Backend
   uv sync --locked
   cp .env.example .env
   uv run --locked python run.py

2. In a second terminal, start the frontend:

   cd Frontend
   npm ci
   npm run dev

3. Open http://localhost:5173. The backend API is available at http://127.0.0.1:8000.

Reproducing the Adaptation Cases

The three QuASAr cases can be exercised by selecting or injecting the corresponding runtime conditions:

• C1: introduce excessive backend latency, unavailability, or an unsuitable backend status. The trace should identify D1, validate an alternative backend, and rebind the corresponding adapter when the candidate is admissible.
• C2: introduce simulated noise or execution-quality degradation. The trace should identify D4, validate the proposed shot value against its configured bounds, and apply the accepted parameter.
• C3: provide an application or problem context in which the domain policy changes the applicability of the HQC capability. The trace should identify D6 and preserve, enable, or bypass HQC execution according to the validated candidate.

The original operational scenarios and the C1–C3 cases represent different views of the prototype. C1–C3 organize the adaptation mechanisms and should not be treated as a one-to-one renaming of every original scenario or execution.

Scope and Limitations

• Environment: quantum execution and runtime degradation are simulated; no physical QPUs are used.
• Adaptation scope: only the runtime decisions exercised by C1–C3 are implemented.
• Governance: Knowledge and governance assets are distributed, and guardrails cover only the constraints required by these cases.
• Backend semantics: Qiskit and Cirq execute different workloads; C1 demonstrates adapter rebinding, not semantic-preserving migration.
• Reproducibility: sampled observations and external Gemini reasoning may produce different results across runs.
• Docker services: reconfiguration affects only matching pre-existing containers; the repository does not provision them.