Migrating from Previous Versions#

The Amplify SDK v1 has lost some compatibility with v0. If you have been using an older version, this section explains how to maintain your code so that it will continue to work.

Continue using the Amplify SDK v0#

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

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

To include additional packages, use the following.

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

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

https://amplify.fixstars.com/en/docs/amplify/v0/

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.

Please also note that it may stop working due to changes in the environment, such as 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#

BinarySymbolGenerator and IsingSymbolGenerator have been replaced by VariableGenerator with the addition of integer and real variables. The type of variable is specified by the array(), scalar(), and matrix() method arguments.

Previous writing style:
from amplify import BinarySymbolGenerator, IsingSymbolGenerator

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

gen = IsingSymbolGenerator()
s = gen.array(shape=(4, 4))
New writing style:
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 is deprecated and will not be available.

Matrix-style objective functions are now constructed using the matrix() method instead of directly creating a matrix class. Also, the Matrix class now includes quadratic, linear, and constant terms of the coefficients and the variables they contain. See β€œObjective Function with a Coefficient Matrix” for more information.

Previous writing style (currently not working):
from amplify import BinaryMatrix

m = BinaryMatrix(3)

m[0, 0] = -2
m[0, 1] = 1
m[1, 2] = -1
m[2, 2] = 1
New writing style:
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 have moved the constraint creation functions and classes from the amplify.constraint submodule to the amplify module. In addition, we have removed the penalty function, and the users can now define their own penalty functions by constructing Constraint classes. See specifying penalty functions for details. All other helper functions are only available by changing modules.

Previous writing style:
from amplify.constraint import equal_to, penalty

c = equal_to(q.sum(), 1)
p = penalty(q[0] * q[1])
New writing style:
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, models can be created by explicitly constructing the model class Model in the Amplify SDK v1 or by summing the objective function and constraints.

In previous versions, BinaryQuadraticModel and IsingQuadraticModel were the classes that represented the model and 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, as they are compatible with solvers that can handle various variable types and orders. Therefore, the Amplify SDK no longer performs the model transformation process when the model is constructed, but rather, the optimal transformation process for the solver is performed within the solve() function by passing the client corresponding to the solver to be used to the solve() function.

Previous writing style:
from amplify import BinaryQuadraticModel

model = BinaryQuadraticModel(q.sum() ** 2, c)
New writing style:
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 BinaryQuadraticModel and IsingQuadraticModel attributes, but in Amplify SDK v1, you can obtain them from the attribute of the Result class, which is the return value of the solve() function, or you can explicitly call a model conversion method to check it. See β€œVariable Conversion and Degree Reduction” for details.

Executing the solver#

We have moved the solver client from the amplify.client submodule to the amplify module. The Solver class has also been removed, and the solver is now executed by passing the model and solver client to the solve() function. You can pass all model transformation and graph embedding parameters as parameters to the solve() function rather than as attributes of the model or solver class.

Previous writing style:
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)
New writing style:
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)

Also, the Amplify SDK sets the solution of intermediate models (old logical models) and the result of graph embedding to attributes of the Result class, which is the return value of the solve() function. See β€œVariable Conversion and Degree Reduction” and β€œGraph Embedding” for details.

Using the backward-compatible API#

To ensure that code written in v0 will work with Amplify SDK v1, we provide the legacy API as a backward-compatible API for v1. The backward-compatible API is not guaranteed to be 100% compatible, but 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.

This will be output as a warning (DeprecationWarning) when the backward-compatible API is used.

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

Classes#

Amplify SDK v0 (link to v1 compatible API)

Backward-compatible API details

BinaryPoly, IsingPoly

Subclassed as an alias of Poly, but is not restricted to binary or Ising variables. Also, constructors and some methods are incompatible.

BinaryPolyArray, IsingPolyArray

Subclassed as an alias of PolyArray, but not restricted to binary or Ising variables. Also, constructors and some methods are not compatible.

BinaryIntPoly, IsingIntPoly,
BinaryIntPolyArray, IsingIntPolyArray

Not provided

BinarySymbolGenerator, IsingSymbolGenerator

Function as VariableGenerator, restricted to binary and Ising variables, respectively.

BinaryIntSymbolGenerator, IsingIntSymbolGenerator

Not provided

BinaryMatrix, IsingMatrix

Subclassed as an alias for Matrix, but not restricted to binary or Ising variables. Also, the interfaces are not interchangeable.

BinaryIntMatrix, IsingIntMatrix

Not provided

BinaryQuadraticModel, 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 solve() function; they can only be passed to the backward-compatible Solver class.

BinaryIntQuadraticModel, IsingIntQuadraticModel

Not provided

Solver, SolverResult, SolverSolution

Provided the same interface as v0 as a wrapper class for the solve() function. The return values of methods and properties are changed to the corresponding v1 classes.

Functions#

Amplify SDK v0 (link to v1 compatible API)

Backward-compatible API details

replace_all()

Not provided

sum_poly()

Alias for sum

pair_sum()

Not provided

product()

Not provided

intersection()

Not provided

union()

Not provided

symmetric_difference()

Not provided

SymbolGenerator()

Alias for VariableGenerator

gen_symbols

Not provided

decode_solution()

A function version of evaluate()

convert_to_matrix

Not provided

Namespace#

Amplify SDK v0 (link to v1 compatible API)

Backward-compatible API details

amplify.constraint

Provided for compatibility

amplify.client

Provided for compatibility