API Reference

Web API v2

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.

Basic usage

End point

 https://annealing−cloud.com/api/v2/ 

Authentication method

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 

Parameter type

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

API Status

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.

POST /solve

Request parameter (JSON format)

About setting values

type

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

model

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.

model coordinates and coefficients

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

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.

outputs

The content to be included in the return result can be set. When not set, it will operate with the initial value.

*1 About parameters.temperature_initial/temperature_target

・Minimum value
Note that this is a real number greater than or equal to 0, not including 0.

*2 Maximum value of outputs.num_outputs

The maximum specified value is the number of times of num_executions of the request.

Setting example

{
  "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
  }
}

Response (JSON format)

Setting example

{
  "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"
}