Skip to content

Commit daaac1d

Browse files
ThoriumThorium
committed
Merge dev into main for v0.5.0-beta release
2 parents af8ff99 + 2a3e11d commit daaac1d

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

52 files changed

+14848
-118
lines changed

‎ARCHITECTURE_ISSUES.md‎

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
# Architecture Issues & Technical Debt
2+
3+
## ✅ RESOLVED: CircuitValidator Extensibility (2025-11-25)
4+
5+
### Problem (Before)
6+
`CircuitValidator.fs` used a **closed discriminated union** for backends, which made it impossible to add new providers without modifying the library.
7+
8+
### Solution (Implemented)
9+
Refactored to use **configurable `BackendConstraints`** with factory functions:
10+
11+
```fsharp
12+
// User-extensible constraint system
13+
type BackendConstraints = {
14+
Name: string
15+
MaxQubits: int
16+
SupportedGates: Set<string>
17+
MaxCircuitDepth: int option
18+
HasAllToAllConnectivity: bool
19+
ConnectedPairs: Set<int * int>
20+
}
21+
22+
// Factory functions for built-in providers
23+
module BackendConstraints =
24+
let ionqSimulator () : BackendConstraints = { ... }
25+
let ionqHardware () : BackendConstraints = { ... }
26+
let rigettiAspenM3 () : BackendConstraints = { ... }
27+
let create name maxQubits gates ... = { ... } // User-extensible
28+
```
29+
30+
### Current State (After)
31+
- **QUBO Encoding**: ✅ Provider-agnostic (pure math transformations)
32+
- **CircuitValidator**: ✅ Provider-agnostic with extensible constraints
33+
- **IonQ Backend**: ✅ Integrated pre-flight validation (`submitAndWaitForResultsWithValidationAsync`)
34+
- **Rigetti Backend**: ✅ Integrated pre-flight validation (`validateProgramWithConstraints`)
35+
- **KnownTargets Module**: ✅ Auto-detects constraints from Azure Quantum target strings
36+
37+
### Benefits Achieved
38+
1. ✅ **Extensible**: Users can create custom `BackendConstraints` for any provider
39+
2. ✅ **Early validation**: Catches errors before expensive Azure API calls
40+
3. ✅ **Third-party friendly**: IBM, Google, Amazon Braket can be added without library changes
41+
4. ✅ **Type-safe**: F# type system prevents invalid configurations
42+
5. ✅ **No breaking changes**: Clean API design (no deprecated legacy code)
43+
44+
### Example Usage
45+
46+
```fsharp
47+
// Use built-in constraints for local simulator
48+
let localConstraints = BackendConstraints.localSimulator()
49+
let result = CircuitValidator.validateCircuit localConstraints myCircuit
50+
51+
// Use built-in constraints for cloud backends
52+
let ionqConstraints = BackendConstraints.ionqSimulator()
53+
let rigettiConstraints = BackendConstraints.rigettiAspenM3()
54+
55+
// Create custom constraints for a new provider
56+
let ibmConstraints = BackendConstraints.create
57+
"IBM Quantum"
58+
127 // qubits
59+
["H"; "X"; "Y"; "Z"; "CX"; "RZ"; "SX"] // gates
60+
(Some 1000) // max depth
61+
false // limited connectivity
62+
[(0,1); (1,2); (2,3)] // connectivity graph
63+
64+
// Auto-detect from target string (includes local simulator)
65+
let constraints = CircuitValidator.KnownTargets.getConstraints "local"
66+
let azureConstraints = CircuitValidator.KnownTargets.getConstraints "ionq.simulator"
67+
```
68+
69+
### Supported Backend Constraints
70+
71+
| Backend | Factory Function | Max Qubits | Connectivity | Depth Limit |
72+
|---------|-----------------|------------|--------------|-------------|
73+
| Local QAOA Simulator | `BackendConstraints.localSimulator()` | 10 | All-to-all | None |
74+
| IonQ Simulator | `BackendConstraints.ionqSimulator()` | 29 | All-to-all | 100 gates |
75+
| IonQ Hardware (Aria) | `BackendConstraints.ionqHardware()` | 11 | All-to-all | 100 gates |
76+
| Rigetti Aspen-M-3 | `BackendConstraints.rigettiAspenM3()` | 79 | Limited | 50 gates |
77+
78+
---
79+
80+
## 📋 Original Proposed Solution (v1.0) - NOW IMPLEMENTED
81+
82+
### 1. Make Backend Constraints Configurable
83+
84+
**Replace closed enum with configuration:**
85+
86+
```fsharp
87+
// OLD (current - closed)
88+
type Backend =
89+
| IonQSimulator
90+
| IonQHardware
91+
| RigettiAspenM3
92+
93+
// NEW (proposed - open)
94+
type BackendConstraints = {
95+
Name: string
96+
MaxQubits: int
97+
SupportedGates: Set<string>
98+
MaxCircuitDepth: int option
99+
HasAllToAllConnectivity: bool
100+
ConnectedPairs: Set<int * int>
101+
}
102+
103+
// Factory functions for built-in providers
104+
module BackendConstraints =
105+
let ionqSimulator () = { ... }
106+
let ionqHardware () = { ... }
107+
let rigettiAspenM3 () = { ... }
108+
109+
// Users can create custom constraints
110+
let custom name maxQubits gates connectivity = { ... }
111+
```
112+
113+
### 2. Integrate Validation into Submission Path
114+
115+
**Add validation hooks in backends:**
116+
117+
```fsharp
118+
// IonQBackend.fs
119+
let submitAndWaitForResultsAsync
120+
(httpClient: HttpClient)
121+
(workspaceUrl: string)
122+
(circuit: IonQCircuit)
123+
(shots: int)
124+
(target: string)
125+
(constraints: BackendConstraints option) // <-- NEW
126+
: Async<Result<Map<string, int>, QuantumError>> =
127+
async {
128+
// Validate before submission (if constraints provided)
129+
match constraints with
130+
| Some c ->
131+
let circuitInfo = extractCircuitInfo circuit
132+
match CircuitValidator.validateCircuit c circuitInfo with
133+
| Error errors ->
134+
return Error (QuantumError.InvalidCircuit errors)
135+
| Ok () -> ()
136+
| None -> ()
137+
138+
// Proceed with submission...
139+
}
140+
```
141+
142+
### 3. Provide Default Constraints per Target
143+
144+
```fsharp
145+
// Map Azure Quantum target strings to constraints
146+
module KnownTargets =
147+
let getConstraints (target: string) : BackendConstraints option =
148+
match target with
149+
| "ionq.simulator" -> Some (BackendConstraints.ionqSimulator())
150+
| "ionq.qpu.aria-1" -> Some (BackendConstraints.ionqHardware())
151+
| "rigetti.sim.qvm" -> Some (BackendConstraints.rigettiAspenM3())
152+
| _ -> None // Unknown target - skip validation
153+
```
154+
155+
---
156+
157+
## 🎯 Benefits of Solution
158+
159+
1. ✅ **Extensible**: Users can add custom backend constraints without forking
160+
2. ✅ **Early validation**: Catch errors before expensive API calls
161+
3. ✅ **Third-party friendly**: IBM, Google, Amazon Braket providers can be added
162+
4. ✅ **Backward compatible**: Optional parameter, existing code works unchanged
163+
5. ✅ **Type-safe**: F# type system prevents invalid configurations
164+
165+
---
166+
167+
## 📊 How to Use Validation (v0.5.0-beta)
168+
169+
### IonQ Backend with Auto-Validation:
170+
```fsharp
171+
// Validation happens automatically before submission
172+
let! result = IonQBackend.submitAndWaitForResultsWithValidationAsync
173+
httpClient
174+
workspaceUrl
175+
circuit
176+
1000 // shots
177+
"ionq.simulator"
178+
None // Auto-detect constraints from target string
179+
180+
// Or provide custom constraints
181+
let customConstraints = BackendConstraints.create "Custom" 10 ["H"; "CNOT"] None true []
182+
let! result = IonQBackend.submitAndWaitForResultsWithValidationAsync
183+
httpClient workspaceUrl circuit 1000 "ionq.simulator" (Some customConstraints)
184+
```
185+
186+
### Rigetti Backend with Pre-Flight Validation:
187+
```fsharp
188+
// Validate before creating job submission
189+
let validationResult = RigettiBackend.validateProgramWithConstraints
190+
program
191+
"rigetti.sim.qvm"
192+
None // Auto-detect constraints
193+
194+
match validationResult with
195+
| Ok () ->
196+
// Submit job...
197+
let submission = RigettiBackend.createJobSubmission program 1000 "rigetti.sim.qvm" None
198+
JobLifecycle.submitJobAsync httpClient workspaceUrl submission
199+
| Error (InvalidCircuit errors) ->
200+
// Handle validation errors before submission
201+
printfn "Validation failed: %A" errors
202+
```
203+
204+
### Manual Validation for Any Circuit:
205+
```fsharp
206+
let constraints = BackendConstraints.ionqSimulator()
207+
let circuitInfo = {
208+
NumQubits = 5
209+
GateCount = 100
210+
UsedGates = Set.ofList ["H"; "CNOT"; "RX"]
211+
TwoQubitGates = [(0,1); (1,2)]
212+
}
213+
214+
match CircuitValidator.validateCircuit constraints circuitInfo with
215+
| Ok () -> printfn "Circuit valid!"
216+
| Error errors ->
217+
let errorMsg = CircuitValidator.formatValidationErrors errors
218+
printfn "%s" errorMsg
219+
```
220+
221+
---
222+
223+
## 🔍 Related Components
224+
225+
**Provider-Agnostic (Good!):**
226+
- ✅ `QuboEncoding.fs` - Pure mathematical transformations
227+
- ✅ `Authentication.fs` - Works with any Azure service
228+
- ✅ `JobLifecycle.fs` - Generic job submission/polling
229+
- ✅ `Client.fs` - REST API wrapper (not provider-specific)
230+
231+
**Provider-Specific (Needs Review):**
232+
- ⚠️ `CircuitValidator.fs` - Hardcoded backend enum
233+
- ⚠️ `IonQBackend.fs` - IonQ-specific circuit format
234+
- ⚠️ `RigettiBackend.fs` - Quil-specific assembly
235+
236+
**Verdict:** Backend modules SHOULD be provider-specific (they handle different formats).
237+
CircuitValidator should be configurable, not hardcoded.
238+
239+
---
240+
241+
## 📅 Roadmap
242+
243+
### v0.5.0-beta (Current - November 2025)
244+
- ✅ Working IonQ and Rigetti backends
245+
- ✅ Configurable backend constraints (IMPLEMENTED)
246+
- ✅ Automatic validation before submission (IMPLEMENTED)
247+
- ✅ Built-in constraint definitions for IonQ and Rigetti (IMPLEMENTED)
248+
- ✅ User-extensible constraint system (IMPLEMENTED)
249+
- ✅ KnownTargets module for auto-detection (IMPLEMENTED)
250+
251+
### v1.0 (Future)
252+
- 🎯 Add built-in constraints for IBM Quantum
253+
- 🎯 Add built-in constraints for Amazon Braket
254+
- 🎯 Add built-in constraints for Google Cirq/Quantum AI
255+
- 🎯 Enhanced connectivity graph validation (routing algorithms)
256+
- 🎯 Circuit optimization suggestions based on constraints
257+
258+
### Future
259+
- Advanced circuit decomposition for unsupported gates
260+
- Multi-provider circuit transpilation
261+
- Automatic qubit mapping for limited connectivity
262+
263+
---
264+
265+
**Date:** 2025-11-25
266+
**Status:** RESOLVED ✅
267+
**Implementation:** All proposed features implemented in v0.5.0-beta
268+
**Test Coverage:** 547 tests passing
269+
**Breaking Changes:** None (clean API design)

‎LICENSE‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
This is free and unencumbered software released into the public domain.
2+
3+
Anyone is free to copy, modify, publish, use, compile, sell, or
4+
distribute this software, either in source code form or as a compiled
5+
binary, for any purpose, commercial or non-commercial, and by any
6+
means.
7+
8+
In jurisdictions that recognize copyright laws, the author or authors
9+
of this software dedicate any and all copyright interest in the
10+
software to the public domain. We make this dedication for the benefit
11+
of the public at large and to the detriment of our heirs and
12+
successors. We intend this dedication to be an overt act of
13+
relinquishment in perpetuity of all present and future rights to this
14+
software under copyright law.
15+
16+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
19+
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
20+
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
21+
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
22+
OTHER DEALINGS IN THE SOFTWARE.
23+
24+
For more information, please refer to <https://unlicense.org>

0 commit comments

Comments
 (0)