# Migrating from Previous Versions

The Amplify SDK v1 is not fully compatible with v0. If you use an older version, this section explains how to maintain your code so that it continues to work.

## Continue using the Amplify SDK v0

To keep your current code completely unchanged, you can continue to use the Amplify SDK v0.

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

To include additional packages, use the following.

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

Documentation for the Amplify SDK v0 is available at the following URL.

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

```{important}

The Amplify SDK v0 is not guaranteed to work continuously. Other than critical bug fixes, there will be no feature additions or updates to the supported solvers.

It may also stop working due to changes in the environment. Examples are the release of a new version of Python or changes in solver specifications.
```

## Migrating to the Amplify SDK v1

You can use the following guidelines to migrate code written in v0 to v1

### Creating decision variables

The Amplify SDK v1 replaces {py:class}`~amplify.BinarySymbolGenerator` and {py:class}`~amplify.IsingSymbolGenerator` with {py:class}`~amplify.VariableGenerator`. It also adds integer and real variables. The type of variable is specified by the {py:meth}`~amplify.VariableGenerator.array`, {py:meth}`~amplify.VariableGenerator.scalar`, and {py:meth}`~amplify.VariableGenerator.matrix` method arguments.

````{dropdown} Previous writing style:
```{testcode}
from amplify import BinarySymbolGenerator, IsingSymbolGenerator

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

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

````{dropdown} New writing style:
```{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))
```
````

### Creating the objective function

Once you create the variables described above, you can construct a polynomial as in previous versions. However, [dictionary construction](https://amplify.fixstars.com/en/docs/amplify/v0/polynomial.html#id2) is deprecated and will not be available.

Matrix-style objective functions are now constructed using the {py:meth}`~amplify.VariableGenerator.matrix` method instead of directly creating a matrix class. Also, the {py:class}`~amplify.Matrix` class now includes quadratic, linear, and constant terms of the coefficients and the variables they contain. See "[](matrix.md)" for more information.

````{dropdown} Previous writing style (currently not working):
```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} New writing style:
```{testcode}
from amplify import VariableGenerator

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

# Obtain quadratic terms
m.quadratic[0, 0] = -2
m.quadratic[0, 1] = 1
m.quadratic[1, 2] = -1
m.quadratic[2, 2] = 1

# Obtain variables corresponding to the coefficient matrix
q = m.variable_array
```
````

### Creating constraints

We moved the constraint creation functions and classes from the `amplify.constraint` submodule to the `amplify` module. In addition, we removed the penalty function, and the users can now define their own penalty functions by constructing {py:class}`~amplify.Constraint` classes. See [specifying penalty functions](#specify-penalty) for details. All other helper functions are only available by changing modules.

````{dropdown} Previous writing style:
```{testcode}
from amplify.constraint import equal_to, penalty

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

````{dropdown} New writing style:
```{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])
```
````

### Model creation

As before, you can create a model in two ways in the Amplify SDK v1. Construct the model class {py:class}`~amplify.Model` explicitly, or sum the objective function and constraints.

In previous versions, {py:class}`~amplify.BinaryQuadraticModel` and {py:class}`~amplify.IsingQuadraticModel` were the classes that represented the model. They were also responsible for transforming the model into a second-order model based on the type of variables. In Amplify SDK v1, however, the models are no longer bound to variable types and orders. They are compatible with solvers that handle different variable types and orders. Therefore, the Amplify SDK no longer transforms the model when the model is constructed. Instead, the {py:func}`~amplify.solve` function performs the optimal transformation for the solver. You pass the client for the solver to the {py:func}`~amplify.solve` function.

````{dropdown} Previous writing style:
```{testcode}
from amplify import BinaryQuadraticModel

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

````{dropdown} New writing style:
```{testcode}
from amplify import Model

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

Previously, the users could obtain the result of the conversion to a quadratic model from the {py:class}`~amplify.BinaryQuadraticModel` and {py:class}`~amplify.IsingQuadraticModel` attributes. In Amplify SDK v1, you can obtain them from the attribute of the {py:class}`~amplify.Result` class. This class is the return value of the {py:func}`~amplify.solve` function. You can also explicitly call a model conversion method to check it. See "[](intermediate.md)" for details.

### Executing the solver

We moved the solver client from the `amplify.client` submodule to the `amplify` module. The {py:class}`~amplify.Solver` class is also removed, and the solver is now executed by passing the model and solver client to the {py:func}`~amplify.solve` function. You can pass all model transformation and graph embedding parameters to the {py:func}`~amplify.solve` function. You pass them as parameters rather than as attributes of the model or solver class.

{py:class}`~amplify.FixstarsClient` is still available in Amplify SDK v1, but it is recommended to use {py:class}`~amplify.AmplifyAEClient`, which supports the new version of the Amplify AE solver. For details, see "[](clients/fixstars.md)".

````{dropdown} Previous writing style:
```python
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)
```
```{testcode}
:hide:
import os

from amplify import Solver, QuadratizationMethod
from amplify.client import FixstarsClient

client = FixstarsClient()
client.url = os.getenv("TEST_AE_URL", "")
client.token = os.getenv("TEST_AE_TOKEN", "")
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} New writing style:
```python
from amplify import AmplifyAEClient, solve

client = AmplifyAEClient()
# client.token = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
client.parameters.time_limit_ms = 1000

model = Model(q.sum() **2, c)
result = solve(model, client, quadratization_method="Substitute", filter_solution=False)
```
```{testcode}
:hide:
import os

from amplify import AmplifyAEClient, solve

client = AmplifyAEClient()
client.url = os.getenv("TEST_AE_URL", "")
client.token = os.getenv("TEST_AE_TOKEN", "")
client.parameters.time_limit_ms = 1000

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

Also, the Amplify SDK sets the solution of intermediate models (old logical models) and the result of graph embedding to attributes of the {py:class}`~amplify.Result` class. This class is the return value of the {py:func}`~amplify.solve` function. See "[](intermediate.md)" and "[](graph.md)" for details.

## Using the backward-compatible API

We provide the legacy API as a backward-compatible API for v1. It lets code written in v0 work with Amplify SDK v1. The backward-compatible API is not guaranteed to be 100% compatible. However, it maintains compatibility with commonly used features and should work without modification in most cases.

```{important}
We recommend migrating to the v1 API as soon as possible, as the backward-compatible API may be removed in future releases.

When the backward-compatible API is used, this is output as a warning ({py:class}`DeprecationWarning`).
```

We provide the backward-compatible API with the following policy.

### Classes

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

* - Amplify SDK v0 (link to v1 compatible API)
  - Backward-compatible API details
* - {py:class}`~amplify.BinaryPoly`, {py:class}`~amplify.IsingPoly`
  - Subclassed as an alias of {py:class}`~amplify.Poly`, but is not restricted to binary or Ising variables. Also, constructors and some methods are incompatible.
* - {py:class}`~amplify.BinaryPolyArray`, {py:class}`~amplify.IsingPolyArray`
  - Subclassed as an alias of {py:class}`~amplify.PolyArray`, but not restricted to binary or Ising variables. Also, constructors and some methods are not compatible.
* - `BinaryIntPoly`, `IsingIntPoly`,  
    `BinaryIntPolyArray`, `IsingIntPolyArray`
  - Not provided
* - {py:class}`~amplify.BinarySymbolGenerator`, {py:class}`~amplify.IsingSymbolGenerator`
  - Function as {py:class}`~amplify.VariableGenerator`, restricted to binary and Ising variables, respectively.
* - `BinaryIntSymbolGenerator`, `IsingIntSymbolGenerator`
  - Not provided
* - {py:class}`~amplify.BinaryMatrix`, {py:class}`~amplify.IsingMatrix`
  - Subclassed as an alias for {py:class}`~amplify.Matrix`, but not restricted to binary or Ising variables. Also, the interfaces are not interchangeable.
* - `BinaryIntMatrix`, `IsingIntMatrix`
  - Not provided
* - {py:class}`~amplify.BinaryQuadraticModel`, {py:class}`~amplify.IsingQuadraticModel`
  - These are not created unless you explicitly call the constructor. They serve as v0-compatible models that can be used to obtain quadratic intermediate models (old logical models) of the binary and Ising variables, respectively. However, they cannot be passed to the new {py:func}`~amplify.solve` function; they can only be passed to the backward-compatible {py:class}`~amplify.Solver` class.
* - `BinaryIntQuadraticModel`, `IsingIntQuadraticModel`
  - Not provided
* - {py:class}`~amplify.Solver`, {py:class}`~amplify.SolverResult`, {py:class}`~amplify.SolverSolution`
  - Provided the same interface as v0 as a wrapper class for the {py:func}`~amplify.solve` function. The return values of methods and properties are changed to the corresponding v1 classes.
```

### Functions

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

* - Amplify SDK v0 (link to v1 compatible API)
  - Backward-compatible API details
* - `replace_all()`
  - Not provided
* - {py:func}`~amplify.sum_poly`
  - Alias for {py:class}`~amplify.sum`
* - `pair_sum()`
  - Not provided
* - `product()`
  - Not provided
* - `intersection()`
  - Not provided
* - `union()`
  - Not provided
* - `symmetric_difference()`
  - Not provided
* - {py:func}`~amplify.SymbolGenerator`
  - Alias for {py:class}`~amplify.VariableGenerator`
* - `gen_symbols`
  - Not provided
* - {py:func}`~amplify.decode_solution`
  - A function version of {py:meth}`~amplify.PolyArray.evaluate`
* - `convert_to_matrix`
  - Not provided
```

### Namespace

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

* - Amplify SDK v0 (link to v1 compatible API)
  - Backward-compatible API details
* - `amplify.constraint`
  - Provided for compatibility
* - `amplify.client`
  - Provided for compatibility
```