{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "bf9bf4e5-c00f-4124-8d2e-d00dc04cc436",
   "metadata": {},
   "source": [
    "# Using `cutqc2` on the command line\n",
    "\n",
    "`cutqc2` has 3 main functionalities, along with some optional ones useful for debugging.\n",
    "\n",
    "1. **Circuit cutting**: Cut large quantum circuits into smaller sub-circuits that can be executed on smaller quantum devices.\n",
    "2. **Execution**: Execute the sub-circuits on quantum hardware or simulators, and collect the results.\n",
    "3. **Postprocessing**: Reconstruct the results of the original circuit from the results of the sub-circuits.\n",
    "4. **(Optional) Verify**: Verify the results of the original circuit using classical simulation.\n",
    "5. **(Optional) Visualize**: Plot the probability distribution of the results.\n",
    "\n",
    "## Circuit cutting and execution\n",
    "\n",
    "Steps 1 and 2 are performed using the `cutqc2 cut` command.\n",
    "\n",
    "Say you have a qasm3 file representing a quantum circuit. Some examples are provided in the `examples/scripts` folder in the codebase. You can cut and execute the circuit as follows:\n",
    "\n",
    "```\n",
    "cutqc2 cut \\\n",
    "  --file supremacy_6qubit.qasm3 \\\n",
    "  --max-subcircuit-width 5 \\\n",
    "  --max-cuts 10 \\\n",
    "  --num-subcircuits 3 \\\n",
    "  --output-file supremacy_6qubit.zarr\n",
    "```\n",
    "\n",
    "This will:\n",
    " - Cut the circuit into sub-circuits with a maximum width of 5 qubits, and a maximum of 10 cuts.\n",
    " - The `num-subcircuits` parameter specifies how many sub-circuits to create. You can specify this parameter multiple times - `cutqc2` will try each in sequence till it finds a suitable cut solution.\n",
    " - Run each sub-circuit on a simulator (by default, `qiskit`'s statevector simulator is used).\n",
    " - Save results (that can be used for reconstruction) in a `zarr` file named `supremacy_6qubit.zarr`. If you do not specify an `--output-file`, a default filename (that includes a timestamp, among other things) will be used.\n",
    "\n",
    "### Downloading a pre-generated and pre-cut circuit\n",
    "\n",
    "To download a pre-generated and pre-cut circuit from `cutqc2`, you can use the `cutqc2 download` command.\n",
    "Use `cutqc2 download --list` to see a list of available files, and `cutqc2 download\n",
    "\n",
    "## Postprocessing\n",
    "\n",
    "Once you have the `zarr` file with the results of the sub-circuits, you can reconstruct the results of the original circuit using the `cutqc2 postprocess` command:\n",
    "\n",
    "```\n",
    "cutqc2 postprocess \\\n",
    "  --file supremacy_6qubit.zarr \\\n",
    "  --save\n",
    "```\n",
    "\n",
    "This will:\n",
    " - Read the `zarr` file with the results of the sub-circuits.\n",
    " - Combine (reconstrcut) the results so they are identical to what you would have obtained by executing the original circuit. **This is a computationally and memory intensive step!** that can benefit from GPU and MPI support.\n",
    " - Save the reconstructed results back into the same `zarr` file.\n",
    "\n",
    "To run this command in a cluster setting with multiple nodes (each having access to a GPU), use `mpirun` to execute this step:\n",
    "\n",
    "```\n",
    "mpirun -np 4 cutqc2 postprocess \\\n",
    "  --file supremacy_6qubit.zarr \\\n",
    "  --save\n",
    "```\n",
    "\n",
    "A job scheduler like `slurm` will typically be used for this step. See the [deployment](05_deployment.ipynb) notebook on how we use `cutqc2` on our clusters for some deployment tips.\n",
    "\n",
    "## Verification\n",
    "\n",
    "Finally, you can verify the results of the original circuit using classical simulation with the `cutqc2 verify` command:\n",
    "\n",
    "```\n",
    "cutqc2 verify \\\n",
    "  --file supremacy_6qubit.zarr\n",
    "```\n",
    "\n",
    "This will:\n",
    " - Read the `zarr` file with the results of the original circuit (reconstructed in the previous step).\n",
    " - Classically simulate the original circuit using `qiskit`'s statevector simulator to obtain reference results. \n",
    " - Compare the reconstructed results with the reference results.\n",
    "\n",
    "Obviously, running the original circuit using classical simulation is **only feasible for small circuits** (up to about 20 qubits).\n",
    "\n",
    "## Visualization\n",
    "\n",
    "Plotting of the complete state vector (stiched together from the state vectors of the individual circuits, is possible using the `plot` command:\n",
    "\n",
    "```\n",
    "cutqc2 plot \\\n",
    "  --file supremacy_6qubit.zarr \\\n",
    "  --output-file supremacy_6qubit.png\n",
    "```\n",
    "\n",
    "You can include the flag `--plot-ground-truth` to also plot ground truth values (determined by running `qiskit`'s statevector simulator). As is the case with `verify`, this is **only feasible for small circuits**.\n",
    "\n",
    "You can see some complete examples in the `examples/scripts` folder.\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.12.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}