Quickstart¶
You can run the Amplify SDK in any of the following ways.
This procedure installs the Amplify SDK on your PC and runs the sample code.
You need Python installed on your PC.
You need an Amplify Annealing Engine API token to run the solver.
You can try the sample code on the Amplify tutorial page.
You do not need an Amplify Annealing Engine API token to run the solver.
When the page expires (about 20 minutes), your input and execution results will be discarded.
Note
An Amplify Annealing Engine API token is required to run the sample code.
Anyone can get an API token for free by registering as an Amplify user.
Installation¶
The Amplify SDK has been tested in the following environments.
3.9
3.10
3.11
3.12
3.13
Windows 10/11
Linux
Ubuntu 20.04/22.04, Rocky Linux 8/9
x86_64, ARM64
macOS
x86_64 (Monterey or later)
ARM64 (Monterey or later)
First, ensure your Python version is included in the above list.
$ python3 --version
You can install the Amplify SDK in your environment from PyPI with the following command.
$ python3 -m pip install -U amplify
Hint
If you use a D-Wave machine or a quantum algorithm such as QAOA, install the following command to include additional packages.
$ python3 -m pip install -U 'amplify[extra]'
Caution
Some Python versions may not support the additional packages.
You can verify the installed version once the Amplify SDK has been successfully installed as follows.
>>> import amplify
>>> amplify.__version__
1.3.1
Running the example code¶
Now that the installation is complete let’s use Amplify to solve a simple QUBO problem. Here, we will use Fixstars Amplify Annealing Engine (hereafter referred to as Amplify AE) as the solver. If you do not have an Amplify AE account, please register here to get an API token.
Let’s consider the following problem.
- The objective function
- \[ \text{minimize:} \quad f = q_0 q_1 + q_0 - q_1 + 1 \]
- The decision variables
- \[ q_0, q_1 \in \{0, 1\} \]
- The constraints
- \[ \text{None} \]
With a little thought, we can see that the function \(f\) has a minimum value \(f = 0\) when \(q_0 = 0\) and \(q_1 = 1\). Let’s solve this problem using the Amplify SDK and see if we get the correct answer.
1. Creating a variable array¶
To obtain a solution to a combinatorial optimization problem with the Amplify SDK, you need to define the objective function, decision variables, and constraints in your program code.
First, let’s define the decision variables. In the example problem above, the decision variables are the binary variables \(q_0\) and \(q_1\), which take the values 0 or 1. Using the VariableGenerator class, you can define a variable array q of length 2 that outputs decision variables as follows
>>> from amplify import VariableGenerator
>>> gen = VariableGenerator() # Create a generator for decision variables
>>> q = gen.array("Binary", 2) # Generate a variable array of two binary decision variables
>>> print(q)
[q_0, q_1]
2. Creating the objective function¶
Next, we will create the objective function using the variables you have defined above. The objective function \(f = q_0 q_1 + q_0 - q_1 + 1\) in the example problem can be determined using the variable array q as follows. Note that the subscripts of the variable \(q\) correspond to the array indices.
>>> f = q[0] * q[1] + q[0] - q[1] + 1
>>> print(f)
q_0 q_1 + q_0 - q_1 + 1
Since there are no constraints in this sample problem, the formulation is complete.
3. Creating a solver client¶
Since we use Amplify AE as the solver this time, we will create a client class (FixstarsClient) of Amplify AE as the solver client.
We must set up an API token to send the formulated problem to Amplify AE by setting the API token to the token property of FixstarsClient. We will also set the solver timeout to 1 second.
>>> from amplify import FixstarsClient
>>> client = FixstarsClient()
>>> client.token = "***input your token***"
>>> client.parameters.timeout = 1000 # Set run time to 10000 ms
4. Running the solver¶
We can execute the solver using the solve() function. This function takes a formulated problem and a solver client as arguments and returns the result of the solver run.
>>> from amplify import solve
>>> result = solve(f, client)
5. Checking the solution¶
The result from the solver is returned as an instance of Result. This instance contains the results of the solver run and information about the model conversions performed. Depending on the solver used and the parameters set, there may be more than one solution, but by calling the best property, the SDK returns the best solution obtained as an instance of the Solution class instance. The Solution class contains the values of the variables and the objective function.
>>> result.best.objective # Value of the objective function
0.0
>>> result.best.values # Values of the variables
Values({Poly(q_0): 0, Poly(q_1): 1})
The values of the variables are obtained as instances of the Values class, which is a dictionary with the decision variables and their values as keys and values. To make the solution easier to see, the evaluate method on the variable array returns an array in which the elements of the variable array are replaced by the values of the Values class.
>>> print(f"{q} = {q.evaluate(result.best.values)}")
[q_0, q_1] = [0. 1.]
From the above, we know that the solution to our example problem is \(q_0 = 0\) and \(q_1 = 1\).
Next steps¶
These are the steps of formulating the problem and running the solver using the Amplify SDK. Although we have just covered a straightforward two-variable problem, you can apply the above steps similarly to more complex problems.
For the next step, let’s see the Tutorial to learn how to solve various problems with the Amplify SDK. To learn more about the features of the Amplify SDK, continue with the Amplify SDK Overview.