Annealing Cloud Web API provides annealing machine operations using the Ising model as a Web API that
communicates via HTTP.
In Web API v2, you can choose to run the ASIC version (4bit), GPU (King's graph) version (32bit/int),
or GPU (King's graph) version (32bit/float).
Please see About CMOS Annealing Machine to learn
more.
https://annealing−cloud.com/api/v2/
Add the Authorization: Bearer
to the request header and set the token.
To get the API token, please request a token. The
expiration date of the token is 30 days from when it was issued.
Authorization: Bearer XXXXXXXXXXXXXXXXXXXXX
Both input and output are in JSON format. Please set the input parameters in the HTTP body in the specified JSON format.
Request execution example (cURL case)
$ curl -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXX ' -d '{"type" : 5, "model": [ [0,0,0,0,1], [0,1,0,0,-1] ]}' https://annealing-cloud.com/api/v2/solve
Set the status code for the result of communication. Basically, HTTP status is set to 200, except for
statuses
undecidable by the system such as communication error, and it is notified by status
of
response JSON.
code | status | reason |
---|---|---|
0 | Success | - |
3 | Authorization error | Token Authorization error (or token expired) |
10 | Busy | Server is waiting in queue |
17 | Type specification error | Specified type does not exist |
33 | Hardware error | |
49 | Invalid JSON format | |
50 | Invalid parameter | Invalid parameter is included |
51 | Required error | Required item is not set |
52 | Model setting range error | Coordinate that exceeds the allowable range is set |
53 | Model setting value error | Value that exceeds the allowable range is set |
255 | Unknown error | Unknown error |
key | Description | Required | Data type | Minimum value | Maximum value | Default value |
---|---|---|---|---|---|---|
type | Execution machine type |
- | integer | - | - | - |
num_executions | Annealing execution count | - | integer | 1 | 10 | 1 |
model | Two dimensional array representing Ising model |
◯ | array | * Described in the next paragraph | - | |
parameters | Execution parameter control setting | - | object | - | - | - |
temperature_num_steps | Temperature change step number | - | integer | 1 | 100 | 10 |
temperature_step_length | Length per temperature step | - | integer | 1 | 1000 | 100 |
temperature_initial | Initial temperature | - | number | 0 or more *1 |
3.402823e+38 | 10.0 |
temperature_target | Final temperature | - | number | 0 or more *1 |
3.402823e+38 | 0.01 |
outputs | Control of values included in response | - | object | - | - | - |
energies | Output energy value | - | boolean | - | - | true |
spins | Output spin value array | - | boolean | - | - | true |
execution_time | Output execution time (nsec) | - | boolean | - | - | false |
num_outputs | Number of outputs of spin value and energy value (Energy value ascending order, 0 outputs all) |
- | integer | 0 | *2 | 0 |
averaged_spins | Output average value per site of spin | - | boolean | - | - | false |
averaged_energy | Output the average value of energy | - | boolean | - | - | false |
You can specify the type of machine to run the process. Please select one of the following options.
3 : GPU 32bit(int)
4 : GPU 32bit(float)
5 : ASIC 4bit
The model parameter is an array of integer values [x0, y0, x1, y1, p]
with 5 elements
representing the vertices or interactions of the Ising model. The order in which they are specified
does
not affect the calculation results.
x and y represent the coordinates (x-axis, y-axis) on the Ising model, respectively, and p represents
the coefficient.
Set the Ising model in the form x0 == x1, y0 == y1
to represent the vertex = first order
term (magnetic field), and set x0, y0
and x1, y1
to be adjacent to each
other to represent the interaction of two vertices.
Adjacent means up-down, left-right, and diagonal. An error occurs if the coordinate specification of two non-adjacent vertices is included.
Set the coordinates xy and the coefficient p within the range that can be specified for each type. If 0 is set for the coefficient, it will be treated as not set.
If you set overlapping coordinates or interactions, p will be added. For example, if
[1, 1, 1, 2, 2]
and [1, 1, 1, 2, -1]
are set at the same time, then
2 + (-1) = 1
, and [1, 1, 1, 2, 1]
is treated as if it were specified. Note
that p can be set as a single item or as a combined value within the specified
range. An error will occur if p is out of the specified range as a result of duplicate addition.
The coordinates and coefficients should be set within the following ranges, respectively:
type: 3
Coordinates: 0 <= x <= 511, 0 <= y <= 511 Coefficient: -2147483648 <= p <= 2147483647
type: 4
Coordinates: 0 <= x <= 511, 0 <= y <= 511 Coefficient: -3.402823e+38 <= p <= 3.402823e+38
type: 5
Coordinates: 0 <= x <= 383, 0 <= y <= 383 Coefficient: -7 <= p <= 7
Parameters to determine the cooling schedule based on geometric cooling used for annealing can be set. When not set, it will operate with the initial value. For details see here.
The content to be included in the return result can be set. When not set, it will operate with the initial value.
・Minimum value
Note that this is a real number greater than or equal to 0, not including 0.
The maximum specified value is the number of times of num_executions of the request.
{
"num_executions": 5,
"model": [
[0,0,0,0,1],
[0,1,0,2,-1],
[1,0,1,1,1],
[1,1,1,2,1],
[2,0,2,1,1],
[2,1,2,2,1],
[0,0,1,0,1],
[1,0,2,0,1],
[0,1,1,1,-1]
],
"parameters": {
"temperature_initial": 30.0,
"temperature_target": 0.0000001
},
"outputs": {
"averaged_spins": true,
"averaged_energy": true
}
}
key | Description | Data type | Setting example |
---|---|---|---|
status | Web API execution result | integer | 0 |
message | Message (Set only for error) |
string | Invalid json format |
job_id | ID identifying the job | string | b26315de-a2b2-4766-b9fd-42ad34139512 |
result | Execution result | - | - |
execution_time | Execution time (nsec) | number | 431290200 |
energies | Energy value Array of number of executions |
array | [-3.0,-3.0,-2.0] |
spins | Spin Three-dimensional array for the number of executions |
array | [[[0,1,1],[1,0,-1],[1,2,1]],[[0,1,-1], ... |
averaged_energy | Average value of energy | number | -5.0 |
averaged_spins | Average per spin site | array | [[0,1,1],[1,0,-1],[1,2,1]] |
{
"status": 0,
"result": {
"energies": [-3.0,-3.0,-2.0],
"execution_time":61881392,
"spins":[[[1,0,1],[0,1,1],[1,2,1]],[[1,0,1],[0,1,1],[1,2,1]],[[1,0,1],[0,1,1],[1,2,1]]]
},
"job_id":"b26315de-a2b2-4766-b9fd-42ad34139512"
}