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:

Table 56 JSON Encoding Properties: Problems¶
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:

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.

Table 57 JSON Encoding Properties: Solver Parameters (params)¶
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:

Table 58 JSON Encoding Properties: Solutions¶
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.