NTT-learning/notebooks/foundations/01_convolution_to_toy_ntt/lecture.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "pedagogy": {
          "role": "meta",
          "difficulty": 1,
          "kind": "orientation",
          "title": "Objectives"
        }
      },
      "source": "## META | difficulty 1 | Objectives\n\nThis notebook introduces the first technical bundle.\n\nFocus:\n\n- why polynomial multiplication matters\n- what negacyclic folding changes\n- how a tiny toy NTT gives a matrix-level view\n- what a butterfly does locally\n"
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "pedagogy": {
          "role": "mandatory",
          "difficulty": 2,
          "kind": "explanation",
          "title": "Convolution Before Transforms"
        }
      },
      "source": "## MANDATORY | difficulty 2 | Convolution Before Transforms\n\nStart with the concrete problem. Two coefficient arrays multiply by accumulating all pairwise products.\nThat schoolbook view is the baseline the learner should be able to inspect by hand before a transform is introduced.\n"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "pedagogy": {
          "role": "mandatory",
          "difficulty": 2,
          "kind": "demo",
          "title": "Inspect Convolution And Negacyclic Folding"
        }
      },
      "outputs": [],
      "source": "# MANDATORY | difficulty 2 | Inspect Convolution And Negacyclic Folding\n\nfrom ntt_learning.toy_ntt import negacyclic_multiply, schoolbook_convolution\n\nleft = [2, 1, 3, 0]\nright = [1, 4, 0, 2]\n\nprint(\"convolution:\", schoolbook_convolution(left, right))\nprint(\"negacyclic in x^4 + 1:\", negacyclic_multiply(left, right, n=4))\n"
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "pedagogy": {
          "role": "mandatory",
          "difficulty": 2,
          "kind": "explanation",
          "title": "Toy NTT As A Round Trip"
        }
      },
      "source": "## MANDATORY | difficulty 2 | Toy NTT As A Round Trip\n\nA tiny transform is useful because it keeps every entry inspectable. The first goal is not Kyber fidelity.\nThe first goal is to see that the transform maps one coefficient view to another and can be inverted.\n"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "pedagogy": {
          "role": "mandatory",
          "difficulty": 2,
          "kind": "demo",
          "title": "Run A Tiny Forward And Inverse NTT"
        }
      },
      "outputs": [],
      "source": "# MANDATORY | difficulty 2 | Run A Tiny Forward And Inverse NTT\n\nfrom ntt_learning.toy_ntt import find_primitive_root, forward_ntt, inverse_ntt\n\nmodulus = 17\nomega = find_primitive_root(order=4, modulus=modulus)\nsignal = [3, 1, 4, 1]\nspectrum = forward_ntt(signal, modulus=modulus, omega=omega)\n\nprint(\"primitive 4th root:\", omega)\nprint(\"forward spectrum:\", spectrum)\nprint(\"inverse recovery:\", inverse_ntt(spectrum, modulus=modulus, omega=omega))\n"
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "pedagogy": {
          "role": "mandatory",
          "difficulty": 3,
          "kind": "explanation",
          "title": "Butterflies Are Local Dataflow"
        }
      },
      "source": "## MANDATORY | difficulty 3 | Butterflies Are Local Dataflow\n\nA butterfly is a local rewrite of a pair. The pair changes because one branch is twiddled by a zeta value.\nThis is separate from the global story about polynomial multiplication.\n\nForward Cooley-Tukey and inverse Gentleman-Sande have the same shape intuition: pair values, combine them, and move layer by layer.\n"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "pedagogy": {
          "role": "mandatory",
          "difficulty": 3,
          "kind": "demo",
          "title": "Compare Pairwise And Stage-Level Butterfly Views"
        }
      },
      "outputs": [],
      "source": "# MANDATORY | difficulty 3 | Compare Pairwise And Stage-Level Butterfly Views\n\nfrom ntt_learning.toy_ntt import action_rows, apply_ct_stage, ct_butterfly_pair, gs_butterfly_pair\n\nprint(\"single CT pair:\", ct_butterfly_pair(top=7, bottom=5, zeta=3, modulus=17))\nprint(\"single GS pair:\", gs_butterfly_pair(top=7, bottom=5, zeta=3, modulus=17))\n\nvalues = [3, 1, 4, 1]\nstage_output, stage_actions = apply_ct_stage(values, block_size=2, zetas=1, modulus=17)\n\nprint(\"stage output:\", stage_output)\nprint(\"stage trace:\", action_rows(stage_actions))\n"
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "pedagogy": {
          "role": "mandatory",
          "difficulty": 2,
          "kind": "quiz",
          "title": "Retrieval Check"
        }
      },
      "source": "## MANDATORY | difficulty 2 | Retrieval Check\n\nQuiz:\n\n1. What changes when schoolbook multiplication is folded negacyclically?\n2. Why is the toy NTT introduced before Kyber indexing details?\n3. In a butterfly, which part of the computation is local and directly inspectable?\n"
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "pedagogy": {
          "role": "facultative",
          "difficulty": 4,
          "kind": "exploration",
          "title": "Optional Extension"
        }
      },
      "source": "## FACULTATIVE | difficulty 4 | Optional Extension\n\nIf the local pairings already feel comfortable, inspect a bit-reversed ordering next. That prepares the learner\nfor later discussions of array ordering without mixing it into the mandatory route too early.\n"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "pedagogy": {
          "role": "facultative",
          "difficulty": 4,
          "kind": "exploration",
          "title": "Bit-Reversed Ordering"
        }
      },
      "outputs": [],
      "source": "# FACULTATIVE | difficulty 4 | Bit-Reversed Ordering\n\nfrom ntt_learning.toy_ntt import bit_reversed_order\n\nprint(bit_reversed_order([0, 1, 2, 3, 4, 5, 6, 7]))\n"
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "pedagogy": {
          "role": "meta",
          "difficulty": 1,
          "kind": "handoff",
          "title": "Next Notebook"
        }
      },
      "source": "## META | difficulty 1 | Next Notebook\n\nNext notebook: `lab.ipynb`\n"
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "name": "python"
    },
    "ntt_learning": {
      "title": "Lecture: Convolution To Toy NTT",
      "contract_version": "0.1",
      "sequence": [
        "notebooks/START_HERE.ipynb",
        "notebooks/COURSE_BLUEPRINT.ipynb",
        "notebooks/foundations/01_convolution_to_toy_ntt/lecture.ipynb",
        "notebooks/foundations/01_convolution_to_toy_ntt/lab.ipynb",
        "notebooks/foundations/01_convolution_to_toy_ntt/problems.ipynb",
        "notebooks/foundations/01_convolution_to_toy_ntt/studio.ipynb"
      ]
    }
  },
  "nbformat": 4,
  "nbformat_minor": 5
}