Maestro 0.3.11
Unified interface for quantum circuit simulation
Loading...
Searching...
No Matches
Interface.h
Go to the documentation of this file.
1
9
10#pragma once
11
12#ifndef _MAESTRO_INTERFACE_H_
13#define _MAESTRO_INTERFACE_H_
14
15#include "InterfaceTypes.h"
16#include <stddef.h>
17
18#ifdef __cplusplus
19extern "C"
20{
21#endif
22// Fusion queries do not flush. Width zero means Maestro fusion is unsupported.
23// Statistics are cumulative for this simulator, including restored executions.
24#ifdef _WIN32
25 __declspec(dllexport)
26#endif
27 unsigned GetGateFusionMaxQubits(void *sim);
28#ifdef _WIN32
29 __declspec(dllexport)
30#endif
31 int IsGateFusionEnabled(void *sim);
32#ifdef _WIN32
33 __declspec(dllexport)
34#endif
35 int GetGateFusionStatistics(void *sim, MaestroGateFusionStatistics *statistics);
36
37// Matrix buffers contain row-major, interleaved real/imaginary doubles:
38// 8, 32 or 128 doubles for a 2x2, 4x4 or 8x8 matrix. The first target is
39// the least-significant local matrix bit. Return 1 on success, 0 on error;
40// no exception crosses these entry points. Buffers are copied during the call.
41#ifdef _WIN32
42 __declspec(dllexport)
43#endif
44 int ApplyGenericOneQubitGate(void *sim, unsigned long qubit, const double *matrix);
45#ifdef _WIN32
46 __declspec(dllexport)
47#endif
48 int ApplyGenericTwoQubitGate(void *sim, unsigned long qubit0, unsigned long qubit1, const double *matrix);
49#ifdef _WIN32
50 __declspec(dllexport)
51#endif
52 int ApplyGenericThreeQubitGate(void *sim, unsigned long qubit0, unsigned long qubit1, unsigned long qubit2, const double *matrix);
53
54// Native request API, schema version 2. All returned strings (including errors)
55// are UTF-8 JSON owned by the caller and must be released with FreeResult.
56// No C++ exception crosses these entry points. Null means allocation failure.
57#ifdef _WIN32
58 __declspec(dllexport)
59#endif
60 char *MaestroRunRequestJson(const char *request);
61#ifdef _WIN32
62 __declspec(dllexport)
63#endif
64 char *MaestroValidateRequestJson(const char *request);
65#ifdef _WIN32
66 __declspec(dllexport)
67#endif
69#ifdef _WIN32
70 __declspec(dllexport)
71#endif
73
74#ifdef _WIN32
75 __declspec(dllexport)
76#endif
77 void *GetMaestroObject();
78
79#ifdef _WIN32
80 __declspec(dllexport)
81#endif
83
84#ifdef _WIN32
85 __declspec(dllexport)
86#endif
87 unsigned long int CreateSimpleSimulator(int nrQubits);
88#ifdef _WIN32
89 __declspec(dllexport)
90#endif
91 void DestroySimpleSimulator(unsigned long int simHandle);
92#ifdef _WIN32
93 __declspec(dllexport)
94#endif
95 int RemoveAllOptimizationSimulatorsAndAdd(unsigned long int simHandle, int simType, int simExecType);
96#ifdef _WIN32
97 __declspec(dllexport)
98#endif
99 int AddOptimizationSimulator(unsigned long int simHandle, int simType, int simExecType);
100#ifdef _WIN32
101 __declspec(dllexport)
102#endif
103 char *SimpleExecute(unsigned long int simpleSim, const char *circuitStr, const char *jsonConfig);
104#ifdef _WIN32
105 __declspec(dllexport)
106#endif
107 char *SimpleEstimate(unsigned long int simpleSim, const char *circuitStr, const char *observableStr, const char *jsonConfig);
108#ifdef _WIN32
109 __declspec(dllexport)
110#endif
111 void FreeResult(char *result);
112
113#ifdef _WIN32
114 __declspec(dllexport)
115#endif
116 unsigned long int CreateSimulator(int simType, int simExecType);
117#ifdef _WIN32
118 __declspec(dllexport)
119#endif
120 void *GetSimulator(unsigned long int simHandle);
121#ifdef _WIN32
122 __declspec(dllexport)
123#endif
124 void DestroySimulator(unsigned long int simHandle);
125#ifdef _WIN32
126 __declspec(dllexport)
127#endif
128 int InitializeSimulator(void *sim);
129#ifdef _WIN32
130 __declspec(dllexport)
131#endif
132 int ResetSimulator(void *sim);
133#ifdef _WIN32
134 __declspec(dllexport)
135#endif
136 int ConfigureSimulator(void *sim, const char *key, const char *value);
137#ifdef _WIN32
138 __declspec(dllexport)
139#endif
140 char *GetConfiguration(void *sim, const char *key);
141#ifdef _WIN32
142 __declspec(dllexport)
143#endif
144 unsigned long int AllocateQubits(void *sim, unsigned long int nrQubits);
145#ifdef _WIN32
146 __declspec(dllexport)
147#endif
148 unsigned long int GetNumberOfQubits(void *sim);
149#ifdef _WIN32
150 __declspec(dllexport)
151#endif
152 int ClearSimulator(void *sim);
153#ifdef _WIN32
154 __declspec(dllexport)
155#endif
156 unsigned long long int Measure(void *sim, const unsigned long int *qubits, unsigned long int nrQubits);
157#ifdef _WIN32
158 __declspec(dllexport)
159#endif
160 int ApplyReset(void *sim, const unsigned long int *qubits, unsigned long int nrQubits);
161#ifdef _WIN32
162 __declspec(dllexport)
163#endif
164 double Probability(void *sim, unsigned long long int outcome);
165#ifdef _WIN32
166 __declspec(dllexport)
167#endif
168 void FreeDoubleVector(double *vec);
169#ifdef _WIN32
170 __declspec(dllexport)
171#endif
172 void FreeULLIVector(unsigned long long int *vec);
173#ifdef _WIN32
174 __declspec(dllexport)
175#endif
176 double *Amplitude(void *sim, unsigned long long int outcome);
177#ifdef _WIN32
178 __declspec(dllexport)
179#endif
180 double *AllProbabilities(void *sim);
181#ifdef _WIN32
182 __declspec(dllexport)
183#endif
184 double *Probabilities(void *sim, const unsigned long long int *qubits, unsigned long int nrQubits);
185#ifdef _WIN32
186 __declspec(dllexport)
187#endif
188 unsigned long long int *SampleCounts(void *sim, const unsigned long long int *qubits, unsigned long int nrQubits, unsigned long int shots);
189#ifdef _WIN32
190 __declspec(dllexport)
191#endif
192 int GetSimulatorType(void *sim);
193#ifdef _WIN32
194 __declspec(dllexport)
195#endif
196 int GetSimulationType(void *sim);
197#ifdef _WIN32
198 __declspec(dllexport)
199#endif
200 int FlushSimulator(void *sim);
201#ifdef _WIN32
202 __declspec(dllexport)
203#endif
204 int SaveStateToInternalDestructive(void *sim);
205#ifdef _WIN32
206 __declspec(dllexport)
207#endif
209#ifdef _WIN32
210 __declspec(dllexport)
211#endif
212 int SaveState(void *sim);
213#ifdef _WIN32
214 __declspec(dllexport)
215#endif
216 int RestoreState(void *sim);
217#ifdef _WIN32
218 __declspec(dllexport)
219#endif
220 int SetMultithreading(void *sim, int multithreading);
221#ifdef _WIN32
222 __declspec(dllexport)
223#endif
224 int GetMultithreading(void *sim);
225#ifdef _WIN32
226 __declspec(dllexport)
227#endif
228 int IsQcsim(void *sim);
229#ifdef _WIN32
230 __declspec(dllexport)
231#endif
232 unsigned long long int MeasureNoCollapse(void *sim);
233
234#ifdef _WIN32
235 __declspec(dllexport)
236#endif
237 int ApplyX(void *sim, int qubit);
238#ifdef _WIN32
239 __declspec(dllexport)
240#endif
241 int ApplyY(void *sim, int qubit);
242#ifdef _WIN32
243 __declspec(dllexport)
244#endif
245 int ApplyZ(void *sim, int qubit);
246#ifdef _WIN32
247 __declspec(dllexport)
248#endif
249 int ApplyH(void *sim, int qubit);
250#ifdef _WIN32
251 __declspec(dllexport)
252#endif
253 int ApplyS(void *sim, int qubit);
254#ifdef _WIN32
255 __declspec(dllexport)
256#endif
257 int ApplySDG(void *sim, int qubit);
258#ifdef _WIN32
259 __declspec(dllexport)
260#endif
261 int ApplyT(void *sim, int qubit);
262#ifdef _WIN32
263 __declspec(dllexport)
264#endif
265 int ApplyTDG(void *sim, int qubit);
266#ifdef _WIN32
267 __declspec(dllexport)
268#endif
269 int ApplySX(void *sim, int qubit);
270#ifdef _WIN32
271 __declspec(dllexport)
272#endif
273 int ApplySXDG(void *sim, int qubit);
274#ifdef _WIN32
275 __declspec(dllexport)
276#endif
277 int ApplyK(void *sim, int qubit);
278#ifdef _WIN32
279 __declspec(dllexport)
280#endif
281 int ApplyP(void *sim, int qubit, double theta);
282#ifdef _WIN32
283 __declspec(dllexport)
284#endif
285 int ApplyRx(void *sim, int qubit, double theta);
286#ifdef _WIN32
287 __declspec(dllexport)
288#endif
289 int ApplyRy(void *sim, int qubit, double theta);
290#ifdef _WIN32
291 __declspec(dllexport)
292#endif
293 int ApplyRz(void *sim, int qubit, double theta);
294#ifdef _WIN32
295 __declspec(dllexport)
296#endif
297 int ApplyU(void *sim, int qubit, double theta, double phi, double lambda, double gamma);
298#ifdef _WIN32
299 __declspec(dllexport)
300#endif
301 int ApplyCX(void *sim, int controlQubit, int targetQubit);
302#ifdef _WIN32
303 __declspec(dllexport)
304#endif
305 int ApplyCY(void *sim, int controlQubit, int targetQubit);
306#ifdef _WIN32
307 __declspec(dllexport)
308#endif
309 int ApplyCZ(void *sim, int controlQubit, int targetQubit);
310#ifdef _WIN32
311 __declspec(dllexport)
312#endif
313 int ApplyCH(void *sim, int controlQubit, int targetQubit);
314#ifdef _WIN32
315 __declspec(dllexport)
316#endif
317 int ApplyCSX(void *sim, int controlQubit, int targetQubit);
318#ifdef _WIN32
319 __declspec(dllexport)
320#endif
321 int ApplyCSXDG(void *sim, int controlQubit, int targetQubit);
322#ifdef _WIN32
323 __declspec(dllexport)
324#endif
325 int ApplyCP(void *sim, int controlQubit, int targetQubit, double theta);
326#ifdef _WIN32
327 __declspec(dllexport)
328#endif
329 int ApplyCRx(void *sim, int controlQubit, int targetQubit, double theta);
330#ifdef _WIN32
331 __declspec(dllexport)
332#endif
333 int ApplyCRy(void *sim, int controlQubit, int targetQubit, double theta);
334#ifdef _WIN32
335 __declspec(dllexport)
336#endif
337 int ApplyCRz(void *sim, int controlQubit, int targetQubit, double theta);
338#ifdef _WIN32
339 __declspec(dllexport)
340#endif
341 int ApplyCCX(void *sim, int controlQubit1, int controlQubit2, int targetQubit);
342#ifdef _WIN32
343 __declspec(dllexport)
344#endif
345 int ApplySwap(void *sim, int qubit1, int qubit2);
346#ifdef _WIN32
347 __declspec(dllexport)
348#endif
349 int ApplyCSwap(void *sim, int controlQubit, int qubit1, int qubit2);
350#ifdef _WIN32
351 __declspec(dllexport)
352#endif
353 int ApplyCU(void *sim, int controlQubit, int targetQubit, double theta, double phi, double lambda, double gamma);
354// MPO extensions. Return 1 on success, 0 on invalid arguments/backend failure.
355// Bit vectors are q0-first; matrices are column-major interleaved doubles.
356// GetDensityMatrix capacity counts doubles. SampleCountsBits capacity counts
357// histogram entries and must be >= shots; outcomes needs capacity*width bytes,
358// counts needs capacity entries. Each outcome follows the supplied qubit order.
359#ifdef _WIN32
360 __declspec(dllexport)
361#endif
362 int MaestroProbabilityBits(void *sim, const unsigned char *bits, size_t width, double *result);
363#ifdef _WIN32
364 __declspec(dllexport)
365#endif
366 int MaestroDensityMatrixElementBits(void *sim, const unsigned char *row, const unsigned char *col, size_t width, double *real, double *imag);
367#ifdef _WIN32
368 __declspec(dllexport)
369#endif
370 int MaestroDensityMatrixTrace(void *sim, double *real, double *imag);
371#ifdef _WIN32
372 __declspec(dllexport)
373#endif
374 int MaestroExpectationValueComplex(void *sim, const char *pauli, int normalized, double *real, double *imag);
375
376// Batch observables on the current state, in input order, without collapsing it.
377// capacity counts entries in each output array and must be >= count. For count
378// zero the arrays may be null. Strings are q0-first. The real API follows the
379// scalar real query's padding rules; complex MPO queries require full width.
380// Return 1 on success, 0 on failure; output buffers are unchanged on failure.
381#ifdef _WIN32
382 __declspec(dllexport)
383#endif
384 int MaestroExpectationValues(void *sim, const char *const *paulis, size_t count, double *values, size_t capacity);
385#ifdef _WIN32
386 __declspec(dllexport)
387#endif
388 int MaestroExpectationValuesComplex(void *sim, const char *const *paulis, size_t count, int normalized, double *real, double *imag, size_t capacity);
389// Full pure-state readout in logical basis order (q0 is the low bit).
390// capacity counts complex entries; interleaved holds 2*capacity doubles.
391// Returns 0 on failure without modifying the output buffer.
392#ifdef _WIN32
393 __declspec(dllexport)
394#endif
395 int MaestroGetStateVector(void *sim, double *interleaved, size_t capacity);
396// Read-only <psi|O_(count-1)...O_0|psi> on MPS. Each operator is a row-major
397// 2x2 matrix (8 interleaved doubles). Repeated target qubits are allowed and
398// applied in list order. count=0 is identity; the input arrays may be null.
399// Returns 0 on failure without modifying real/imag.
400#ifdef _WIN32
401 __declspec(dllexport)
402#endif
403 int MaestroExpectationValueOperators(void *sim, const unsigned long int *qubits, size_t count, const double *matrices, double *real, double *imag);
404#ifdef _WIN32
405 __declspec(dllexport)
406#endif
407 int MaestroGetDensityMatrix(void *sim, int normalized, double *interleaved, size_t capacity);
408#ifdef _WIN32
409 __declspec(dllexport)
410#endif
411 int MaestroApplyOperator(void *sim, const unsigned long int *qubits, size_t count, const double *interleaved, int normalize);
412#ifdef _WIN32
413 __declspec(dllexport)
414#endif
415 // Empty lists are no-ops on supported simulators; qubits may be null when count is zero.
416 int MaestroMoveAtBeginningOfChain(void *sim, const unsigned long int *qubits, size_t count);
417#ifdef _WIN32
418 __declspec(dllexport)
419#endif
420 int MaestroSampleCountsBits(void *sim, const unsigned long int *qubits, size_t width, size_t shots, unsigned char *outcomes, unsigned long long *counts,
421 size_t capacity, size_t *written);
422#ifdef _WIN32
423 __declspec(dllexport)
424#endif
425 int MaestroMeasureBits(void *sim, const unsigned long int *qubits, size_t width, unsigned char *outcomes);
426
427#ifdef __cplusplus
428}
429#endif
430
431#endif
int MaestroGetStateVector(void *sim, double *interleaved, size_t capacity)
int ApplyK(void *sim, int qubit)
double Probability(void *sim, unsigned long long int outcome)
char * GetConfiguration(void *sim, const char *key)
int GetGateFusionStatistics(void *sim, MaestroGateFusionStatistics *statistics)
int MaestroMoveAtBeginningOfChain(void *sim, const unsigned long int *qubits, size_t count)
int MaestroMeasureBits(void *sim, const unsigned long int *qubits, size_t width, unsigned char *outcomes)
int InitializeSimulator(void *sim)
int RestoreState(void *sim)
char * MaestroRunRequestJson(const char *request)
char * MaestroValidateRequestJson(const char *request)
void FreeDoubleVector(double *vec)
int ApplyRx(void *sim, int qubit, double theta)
int ApplyReset(void *sim, const unsigned long int *qubits, unsigned long int nrQubits)
int ApplyX(void *sim, int qubit)
int ApplyU(void *sim, int qubit, double theta, double phi, double lambda, double gamma)
int MaestroExpectationValues(void *sim, const char *const *paulis, size_t count, double *values, size_t capacity)
int AddOptimizationSimulator(unsigned long int simHandle, int simType, int simExecType)
unsigned long int CreateSimulator(int simType, int simExecType)
int ApplyCRy(void *sim, int controlQubit, int targetQubit, double theta)
int ApplyTDG(void *sim, int qubit)
int ApplyCSXDG(void *sim, int controlQubit, int targetQubit)
int MaestroProbabilityBits(void *sim, const unsigned char *bits, size_t width, double *result)
void FreeResult(char *result)
int ApplyS(void *sim, int qubit)
int MaestroDensityMatrixElementBits(void *sim, const unsigned char *row, const unsigned char *col, size_t width, double *real, double *imag)
int ApplyCX(void *sim, int controlQubit, int targetQubit)
unsigned long int AllocateQubits(void *sim, unsigned long int nrQubits)
char * SimpleExecute(unsigned long int simpleSim, const char *circuitStr, const char *jsonConfig)
int ApplyGenericThreeQubitGate(void *sim, unsigned long qubit0, unsigned long qubit1, unsigned long qubit2, const double *matrix)
int ApplyCRz(void *sim, int controlQubit, int targetQubit, double theta)
unsigned long int GetNumberOfQubits(void *sim)
double * AllProbabilities(void *sim)
void * GetMaestroObjectWithMute()
unsigned long long int MeasureNoCollapse(void *sim)
int MaestroGetDensityMatrix(void *sim, int normalized, double *interleaved, size_t capacity)
int ApplyCP(void *sim, int controlQubit, int targetQubit, double theta)
int ApplySXDG(void *sim, int qubit)
void * GetMaestroObject()
int GetMultithreading(void *sim)
int ApplySDG(void *sim, int qubit)
unsigned long long int Measure(void *sim, const unsigned long int *qubits, unsigned long int nrQubits)
int ApplyCSwap(void *sim, int controlQubit, int qubit1, int qubit2)
void DestroySimpleSimulator(unsigned long int simHandle)
int ApplyCCX(void *sim, int controlQubit1, int controlQubit2, int targetQubit)
int MaestroExpectationValueOperators(void *sim, const unsigned long int *qubits, size_t count, const double *matrices, double *real, double *imag)
int ApplyY(void *sim, int qubit)
double * Amplitude(void *sim, unsigned long long int outcome)
char * MaestroFinalizeDistributedMpiGpuJson(void)
int ApplyZ(void *sim, int qubit)
int ApplyH(void *sim, int qubit)
int ApplyCY(void *sim, int controlQubit, int targetQubit)
char * MaestroGetCapabilitiesJson(void)
char * SimpleEstimate(unsigned long int simpleSim, const char *circuitStr, const char *observableStr, const char *jsonConfig)
double * Probabilities(void *sim, const unsigned long long int *qubits, unsigned long int nrQubits)
int SetMultithreading(void *sim, int multithreading)
int ApplyCU(void *sim, int controlQubit, int targetQubit, double theta, double phi, double lambda, double gamma)
void DestroySimulator(unsigned long int simHandle)
int ApplySwap(void *sim, int qubit1, int qubit2)
int IsGateFusionEnabled(void *sim)
void * GetSimulator(unsigned long int simHandle)
int ApplyRy(void *sim, int qubit, double theta)
int ApplyP(void *sim, int qubit, double theta)
int SaveStateToInternalDestructive(void *sim)
int ApplyCH(void *sim, int controlQubit, int targetQubit)
int MaestroExpectationValuesComplex(void *sim, const char *const *paulis, size_t count, int normalized, double *real, double *imag, size_t capacity)
int FlushSimulator(void *sim)
int ApplyGenericOneQubitGate(void *sim, unsigned long qubit, const double *matrix)
unsigned long int CreateSimpleSimulator(int nrQubits)
int GetSimulationType(void *sim)
int ResetSimulator(void *sim)
unsigned long long int * SampleCounts(void *sim, const unsigned long long int *qubits, unsigned long int nrQubits, unsigned long int shots)
int ApplySX(void *sim, int qubit)
int ApplyCZ(void *sim, int controlQubit, int targetQubit)
int ApplyRz(void *sim, int qubit, double theta)
int ApplyGenericTwoQubitGate(void *sim, unsigned long qubit0, unsigned long qubit1, const double *matrix)
int GetSimulatorType(void *sim)
int RestoreInternalDestructiveSavedState(void *sim)
int MaestroExpectationValueComplex(void *sim, const char *pauli, int normalized, double *real, double *imag)
int ApplyT(void *sim, int qubit)
int MaestroSampleCountsBits(void *sim, const unsigned long int *qubits, size_t width, size_t shots, unsigned char *outcomes, unsigned long long *counts, size_t capacity, size_t *written)
int ApplyCRx(void *sim, int controlQubit, int targetQubit, double theta)
int MaestroDensityMatrixTrace(void *sim, double *real, double *imag)
int ConfigureSimulator(void *sim, const char *key, const char *value)
int ApplyCSX(void *sim, int controlQubit, int targetQubit)
int ClearSimulator(void *sim)
unsigned GetGateFusionMaxQubits(void *sim)
int IsQcsim(void *sim)
int RemoveAllOptimizationSimulatorsAndAdd(unsigned long int simHandle, int simType, int simExecType)
void FreeULLIVector(unsigned long long int *vec)
int MaestroApplyOperator(void *sim, const unsigned long int *qubits, size_t count, const double *interleaved, int normalize)
int SaveState(void *sim)