Problem Resources¶
A problem resource represents a problem submitted by a user to a solver, including large problems uploaded in multiple parts. See the Data Encoding chapter to understand the supported data types for problems (and solutions).
SAPI Endpoints¶
The following table provides an overview of the SAPI URLs that map to problem resources.
| URL | Method | Reference |
|---|---|---|
| /bqm/multipart | POST | Initiate a Multi-Part Upload |
| /bqm/multipart/<id>/part/<part> | PUT | Upload Data in a Multi-Part Upload |
| /bqm/multipart/<id>/combine | POST | Complete a Multi-Part Upload with Checksum |
| /bqm/multipart/<id>/status | GET | Status for a Multi-Part Upload |
| /problems/ | POST | Submit Problem |
| /problems/ | DELETE | Cancel Multiple Problems |
| /problems/<problem_id> | DELETE | Cancel a Problem by ID |
| /problems/<filters> | GET | List Problems |
| /problems/<problem_id>/ | GET | Get Problem |
| /problems/<problem_id>/info | GET | Get Problem Information |
| /problems/<problem_id>/answer/ | GET | Get Problem Answer |
| /problems/<problem_id>/messages/ | GET | Get Problem Messages |
Problem Lifecycle¶
A problem may have one of the following statuses:
| Status | Description |
|---|---|
| PENDING | Problem was submitted and is queued for processing. |
| IN_PROGRESS | Problem is currently being processed. |
| COMPLETED | Problem completed successfully. |
| FAILED | Problem processing failed. |
| CANCELLED | Problem was cancelled. |
Note
If a quota is reached before a problem is processed, the problem remains in a PENDING state until the quota resets or the problem expires.
Fig. 122 Initially a problem is in the PENDING state. When the D-Wave system starts to process a problem, its state changes to IN_PROGRESS. After completion, the problem status changes to either COMPLETED or FAILED (if an error occurred). COMPLETED, FAILED, and CANCELLED are all terminal states. After a problem enters a terminal state, its status does not change. Users can cancel a problem at any time before it reaches its terminal state.¶
Large Problem Upload¶
For large problems (starting from several megabytes and higher), upload the problem
data in multiple parts using the $SAPI_HOME/bqm/multipart endpoints.
- Maximum problem size currently supported is 50 GB.
- Size of all parts must be 5M (5242880 bytes), except the last, which may be smaller.
This example uses curl to upload a 7 megabyte problem. For simplicity, the
problem is stored in two files of 5 MB and 2 MB, respectively. Both commands and responses
are shown. Status requests are optional. For details, see the command descriptions below.
$ curl -H "X-Auth-Token: $SAPI_TOKEN" -H "Content-type: application/json" -X POST $SAPI_HOME/bqm/multipart/ -d '{"size":7340032}'
{"id":"60aa9e10-642b-4a90-a85e-d8a28ceab065"}
$ id=60aa9e10-642b-4a90-a85e-d8a28ceab065
$ curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/bqm/multipart/$id/status
{"status": "UPLOAD_IN_PROGRESS", "parts": []}
$ curl -H "X-Auth-Token: $SAPI_TOKEN" -H "X-Content-MD5: 3UzghguXkRNBgPS80YHkjA==" -H "Content-type: application/octet-stream" -X PUT $SAPI_HOME/bqm/multipart/$id/part/1 -d @"5Mbqm.txt"
$ curl -H "X-Auth-Token: $SAPI_TOKEN" -H "X-Content-MD5: nVEskva/D3fLGgKc/F58bA==" -H "Content-type: application/octet-stream" -X PUT $SAPI_HOME/bqm/multipart/$id/part/2 -d @"2Mbqm.txt"
$ curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/bqm/multipart/$id/status
{"status": "UPLOAD_IN_PROGRESS", "parts": [{"part_number": 1, "checksum": "dd4ce0860b9791134180f4bcd181e48c"}, {"part_number": 2, "checksum": "9d512c92f6bf0f77cb1a029cfc5e7c6c"}]}
$ curl -H "X-Auth-Token: $SAPI_TOKEN" -H "Content-type: application/json" -X POST $SAPI_HOME/bqm/multipart/$id/combine/ -d '{"checksum":"33e03d49ccfa4c132a307790b6b78644"}'
{}
$ curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/bqm/multipart/$id/status
{"status": "UPLOAD_COMPLETED", "parts": []}
Initiate a Multi-Part Upload¶
To initiate the uploading of a large problem in multiple parts, send an HTTP POST
request to $SAPI_HOME/bqm/multipart/.
The POST request body should contain the number of bytes, size, as an integer,
required to store the problem.
This example uses curl:
$ curl -H "X-Auth-Token: $SAPI_TOKEN" -H "Content-type: application/json" -X POST $SAPI_HOME/bqm/multipart/ -d '{"size":<size>}'
Upload Data in a Multi-Part Upload¶
To upload parts of a large problem uploaded in multiple parts, send an HTTP PUT
request to $SAPI_HOME/bqm/multipart/<id>/part/<part>/ for each part.
The POST request body should contain the data for one part of the problem and the
header should contain the MD5 checksum.
Each part’s size should be 5 MB (5242880 bytes), except the last, which may be smaller.
This example uses curl:
curl -H "X-Auth-Token: $SAPI_TOKEN" -H "X-Content-MD5: <MD5 checksum>" -H "Content-type: application/octet-stream" -X PUT $SAPI_HOME/bqm/multipart/$id/part/<part number> -d <data for one part>
The MD5 checksum can be found, for example, using the Python hashlib library function hashlib.md5(). The following Python code example finds the checksum for a 5 MB problem part saved in a file named 5Mbqm.txt:
>>> import hashlib
>>> import base64
>>> hash_md5_5m = hashlib.md5()
>>> with open("5mbqm.txt", "r") as file:
for chunk in iter(lambda: file.read(4096), ""):
hash_md5_5m.update(chunk.encode())
>>> print(base64.b64encode(hash_md5_5m.digest()).decode('utf-8'))
3UzghguXkRNBgPS80YHkjA==
Complete a Multi-Part Upload with Checksum¶
To complete the upload a large problem uploaded in multiple parts, send an HTTP POST
request to $SAPI_HOME/bqm/multipart/<id>/combine with the combined checksum.
The POST request body should contain the checksum for the entire problem, as a string.
Note
Amazon calculates the checksum of the combined file in a particular way. Rather than the checksum from combining the parts, it concatenates all the checksums of the parts and then calculates the checksum of that concatenation. Your checksum must follow this same format.
This example uses curl:
curl -H "X-Auth-Token: $SAPI_TOKEN" -H "Content-type: application/json" -X POST $SAPI_HOME/bqm/multipart/$id/combine/ -d '{"checksum":"<Amazon-style checksum>"}'
The checksum can be found, for example, using the Python hashlib library function hashlib.md5(). The example below finds the concatenated checksum for a large problem saved in two parts with MD5 checksums (see Upload Data in a Multi-Part Upload for information on calculating checksums for the parts) in variables hash_md5_5m and hash_md5_2m:
>>> import hashlib
>>> print((hashlib.md5(bytes.fromhex(
... hash_md5_5m.hexdigest() +
... hash_md5_2m.hexdigest())
... )).hexdigest())
33e03d49ccfa4c132a307790b6b78644
Status for a Multi-Part Upload¶
To get the status of a large problem uploaded in multiple parts, send an HTTP GET
request to $SAPI_HOME/bqm/multipart/<id>/status.
The GET request should contain no body.
This example uses curl:
curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/bqm/multipart/$id/status
Response¶
The system returns the status as a string with parts and checksums.
Response codes are as follows:
| Response Code | Meaning |
|---|---|
200 |
Success. |
400 |
Failed to upload, no or invalid checksum. |
404 |
Failed to find specified upload. |
500 |
Unspecified failure. |
Submit Problem¶
Request¶
To submit problems, send an HTTP POST request to $SAPI_HOME/problems/.
The POST request body should contain JSON-encoded problem information.
When possible, if you have more than one problem, submit them in a single query.
This example uses curl:
curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/problems -X POST \
-d '[{"type":"ising","solver":"c4-sw_sample","label": "Structural Network: problem 5","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 submitting a large problem uploaded as a multi-part problem:
curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/problems -X POST \
-d '[{"type":"ising","label": "Structural Network: problem 5","solver":"hybrid-solver1","data":{"format": "ref", "data": "9b515c01-e311-46c3-b696-ded3fdfe5d0b"},"params":{"answer_mode":"histogram","num_reads":1}}]'
Problem Data¶
The JSON data for the submitted problem includes the following key-value pairs:
| Key | Value |
|---|---|
| data | Problem data; see the Data Encoding section. |
| label | (Optional, defaults to null) User-defined string (label) for a problem. |
| params | Solver-specific parameters. See Data Encoding for Solver Parameters. |
| solver | Solver to be used. |
| type | One of the supported problem types (ising or qubo). |
Note
The allowed problem types are listed in the solver’s properties.
Response¶
The system returns a list with the results to the corresponding problems in the JSON request.
Error in problem (example):
{
"error_code": 400,
"error_msg": "Missing parameter 'num_reads' in problem JSON"
}
| Key | Value |
|---|---|
| error_code | Error code describing the type of error encountered; 400 for missing parameters, 403 for no access to solver, 429 for too many requests. |
| error_msg | Message describing the error encountered |
Successful completion (example):
{
"status": "COMPLETED",
"earliest_estimated_completion": "2018-08-13T20:47:03.009543Z",
"solved_on": "2018-08-13T20:47:03.066239Z",
"solver": "c4-sw_sample",
"submitted_on": "2018-08-13T20:47:03.009343Z",
"answer": {
"num_variables": 128,
"format": "qp",
"energies": "zczMzMzMDMA=",
"num_occurrences": "CgAAAA==",
"active_variables": "AAAAAAEAAAACAAAABAAAAA==",
"solutions": "sA==",
"timing": {}
},
"latest_estimated_completion": "2018-08-13T20:47:03.009543Z",
"type": "ising",
"id": "d8b0a7d0-01e5-4d27-bae2-93cd23f3204c",
"label": "Structural Network: problem 5"
}
Completion with errors (example):
{
"status": "FAILED",
"solved_on": "2018-01-18T10:26:00.020954",
"solver": "c4-sw_sample",
"submitted_on": "2018-01-18T10:25:59.941674",
"type": "ising",
"id": "f004cea4-0f18-4b44-8aca-4e3acbb6831b",
"label": "Structural Network: problem 5",
"error_message": "Some error message"
}
| Key | Value |
|---|---|
| answer | Content of the answer depends on the solver and parameters used. See Data Encoding for Solutions for more details about the structure of this field. |
| earliest_estimated_completion | Estimated completion time: beginning of range. |
| error_message | Error message generated by the system if problem status is FAILED. |
| id | Unique identifier of the problem; can be used later to retrieve problem information, the answer, and the messages. |
| label | (Optional, defaults to null) User-defined string (label) for a problem. |
| latest_estimated_completion | Estimated completion time: end of range. |
| solved_on | If this problem is in terminal state (COMPLETED, CANCELLED or FAILED), time when problem was solved. Empty otherwise. |
| solver | Name of the solver to which the problem was submitted. |
| status | One of the problem states as defined in Problem Lifecycle. |
| submitted_on | Time when problem was submitted. |
| type | Problem type as specified when the problem was submitted. |
Cancel Multiple Problems¶
Request¶
To cancel PENDING problems, send an HTTP DELETE request to $SAPI_HOME/problems/.
The request body should be a JSON-encoded list of problem IDs; if the request body is empty, the request has no effect.
When possible, if you have more than one problem to cancel, submit them in a single query.
This example uses curl:
curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/problems/?id=792749f9-3bbc-4eea-84da-e51726ac0be6,id2,id3 -X DELETE
Response¶
The system returns a list with the results to the corresponding problems in the JSON request in one of the following formats.
Error in problem (example):
{
"error_code": 409,
"error_msg": "Problem already terminated"
}
Response codes are as follows:
| Response Code | Meaning |
|---|---|
200 |
Success. |
202 |
Cancellation request received. Relevant for in-progress jobs. The problem is cancelled if the request was received in time; otherwise, it will complete. |
404 |
Problem with the specified ID does not exist. |
409 |
Problem reached one of terminal states before the call. |
429 |
Number of API requests exceeds the permitted limit. |
| Key | Value |
|---|---|
| error_code | Error code describing the type of error encountered |
| error_msg | Message describing the error encountered |
Successful cancellation (example):
{
"status": "CANCELLED",
"solved_on": "2018-01-18T10:26:00.020954",
"solver": "c4-sw_sample",
"submitted_on": "2018-01-18T10:25:59.941674",
"type": "ising",
"id": "f004cea4-0f18-4b44-8aca-4e3acbb6831b",
"label": "Structural Network: problem 5"
}
| Key | Value |
|---|---|
| id | Unique identifier of the problem. |
| label | (Optional, defaults to null) User-defined string (label) for a problem. |
| status | Problem state: CANCELLED. |
| submitted_on | The time when problem was submitted. |
| solved_on | The time when problem was cancelled. |
| type | Problem type as specified when the problem was submitted. |
Cancel a Problem by ID¶
Request¶
To cancel a previously submitted problem, make an HTTP DELETE request to $SAPI_HOME/problems/.
$SAPI_HOME/problems/<problem_id>/
Response¶
The system returns the problem formatted as a JSON object.
Example of the output:
{ "status": "CANCELLED", "id": "cc2c8f78-1cdf-48b8-9ffd-63bc5244dc4c", "label": "Test Ising Problem 12", "solver": "hybrid_binary_quadratic_model_version2", "type": "bqm", "submitted_on": "2021-01-22T15:10:27.888129Z", "solved_on": "2021-01-22T15:11:18.360580Z" }
Response codes are as follows:
| Response Code | Meaning |
|---|---|
200 |
Success. |
202 |
Cancellation request received. Relevant for in-progress jobs. The problem is cancelled if the request was received in time; otherwise, it will complete. |
404 |
Problem with the specified ID does not exist. |
409 |
Problem reached one of terminal states before the call. |
429 |
Number of API requests exceeds the permitted limit. |
List Problems¶
Request¶
To retrieve a list of previously submitted problems, make an HTTP GET request to $SAPI_HOME/problems/.
You can filter the results using one or more of the following parameters:
| Key | Value |
|---|---|
| id | comma-separated list of problem IDs |
| label | (Optional, defaults to null) Filter the results by problems with labels that contain the given text. |
| max_results | Maximum number of results to return. Returns up to 1000 if not specified. |
| status | Problem state: COMPLETED, IN_PROGRESS, PENDING, FAILED, CANCELLED. |
| solver | Solver name (e.g., hybrid_v1). |
This example uses curl:
$ curl -H "X-Auth-Token: $SAPI_TOKEN" -X GET "$SAPI_HOME/problems/?solver=hybrid_v1&max_results=5&status=COMPLETED"
Response¶
The system returns problems as a JSON list.
Example of the output:
[
{
"status": "COMPLETED",
"solved_on": "2012-12-05T19:15:04+00:00",
"solver": "SR8",
"submitted_on": "2012-12-05T19:06:57+00:00",
"type": "ising",
"id": "0b759042-726e-4665-b04b-3b42e1ed0b01",
"label": "Structural Network: problem 5"
},
{
"status": "COMPLETED",
"solved_on": "2012-12-05T19:15:07+00:00",
"solver": "SR8",
"submitted_on": "2012-12-05T19:06:57+00:00",
"type": "ising",
"id": "80387b7a-0976-43da-8ed0-e7a27821c177",
"label": "Structural Network: problem 5"
}
]
Response codes are as follows:
| Response Code | Meaning |
|---|---|
200 |
Response contains valid problems list. |
404 |
Problem with specified ID does not exist. |
429 |
Number of API requests exceeds the permitted limit. |
Get Problem¶
Request¶
To retrieve a previously submitted problem, make an HTTP GET request to $SAPI_HOME/problems/:
$SAPI_HOME/problems/<problem_id>/
When possible, if you want more than one problem, submit the request in a single query.
Response¶
When a problem is solved, the system includes the specified problem formatted as a JSON object in its response.
Example of the output:
{ "status": "PENDING", "solved_on": null, "solver": "4.7_C4_19091607.17_C6", "submitted_on": "2018-01-18T10:06:10.025064", "type": "ising", "id": "894fb8e7-4176-4b39-92f4-10ad56432f09", "label": "Structural Network: problem 5" }
Response codes are as follows:
| Response Code | Meaning |
|---|---|
200 |
Success |
404 |
Problem with specified ID does not exist. |
429 |
Number of API requests exceeds the permitted limit. |
Get Problem Information¶
Request¶
To retrieve information about a problem, make an HTTP GET request to $SAPI_HOME/problems/<problem ID>/info:
This example uses curl:
$ curl -H "X-Auth-Token: $SAPI_TOKEN" -X GET "$SAPI_HOME/problems/b46176c1-4089-4772-804f-2028cbf2e9a4/info"
Response¶
Returns information about the problem including the problem ID, the problem or an ID for a large problem uploaded in multiple parts by Upload Data in a Multi-Part Upload, metadata about the submission, and the answer returned by the solver.
Below is an edited example of a JSON-encoded problem answer in a response message:
{"id": "b46176c1-4089-4772-804f-2028cbf2e9a4",
"data":
{"format": "ref",
"data": "bd8d6ec0-4435-4f44-bed8-70d9e322f8b9"},
"params":
{"time_limit": 2},
"metadata":
{"submitted_by": "ISDE-3fthis99is99an99api99toek0667c04",
"solver": "hybrid_v1",
"type": "bqm",
"submitted_on": "2020-01-21T18:12:41.860425Z",
"solved_on": "2020-01-21T18:12:43.980222Z",
"earliest_estimated_completion": "2020-01-21T18:12:43.860425Z",
"latest_estimated_completion": "2020-01-21T18:13:10.660425Z",
"status": "COMPLETED",
"messages": [],
"label": "Structural Network: problem 5"},
"answer":
{"format": "bq",
"data":
{"type": "SampleSet",
"version":
{"sampleset_schema": "3.0.0"},
"num_variables": 300,
"num_rows": 1,
"sample_data":
{"type": "array",
"data": [[2567045157, ... , 1140850688, 32]],
"data_type": "uint32",
"shape": [1, 10],
"use_bytes": false},
"sample_type": "float64",
"vectors":
{"energy":
{"type": "array",
"data": [-40.0],
"data_type": "float64",
"shape": [1],
"use_bytes": false},
"num_occurrences":
{"type": "array",
"data": [1],
"data_type": "int64",
"shape": [1],
"use_bytes": false}},
"variable_labels": [0, 1, 2, 3,... 297, 298, 299],
"variable_type": "BINARY",
"info": {}}}}
Get Problem Answer¶
Request¶
To retrieve an answer for the problem, make an HTTP GET request to $SAPI_HOME/problems/:
$SAPI_HOME/problems/<problem_id>/answer/
Response¶
When a problem is solved, the system returns the problem answer formatted as a JSON object, or 404 if none exists.
Below is an example of a JSON-encoded problem answer in a response message:
{
"answer": {
"format": "qp",
"num_variables": 1152,
"solutions": "AwEAAg==",
"energies": "gBSuR+F6lL+AFK5H4XqUv4AUrkfhepS/gBSuR+F6lL8=",
"active_variables": "AQAAAAQAAAA=",
"num_occurrences": "AwAAAAIAAAACAAAAAwAAAA==",
"timing": {
}
}
}
See the Data Encoding for Solutions section for a list of the key-value pairs returned in the response.
Response codes are as follows:
| Response Code | Meaning |
|---|---|
200 |
Success. |
404 |
Answer for the problem does not exist. |
429 |
Number of API requests exceeds the permitted limit. |
Get Problem Messages¶
Request¶
To retrieve messages for a problem, make an HTTP GET request to $SAPI_HOME/problems/.
$SAPI_HOME/problems/<problem_id>/messages/
Response¶
The system returns messages formatted as a JSON object or 404 if an incorrect problem ID is specified.
If there are no messages, an empty list is returned.
Example of the output:
[
{
"timestamp": "2011-06-06T14:24:40.393751",
"message": "Internal SAPI error occurred.",
"severity": "ERROR"
}
]
Response codes are as follows:
| Response Code | Meaning |
|---|---|
200 |
Success. |
404 |
Problem does not exist. |
429 |
Number of API requests exceeds the permitted limit. |