[add] examples, update readme

README.md

@@ -13,12 +13,13 @@ The library can be easily installed from [PyPi][pypi-page]:
 ```
 pip install htstabilizer
 ```
+Alternatively, you can clone the [repository][repository] and include it in your project. 
 
 ## Tailored to your hardware connectivity
 
 A total of 13 connectivities are currently supported, ranging from 2 to 5 qubits. For each supported number of qubits, circuits for full connectivity and line connectivity are available. Additionally, other connectivities that occur in current quantum chips or which are subgraphs of existing hardware are supported. 
 
-The following graphics show all available connectivities. 
+The following graphics show all currently available connectivities. 
 
 ### 2 qubits
 ![][2-qubit-con]
@@ -41,11 +42,35 @@ pqc = get_preparation_circuit(Stabilizer(["XZZ", "ZXI", "ZIX"]), "linear")
 
 rqc = get_readout_circuit(Stabilizer(["XZZ", "ZXI", "ZIX"]), "linear")
 
+qc = QuantumCircuit(5)
+# ... build Clifford circuit
+compressed_qc = compress_preparation_circuit(qc, "T")
 ```
 
 
+## Examples
+
+View the examples for exploring the functionality:
+
+- [Compressing Clifford preparation circuits][example-compress]
+- [Generating readout circuits][example-readout]
+- [Perform state tomography][example-tomography]
+
+
+## License
+[MIT License][license]
+
 [pypi-page]: https://pypi.org/project/htstabilizer/
+[repository]: https://github.com/Mc-Zen/htstabilizer
+[license]: https://github.com/Mc-Zen/htstabilizer/blob/master/LICENSE.txt
+
 [2-qubit-con]: https://github.com/Mc-Zen/htstabilizer/blob/master/docs/images/2-qubit%20connectivities.png
 [3-qubit-con]: https://github.com/Mc-Zen/htstabilizer/blob/master/docs/images/3-qubit%20connectivities.png
 [4-qubit-con]: https://github.com/Mc-Zen/htstabilizer/blob/master/docs/images/4-qubit%20connectivities.png
 [5-qubit-con]: https://github.com/Mc-Zen/htstabilizer/blob/master/docs/images/5-qubit%20connectivities.png
+
+[example-compress]: https://github.com/Mc-Zen/htstabilizer/blob/master/examples/compress_preparation_circuit.py
+[example-readout]: https://github.com/Mc-Zen/htstabilizer/blob/master/examples/readout_circuit.py
+[example-tomography]: https://github.com/Mc-Zen/htstabilizer/blob/master/examples/state_tomography.py
+
+

examples/compress_preparation_circuit.py

@@ -0,0 +1,29 @@
+
+from htstabilizer.stabilizer_circuits import *
+from qiskit.quantum_info import random_clifford
+
+"""
+You can compress a Clifford circuit by replacing it with a
+hardware-tailored optimized circuit. 
+
+The resulting circuit will only contain two-qubit gates between 
+connected qubits (with respect to the given connectivity), so no 
+further SWAP gates will be introduced when transpiling the circuit
+to hardware connectivity. 
+
+Hint: try 
+    >>> from htstabilizer.connectivity_support import *
+    >>> get_available_connectivities()
+to get a list of all available connectivities and for instance
+    >>> get_connectivity_graph(5, "T").draw()
+to display the graph of a specific connectivity.
+"""
+
+
+# Generate some Clifford circuit
+qc = random_clifford(5, seed=23).to_circuit()
+
+# Optimizing it for T-shaped connectivity
+compressed_qc = compress_preparation_circuit(qc, "T")
+print(qc)
+print(compressed_qc)

examples/readout_circuit.py

@@ -0,0 +1,49 @@
+from htstabilizer.stabilizer_circuits import *
+
+
+"""
+Example: Get a readout circuit for a 3-qubit stabilizer group
+optimized for linear connectivity.
+
+Hint: try 
+    >>> from htstabilizer.connectivity_support import *
+    >>> get_available_connectivities()
+to get a list of all available connectivities and for instance
+    >>> get_connectivity_graph(5, "T").draw()
+to display the graph of a specific connectivity.
+"""
+qc = get_readout_circuit(Stabilizer(["XZZ", "ZXI", "ZIX"]), "linear")
+
+
+"""
+Notes on building the `Stabilizer` object
+"""
+
+
+# You can also pass a QuantumCircuit that only contains Clifford gates:
+qc = QuantumCircuit(3)
+# ... add gates
+stabilizer = Stabilizer(qc, validate=True)
+
+# If you specify `validate=True`, then the stabilizer will check
+# that the given Paulis actually form a valid stabilizer:
+stabilizer = Stabilizer(["XZZ", "ZXI", "ZIX"], validate=True)
+
+# You can initialize a Stabilizer through a graph representing
+# a graph state:
+graph = Graph(3)
+graph.add_path([0, 1, 2])
+stabilizer = Stabilizer(graph)
+
+
+# ... or by passing X and Z matrices for the stabilizer
+import numpy as np
+R = np.array([[1, 0, 0],
+              [0, 1, 0],  # each column corresponds to one Pauli
+              [0, 0, 1]])
+S = np.array([[0, 1, 1],
+              [1, 0, 0],
+              [1, 0, 0]])
+s3 = Stabilizer((R, S))
+
+# This would be equivalent to `Stabilizer(["XZZ", "ZXI", "ZIX"])`

examples/state_tomography.py

@@ -0,0 +1,54 @@
+
+from htstabilizer.tomography import *
+import qiskit
+
+
+backend = qiskit.Aer.get_backend("qasm_simulator")
+
+
+# Create a preparation circuit for the state to measure
+preparation_circuit = QuantumCircuit(5)
+preparation_circuit.h(0)
+preparation_circuit.cx(range(4), range(1, 5))
+
+
+##############################
+# Full state tomography
+##############################
+
+# Get 2^5 optimized circuits for measurement on linear hardware connectivity
+qst = full_state_tomography_circuits(preparation_circuit, "linear")
+job = qiskit.execute(qst, backend=backend, shots=100)
+
+fitter = FullStateTomographyFitter(job.result(), qst)
+
+# We can get a dictionaray of expectation values
+print(fitter.expectation_values())
+# Or the state matrix
+print(fitter.density_matrix())
+
+
+# It is possible to measure marginals by passing the a list of qubits to measure
+qst = full_state_tomography_circuits(preparation_circuit, "all", measured_qubits=[0, 1])
+job = qiskit.execute(qst, backend=backend, shots=100)
+
+fitter = FullStateTomographyFitter(job.result(), qst)
+print(fitter.density_matrix())
+
+
+
+
+##############################
+# Measure only a stabilizer group
+##############################
+
+smc = stabilizer_measurement_circuit(
+    preparation_circuit,
+    Stabilizer(["XX", "YY"]),
+    "all",
+    measured_qubits=[0, 1]
+)
+job = qiskit.execute(smc, backend=backend, shots=100)
+
+fitter = StabilizerMeasurementFitter(job.result(), smc)
+print(fitter.expectation_values())

tests/test_examples.py

@@ -0,0 +1,24 @@
+# This test file is designated for running the example files
+# (and checking that they run without error). The example files
+# lie in the example folder and thus a call to for example
+#    import htstabilizer.graph
+# results in an import error. 
+# To solve this, we add the src/ directory to the sys path here
+
+import unittest
+import sys
+
+sys.path.insert(0, "src/") # simulate the package being installed, so that
+
+
+class TestExamples(unittest.TestCase):
+
+    def test_readout_example(self):
+        import examples.readout_circuit
+
+    def test_tomography_example(self):
+        import examples.state_tomography
+
+    def test_compress_preparation_circuit(self):
+        import examples.compress_preparation_circuit
+