{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Quick Start Guide\n",
    "\n",
    "This notebook provides a quick introduction to StateTracker, a Python library for creating composable states with unidirectional state propagation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installation\n",
    "\n",
    "Install from PyPI:\n",
    "\n",
    "```bash\n",
    "pip install statetracker\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Basic Usage\n",
    "\n",
    "All states must be created within a `Manager` context:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-17T20:47:44.819254Z",
     "iopub.status.busy": "2026-01-17T20:47:44.819017Z",
     "iopub.status.idle": "2026-01-17T20:47:45.770051Z",
     "shell.execute_reply": "2026-01-17T20:47:45.769582Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[0, 1, 2]\n"
     ]
    }
   ],
   "source": [
    "from statetracker import Manager, State\n",
    "\n",
    "with Manager():\n",
    "    A = State(num_values=3, name=\"A\")\n",
    "    print(list(A))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## State Operations\n",
    "\n",
    "### Product (Cartesian Product)\n",
    "\n",
    "Use `product` to create Cartesian products:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-17T20:47:45.790246Z",
     "iopub.status.busy": "2026-01-17T20:47:45.790066Z",
     "iopub.status.idle": "2026-01-17T20:47:45.793161Z",
     "shell.execute_reply": "2026-01-17T20:47:45.792719Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "C=0, A=0, B=0\n",
      "C=1, A=1, B=0\n",
      "C=2, A=0, B=1\n",
      "C=3, A=1, B=1\n",
      "C=4, A=0, B=2\n",
      "C=5, A=1, B=2\n"
     ]
    }
   ],
   "source": [
    "from statetracker import Manager, State, product\n",
    "\n",
    "with Manager():\n",
    "    A = State(num_values=2, name=\"A\")\n",
    "    B = State(num_values=3, name=\"B\")\n",
    "    C = product([A, B], name=\"C\")  # 6 states\n",
    "\n",
    "    for _ in C:\n",
    "        C.print_states()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Stack (Disjoint Union)\n",
    "\n",
    "Use `stack` to create disjoint unions where only one state is active at a time:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-17T20:47:45.794650Z",
     "iopub.status.busy": "2026-01-17T20:47:45.794550Z",
     "iopub.status.idle": "2026-01-17T20:47:45.797053Z",
     "shell.execute_reply": "2026-01-17T20:47:45.796494Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "C=0, A=0, B=None\n",
      "C=1, A=1, B=None\n",
      "C=2, A=None, B=0\n",
      "C=3, A=None, B=1\n",
      "C=4, A=None, B=2\n"
     ]
    }
   ],
   "source": [
    "from statetracker import Manager, State, stack\n",
    "\n",
    "with Manager():\n",
    "    A = State(num_values=2, name=\"A\")\n",
    "    B = State(num_values=3, name=\"B\")\n",
    "    C = stack([A, B], name=\"C\")  # 5 states\n",
    "\n",
    "    for _ in C:\n",
    "        # Only one of A or B is active at a time (the other is None)\n",
    "        C.print_states()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Slicing\n",
    "\n",
    "Use Python slice syntax to select subsets of states:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-17T20:47:45.798358Z",
     "iopub.status.busy": "2026-01-17T20:47:45.798258Z",
     "iopub.status.idle": "2026-01-17T20:47:45.801471Z",
     "shell.execute_reply": "2026-01-17T20:47:45.800977Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "A has 10 states\n",
      "\n",
      "B (slice [2:5]) has 3 states: [0, 1, 2]\n",
      "B=0, A=2\n",
      "B=1, A=3\n",
      "B=2, A=4\n",
      "\n",
      "C (reversed) has 10 states: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]\n",
      "C=0, A=9\n",
      "C=1, A=8\n",
      "C=2, A=7\n",
      "C=3, A=6\n",
      "C=4, A=5\n",
      "C=5, A=4\n",
      "C=6, A=3\n",
      "C=7, A=2\n",
      "C=8, A=1\n",
      "C=9, A=0\n"
     ]
    }
   ],
   "source": [
    "from statetracker import Manager, State\n",
    "\n",
    "with Manager():\n",
    "    A = State(num_values=10, name=\"A\")\n",
    "    B = A[2:5].named(\"B\")  # States 2, 3, 4\n",
    "    C = A[::-1].named(\"C\")  # Reversed: 9, 8, 7, ..., 0\n",
    "\n",
    "    print(f\"A has {A.num_values} states\")\n",
    "    print(f\"\\nB (slice [2:5]) has {B.num_values} states: {list(B)}\")\n",
    "    for _ in B:\n",
    "        B.print_states()\n",
    "\n",
    "    print(f\"\\nC (reversed) has {C.num_values} states: {list(C)}\")\n",
    "    for _ in C:\n",
    "        C.print_states()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## State Propagation\n",
    "\n",
    "StateTracker uses unidirectional state propagation. Setting a child state's state automatically updates all parent states:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-17T20:47:45.802796Z",
     "iopub.status.busy": "2026-01-17T20:47:45.802713Z",
     "iopub.status.idle": "2026-01-17T20:47:45.805009Z",
     "shell.execute_reply": "2026-01-17T20:47:45.804653Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "After setting C.state = 5:\n",
      "A.state = 1\n",
      "B.state = 2\n"
     ]
    }
   ],
   "source": [
    "from statetracker import Manager, State, product\n",
    "\n",
    "with Manager():\n",
    "    A = State(num_values=2, name=\"A\")\n",
    "    B = State(num_values=3, name=\"B\")\n",
    "    C = product([A, B])\n",
    "\n",
    "    C.value = 5  # Set child state\n",
    "    print(\"After setting C.value = 5:\")\n",
    "    print(f\"A.value = {A.value}\")  # 1 (automatically updated)\n",
    "    print(f\"B.value = {B.value}\")  # 2 (automatically updated)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Inspecting States\n",
    "\n",
    "Use `get_states()` and `print_states()` to conveniently view all state states at once:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "C=5, A=1, B=2\n",
      "{'C': 5, 'A': 1, 'B': 2}\n"
     ]
    }
   ],
   "source": [
    "from statetracker import Manager, State, product\n",
    "\n",
    "with Manager():\n",
    "    A = State(num_values=2, name=\"A\")\n",
    "    B = State(num_values=3, name=\"B\")\n",
    "    C = product([A, B], name=\"C\")\n",
    "\n",
    "    C.value = 5\n",
    "    C.print_states()  # Print all states in one line\n",
    "\n",
    "    states = C.get_states()  # Get states as a dictionary\n",
    "    print(states)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Visualization\n",
    "\n",
    "Use `print_dag()` to visualize state dependencies:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-17T20:47:45.806540Z",
     "iopub.status.busy": "2026-01-17T20:47:45.806440Z",
     "iopub.status.idle": "2026-01-17T20:47:45.809625Z",
     "shell.execute_reply": "2026-01-17T20:47:45.809105Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "C (counter, io=0, n=6)\n",
      "└── [op=Product]\n",
      "    ├── A (counter, io=0, n=2)\n",
      "    └── B (counter, io=0, n=3)\n"
     ]
    }
   ],
   "source": [
    "from statetracker import Manager, State, product\n",
    "\n",
    "with Manager():\n",
    "    A = State(num_values=2, name=\"A\")\n",
    "    B = State(num_values=3, name=\"B\")\n",
    "    C = product([A, B], name=\"C\")\n",
    "\n",
    "    C.print_dag()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Next Steps\n",
    "\n",
    "- See the **Concepts** page for a deeper understanding of state algebra\n",
    "- Explore the **Operations** reference for all available operations\n",
    "- Check the **API Reference** for detailed function documentation"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "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.10.16"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}