Data Encoding¶
This section describes the data encoding for problems and solutions.
Data Encoding for Problems¶
The REST API supports two types of encoding for problems submitted to the system.
Use the appropriate code in the type
field of the submission message.
Problem Type | Code |
---|---|
Ising | ising |
QUBO | qubo |
JSON Encoding¶
Problems are encoded as JSON objects with the following properties:
Key | Value |
---|---|
format | String: qp or, for large (multi-part upload) problems, ref |
lin | Linear coefficients (base64-encoded little-endian doubles). One value per working qubit in the same order as solver’s qubits property; NaN indicates an inactive qubit. |
quad | Quadratic coefficients (base64-encoded little-endian doubles). One value per active coupler in the same order as solver’s couplers property. An active coupler means that both qubits the coupler is incident to are active. NaN values are not permitted. |
data | Unique identifier of the problem. |
An example of an HTTP POST request for submitting a problem using curl
in JSON encoding is as follows:
curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/problems -X POST
-d '[{"type":"ising","solver":"c4-sw_sample","data":{"lin":"AAAAAAAA4L8AAAAAAADwPwAAAAAAAAAAAAAAAAAA+H+amZmZmZnJPwAAAAAAAPh/AAAAAAAA+H8A\r\nAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAA\r\nAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAA\r\nAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAA\r\nAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAA\r\nAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA\r\n+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4\r\nfwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/\r\nAAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8A\r\nAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAA\r\nAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAA\r\nAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAA\r\nAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAA\r\nAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA\r\n+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4\r\nfwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/\r\nAAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8A\r\nAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fw==","quad":"AAAAAAAA8L8AAAAAAADgP5qZmZmZmem/","format":"qp"},"params":{"answer_mode":"histogram","num_reads":10}}]'
An example of an HTTP POST request for submitting a large problem uploaded as
a multi-part problem, using curl
in JSON encoding is as follows:
curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/problems -X POST
-d '[{"type":"ising","solver":"hybrid-solver1","data":{"format": "ref", "data": "9b515c01-e311-46c3-b696-ded3fdfe5d0b"},"params":{"answer_mode":"histogram","num_reads":1}}]'
Text Encoding¶
Note
While the REST API still supports text encoding, support for this will be deprecated in an upcoming release.
Problem data is passed via SAPI as text, where each line represents a linear or quadratic coefficient:
128 3
1 1 -1
2 2 1
1 5 -3
The first line consists of the number of qubits followed by the number of variables used for the problem (that is, the number of qubits and couplers whose values we are setting). Each subsequent line consists of two variable indices, followed by the strength of the coupler that connects them. If the first two variable indices are the same, the third number in the line is the weight of the qubit of the previous indices.
An example of an HTTP POST request for submitting a problem with the above data using curl
in text encoding is as follows:
curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/problems -X POST
-d '[{"solver": "c4-sw_sample", "data": "128 3\n1 1 -1\n2 2 1\n1 5 -3",
"type": "ising", "params": {"num_reads": 123}}]'
Data Encoding for Solver Parameters¶
Solver parameters, contained in the params
JSON object, contain key/value pairs; see the table below.
The parameters and their default values are described in Solver Properties and Parameters Reference.
Key | Value |
---|---|
anneal_offsets | JSON array of length equal to the solver property anneal_offset_ranges |
anneal_schedule | JSON array of two element arrays of floating-point numbers |
annealing_time | Integer |
answer_mode | [“raw” | “histogram”] |
auto_scale | [true | false] |
beta | Float |
chains | JSON list of lists of qubit indices. The lists are the chains, and they must be disjoint. This parameter is used only by post-processing. |
flux_biases | JSON array of floating point numbers with length equal to the num_qubits property of the solver. Use 0 for unused or unavailable devices. |
flux_drift_compensation | [true | false] |
initial_state | JSON array of length equal to num_qubits, containing {1,0,3} for QUBO problems and {1,-1,3} for Ising problems. Use 3 for inactive qubits. This format allows you to take an answer from the SAPI clients and send it directly as this parameter. |
max_answers | Positive integer |
num_reads | Positive integer |
num_spin_reversal_transforms | Zero or a positive integer |
postprocess | [“”|”sampling”|”optimization”] |
programming_thermalization | Integer bounded by solver property programming_thermalization_range |
readout_thermalization | Integer bounded by solver property readout_thermalization_range |
reduce_intersample_correlation | [true | false] |
reinitialize_state | [true | false] |
Data Encoding for Solutions¶
The solution encoding for submitted problems is a JSON object with the following properties:
Key | Value |
---|---|
format | String: qp |
num_variables | Total number of variables (active or otherwise) that the solver has. JSON integer. |
solutions | Base-64–encoded string of bit-packed solutions (with 0 = -1 for Ising problems). Bits are in little-endian order. Each solution is padded to end on a byte boundary and contains values for active qubits only. |
energies | Base-64–encoded string of energies, each a little-endian 8-byte floating-point number (doubles). |
active_variables | Base-64–encoded string of the indices of the problem’s active variables. The indices are 4-byte little-endian integers. |
num_occurrences | Base-64–encoded string of the number of occurrences of each solution. The numbers are 4-byte little-endian integers. Answers are ordered by energy. |
timing | Solver-specific JSON object describing the reported time that the solver took to handle the problem. |
Note
If the problem is submitted with the backwards-compatible formatting, the answer is also backwards-compatible:
all the attributes are JSON arrays instead of base-64–encoded bytes, except the solutions
field, which is a
base-64 encoding of the bit-packed solutions without padding between them.