Client

This section describes the Ising machine clients.

Client Class Overview

The client class provides an interface to obtain and set hardware parameters for each Ising machine, and also to handle input and execution of given problems. There are two types of parameter settings:

  • Settings for access information to the Ising machine

  • Settings for hardware execution parameters

The interfaces to the parameters are classified in each category.

The followings are the common inputs for both inputting and executing problems.

Each of the above models needs to be a “physical model”. In other words, the coupling between variables in the models is associated with a graph that is based on hardware specifications, and depending on the graph, the coupling between variables may be restricted. In addition, some Ising machines may have their own input format.

The client class can also be used as a direct solver for the physical model, but the solver class can be used as a solver for the logical model by giving the client object as a driver for the solver class Solver. In the latter case, the solver class takes over the operations of the client object, so there is no need for direct execution operations.

Note

For normal use, the execution procedures using the solver class are recommended. See Solver for specific instructions.

Common Interface

Attribute

All clients have the following attributes in common. The ones with optional are provided for some clients only.

  • num_bits : Obtain the maximum number of physical bits that can be executed by the Ising machine.

  • parameters : Obtain the execution parameters specific to each client.

  • version : Obtain the client version information.

  • url : Obtain and set the API endpoint URL.

  • proxy : Obtain and set the proxy server address.

  • token (optional) : Obtain and set the API token.

  • compression (optional) : Compress (if possible) and forward the transmitted data.

Method

All clients have the solve() method in common. The followings are the possible inputs. The second argument of the input for the matrix object represents a constant term.

The solve() method returns an object of the client-specific ClientResult class.

The ClientResult class has the following attributes in common. The one with optional is only provided for some clients.

  • annealing_time_ms : Obtain the (typical) execution time in milliseconds.

  • execution_parameters (optional) : Obtain the execution parameters.

  • timing : Obtain the execution parameters.

  • solutions : Obtain a list of execution results. Each element has the following attributes.

    • energy : Obtain the energy value (evaluated value of the physical model).

    • values : Obtain the values of physical variables as a list.

    • frequency : Obtain the number of identical solutions.

The following operator overloading is also implemented. For example, the following is provided for the instance result of the ClientResult class

  • result[n] (__getitem__) : Transparently return element access result.solutions[n] to index n of solutions.

  • len(result) (__len__) : Transparently return len(result.solutions), the number of elements in solutions.

  • for s in result: (__iter__) : Transparently return the result.solutions iterator.

Note

See the client reference Client for the details of each client and related classes.

Fixstars

Name

Fixstars Amplify Annealing Engine

Client class

FixstarsClient

Execution parameter class

FixstarsClientParameters

Execution result class

FixstarsClientResult

Execution time class

FixstarsClientResultTiming

Physical graph

Fully Connected coupling

Number of physical bits

65536~

Number of logical bits (Fully connected coupling)

65536~

API endpoint (default)

https://optigan.fixstars.com/

Example

from amplify import BinaryPoly, gen_symbols
from amplify.client import FixstarsClient

q = gen_symbols(BinaryPoly, 8)
f = 2 * q[0] * q[4] - q[0] - q[4] + 1

client = FixstarsClient()
client.token = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
client.parameters.timeout = 1000  # Timeout is 1 second

result = client.solve(f)
>>> f
2.000000 q_0 q_4 - q_0 - q_4 + 1.000000
>>> [f"energy = {s.energy}, q[0] = {s.values[0]}, q[4] = {s.values[4]}" for s in result]
['energy = 0.0, q[0] = 0, q[4] = 1']

D-Wave

Name

D-Wave Sampler (Ocean SDK)

Client class

DWaveSamplerClient

Execution parameter class

DWaveSamplerClientQuantumSolverParametersOcean

Execution result class

DWaveSamplerClientResult

Execution time class

DWaveSamplerClientResultTiming

Physical graph

Pegasus graph (Advantage_system1.1)、Chimera graph (DW_2000Q_6, DW_2000Q_VFYC_6)

Number of physical bits

5436 (Advantage_system1.1), 2041 (DW_2000Q_6), 2048 (DW_2000Q_VFYC_6)

Number of logical bits (Fully connected coupling)

123 (Advantage_system1.1), 64 (DW_2000Q_6, DW_2000Q_VFYC_6)

API endpoint (default)

https://cloud.dwavesys.com/sapi

Name

Leap Hybrid Solver (Ocean SDK)

Client class

LeapHybridSamplerClient

Execution parameter class

LeapHybridSamplerClientLeapHybridSolverParameters

Execution result class

LeapHybridSamplerClientResult

Execution time class

LeapHybridSamplerClientResultTiming

Physical graph

Fully Connected coupling

Number of physical bits

10000

Number of logical bits (Fully connected coupling)

10000

API endpoint (default)

https://cloud.dwavesys.com/sapi

Name

D-Wave SAPI (deprecated: aliases of D-Wave Sampler)

Client class

DWaveClient

Execution parameter class

DWaveClientQuantumSolverParameters

Execution result class

DWaveClientResult

Execution time class

DWaveClientResultTiming

Note

In order to use D-Wave Sampler and Leap Hybrid Solver, the dwave-system module needs to be installed.

Note

The client class DWaveClient will be removed in a future update. Currently it is an alias for DWaveSamplerClient.

Attribute

Additionally it has the following attributes.

  • solver : Obtain and set the solver name to be used.

  • solver_names : Obtain a list of solvers available in D-Wave Cloud.

Example

DWaveClient

from amplify import BinaryPoly, gen_symbols
from amplify.client import DWaveClient

q = gen_symbols(BinaryPoly, 8)
f = 2 * q[0] * q[4] - q[0] - q[4] + 1

client = DWaveClient()
client.token = "XXXX-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
client.solver = "DW_2000Q_VFYC_6"
client.parameters.num_reads = 100  # Execution count

result = client.solve(f)
>>> f
2.000000 q_0 q_4 - q_0 - q_4 + 1.000000
>>> client.solver_names
['c4-sw_sample', 'DW_2000Q_VFYC_6', 'c4-sw_optimize', 'DW_2000Q_6', 'hybrid_binary_quadratic_model_version2', 'Advantage_system1.1']
>>> [f"energy = {s.energy}, q[0] = {s.values[0]}, q[4] = {s.values[4]}" for s in result]
['energy = 0.0, q[0] = 0, q[4] = 1',
 'energy = 0.0, q[0] = 1, q[4] = 0']

DWaveSamplerClient

from amplify import BinaryPoly, gen_symbols
from amplify.client.ocean import DWaveSamplerClient

client = DWaveSamplerClient()
client.token = "XXXX-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
client.solver = "Advantage_system1.1"
client.parameters.num_reads = 100  # Execution count

# The given problem must follow the graph structure of `client.solver` (Pegasus graph, Chimera graph).
# For example, "Advantage_system1.1" does not have any nodes between 0 and 29, so we need to give it a polynomial consisting of the indices after that.
q = gen_symbols(BinaryPoly, 32)
f = 2 * q[30] * q[31] - q[30] - q[31] + 1

result = client.solve(f)
>>> f
2.000000 q_30 q_31 - q_30 - q_31 + 1.000000
>>> [f"energy = {s.energy}, q[30] = {s.values[30]}, q[31] = {s.values[31]}" for s in result]
['energy = 0.0, q[30] = 0, q[31] = 1',
 'energy = 0.0, q[30] = 1, q[31] = 0']

Note

The following parameters are currently not supported in Advantage_system1.1.

  • beta

  • chains

  • postprocess

Note

The physical graph of a D-Wave machine is a Pegasus graph (Chimera graph). The method solve will only solve problems along the Pegasus graph (Chimera graph). For example, the following problem will result in an error:

from amplify import BinaryPoly, gen_symbols
from amplify.client.ocean import DWaveSamplerClient

client = DWaveSamplerClient()
client.token = "XXXX-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
client.solver = "DW_2000Q_VFYC_6" # Physical graph is chimera graph


q = gen_symbols(BinaryPoly, 2)
f = 2 * q[0] * q[1] # Incorrect problem (there is no coupling between 0 and 1 in the chimera graph)

# result = client.solve(f) # Error: Problem graph incompatible with solver

LeapHybridSamplerClient

from amplify import BinaryPoly, gen_symbols
from amplify.client.ocean import LeapHybridSamplerClient

q = gen_symbols(BinaryPoly, 8)
f = 2 * q[0] * q[4] - q[0] - q[4] + 1

client = LeapHybridSamplerClient()
client.token = "XXXX-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
client.solver = "hybrid_binary_quadratic_model_version2"
client.parameters.time_limit = 3  # Time limit is 3 seconds

result = client.solve(f)
>>> f
2.000000 q_0 q_4 - q_0 - q_4 + 1.000000
>>> [f"energy = {s.energy}, q[0] = {s.values[0]}, q[4] = {s.values[4]}" for s in result]
['energy = 0.0, q[0] = 0, q[4] = 1']

Fujitsu

Name

FujitsuDASolver

Client class

FujitsuDASolverClient

Execution parameter class

FujitsuDASolverClientParameters

Execution result class

FujitsuDASolverClientResult

Execution time class

FujitsuDASolverClientResultTiming

Physical graph

Fully Connected coupling

Number of physical bits

1024

Number of logical bits (Fully connected coupling)

1024

API endpoint (default)

https://api.aispf.global.fujitsu.com/da/

Name

FujitsuDASolver (Expert Mode)

Client class

FujitsuDASolverExpertClient

Execution parameter class

FujitsuDASolverExpertClientParameters

Execution result class

FujitsuDASolverExpertClientResult

Execution time class

FujitsuDASolverExpertClientResultTiming

Physical graph

Fully Connected coupling

Number of physical bits

1024

Number of logical bits (Fully connected coupling)

1024

API endpoint (default)

https://api.aispf.global.fujitsu.com/da/

Name

FujitsuDAPTSolver

Client class

FujitsuDAPTSolverClient

Execution parameter class

FujitsuDAPTSolverClientParameters

Execution result class

FujitsuDAPTSolverClientResult

Execution time class

FujitsuDAPTSolverClientResultTiming

Physical graph

Fully Connected coupling

Number of physical bits

1024

Number of logical bits (Fully connected coupling)

1024

API endpoint (default)

https://api.aispf.global.fujitsu.com/da/

Name

FujitsuDAMixedModeSolver

Client class

FujitsuDAMixedModeSolverClient

Execution parameter class

FujitsuDAMixedModeSolverClientParameters

Execution result class

FujitsuDAMixedModeSolverClientResult

Execution time class

FujitsuDAMixedModeSolverClientResultTiming

Physical graph

Fully Connected coupling

Number of physical bits

1024

Number of logical bits (Fully connected coupling)

1024

API endpoint (default)

https://api.aispf.global.fujitsu.com/da/

Name

FujitsuDA2Solver

Client class

FujitsuDA2SolverClient

Execution parameter class

FujitsuDA2SolverClientParameters

Execution result class

FujitsuDA2SolverClientResult

Execution time class

FujitsuDA2SolverClientResultTiming

Physical graph

Fully Connected coupling

Number of physical bits

8192

Number of logical bits (Fully connected coupling)

8192

API endpoint (default)

https://api.aispf.global.fujitsu.com/da/

Name

FujitsuDA2Solver (Expert Mode)

Client class

FujitsuDA2SolverExpertClient

Execution parameter class

FujitsuDA2SolverExpertClientParameters

Execution result class

FujitsuDA2SolverExpertClientResult

Execution time class

FujitsuDA2SolverExpertClientResultTiming

Physical graph

Fully Connected coupling

Number of physical bits

8192

Number of logical bits (Fully connected coupling)

8192

API endpoint (default)

https://api.aispf.global.fujitsu.com/da/

Name

FujitsuDA2PTSolver

Client class

FujitsuDA2PTSolverClient

Execution parameter class

FujitsuDA2PTSolverClientParameters

Execution result class

FujitsuDA2PTSolverClientResult

Execution time class

FujitsuDA2PTSolverClientResultTiming

Physical graph

Fully Connected coupling

Number of physical bits

8192

Number of logical bits (Fully connected coupling)

8192

API endpoint (default)

https://api.aispf.global.fujitsu.com/da/

Name

FujitsuDA2MixedModeSolver

Client class

FujitsuDA2MixedModeSolverClient

Execution parameter class

FujitsuDA2MixedModeSolverClientParameters

Execution result class

FujitsuDA2MixedModeSolverClientResult

Execution time class

FujitsuDA2MixedModeSolverClientResultTiming

Physical graph

Fully Connected coupling

Number of physical bits

8192

Number of logical bits (Fully connected coupling)

8192

API endpoint (default)

https://api.aispf.global.fujitsu.com/da/

Name

FujitsuDA3SolverClient

Client class

FujitsuDA3SolverClient

Execution parameter class

FujitsuDA3SolverClientParameters

Execution result class

FujitsuDA3SolverClientResult

Execution time class

FujitsuDA3SolverClientResultTiming

Physical graph

Fully Connected coupling

Number of physical bits

100000

Number of logical bits (Fully connected coupling)

100000

API endpoint (default)

https://api.aispf.global.fujitsu.com/da/

Attribute

Additionally it has the following attributes.

Example

FujitsuDA2PTSolverClient

from amplify import BinaryPoly, gen_symbols
from amplify.client import FujitsuDA2PTSolverClient

q = gen_symbols(BinaryPoly, 8)
f = 2 * q[0] * q[4] - q[0] - q[4] + 1

client = FujitsuDA2PTSolverClient()
client.token = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
client.parameters.number_iterations = 1000

result = client.solve(f)
>>> f
2.000000 q_0 q_4 - q_0 - q_4 + 1.000000
>>> [f"energy = {s.energy}, q[0] = {s.values[0]}, q[4] = {s.values[4]}" for s in result]
['energy = 0.0, q[0] = 0, q[4] = 1',
 'energy = 0.0, q[0] = 1, q[4] = 0']

Toshiba

Name

Toshiba SBM

Client class

ToshibaClient

Execution parameter class

ToshibaClientParameters

Execution result class

ToshibaClientResult

Execution time class

ToshibaClientResultTiming

Physical graph

Fully Connected coupling

Number of physical bits

10000

Number of logical bits (Fully connected coupling)

10000

API endpoint (default)

N/A

Example

ToshibaClient

from amplify import BinaryPoly, gen_symbols
from amplify.client import ToshibaClient

q = gen_symbols(BinaryPoly, 8)
f = 2 * q[0] * q[4] - q[0] - q[4] + 1

client = ToshibaClient()
client.url = "http://xxx.xxx.xxx.xxx"
client.parameters.timeout = 1  # Timeout is 1 second

result = client.solve(f)
>>> f
2.000000 q_0 q_4 - q_0 - q_4 + 1.000000
>>> [f"energy = {s.energy}, q[0] = {s.values[0]}, q[4] = {s.values[4]}" for s in result]
['energy = 0.0, q[0] = 0, q[4] = 1']

Hitachi

Name

Hitachi CMOS annealing machine (type 4: GPU)

Client class

HitachiClient

Execution parameter class

HitachiClientParameters

Execution result class

HitachiClientResult

Execution time class

HitachiClientResultTiming

Physical graph

King Graph

Number of physical bits

262144 (512x512)

Number of logical bits (Fully connected coupling)

512

API endpoint (default)

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

HitachiClient

from amplify import BinaryPoly, gen_symbols
from amplify.client import HitachiClient

q = gen_symbols(BinaryPoly, 512, 512)
f = -2 * q[0][0] * q[1][1] - q[0][0] - q[1][1] + 1

client = HitachiClient()
client.token = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
client.parameters.temperature_num_steps = 10
client.parameters.temperature_step_length = 100
client.parameters.temperature_initial = 100.0
client.parameters.temperature_target = 0.02

result = client.solve(f)
>>> f
- 2.000000 q_0 q_513 - q_0 - q_513 + 1.000000
>>> [f"energy = {s.energy}, q[0][0] = {s.values[0]}, q[1][1] = {s.values[513]}" for s in result]
['energy = -3.0, q[0][0] = 1, q[1][1] = 1']

Note

The physical graph of the CMOS annealing machine is a king graph of size 512x512. Please note that the index \(i\) of the physical model variable is given by \(i = L x + y\) for coordinates \(x\) and \(y\) on the king graph. Here, \(L = 512\) is the length of one side of the king graph.