# Quickstart You can run the Amplify SDK in any of the following ways. ````{grid} 1 1 1 1 :padding: 2 2 4 4 :gutter: 4 ```{grid-item-card} 💻 Install and Run on Your PC :link: how-to-install :link-type: ref 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. ``` %```{grid-item-card} 🧪 Run on Google Collab %:link: https://colab.research.google.com %:link-type: url %Run the Amplify SDK sample code using Google Collab. %* A Google account is required in advance. %* You need an **Amplify Annealing Engine** API token to run the solver. %``` ```{grid-item-card} ☁️ Try it out on BinderHub :link: https://amplify.fixstars.com/en/demo :link-type: url 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](https://amplify.fixstars.com/en/register). ``` (how-to-install)= ## Installation The Amplify SDK has been tested in the following environments. ````{grid} 1 2 2 2 :gutter: 5 :padding: 2 2 5 5 ```{grid-item-card} Python versions * 3.8 * 3.9 * 3.10 * 3.11 * 3.12 ``` ```{grid-item-card} Supported OS * 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. ```bash $ python3 --version ``` You can install the Amplify SDK in your environment from [PyPI](https://pypi.org/project/amplify/) with the following command. ```bash $ 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. ```bash $ 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. ```python >>> import amplify >>> amplify.__version__ 1.2.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](https://amplify.fixstars.com/en/engine) (hereafter referred to as Amplify AE) as the solver. If you do not have an Amplify AE account, please register [here](https://amplify.fixstars.com/en/register) to get an API token. Let's consider the following problem. ```{card} Sample QUBO Problem :width: 50% :margin: 3 3 auto auto 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 {py:class}`~amplify.VariableGenerator` class, you can define a variable array `q` of length 2 that outputs decision variables as follows ```{doctest} >>> 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`{l=python} as follows. Note that the subscripts of the variable $q$ correspond to the array indices. ```{doctest} >>> 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 ({py:class}`~amplify.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 {py:attr}`~amplify.FixstarsClient.token` property of {py:class}`~amplify.FixstarsClient`. We will also set the solver timeout to 1 second. ```{doctest} >>> from amplify import FixstarsClient >>> client = FixstarsClient() >>> client.token = "***input your token***" # doctest: +SKIP >>> client.parameters.timeout = 1000 # Set run time to 10000 ms ``` ### 4. Running the solver We can execute the solver using the {py:func}`~amplify.solve` function. This function takes a formulated problem and a solver client as arguments and returns the result of the solver run. ```{doctest} >>> from amplify import solve >>> result = solve(f, client) ``` ### 5. Checking the solution The result from the solver is returned as an instance of {py:class}`~amplify.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 {py:class}`~amplify.Result.best` property, the SDK returns the best solution obtained as an instance of the {py:class}`~amplify.Result.Solution` class instance. The {py:class}`~amplify.Result.Solution` class contains the values of the variables and the objective function. ```{doctest} >>> 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 {py:class}`~amplify.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 {py:class}`~amplify.PolyArray.evaluate` method on the variable array returns an array in which the elements of the variable array are replaced by the values of the {py:class}`~amplify.Values` class. ```{doctest} >>> 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](https://amplify.fixstars.com/en/demo) to learn how to solve various problems with the Amplify SDK. To learn more about the features of the Amplify SDK, continue with the [](overview.md). `````{grid} 1 2 2 2 :margin: 4 0 0 0 ````{grid-item-card} ☁️ To view different applications :margin: auto ```{button-link} https://amplify.fixstars.com/en/demo :color: info :click-parent: :expand: **Proceed to Tutorial** ``` ```` ````{grid-item-card} ⏩ To learn more about the features :margin: auto ```{button-ref} overview :ref-type: myst :color: success :click-parent: :expand: **Proceed to Amplify SDK Overview** ``` ```` `````