==========
Quickstart
==========

.. note::
    You have the option to use a managed storage with the SDK, but it only supports up to 10,000 vector variables. If you
    need to run bigger problems, use the AWS S3 bucket option that supports up to 100,000 variables.

Example with managed storage
----------------------------

The following code is a quick and a simple example using TitanQ SDK.
Note at the highlighted line,  ``Model`` is created without a ``storage_client``.

.. code-block:: python
    :linenos:
    :emphasize-lines: 20

    import numpy as np
    from titanq import Model, Vtype, Target, S3Storage

    TITANQ_API_KEY="<insert your TitanQ API key here>"

    # Problem construction
    edges = {0:[4,5,6,7], 1:[4,5,6,7], 2:[4,5,6,7], 3:[4,5,6,7], 4:[0,1,2,3], 5:[0,1,2,3], 6:[0,1,2,3], 7:[0,1,2,3]}
    size = len(edges)

    # construct the weight matrix from the edges list
    weights = np.zeros((size, size), dtype=np.float32)
    for root, connections in edges.items():
        for c in connections:
            weights[root][c] = 1

    # construct the bias vector (Uniform weighting across all nodes)
    bias = np.asarray([0]*size, dtype=np.float32)

    # TitanQ SDK
    model = Model(api_key=TITANQ_API_KEY)
    model.add_variable_vector('x', size, Vtype.BINARY)
    model.set_objective_matrices(weights, bias, Target.MINIMIZE)
    response = model.optimize(timeout_in_secs=1, coupling_mult=0.75, num_engines=2)

    print("-" * 15, "+", "-" * 26, sep="")
    print("Ising energy   | Result vector")
    print("-" * 15, "+", "-" * 26, sep="")
    for ising_energy, result_vector in response.result_items():
        print(f"{ising_energy: <14f} | {result_vector}")

Example using AWS S3 Buckets
----------------------------

The following section is for developers wishing to use the TitanQ with S3 buckets.

1. Create Bucket
^^^^^^^^^^^^^^^^

To use the Python SDK, we only need to create a single bucket.

Start by going to the S3 management console

.. image:: _static/aws_menu_s3.png

Select **Create Bucket**.

.. image:: _static/s3_bucket_create_launch.png

In the Create Bucket dialog

    - Give the bucket a unique name (unique across all of AWS)
        - For the bucket name, a good choice might be **companyname-projectname-bucket**
    - Ensure **Block all public access** is selected
    - Select **Create Bucket**

.. image:: _static/s3_bucket_create_combined.png

After the bucket is created, recover its ARN ("Amazon Resource Name").

    - In the S3 dashboard, click on the newly-created bucket
    - Select the **Properties** tab
    - Save the **ARN** for later use

.. image:: _static/s3_bucket_arn.png

2. Create Policy
^^^^^^^^^^^^^^^^

We only need a single policy.

Go to the **IAM** dashboard (**not** the IAM Identity Center).

.. image:: _static/aws_menu_iam.png

Select the **Policies** submenu.

.. image:: _static/iam_policies.png

Select **Create Policy**.

.. image:: _static/iam_policy_create.png

Select the **JSON** edit mode and paste the following in the editor area.

.. code-block:: js
    :linenos:

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": [
                        "s3:GetObject",
                        "s3:PutObject"
                    ],
                "Resource": [
                    "arn:aws:s3:::companyname-projectname-bucket/*"
                ]
            }
        ]
    }

where the ``Resource`` key should be adjusted to match your own **source bucket ARN** from the previous step.

.. image:: _static/json_policy_getputobject.png

Click **Next**

In the following "Review and Create Policy" dialog, enter a policy name, eg. **myReadAndWritePolicy** and click Create.

.. image:: _static/iam_policy_review_create.png


3. Create User
^^^^^^^^^^^^^^

We only need a single user.

Back at the IAM dashboard, select the **Users** submenu.

.. image:: _static/iam_users.png

Select **Create** User.

.. image:: _static/iam_user_create_0.png

Pick a name for the user then click **Next**.

.. image:: _static/iam_user_create_1.png

Select **Attach policies directly**.

.. note::
    You may want to Filter by Type: "Customer Managed" to help locate the policies we previously created.

Select the previously-created **policy** only and click **Next**.

.. image:: _static/iam_user_attach_policy.png

On the following page, you can finally click **Create User**.

4. Generating Credentials
^^^^^^^^^^^^^^^^^^^^^^^^^

Now we generate the crendetials required for the TitanQ service to access the bucket.

Starting at the IAM > Users dashboard, select the **previously created user**.

In the user's info panel, navigate to the **Security credentials** tab and select **Create access key**.

.. image:: _static/iam_user_create_access_key_0.png

In the Access key best practices & alternative dialog, pick **Other**, then **Next**.

.. image:: _static/iam_user_create_access_key_1.png

In the following dialog, you can optionally add a **Description**. Click **Create Access Key**.

Finally, in the Retrieve Access Key Dialog, copy **both** the **Access Key ID **and **Secret Access Key** for later use.

.. warning::
    This will be the **one and only** opportunity to retrieve the Secret Access Key.

.. image:: _static/iam_user_retrieve_access_key.png

Click **Done**.

5. Putting it all together
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python
    :linenos:

    import numpy as np
    from titanq import Model, Vtype, Target, S3Storage

    TITANQ_API_KEY="<insert your TitanQ API key here>"

    AWS_BUCKET_NAME="<insert AWS bucket name here>"
    AWS_ACCESS_KEY="<insert AWS bucket access key here>"
    AWS_SECRET_ACCESS_KEY="<insert AWS secret access key here>"

    # Problem construction
    edges = {0:[4,5,6,7], 1:[4,5,6,7], 2:[4,5,6,7], 3:[4,5,6,7], 4:[0,1,2,3], 5:[0,1,2,3], 6:[0,1,2,3], 7:[0,1,2,3]}
    size = len(edges)

    # construct the weight matrix from the edges list
    weights = np.zeros((size, size), dtype=np.float32)
    for root, connections in edges.items():
        for c in connections:
            weights[root][c] = 1

    # construct the bias vector (Uniform weighting across all nodes)
    bias = np.asarray([0]*size, dtype=np.float32)

    # TitanQ SDK
    model = Model(
        api_key=TITANQ_API_KEY,
        storage_client=S3Storage(
            bucket_name=AWS_BUCKET_NAME,
            access_key=AWS_ACCESS_KEY,
            secret_key=AWS_SECRET_ACCESS_KEY
        )
    )
    model.add_variable_vector('x', size, Vtype.BINARY)
    model.set_objective_matrices(weights, bias, Target.MINIMIZE)
    response = model.optimize(timeout_in_secs=1, coupling_mult=0.75, num_engines=2)

    print("-" * 15, "+", "-" * 26, sep="")
    print("Ising energy   | Result vector")
    print("-" * 15, "+", "-" * 26, sep="")
    for ising_energy, result_vector in response.result_items():
        print(f"{ising_energy: <14f} | {result_vector}")