# ソルバークライアント

Amplify SDK からソルバーを実行するには、各ソルバーを抽象化したソルバークライアントを作成して、接続先、API トークン、実行パラメータなどを指定する必要があります。また、ソルバークライアントは対応関係にあるソルバーの扱える変数の種類、制約条件の有無、次数などの機能の情報を持ちます。Amplify SDK はこれを利用して **変数変換**、**次数下げ**、**制約条件の実装**、**ハードウェアトポロジーへの埋め込み** などの **モデル変換** を自動で行います。

## ソルバークライアントの構成

Amplify Annealing Engine (AE) を例として、クライアント {py:class}`~amplify.FixstarsClient` を次のように作成します。

```{testcode}
from amplify import FixstarsClient

client = FixstarsClient()
```

```{tip}
Amplify AE は[ユーザ登録](https://amplify.fixstars.com/register)を行うと無償の API トークンを入手できます。
```

クライアントクラスのほとんどのパラメータは、構築後はソルバーのデフォルト値で初期化 (または未設定) されているため、クライアントごとの必須パラメータを設定すればすぐに使えるようになります。設定が必須のパラメータはクライアントによって異なりますが、多くのクラウド型ソルバーでは `token` アトリビュートに API トークンを設定する必要があります。

```{testcode}
client.token = "YOUR_API_TOKEN"
```

全てのクライアントにおいて、ソルバーの実行パラメータの取得と設定は `parameters` プロパティ内のアトリビュートに設定します。設定項目は可能な限りソルバーの API に即しているため、詳細は下記の各ソルバーのリファレンスを参照してください。

たとえば Amplify AE では、実行時間を次のように設定します。

```{testcode}
from datetime import timedelta

client.parameters.timeout = timedelta(milliseconds=1000)  # 1000 ミリ秒
```

```{tip}
各クライアントのパラメータごとに時間の単位や時刻のフォーマットが異なるため、Amplify SDK では {py:mod}`datetime` モジュールを利用して入出力できるようになっています。
```

クライアントクラスに設定したパラメータは、{py:class}`str` や {py:func}`print` 関数によって文字列として表示することができます。

```{doctest}
>>> print(client)   # doctest: +NORMALIZE_WHITESPACE
{"url":"https://optigan.fixstars.com","token":"YOUR_API_TOKEN","compression":true,"parameters":{"outputs":{},"timeout":1000}}
```

一部のパラメータでは {py:obj}`None` を設定すると、未設定つまりソルバーのデフォルト値が使用されます。

```{testcode}
client.parameters.timeout = None  # ソルバーのデフォルト値にリセット
```

## ソルバークライアントの一覧

(solver-clients)=

Amplify SDK は下記のソルバー・マシンに対応しています。

``````{grid} 2
:gutter: 3
`````{grid-item-card} [Fixstars Amplify Annealing Engine](https://amplify.fixstars.com/ja/engine)
````{button-ref} amplify.FixstarsClient
:expand:
amplify.FixstarsClient
````
^^^
{bdg-primary}`QUBO` {bdg-success}`GPU` {bdg-secondary}`☁️ Cloud`
+++
````{grid} 2
:margin: 0
:padding: 0
```{grid-item}
:margin: 0
:padding: 0 0 2 2
[{bdg-info}`📖 API Reference`](https://amplify.fixstars.com/ja/docs/amplify/v0/amplify-ae/reference.html)
```
```{grid-item}
:margin: 0
:padding: 0 0 2 2
:class: sd-text-right
[Learn more »](#clients-FixstarsClient)
```
````
`````
`````{grid-item-card} [D-Wave Advantage](https://docs.dwavesys.com/docs/latest/doc_getting_started.html)
````{button-ref} amplify.DWaveSamplerClient
:expand:
amplify.DWaveSamplerClient
````
^^^
{bdg-primary}`QUBO` {bdg-primary}`Ising` {bdg-success}`QPU` {bdg-secondary}`☁️ Cloud` {bdg-warning}`Pegasus Graph`
+++
````{grid} 2
:margin: 0
:padding: 0
```{grid-item}
:margin: 0
:padding: 0 0 2 2
[{bdg-info}`📖 Parameter Reference`](https://docs.dwavesys.com/docs/latest/c_solver_parameters.html)
```
```{grid-item}
:margin: 0
:padding: 0 0 2 2
:class: sd-text-right
[Learn more »](#clients-DWaveSamplerClient)
```
````
`````
`````{grid-item-card} [Leap's Hybrid BQM Solver](https://docs.dwavesys.com/docs/latest/doc_leap_hybrid.html)
````{button-ref} amplify.LeapHybridSamplerClient
:expand:
amplify.LeapHybridSamplerClient
````
^^^
{bdg-primary}`QUBO` {bdg-success}`Hybrid` {bdg-secondary}`☁️ Cloud`
+++
````{grid} 2
:margin: 0
:padding: 0
```{grid-item}
:margin: 0
:padding: 0 0 2 2
[{bdg-info}`📖 Parameter Reference`](https://docs.dwavesys.com/docs/latest/c_solver_parameters.html)
```
```{grid-item}
:margin: 0
:padding: 0 0 2 2
:class: sd-text-right
[Learn more »](#clients-LeapHybridSamplerClient)
```
````
`````
`````{grid-item-card} [Leap's Hybrid CQM Solver](https://docs.dwavesys.com/docs/latest/doc_leap_hybrid.html)
````{button-ref} amplify.LeapHybridCQMSamplerClient
:expand:
amplify.LeapHybridCQMSamplerClient
````
^^^
{bdg-primary}`MIP` {bdg-success}`Hybrid` {bdg-secondary}`☁️ Cloud`
+++
````{grid} 2
:margin: 0
:padding: 0
```{grid-item}
:margin: 0
:padding: 0 0 2 2
[{bdg-info}`📖 Parameter Reference`](https://docs.dwavesys.com/docs/latest/c_solver_parameters.html)
```
```{grid-item}
:margin: 0
:padding: 0 0 2 2
:class: sd-text-right
[Learn more »](#clients-LeapHybridCQMSamplerClient)
```
````
`````
`````{grid-item-card} [Fujitsu DA4 Solver](https://www.fujitsu.com/jp/digitalannealer/)
````{button-ref} amplify.FujitsuDA4Client
:expand:
amplify.FujitsuDA4Client
````
^^^
{bdg-primary}`QUBO` {bdg-success}`GPU` {bdg-secondary}`☁️ Cloud`
+++
````{grid} 2
:margin: 0
:padding: 0
```{grid-item}
:margin: 0
:padding: 0 0 2 2
[{bdg-info}`📖 API Reference`](https://portal.aispf.global.fujitsu.com/apidoc/da/jp/api-ref/da-qubo-v4-ja.html)
```
```{grid-item}
:margin: 0
:padding: 0 0 2 2
:class: sd-text-right
[Learn more »](#clients-FujitsuDA4Client)
```
````
`````
`````{grid-item-card} [Fujitsu DA3c Solver](https://www.fujitsu.com/jp/digitalannealer/)
````{button-ref} amplify.FujitsuDA3cClient
:expand:
amplify.FujitsuDA3cClient
````
^^^
{bdg-primary}`QUBO` {bdg-success}`GPU` {bdg-secondary}`☁️ Cloud`
+++
````{grid} 2
:margin: 0
:padding: 0
```{grid-item}
:margin: 0
:padding: 0 0 2 2
[{bdg-info}`📖 API Reference`](https://portal.aispf.global.fujitsu.com/apidoc/da/jp/api-ref/da-qubo-v3c-ja.html)
```
```{grid-item}
:margin: 0
:padding: 0 0 2 2
:class: sd-text-right
[Learn more »](#clients-FujitsuDA3cClient)
```
````
`````
`````{grid-item-card} [TOSHIBA SQBM+ V2](https://www.global.toshiba/jp/products-solutions/ai-iot/sbm.html)
````{button-ref} amplify.ToshibaSQBM2Client
:expand:
amplify.ToshibaSQBM2Client
````
^^^
{bdg-primary}`QUBO` {bdg-success}`GPU` {bdg-secondary}`☁️ Cloud`
+++
````{grid} 2
:margin: 0
:padding: 0
```{grid-item}
:margin: 0
:padding: 0 0 2 2
[{bdg-info}`📖 User Guide (v2.0.3)`](/../_static/User_Manual-SQBM+_for_On-premises.pdf)
```
```{grid-item}
:margin: 0
:padding: 0 0 2 2
:class: sd-text-right
[Learn more »](#clients-ToshibaSQBM2Client)
```
````
`````
`````{grid-item-card} [NEC Vector Annealing サービス 2.0](https://jpn.nec.com/nec-vector-annealing-service/)
````{button-ref} amplify.NECVA2Client
:expand:
amplify.NECVA2Client
````
^^^
{bdg-primary}`QUBO` {bdg-success}`VE` {bdg-secondary}`☁️ Cloud`
+++
````{grid} 2
:margin: 0
:padding: 0
```{grid-item}
:margin: 0
:padding: 0 0 2 2
[{bdg-info}`📖 User Guide`](/../_static/nec_vector_annealing_service_2.0_user_guide_v4.pdf)
```
```{grid-item}
:margin: 0
:padding: 0 0 2 2
:class: sd-text-right
[Learn more »](#clients-NECVA2Client)
```
````
`````
`````{grid-item-card} [Gurobi Optimization](https://www.gurobi.com/)
````{button-ref} amplify.GurobiClient
:expand:
amplify.GurobiClient
````
^^^
{bdg-primary}`MIP` {bdg-success}`CPU` {bdg-secondary}`💻 Local`
+++
````{grid} 2
:margin: 0
:padding: 0
```{grid-item}
:margin: 0
:padding: 0 0 2 2
[{bdg-info}`📖 Reference Manual`](https://www.gurobi.com/documentation/current/refman/index.html)
```
```{grid-item}
:margin: 0
:padding: 0 0 2 2
:class: sd-text-right
[Learn more »](#clients-GurobiClient)
```
````
`````
``````

---

{bdg-primary}`QUBO` {bdg-primary}`Ising` {bdg-primary}`MIP`
: ソルバーが直接扱える問題の種類を表します。

    - {bdg-primary}`QUBO` バイナリ変数の二次多項式の目的関数を求解できるソルバーです。基本的には制約条件は扱えませんが、ソルバーによっては等式制約、不等式制約の入力に対応しています。
    - {bdg-primary}`Ising` イジング変数の二次多項式の目的関数を求解できるソルバーです。基本的には制約条件は扱えませんが、ソルバーによっては等式制約、不等式制約の入力に対応しています。
    - {bdg-primary}`MIP` 混合整数計画問題を求解できるソルバーです。バイナリ変数、整数変数と実数変数を扱うことができます。 一般的には一次の問題 (線形計画問題) を対象としていますが、QUBO を含む二次の問題を扱うことができるソルバーもあります。

    ```{note}
    Amplify SDK は、ソルバーが直接扱えない問題に対して、自動で変数変換や次数下げ、制約条件のペナルティ関数の生成といった変換を行います。そのため、ユーザが自身でソルバーが直接扱える形式の問題を作成する必要は必ずしもありません。ただし、ソルバーの種類や入力するモデルの種類によっては、未対応であったり、厳密な定式化にならないことがあります。詳細は [](conversion.md) を参照してください。
    ```

{bdg-warning}`Graph`
: ソルバーに入力できる二次の項を表します。これらのタグがついていないソルバーには、二次の項に関する制限はありません。そうでないソルバーは、与えられる二次の項に制限があり、任意の二次多項式を解くためにはグラフ埋め込みと呼ばれる操作が必要です。扱える問題のサイズは、ソルバーに入力可能な変数の数 $N$ に対して最悪ケースで $O\left( \sqrt N \right)$ 程度になります。詳細は「[](graph.md)」を参照してください。

{bdg-success}`CPU` {bdg-success}`GPU` {bdg-success}`VE` {bdg-success}`QPU` {bdg-success}`Hybrid`
: マシンの動作する演算装置の種類を表します。VE は NEC SX-Aurora TSUBASA Vector Engine を表します。Hybrid は QPU とその他の技術のハイブリッドソルバーである事を表します。

{bdg-secondary}`☁️ Cloud` {bdg-secondary}`💻 Local`
: クラウドサービスとして提供されるソルバーなのか、ユーザのマシンにインストールする必要があるソルバーなのかを表します。