Update README.md to include sampler and estimator

README.md

@@ -8,12 +8,12 @@
 [![Downloads](https://pepy.tech/badge/qiskit-terra)](https://pypi.org/project/qiskit-terra/)<!--- long-description-skip-end -->
 [![DOI](https://zenodo.org/badge/161550823.svg)](https://zenodo.org/badge/latestdoi/161550823)
 
-**Qiskit** is an open-source framework for working with noisy quantum computers at the level of pulses, circuits, and algorithms.
+**Qiskit**  is an open-source SDK for working with quantum computers at the level of extended quantum circuits, operators, and primitives.
 
-This framework allows for building, transforming, and visualizing  quantum circuits. It also contains a compiler that supports
-different quantum computers and a common interface for running programs on different quantum computer architectures.
+This library is the core component of Qiskit, which contains the building blocks for creating and working with quantum circuits, quantum operators, and primitive functions (sampler and estimator).
+It also contains a transpiler that supports optimizing quantum circuits and a quantum information toolbox for creating advanced quantum operators. 
 
-For more details on how to use Qiskit you can refer to the documentation located here:
+For more details on how to use Qiskit, refer to the documentation located here:
 
 <https://qiskit.org/documentation/>
 
@@ -30,61 +30,92 @@ Pip will handle all dependencies automatically and you will always install the l
 
 To install from source, follow the instructions in the [documentation](https://qiskit.org/documentation/contributing_to_qiskit.html#install-install-from-source-label).
 
-## Creating Your First Quantum Program in Qiskit
+## Create your first quantum program in Qiskit
 
-Now that Qiskit is installed, it's time to begin working with Qiskit. To do this
-we create a `QuantumCircuit` object to define a basic quantum program.
+Now that Qiskit is installed, it's time to begin working with Qiskit. The essential parts of a quantum program are:
+1. Define and build a quantum circuit that represents the quantum state
+2. Define the classical output by measurements or a set of observable operators
+3. Depending on the output, use the primitive function `sampler` to sample outcomes or the `estimator` to estimate values.
+
+Create an example quantum circuit using the `QuantumCircuit` class:
 
 ```python
+import numpy as np
 from qiskit import QuantumCircuit
-qc = QuantumCircuit(2, 2)
-qc.h(0)
-qc.cx(0, 1)
-qc.measure([0,1], [0,1])
+
+# 1. A quantum circuit for preparing the quantum state |000> + i |111>
+qc_example = QuantumCircuit(3)
+qc_example.h(0)          # generate superpostion
+qc_example.p(np.pi/2,0)  # add quantum phase
+qc_example.cx(0,1)       # 0th-qubit-Controlled-NOT gate on 1st qubit
+qc_example.cx(0,2)       # 0th-qubit-Controlled-NOT gate on 2nd qubit
 ```
 
-This example makes an entangled state, also called a [Bell state](https://en.wikipedia.org/wiki/Bell_state).
+This simple example makes an entangled state known as a [GHZ state](https://en.wikipedia.org/wiki/Greenberger%E2%80%93Horne%E2%80%93Zeilinger_state) $(|000\rangle + |111\rangle)/\sqrt{2}$. It uses the standard quantum gates: Hadamard gate (`h`), Phase gate (`p`), and CNOT gate (`cx`). 
 
-Once you've made your first quantum circuit, you can then simulate it.
-To do this, first we need to compile your circuit for the target backend we're going to run
-on. In this case we are leveraging the built-in `BasicAer` simulator. However, this
-simulator is primarily for testing and is limited in performance and functionality (as the name
-implies). You should consider more sophisticated simulators, such as [`qiskit-aer`](https://github.com/Qiskit/qiskit-aer/),
-for any real simulation work.
+Once you've made your first quantum circuit, choose which primitive function you will use. Starting with `sampler`,
+we use `measure_all(inplace=False)` to get a copy of the circuit in which all the qubits are measured:
 
 ```python
-from qiskit import transpile
-from qiskit.providers.basicaer import QasmSimulatorPy
-backend_sim = QasmSimulatorPy()
-transpiled_qc = transpile(qc, backend_sim)
+# 2. Add the classical output to be measurement in a different circuit
+qc_measured = qc_example.measure_all(inplace=False)
+
+# 3. Execute using the Sampler primitive
+from qiskit.primitives.sampler import Sampler
+sampler = Sampler()
+job = sampler.run(qc_measured, shots=1000)
+result = job.result()
+print(f" > Quasi probability distribution: {result.quasi_dists}")
 ```
-
-After compiling the circuit we can then run this on the ``backend`` object with:
+Running this will give an outcome similar to `{0: 0.497, 7: 0.503}` which is `000` 50% of the time and `111` 50% of the time up to statistical fluctuations.  
+To illustrate the power of Estimator, we now use the quantum information toolbox to create the operator $XXY+XYX+YXX-YYY$ and pass it to the `run()` function, along with our quantum circuit. Note the Estimator requires a circuit _**without**_ measurement, so we use the `qc_example` circuit we created earlier.
 
 ```python
-result = backend_sim.run(transpiled_qc).result()
-print(result.get_counts(qc))
+# 2. define the observable to be measured 
+from qiskit.quantum_info import SparsePauliOp
+operator = SparsePauliOp.from_list([("XXY", 1), ("XYX", 1), ("YXX", 1), ("YYY", -1)])
+
+# 3. Execute using the Estimator primitive
+from qiskit.primitives import Estimator
+estimator = Estimator()
+job = estimator.run(qc_example, operator, shots=1000)
+result = job.result()
+print(f" > Expectation values: {result.values}")
 ```
 
-The output from this execution will look similar to this:
+Running this will give the outcome `4`. For fun, try to assign a value of +/- 1 to each single-qubit operator X and Y 
+and see if you can achieve this outcome. (Spoiler alert: this is not possible!)
+
+Using the Qiskit-provided `qiskit.primitives.Sampler` and `qiskit.primitives.Estimator` will not take you very far. The power of quantum computing cannot be simulated 
+on classical computers and you need to use real quantum hardware to scale to larger quantum circuits. However, running a quantum 
+circuit on hardware requires rewriting them to the basis gates and connectivity of the quantum hardware.
+The tool that does this is the [transpiler](https://qiskit.org/documentation/apidoc/transpiler.html) 
+and Qiskit includes transpiler passes for synthesis, optimization, mapping, and scheduling. However, it also includes a
+default compiler which works very well in most examples. The following code will map the example circuit to the `basis_gates = ['cz', 'sx', 'rz']` and a linear chain of qubits $0 \rightarrow 1 \rightarrow 2$ with the `coupling_map =[[0, 1], [1, 2]]`.
 
 ```python
-{'00': 513, '11': 511}
+from qiskit import transpile
+qc_transpiled = transpile(qc_example, basis_gates = ['cz', 'sx', 'rz'], coupling_map =[[0, 1], [1, 2]] , optimization_level=3)
 ```
 
 For further examples of using Qiskit you can look at the tutorials in the documentation here:
 
 <https://qiskit.org/documentation/tutorials.html>
 
-### Executing your code on a real quantum chip
+### Executing your code on real quantum hardware
+
+Qiskit provides an abstraction layer that lets users run quantum circuits on hardware from any vendor that provides a compatible interface. 
+The best way to use Qiskit is with a runtime environment that provides optimized implementations of `sampler` and `estimator` for a given hardware platform. This runtime may involve using pre- and post-processing, such as optimized transpiler passes with error suppression, error mitigation, and, eventually, error correction built in. A runtime implements `qiskit.primitives.BaseSampler` and `qiskit.primitives.BaseEstimator` interfaces. For example,
+some packages that provide implementations of a runtime primitive implementation are:
+
+* https://github.com/Qiskit/qiskit-ibm-runtime
 
-You can also use Qiskit to execute your code on a **real quantum processor**.
-Qiskit provides an abstraction layer that lets users run quantum circuits on hardware from any
-vendor that provides an interface to their systems through Qiskit. Using these ``providers`` you can run any Qiskit code against
-real quantum computers. Some examples of published provider packages for running on real hardware are:
+Qiskit also provides a lower-level abstract interface for describing quantum backends. This interface, located in
+``qiskit.providers``, defines an abstract `BackendV2` class that providers can implement to represent their
+hardware or simulators to Qiskit. The backend class includes a common interface for executing circuits on the backends; however, in this interface each provider may perform different types of pre- and post-processing and return outcomes that are vendor-defined. Some examples of published provider packages that interface with real hardware are:
 
-* https://github.com/Qiskit/qiskit-ibmq-provider
-* https://github.com/Qiskit-Partners/qiskit-ionq
+* https://github.com/Qiskit/qiskit-ibm-provider
+* https://github.com/qiskit-community/qiskit-ionq
 * https://github.com/Qiskit-Partners/qiskit-aqt-provider
 * https://github.com/qiskit-community/qiskit-braket-provider
 * https://github.com/qiskit-community/qiskit-quantinuum-provider