IBM Quantum and Amazon Braket Interfaces
========================================

The Ket quantum programming platform provides seamless integration with
industry-leading quantum cloud providers. By using the
:class:`~ket.ibm.IBMDevice` and :class:`~ket.amazon.AmazonBraket` classes,
you can execute Ket quantum circuits on Quantum Processing Units (QPUs)
or simulators provided by IBM Quantum and Amazon Web Services (AWS).

.. important::

   **Execution Model**

   * **Supported Operations:** Execution on these backends is currently limited
     to :func:`~ket.operations.sample` and :func:`~ket.operations.exp_value`.
   * **Batch Mode:** Execution is strictly *batch-based*. Quantum instructions
     are collected and submitted as a single job to the backend, rather than
     executed interactively.


Prerequisites
-------------

Before using these integrations, install the required dependencies.

**IBM Quantum:**

.. code-block:: bash

   pip install ket-lang[ibm]

**Amazon Braket:**

.. code-block:: bash

   pip install ket-lang[amazon]


IBM Quantum Interface (:class:`~ket.ibm.IBMDevice`)
---------------------------------------------------

The :class:`~ket.ibm.IBMDevice` class provides integration with the Qiskit ecosystem.

**Account setup:**

* Create an account and retrieve your token:
  https://quantum.ibm.com/
* Setup instructions:
  https://docs.quantum.ibm.com/start/setup-channel

Basic Usage: Bell State (Local Simulator)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from ket import *
   from ket.ibm import IBMDevice
   from math import sqrt

   device = IBMDevice()
   process = Process(device)

   a, b = process.alloc(2)

   X(a + b)
   CNOT(H(a), b)

   with obs():
       a0 = Z(a)
       a1 = X(a)
       b0 = -(X(b) + Z(b)) / sqrt(2)
       b1 = (X(b) - Z(b)) / sqrt(2)
       h = a0 * b0 + a0 * b1 + a1 * b0 - a1 * b1

   print(exp_value(h).get())

Advanced Usage: Noisy Local Simulation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can provide a custom Qiskit backend to :class:`~ket.ibm.IBMDevice`
to emulate realistic hardware noise.

.. code-block:: python

   from ket import *
   from ket.ibm import IBMDevice
   from qiskit_aer import AerSimulator
   from qiskit_ibm_runtime.fake_provider import FakeBrisbane

   backend = FakeBrisbane()
   simulator = AerSimulator.from_backend(backend)

   device = IBMDevice(simulator)
   process = Process(device)

   # Continue building your circuit...


Amazon Braket Interface (:class:`~ket.amazon.AmazonBraket`)
-----------------------------------------------------------

The :class:`~ket.amazon.AmazonBraket` class connects Ket to AWS Braket,
allowing execution on local simulators, managed cloud simulators, and QPUs.

**Cloud setup:**

To use AWS resources, configure your AWS account with the required
permissions.

* Enable Amazon Braket:
  https://docs.aws.amazon.com/braket/latest/developerguide/braket-enable-overview.html

Targeting AWS Resources
~~~~~~~~~~~~~~~~~~~~~~~

If no ARN is provided, :class:`~ket.amazon.AmazonBraket` defaults to a local simulator.
To target specific backends, provide the device ARN.

.. code-block:: python

   from ket import *
   from ket.amazon import AmazonBraket
   from math import sqrt

   # Local simulator (default)
   device = AmazonBraket()

   # Cloud simulators
   # device = AmazonBraket('arn:aws:braket:::device/quantum-simulator/amazon/tn1')
   # device = AmazonBraket('arn:aws:braket:::device/quantum-simulator/amazon/dm1')

   # Real QPUs
   # device = AmazonBraket('arn:aws:braket:us-east-1::device/qpu/ionq/Aria-1')
   # device = AmazonBraket('arn:aws:braket:us-east-1::device/qpu/ionq/Forte-1')
   # device = AmazonBraket('arn:aws:braket:eu-north-1::device/qpu/iqm/Garnet')
   # device = AmazonBraket('arn:aws:braket:us-west-1::device/qpu/rigetti/Ankaa-3')

   process = Process(device)
   a, b = process.alloc(2)

   X(a + b)
   CNOT(H(a), b)

   with obs():
       a0 = Z(a)
       a1 = X(a)
       b0 = -(X(b) + Z(b)) / sqrt(2)
       b1 = (X(b) - Z(b)) / sqrt(2)
       h = a0 * b0 + a0 * b1 + a1 * b0 - a1 * b1

   print(exp_value(h).get())