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 38 JSON Encoding Properties: Problems
Key Value
format String: qp
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.

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

Text Encoding


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.

Table 39 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 40 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.


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.