docs/tutorials/Migration_Guide_from_qiskit-ibmq-provider.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Migration guide from qiskit-ibmq-provider to qiskit-ibm-provider"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "## Background\n",
    "\n",
    "`qiskit-ibmq-provider` was the original implementation of the `Provider` interface in `qiskit-terra` and the main entry point for accessing IBM Quantum’s systems, simulators, and services. As IBM Quantum expanded, different disjoint services were added to `qiskit-ibmq-provider`, often causing confusion among users, and making new features difficult to find. \n",
    "\n",
    "With the introduction of [Qiskit Runtime](https://quantum-computing.ibm.com/lab/docs/iql/runtime/), we decided it was time to restructure the provider:\n",
    "\n",
    "- The access to backend services (most of the submodules in the previous `qiskit.providers.ibmq`), is replaced by this [qiskit-ibm-provider](https://pypi.org/project/qiskit-ibm-provider/) package. It has a similar interface as the original `qiskit-ibmq-provider` (with `ibm-` instead of `ibmq-`) and gives direct access to the [IBM Quantum compute resources](https://quantum-computing.ibm.com/services/resources). If you need lower-level access to do experiments like device characterization or to research new error correction routines, `qiskit-ibm-provider` is more suitable for you. \n",
    "- The access to Qiskit Runtime service (formerly in `qiskit.providers.ibmq.runtime`), goes into [qiskit-ibm-runtime](https://pypi.org/project/qiskit-ibm-runtime/) package ([documentation](https://qiskit.org/documentation/partners/qiskit_ibm_runtime/)). It provides access to managed services through the Qiskit Runtime primitives which are integrated with the latest quantum computing technologies, such as error  mitigation and correction. If you prefer getting high quality probability distribution or expectation values without having to optimize the circuits yourself, you may want to start here. \n",
    "- The access to the experiment service (formerly in `qiskit.providers.ibmq.experiment`) goes into [qiskit-ibm-experiment](https://pypi.org/project/qiskit-ibm-experiment/) package ([documentation](https://qiskit.org/documentation/partners/qiskit_ibm_experiment/).\n",
    "\n",
    "This migration guide focuses on moving from `qiskit-ibmq-provider` to `qiskit-ibm-provider`. For the rest of the migration guides, see https://ibm.biz/provider_migration_guide "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Quick Start"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'11': 2047, '00': 1953}\n"
     ]
    }
   ],
   "source": [
    "from qiskit import QuantumCircuit, transpile\n",
    "from qiskit_ibm_provider import IBMProvider\n",
    "\n",
    "# Save account credentials.\n",
    "# IBMProvider.save_account(token=MY_API_TOKEN)\n",
    "\n",
    "# Load previously saved account credentials.\n",
    "provider = IBMProvider()\n",
    "\n",
    "# Create a circuit\n",
    "qc = QuantumCircuit(2)\n",
    "qc.h(0)\n",
    "qc.cx(0, 1)\n",
    "qc.measure_all()\n",
    "\n",
    "# Select a backend.\n",
    "backend = provider.get_backend(\"ibmq_qasm_simulator\")\n",
    "\n",
    "# Transpile the circuit\n",
    "transpiled = transpile(qc, backend=backend)\n",
    "\n",
    "# Submit a job.\n",
    "job = backend.run(transpiled)\n",
    "# Get results.\n",
    "print(job.result().get_counts())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary of main changes\n",
    "\n",
    "While the interfaces stay mostly the same, there are a few major changes that require your actions. \n",
    "\n",
    "- `qiskit-ibm-provider` is no longer part of the Qiskit meta package and will need to be installed separately.\n",
    "- Importing and initializing a provider is different. \n",
    "- Some infrequently used methods are no longer supported.\n",
    "- `qiskit-ibm-provider` uses the Qiskit Runtime API under the cover."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installation\n",
    "\n",
    "You can install `qiskit-ibm-provider` using `pip`:\n",
    "\n",
    "```\n",
    "pip install qiskit-ibm-provider\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Initializing an account\n",
    "\n",
    "When using `qiskit-ibmq-provider`, one usually manages accounts and gets a provider using the `IBMQ` global variable. In `qiskit-ibm-provider` the provider is created using the `IBMProvider` class.\n",
    "\n",
    "**Previously:**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from qiskit import IBMQ\n",
    "\n",
    "# Enable an account without saving.\n",
    "# IBMQ.enable_account(token=MY_API_TOKEN)\n",
    "\n",
    "# Save account credentials.\n",
    "# IBMQ.save_account(token=MY_API_TOKEN)\n",
    "\n",
    "# Load a previously saved account.\n",
    "provider = IBMQ.load_account()\n",
    "\n",
    "# Select a different hub/group/project.\n",
    "provider = IBMQ.get_provider(hub=\"ibm-q\", group=\"open\", project=\"main\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**New:**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "from qiskit_ibm_provider import IBMProvider\n",
    "\n",
    "# Save account credentials.\n",
    "# IBMProvider.save_account(token=MY_API_TOKEN)\n",
    "\n",
    "# Load a previously saved account.\n",
    "provider = IBMProvider()\n",
    "\n",
    "# Select a different hub/group/project.\n",
    "provider = IBMProvider(instance=\"ibm-q/open/main\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Loading account from environment variables\n",
    "\n",
    "The environment variables used for account credentials have changed:\n",
    "\n",
    "- `QE_TOKEN` is replaced by `QISKIT_IBM_TOKEN`\n",
    "- `QE_HUB`, `QE_GROUP`, and `QE_PROJECT` is replaced by `QISKIT_IBM_INSTANCE`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Basic usage\n",
    "\n",
    "We demonstrate the basic flow for using the provider, which is essentially the same. We begin by creating a demonstration circuit generating a 2-qubit bell pair:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "from qiskit import QuantumCircuit\n",
    "\n",
    "qc = QuantumCircuit(2)\n",
    "qc.h(0)\n",
    "qc.cx(0, 1)\n",
    "qc.measure_all()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The basic flow of getting a backend, running the circuit using it, getting a job, and obtaining the job results is the same.\n",
    "\n",
    "**Previously:**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from qiskit import IBMQ\n",
    "\n",
    "provider = IBMQ.load_account()\n",
    "backend = provider.get_backend(\"ibmq_qasm_simulator\")\n",
    "job = backend.run(qc)\n",
    "print(job.result().get_counts())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**New:**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from qiskit_ibm_provider import IBMProvider\n",
    "\n",
    "provider = IBMProvider()\n",
    "backend = provider.get_backend(\"ibmq_qasm_simulator\")\n",
    "job = backend.run(qc)\n",
    "print(job.result().get_counts())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Removed functionalities"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- The following parameters are no longer supported in `backend.run()`:\n",
    "\n",
    "    - `job_name`. You can use job tags instead.\n",
    "    - `experiment_id`. You can use job tags instead.\n",
    "    - `job_share_level`. This was deprecated in `qiskit-ibmq-provider` and removed in `qiskit-ibm-provider`.\n",
    "    - `qobj`. This was deprecated in `qiskit-ibmq-provider` and removed in `qiskit-ibm-provider`.\n",
    "    - `memory_slots`.\n",
    "    - `memory_slot_size`.\n",
    "    - `rep_time`. You can use `rep_delay` instead.\n",
    "    - `live_data_enabled`.\n",
    "\n",
    "- Since `job_name`, `job_share_level`, and `experiment_id` are no longer supported, their associated methods are removed, including:\n",
    "    - using job name and experiment ID as filters in `backend.jobs()`\n",
    "    - `job.update_name()`\n",
    "    - `job.name()`\n",
    "    - `job.share_level()`\n",
    "    - `job.experiment_id`\n",
    "\n",
    "- There is no longer a limit on the number of active jobs you can have on a backend, so the following methods have been removed (note this does not apply to the open provider which still has a limit of 5 active jobs).\n",
    "    - `backend.job_limit()`\n",
    "    - `backend.remaining_jobs_count()`\n",
    "    - `backend.active_jobs()`\n",
    "\n",
    "- Retrieving reservation information is no longer supported.\n",
    "\n",
    "- Retrieving calibration data associated with a job, using `job.properties()`, is no longer supported. You can, however, use `backend.properties(datetime=JOB_EXECUTION_TS)` to retrieve this data.\n",
    "\n",
    "- `job.scheduling_mode()` is no longer supported.\n",
    "\n",
    "- `job.wait_for_final_state()` no longer supports a callback function.\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}