# 旧バージョンからの移行

Amplify SDK v1 は v0 とは一部の互換性が失われています。これまで旧バージョンを使っていた場合に、今後も動作し続けるようにコードを維持するための方法について説明します。

## Amplify SDK v0 を使い続ける

現在のコードの動作環境を全く変更せず維持するために、Amplify SDK v0 を使い続けることができます。Amplify SDK モジュールのインストール時に次のようにしてバージョンに制限をかけることで実現できます。

```bash
$ python3 -m pip install -U 'amplify<1.0.0'
```

追加のパッケージを含める場合は、次のようにします。

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

Amplify SDK v0 のドキュメントは次の URL で参照できます。

```{button-link} https://amplify.fixstars.com/ja/docs/amplify/v0/
:color: primary
:expand:
:outline:
```

```{important}
Amplify SDK v0 は今後も継続的に動作することは保証されません。クリティカルなバグ修正以外の機能追加や、対応ソルバーのアップデートなどは行われません。

また、Python の新バージョンのリリースやソルバーの仕様変更など、周辺環境の変化によっても動作しなくなる可能性があるため注意してください。
```

## Amplify SDK v1 に移行する

次のような方針で v0 で書かれたコードを v1 に移行することができます。

### 決定変数の作成

{py:class}`~amplify.BinarySymbolGenerator` と {py:class}`~amplify.IsingSymbolGenerator` は整数変数、実数変数の追加に伴い {py:class}`~amplify.VariableGenerator` に置き換えられました。変数の種類は {py:meth}`~amplify.VariableGenerator.array`, {py:meth}`~amplify.VariableGenerator.scalar`, {py:meth}`~amplify.VariableGenerator.matrix` メソッドの引数で指定します。

````{dropdown} 従来の書き方:
```{testcode}
from amplify import BinarySymbolGenerator, IsingSymbolGenerator

gen = BinarySymbolGenerator()
q = gen.array(10)

gen = IsingSymbolGenerator()
s = gen.array(shape=(4, 4))
```
````

````{dropdown} 新しい書き方:
```{testcode}
from amplify import VariableGenerator

gen = VariableGenerator()
q = gen.array("Binary", 10)
s = gen.array("Ising", shape=(4, 4))
n = gen.array("Integer", shape=(3, 3), bounds=(0, 10))
x = gen.array("Real", shape=(2, 4), bounds=(-0.5, 0.5))
```
````

### 目的関数の作成

上記のように変数を作成すれば、多項式の構築は以前のバージョンと同様に行えます。ただし、[辞書を用いた構築](https://amplify.fixstars.com/ja/docs/amplify/v0/polynomial.html#id2) は廃止されたため、今後は利用出来ません。

行列形式の目的関数の構築は、直接 Matrix クラスを作成するのではなく、{py:meth}`~amplify.VariableGenerator.matrix` メソッドを用いて作成するように変更されました。また、{py:class}`~amplify.Matrix` クラスは係数の二次、一次、定数の項と含まれる変数を内包するようになりました。詳しくは [](matrix.md) を参照してください。

````{dropdown} 従来の書き方 (現在は動作しません):
```python
from amplify import BinaryMatrix

m = BinaryMatrix(3)

m[0, 0] = -2
m[0, 1] = 1
m[1, 2] = -1
m[2, 2] = 1
```
````

````{dropdown} 新しい書き方:
```{testcode}
from amplify import VariableGenerator

gen = VariableGenerator()
m = gen.matrix("Binary", shape=3)

# 二次の項を取得する
m.quadratic[0, 0] = -2
m.quadratic[0, 1] = 1
m.quadratic[1, 2] = -1
m.quadratic[2, 2] = 1

# 係数行列に対応する変数を取得する
q = m.variable_array
```
````

### 制約条件の作成

制約条件を作成するための関数やクラスは、`amplify.constraint` サブモジュールから `amplify` モジュールに移動されました。また、`penalty` 関数は廃止され、ユーザ自身でペナルティ関数を定義する場合は {py:class}`~amplify.Constraint` クラスの構築で行うようになりました。詳しくは [ペナルティ関数の指定](#specify-penalty) を参照してください。その他のヘルパー関数についてはモジュールの変更のみで全て利用可能です。

````{dropdown} 従来の書き方:
```{testcode}
from amplify.constraint import equal_to, penalty

c = equal_to(q.sum(), 1)
p = penalty(q[0] * q[1])
```
````

````{dropdown} 新しい書き方:
```{testcode}
from amplify import Constraint, equal_to

c = equal_to(q.sum(), 1)
p = Constraint(q[0] + q[1], le=1, penalty=q[0] * q[1])
```
````

### モデルの作成

以前と同様に、Amplify SDK v1 でのモデルクラス {py:class}`~amplify.Model` を明示的に構築するか、あるいは目的関数と制約条件の和を取ることで、モデルを作成することができます。

以前のバージョンでは {py:class}`~amplify.BinaryQuadraticModel` と {py:class}`~amplify.IsingQuadraticModel` がモデルを表すクラスとして、変数の種類に応じた二次のモデルへの変換も担っていました。しかし Amplify SDK v1 では、モデルは様々な変数の種類や次数を扱えるソルバーに対応するため、モデル自身に変数の種類や次数への縛りを持たなくなりました。そのため、モデル構築時にはモデル変換処理は行われず、{py:func}`~amplify.solve` 関数に実行したいソルバーに対応したクライアントを渡すことで、{py:func}`~amplify.solve` 関数の内部でソルバーに最適な変換処理が行われるようになりました。


````{dropdown} 従来の書き方:
```{testcode}
from amplify import BinaryQuadraticModel

model = BinaryQuadraticModel(q.sum() ** 2, c)
```
````

````{dropdown} 新しい書き方:
```{testcode}
from amplify import Model

model = Model(q.sum() ** 2, c)
```
````

従来、二次のモデルへの変換結果は {py:class}`~amplify.BinaryQuadraticModel` と {py:class}`~amplify.IsingQuadraticModel` のアトリビュートから取得可能でしたが、Amplify SDK v1 では {py:func}`~amplify.solve` 関数の返り値である {py:class}`~amplify.Result` クラスのアトリビュートから取得するか、あるいは明示的にモデル変換メソッドを呼び出して確認できるようになりました。詳しくは 「[](intermediate.md)」 を参照してください。

### ソルバーの実行

ソルバークライアントは `amplify.client` サブモジュールから `amplify` モジュールに移動されました。また、{py:class}`~amplify.Solver` クラスは廃止され、{py:func}`~amplify.solve` 関数にモデルとソルバークライアントを渡すことで実行されるようになりました。モデル変換やグラフ埋め込みに関するパラメータは、モデルやソルバークラスのアトリビュートではなく、全て {py:func}`~amplify.solve` 関数のパラメータとして与えるように変更されました。

````{dropdown} 従来の書き方:
```{testcode}
from amplify import Solver, QuadratizationMethod
from amplify.client import FixstarsClient

client = FixstarsClient()
# client.token = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
client.parameters.timeout = 1000

model = BinaryQuadraticModel(q.sum() **2, c, method=QuadratizationMethod.SUBSTITUTION)

solver = Solver(client)
solver.filter_solution = False

result = solver.solve(model)
```
````

````{dropdown} 新しい書き方:
```{testcode}
from amplify import FixstarsClient, solve

client = FixstarsClient()
# client.token = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
client.parameters.timeout = 1000

model = Model(q.sum() **2, c)
result = solve(model, client, quadratization_method="Substitute", filter_solution=False)
```
````

また、中間モデル (旧論理モデル) の解や、グラフ埋め込みの結果なども {py:func}`~amplify.solve` 関数の返り値である {py:class}`~amplify.Result` クラスのアトリビュートに設定されるようになりました。詳しくは 「[](intermediate.md)」 と 「[](graph.md)」 を参照してください。


## 後方互換 API を使う

Amplify SDK v1 でも v0 で書かれたコードが動作するように、従来の API を v1 の後方互換 API として提供しています。後方互換 API は 100% の互換性を保証するものではありませんが、よく使われる機能については互換性を維持しているため、多くの場合はそのままで動作するはずです。

```{important}
後方互換 API は将来のバージョンで削除される可能性があるため、早めに v1 API に移行することを推奨します。

このことは実行時に警告 ({py:class}`DeprecationWarning`) として送出されます。
```

次のような方針で後方互換 API を提供しています。

### クラス

```{list-table}
:width: 100%
:header-rows: 1
:widths: 1 1

* - Amplify SDK v0 (リンク先は v1 互換 API)
  - 後方互換 API 詳細
* - {py:class}`~amplify.BinaryPoly`, {py:class}`~amplify.IsingPoly`
  - {py:class}`~amplify.Poly` のエイリアスとしてサブクラス化されていますが、それぞれバイナリ変数、イジング変数には制限されません。また、コンストラクタや一部のメソッドに互換性がありません。
* - {py:class}`~amplify.BinaryPolyArray`, {py:class}`~amplify.IsingPolyArray`
  - {py:class}`~amplify.PolyArray` のエイリアスとしてサブクラス化されていますが、それぞれバイナリ変数、イジング変数には制限されません。また、コンストラクタや一部のメソッドに互換性がありません。
* - `BinaryIntPoly`, `IsingIntPoly`,  
    `BinaryIntPolyArray`, `IsingIntPolyArray`
  - 提供されません。
* - {py:class}`~amplify.BinarySymbolGenerator`, {py:class}`~amplify.IsingSymbolGenerator`
  - それぞれ バイナリ変数、イジング変数専用の {py:class}`~amplify.VariableGenerator` として機能します。
* - `BinaryIntSymbolGenerator`, `IsingIntSymbolGenerator`
  - 提供されません。
* - {py:class}`~amplify.BinaryMatrix`, {py:class}`~amplify.IsingMatrix`
  - {py:class}`~amplify.Matrix` のエイリアスとしてサブクラス化されていますが、それぞれバイナリ変数、イジング変数には制限されません。また、インターフェースに互換性はありません。
* - `BinaryIntMatrix`, `IsingIntMatrix`
  - 提供されません。
* - {py:class}`~amplify.BinaryQuadraticModel`, {py:class}`~amplify.IsingQuadraticModel`
  - これらは明示的にコンストラクタを呼び出さない限り作成されません。それぞれ バイナリ変数とイジング変数の二次の中間モデル (旧論理モデル) を取得することのできる v0 と互換性のあるモデルとして機能します。しかし、新しい {py:func}`~amplify.solve` 関数には渡せず、後方互換用の {py:class}`~amplify.Solver` クラス専用です。
* - `BinaryIntQuadraticModel`, `IsingIntQuadraticModel`
  - 提供されません。
* - {py:class}`~amplify.Solver`, {py:class}`~amplify.SolverResult`, {py:class}`~amplify.SolverSolution`
  - {py:func}`~amplify.solve` 関数のラッパークラスとして v0 と同様のインターフェースを提供します。メソッドやプロパティの返却値は対応する v1 のクラスに変更されています。
```

### 関数

```{list-table}
:width: 100%
:header-rows: 1
:widths: 1 1

* - Amplify SDK v0 (リンク先は v1 互換 API)
  - 後方互換 API 詳細
* - `replace_all()`
  - 提供されません
* - {py:func}`~amplify.sum_poly`
  - {py:class}`~amplify.sum` のエイリアスとします。
* - `pair_sum()`
  - 提供されません
* - `product()`
  - 提供されません
* - `intersection()`
  - 提供されません
* - `union()`
  - 提供されません
* - `symmetric_difference()`
  - 提供されません
* - {py:func}`~amplify.SymbolGenerator`
  - {py:class}`~amplify.VariableGenerator` のエイリアスとします。
* - `gen_symbols`
  - 提供されません。
* - {py:func}`~amplify.decode_solution`
  - {py:meth}`~amplify.PolyArray.evaluate` の関数版として機能します。
* - `convert_to_matrix`
  - 提供されません。
```

### 名前空間

```{list-table}
:width: 100%
:header-rows: 1
:widths: 1 1

* - Amplify SDK v0 (リンク先は v1 互換 API)
  - 後方互換 API 詳細
* - `amplify.constraint`
  - 互換性のために提供されます。
* - `amplify.client`
  - 互換性のために提供されます。
* - `amplify.client.ocean`
  - 互換性のために提供されます。
```