{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "b24be6f6",
   "metadata": {},
   "source": [
    "# 01 - Hello Quantum\n",
    "\n",
    "Your first quantum circuit with QuantSDK. We'll create a single-qubit circuit,\n",
    "put it in superposition, measure it, and inspect the results.\n",
    "\n",
    "**Concepts:** Qubits, superposition, measurement, shots"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "65585643",
   "metadata": {},
   "outputs": [],
   "source": [
    "import quantsdk as qs\n",
    "\n",
    "print(f\"QuantSDK version: {qs.__version__}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "354e314e",
   "metadata": {},
   "source": [
    "## Create a Single-Qubit Circuit\n",
    "\n",
    "Every qubit starts in the |0> state. Let's create a 1-qubit circuit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4b97b3fa",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create a 1-qubit circuit\n",
    "circuit = qs.Circuit(1, name=\"hello-quantum\")\n",
    "print(f\"Qubits: {circuit.num_qubits}\")\n",
    "print(f\"Name: {circuit.name}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4d75d842",
   "metadata": {},
   "source": [
    "## Apply a Hadamard Gate\n",
    "\n",
    "The Hadamard gate puts a qubit into **superposition** — equal probability of |0> and |1>.\n",
    "\n",
    "$$H|0\\rangle = \\frac{1}{\\sqrt{2}}(|0\\rangle + |1\\rangle)$$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "102c0e44",
   "metadata": {},
   "outputs": [],
   "source": [
    "circuit.h(0)          # Hadamard on qubit 0\n",
    "circuit.measure_all()  # Measure\n",
    "\n",
    "print(circuit.draw())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "84842267",
   "metadata": {},
   "source": [
    "## Run the Circuit"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6b0fac5f",
   "metadata": {},
   "outputs": [],
   "source": [
    "result = qs.run(circuit, shots=1000)\n",
    "\n",
    "print(f\"Counts: {result.counts}\")\n",
    "print(f\"Probabilities: {result.probabilities}\")\n",
    "print(f\"Most likely: {result.most_likely}\")\n",
    "print(f\"Shots: {result.shots}\")\n",
    "print(f\"Backend: {result.backend}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fd85f953",
   "metadata": {},
   "source": [
    "## Interpret the Results\n",
    "\n",
    "You should see roughly 50% |0> and 50% |1>. That's superposition!\n",
    "\n",
    "Run the cell above multiple times — the counts change each time (quantum randomness),\n",
    "but the probabilities stay near 50/50."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7aa8a202",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Try with a seed for reproducibility\n",
    "result_seeded = qs.run(circuit, shots=1000, seed=42)\n",
    "print(f\"Seeded counts: {result_seeded.counts}\")\n",
    "\n",
    "# Run again with same seed — identical results!\n",
    "result_seeded2 = qs.run(circuit, shots=1000, seed=42)\n",
    "print(f\"Same seed: {result_seeded2.counts}\")\n",
    "print(f\"Identical? {result_seeded.counts == result_seeded2.counts}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "73772af9",
   "metadata": {},
   "source": [
    "## The Fluent API\n",
    "\n",
    "QuantSDK supports method chaining — build circuits in one line!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7de87c8f",
   "metadata": {},
   "outputs": [],
   "source": [
    "# One-liner: create, apply gates, measure, run\n",
    "result = qs.run(\n",
    "    qs.Circuit(1).h(0).measure_all(),\n",
    "    shots=1000\n",
    ")\n",
    "print(result.counts)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "be100e47",
   "metadata": {},
   "source": [
    "## What's Next?\n",
    "\n",
    "- [02 - Bell States](02_bell_states.ipynb) — Create entangled qubits\n",
    "- [04 - Single-Qubit Gates](04_single_qubit_gates.ipynb) — Explore all single-qubit gates"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}