# 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} ☁️ 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. ``` ```` %```{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. %``` ```{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 is tested in the following environments. ````{grid} 1 2 2 2 :gutter: 5 :padding: 2 2 5 5 ```{grid-item-card} Python versions * 3.10 * 3.11 * 3.12 * 3.13 * 3.14 ``` ```{grid-item-card} Supported OS * Windows 10/11 * Linux * Ubuntu 22.04/24.04/26.04, Rocky Linux 9.6/10.0 * x86_64, ARM64 * macOS * x86_64 (Sonoma or later) * ARM64 (Sonoma 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} To use D-Wave machines or Amplify Quantum, install with the corresponding extra packages: See [D-Wave Systems](clients/dwave.md) and [Quantum Computing Support](quantum/index.md) for details. ```bash # To use D-Wave machines $ python3 -m pip install -U 'amplify[dwave]' # To use Amplify Quantum $ python3 -m pip install -U 'amplify[quantum]' # To install all extra packages $ python3 -m pip install -U 'amplify[full]' ``` ```{caution} Some extra packages may not be available depending on your Python version and OS. ``` ```` After you install the Amplify SDK, you can verify the installed version as follows. ```python >>> import amplify >>> amplify.__version__ 1.7.2 ``` (run-sample-code)= ## 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 check whether we get the correct answer. ### 1. Creating a variable array To obtain a solution to a combinatorial optimization problem with the Amplify SDK, you must define three things in your program code. These are the **objective function**, the **decision variables**, and the **constraints**. 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 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. 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.AmplifyAEClient`) of Amplify AE as the solver client. To send the formulated problem to Amplify AE, we must set up an API token. Set the API token to the {py:attr}`~amplify.AmplifyAEClient.token` property of {py:class}`~amplify.AmplifyAEClient`. We will also set the solver timeout to 1 second. ```{doctest} >>> from amplify import AmplifyAEClient >>> client = AmplifyAEClient() >>> client.token = "***input your token***" # doctest: +SKIP >>> client.parameters.time_limit_ms = 1000 # Set run time to 10000 ms ``` ```{doctest} :hide: >>> import os >>> client.url = os.getenv("TEST_AE_URL", "") >>> client.token = os.getenv("TEST_AE_TOKEN", "") ``` ### 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. When you call the {py:attr}`~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. This class is a dictionary with the decision variables and their values as keys and values. To make the solution easier to see, call the {py:class}`~amplify.PolyArray.evaluate` method on the variable array. It 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. We covered only 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 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** ``` ```` `````