{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting Started"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Basic Usage\n",
    "\n",
    "The main interface is the `Benchmark` class with a context manager API:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from zeropybench import Benchmark\n",
    "\n",
    "bench = Benchmark()\n",
    "\n",
    "data = range(1000)\n",
    "with bench():\n",
    "    sum(data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Multidimensional Benchmarking\n",
    "\n",
    "Tag your benchmarks with arbitrary keyword arguments to compare different methods and parameters:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bench = Benchmark()\n",
    "\n",
    "for n in [10, 100, 1000, 10_000, 100_000]:\n",
    "    data = list(range(n))\n",
    "    with bench(method='sum', n=n):\n",
    "        sum(data)\n",
    "    with bench(method='len', n=n):\n",
    "        len(data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Viewing Results\n",
    "\n",
    "Display the benchmark results as a table:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(bench)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Accessing Raw Data\n",
    "\n",
    "Benchmark runs can be accessed individually:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pprint import pprint\n",
    "\n",
    "pprint(bench[4], sort_dicts=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ":::{note}\n",
    "All time measurements in the raw data are in seconds.\n",
    ":::\n",
    "\n",
    "To get the benchmark data as a list of dictionaries:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bench.to_dicts()[:4]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or as a Polars DataFrame:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bench.to_dataframe()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exporting Benchmark Results\n",
    "\n",
    "Benchmarks can be saved in various formats such as CSV:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bench.write_csv('results.csv')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Parquet:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bench.write_parquet('results.parquet')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or MarkDown:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bench.write_markdown('results.md')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Importing Benchmarks Results\n",
    "\n",
    "Benchmarks saved as CSV or Parquet files can be imported:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from zeropybench import read_benchmark\n",
    "\n",
    "bench = read_benchmark('results.csv')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plotting Results\n",
    "\n",
    "Visualize benchmark results with built-in plotting:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bench.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Save the plot to a file:\n",
    "\n",
    "```python\n",
    "bench.write_plot('results.pdf')\n",
    "```\n",
    "\n",
    "## Subplots\n",
    "\n",
    "Create subplots using the `by` parameter:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create subplots by method\n",
    "bench.plot(by='method')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Speedup Plots with Reference\n",
    "\n",
    "Use the `reference` parameter to add a speedup subplot comparing all methods to a baseline. The speedup is computed as `reference_time / method_time`, so values > 1 mean faster than the reference:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Reload the benchmark data\n",
    "bench = Benchmark()\n",
    "\n",
    "for n in [100, 1000, 10000]:\n",
    "    data = list(range(n))\n",
    "    with bench(method='sum', n=n):\n",
    "        sum(data)\n",
    "    with bench(method='len', n=n):\n",
    "        len(data)\n",
    "\n",
    "# Plot with speedup comparison against 'sum'\n",
    "bench.plot(reference='sum')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The plot legend can also be used to select the reference with `reference='method=sum'`, which is handy for multi-dimensional benchmarks."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Configuration Options\n",
    "\n",
    "Customize the benchmark behavior:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bench = Benchmark(\n",
    "    repeat=10,  # Number of measurement repetitions\n",
    "    min_duration_per_repeat=0.5,  # Minimum duration per repeat (seconds)\n",
    "    verbose=True,  # Print the setup and benchmarked code\n",
    ")\n",
    "\n",
    "data = list(range(1000))\n",
    "with bench():\n",
    "    sum(data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Loading Benchmark Data\n",
    "\n",
    "Use `read_benchmark` to load benchmark results from a CSV or Parquet file:\n",
    "\n",
    "```python\n",
    "from zeropybench import read_benchmark\n",
    "\n",
    "# Load benchmark results from CSV\n",
    "bench = read_benchmark('results.csv')\n",
    "\n",
    "# Or from Parquet\n",
    "bench = read_benchmark('results.parquet')\n",
    "\n",
    "# Display results\n",
    "print(bench)\n",
    "\n",
    "# Create plots\n",
    "bench.plot(x='n', by='method')\n",
    "```\n",
    "\n",
    "The file should have been created with `bench.write_csv()` or `bench.write_parquet()`. The metadata (repeat, min_duration_per_repeat) are automatically restored from the file."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}