# クイックスタート

次のいずれかの方法で Amplify SDK を実行できます。

````{grid} 1 1 1 1
:padding: 2 2 4 4
:gutter: 4
```{grid-item-card}  💻 自身のPCにインストールして実行する
:link: how-to-install
:link-type: ref

この手順では自身のPCに Amplify SDK をインストールしてサンプルコードを実行します。

* PC に Python のインストールが必要です。
* ソルバーの実行には **Amplify Annealing Engine** の API トークンが必要です。  
```
%```{grid-item-card}  🧪 Google Collab で実行する
%:link: https://colab.research.google.com
%:link-type: url

%Google Collab を用いて Amplify SDK のサンプルコードを実行します。  

%* 事前に Google アカウントが必要です。
%* ソルバーの実行には **Amplify Annealing Engine** の API トークンが必要です。
%```
```{grid-item-card}  ☁️ BinderHub で試してみる
:link: https://amplify.fixstars.com/demo
:link-type: url

Amplify のチュートリアルページでサンプルコードを試すことができます。

* **Amplify Annealing Engine** の API トークンが無くても実行できます。
* ページの有効期限 (20分程度) が切れると、入力した内容や実行結果が破棄されます。
```
````

```{note}
サンプルコードの実行には *Amplify Annealing Engine* の API トークンが必要です。  
Amplify の[ユーザ登録](https://amplify.fixstars.com/register)を行うことで、誰でも無償で API トークンを取得できます。
```

(how-to-install)=

## インストール

Amplify SDK は次の環境において動作を確認しています。

````{grid} 1 2 2 2
:gutter: 5
:padding: 2 2 5 5
```{grid-item-card}  Python バージョン
* 3.8
* 3.9
* 3.10
* 3.11
* 3.12
```
```{grid-item-card}  サポート OS
* Windows 10/11
* Linux
    * Ubuntu 20.04/22.04, Rocky Linux 8/9
    * x86_64, ARM64

* macOS
    * x86_64 (Catalina 以降)
    * ARM64 (BigSur 以降)
```
````

最初に、お使いの Python のバージョンが上記のリストに含まれることを確認してください。

```bash
$ python3 --version
```

Amplify SDK は [PyPI](https://pypi.org/project/amplify/) からインストールできます。次のコマンドで自身の環境にインストールされます。

```bash
$ python3 -m pip install -U amplify
```

````{hint}
D-Wave のマシンを使う場合や QAOA などの量子アルゴリズムを使う場合は、次のコマンドで追加のパッケージを含めてインストールしてください。

```bash
$ python3 -m pip install -U 'amplify[extra]'
```

```{caution}
Python のバージョンによっては追加パッケージが対応していないことがあります。
```
````

Amplify SDK が正しくインストールされると、次のようにしてインストールされたバージョンを確認できます。

```python
>>> import amplify
>>> amplify.__version__
1.2.0
```

## サンプルコードの実行

インストールが完了したら、Amplify を用いて簡単な QUBO の問題を解いてみましょう。ここではソルバーとして [Fixstars Amplify Annealing Engine](https://amplify.fixstars.com/engine) (以下 Amplify AE) を使います。Amplify AE のアカウントを持っていない場合は、[こちら](https://amplify.fixstars.com/register)から登録して、API トークンを取得してください。

サンプル問題として次を考えます。

```{card} Sample QUBO Problem
:width: 50%
:margin: 3 3 auto auto
目的関数
:   $$
    \text{minimize:} \quad f = q_0 q_1 + q_0 - q_1 + 1
    $$

決定変数
:   $$
    q_0, q_1 \in \{0, 1\}
    $$

制約条件
:   $$
    \text{None}
    $$
```

少し考えると、関数 $f$ は $q_0 = 0$, $q_1 = 1$ のときに最小値 $f = 0$ となることがわかります。この問題を Amplify で解いて正しい答えが得られるか確認しましょう。

### 1. 変数配列の作成

組合せ最適化問題の解を Amplify SDK で得るためには **目的関数**、**決定変数**、**制約条件** をプログラムコード内で定義する必要があります。

まずは決定変数を定義します。上記のサンプル問題では 0 または 1 の値をとるバイナリ変数 $q_0$, $q_1$ が決定変数です。次のように、決定変数を発行する {py:class}`~amplify.VariableGenerator` クラスを用いて、長さ 2 の変数配列 `q` を定義します。

```{doctest}
>>> from amplify import VariableGenerator
>>> gen = VariableGenerator()     # 決定変数のジェネレータを作成
>>> q = gen.array("Binary", 2)    # 2つのバイナリ変数を持つ変数配列を作成
>>> print(q)
[q_0, q_1]
```

### 2. 目的関数の作成

次に、定義した変数を用いて目的関数を作成します。サンプル問題の目的関数 $f = q_0 q_1 + q_0 - q_1 + 1$ は、変数配列 `q`{l=python} を用いて次のように定義できます。変数 $q$ の添え字が配列のインデックスに対応することに注意してください。

```{doctest}
>>> f = q[0] * q[1] + q[0] - q[1] + 1
>>> print(f)
q_0 q_1 + q_0 - q_1 + 1
```

今回のサンプル問題には制約条件がないため、以上で定式化は完了です。

### 3. ソルバークライアントの作成

今回はソルバーとして Amplify AE を使用するため、ソルバークライアントとして Amplify AE のクライアントクラス ({py:class}`~amplify.FixstarsClient`) を作成します。

定式化した問題を Amplify AE に送信するために API トークンを設定する必要があります。これは、{py:class}`~amplify.FixstarsClient` の {py:attr}`~amplify.FixstarsClient.token` プロパティに API トークンを与えることで設定できます。加えて、ここではソルバーの実行時間を 1秒に設定しておきます。

```{doctest}
>>> from amplify import FixstarsClient
>>> client = FixstarsClient()
>>> client.token = "***input your token***" # doctest: +SKIP
>>> client.parameters.timeout = 1000    # 実行時間を 1000 ミリ秒に設定
```

### 4. ソルバーの実行

ソルバーの実行は {py:func}`~amplify.solve` 関数を用いて行います。この関数は定式化した問題とソルバークライアントを引数として受け取り、ソルバーの実行結果を返します。

```{doctest}
>>> from amplify import solve
>>> result = solve(f, client)
```

### 5. 結果の確認

実行結果は {py:class}`~amplify.Result` クラスのインスタンスとして返されます。このインスタンスにはソルバーを実行した結果や行われたモデルの変換情報などが含まれます。使用するソルバーやパラメータの設定によって複数の解が含まれることがありますが、{py:class}`~amplify.Result.best` プロパティを呼び出すことで得られた解のうち最も良い解を {py:class}`~amplify.Result.Solution` クラスのインスタンスとして取得できます。{py:class}`~amplify.Result.Solution` クラスには変数の値や目的関数の値が格納されています。

```{doctest}
>>> result.best.objective   # 目的関数の値
0.0
>>> result.best.values      # 変数の値
Values({Poly(q_0): 0, Poly(q_1): 1})
```

変数の値は決定変数とその値をキーと値に設定した辞書として扱える {py:class}`~amplify.Values` クラスのインスタンスとして得られます。解を見やすくするために、変数配列の {py:class}`~amplify.PolyArray.evaluate` メソッドを用いて、配列要素の変数を {py:class}`~amplify.Values` クラスの値で置き換えた配列が得られます。

```{doctest}
>>> print(f"{q} = {q.evaluate(result.best.values)}")
[q_0, q_1] = [0. 1.]
```

以上より、今回のサンプル問題の解が $q_0 = 0$, $q_1 = 1$ であることがわかりました。

## 次のステップ

以上が Amplify SDK を用いた定式化とソルバー実行の流れです。ここでは非常に簡単な2変数の問題を扱いましたが、上記の手順はより複雑な問題に対しても同様に適用できます。

次のステップとして、Amplify で問題を解きながら学ぶ [チュートリアル](https://amplify.fixstars.com/ja/demo) を実行しましょう。  
Amplify SDK の機能について詳しく知りたい方は引き続き [](overview.md) に進んでください。

`````{grid} 1 2 2 2
:margin: 4 0 0 0
````{grid-item-card}  ☁️ 具体的な問題を解きたい
:margin: auto
```{button-link} https://amplify.fixstars.com/demo
:color: info
:click-parent:
:expand:
**チュートリアルに進む** 
```
````
````{grid-item-card}  ⏩ 機能を詳しく知りたい
:margin: auto
```{button-ref} overview
:ref-type: doc
:color: success
:click-parent:
:expand:
**Amplify SDK の全体像に進む**
```
````
`````