NTT-learning/notebooks/professional/06_debugging_ntt_failures/lecture.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "pedagogy": {
          "role": "meta",
          "difficulty": 1,
          "kind": "orientation",
          "title": "Objectives"
        }
      },
      "source": "## META | difficulty 1 | Objectives\n\nThis final bundle turns common failure modes into visible patterns instead of vague warnings.\n\nFocus:\n\n- wrong sign in wraparound\n- wrong root or wrong zeta\n- wrong BO / NO comparison\n- missing final scaling\n- wrong mental model for the Kyber modulus\n"
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "pedagogy": {
          "role": "mandatory",
          "difficulty": 3,
          "kind": "explanation",
          "title": "Bad Outputs Have Fingerprints"
        }
      },
      "source": "## MANDATORY | difficulty 3 | Bad Outputs Have Fingerprints\n\nDebugging NTTs is easier when you stop staring at the final vector as one blob.\nEach common mistake leaves a characteristic fingerprint:\n\n- wrong sign flips specific wrapped slots\n- wrong order makes a correct value set appear shuffled\n- missing `n^-1` keeps the shape but scales everything wrong\n- wrong zeta corrupts local pair structure early\n"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "pedagogy": {
          "role": "mandatory",
          "difficulty": 3,
          "kind": "demo",
          "title": "See Four Failure Modes Side By Side"
        }
      },
      "outputs": [],
      "source": "# MANDATORY | difficulty 3 | See Four Failure Modes Side By Side\n\nfrom IPython.display import display\n\nfrom ntt_learning.toy_ntt import (\n    fast_intt_psi_gs_trace,\n    fast_ntt_psi_ct_trace,\n    forward_ntt_psi,\n    negacyclic_reduce,\n    schoolbook_convolution,\n)\nfrom ntt_learning.visuals import plot_vector_comparison\n\nsignal = [1, 2, 3, 4]\nforward_trace = fast_ntt_psi_ct_trace(signal, 7681, 1925)\ninverse_trace = fast_intt_psi_gs_trace(forward_trace.raw_output, 7681, 1925)\n\nraw = schoolbook_convolution([1, 2, 3, 4], [5, 6, 7, 8])\nwrong_sign = [raw[0] + raw[4], raw[1] + raw[5], raw[2] + raw[6], raw[3]]\nwrong_order = list(forward_trace.raw_output)\nwrong_scale = list(inverse_trace.raw_output)\nwrong_root = forward_ntt_psi(signal, 7681, 3383)\n\nprint(\"wrong sign fold:\", wrong_sign)\nprint(\"correct sign fold:\", negacyclic_reduce(raw, n=4))\nprint(\"wrong BO-vs-NO comparison:\", wrong_order)\nprint(\"correct NO output:\", forward_trace.normal_order_output)\nprint(\"missing final scaling:\", wrong_scale)\nprint(\"wrong root in direct transform:\", wrong_root)\ndisplay(\n    plot_vector_comparison(\n        wrong_sign,\n        negacyclic_reduce(raw, n=4),\n        left_label=\"wrong_sign\",\n        right_label=\"correct_sign\",\n        title=\"Wrong sign vs correct negacyclic fold\",\n    )\n)\ndisplay(\n    plot_vector_comparison(\n        wrong_order,\n        forward_trace.normal_order_output,\n        left_label=\"wrong_order\",\n        right_label=\"correct_order\",\n        title=\"Wrong BO/NO comparison\",\n    )\n)\ndisplay(\n    plot_vector_comparison(\n        wrong_scale,\n        inverse_trace.scaled_output,\n        left_label=\"missing_scale\",\n        right_label=\"correct_scale\",\n        title=\"Missing scale vs corrected inverse\",\n    )\n)\n"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "pedagogy": {
          "role": "mandatory",
          "difficulty": 3,
          "kind": "demo",
          "title": "Interactive Failure Picker"
        }
      },
      "outputs": [],
      "source": "# MANDATORY | difficulty 3 | Interactive Failure Picker\n\nimport ipywidgets as widgets\nfrom IPython.display import display\n\nfrom ntt_learning.toy_ntt import fast_intt_psi_gs_trace, fast_ntt_psi_ct_trace, forward_ntt_psi\nfrom ntt_learning.visuals import plot_vector_comparison\n\nforward_trace = fast_ntt_psi_ct_trace([1, 2, 3, 4], 7681, 1925)\ninverse_trace = fast_intt_psi_gs_trace(forward_trace.raw_output, 7681, 1925)\n\nfailures = {\n    \"wrong_order\": list(forward_trace.raw_output),\n    \"correct_order\": list(forward_trace.normal_order_output),\n    \"missing_scale\": list(inverse_trace.raw_output),\n    \"scaled\": list(inverse_trace.scaled_output),\n    \"wrong_root\": forward_ntt_psi([1, 2, 3, 4], 7681, 3383),\n}\nreferences = {\n    \"wrong_order\": list(forward_trace.normal_order_output),\n    \"correct_order\": list(forward_trace.normal_order_output),\n    \"missing_scale\": list(inverse_trace.scaled_output),\n    \"scaled\": list(inverse_trace.scaled_output),\n    \"wrong_root\": list(forward_ntt_psi([1, 2, 3, 4], 7681, 1925)),\n}\n\ndef preview(mode=\"wrong_order\"):\n    print(mode, \"->\", failures[mode])\n    display(\n        plot_vector_comparison(\n            failures[mode],\n            references[mode],\n            left_label=mode,\n            right_label=\"reference\",\n            title=f\"{mode} compared with the correct reference\",\n        )\n    )\n\ndisplay(widgets.interact(preview, mode=sorted(failures)))\n"
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "pedagogy": {
          "role": "mandatory",
          "difficulty": 2,
          "kind": "quiz",
          "title": "Retrieval Check"
        }
      },
      "source": "## MANDATORY | difficulty 2 | Retrieval Check\n\n1. Which mistake keeps the general shape of the inverse output but leaves every entry too large by a shared factor?\n2. Which mistake often disappears once you apply the correct BO -> NO reorder?\n3. Which mistake shows up earliest in local pair traces rather than only at the very end?\n"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "pedagogy": {
          "role": "facultative",
          "difficulty": 4,
          "kind": "exploration",
          "title": "Optional: Trace Rows For Debugging"
        }
      },
      "outputs": [],
      "source": "# FACULTATIVE | difficulty 4 | Optional: Trace Rows For Debugging\n\nfrom ntt_learning.toy_ntt import fast_ntt_psi_ct_trace, stage_rows\n\ntrace = fast_ntt_psi_ct_trace([1, 2, 3, 4], 7681, 1925)\nfor stage in trace.stages:\n    print(\"stage\", stage.stage_index)\n    for row in stage_rows(stage):\n        print(row)\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: Debugging NTT Failures",
      "contract_version": "0.2",
      "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",
        "notebooks/foundations/02_negative_wrapped_ntt/lecture.ipynb",
        "notebooks/foundations/02_negative_wrapped_ntt/lab.ipynb",
        "notebooks/foundations/02_negative_wrapped_ntt/problems.ipynb",
        "notebooks/foundations/02_negative_wrapped_ntt/studio.ipynb",
        "notebooks/butterfly_mechanics/03_fast_forward_ct/lecture.ipynb",
        "notebooks/butterfly_mechanics/03_fast_forward_ct/lab.ipynb",
        "notebooks/butterfly_mechanics/03_fast_forward_ct/problems.ipynb",
        "notebooks/butterfly_mechanics/03_fast_forward_ct/studio.ipynb",
        "notebooks/butterfly_mechanics/04_fast_inverse_gs/lecture.ipynb",
        "notebooks/butterfly_mechanics/04_fast_inverse_gs/lab.ipynb",
        "notebooks/butterfly_mechanics/04_fast_inverse_gs/problems.ipynb",
        "notebooks/butterfly_mechanics/04_fast_inverse_gs/studio.ipynb",
        "notebooks/kyber_mapping/05_kyber_ntt_and_base_multiplication/lecture.ipynb",
        "notebooks/kyber_mapping/05_kyber_ntt_and_base_multiplication/lab.ipynb",
        "notebooks/kyber_mapping/05_kyber_ntt_and_base_multiplication/problems.ipynb",
        "notebooks/kyber_mapping/05_kyber_ntt_and_base_multiplication/studio.ipynb",
        "notebooks/professional/06_debugging_ntt_failures/lecture.ipynb",
        "notebooks/professional/06_debugging_ntt_failures/lab.ipynb",
        "notebooks/professional/06_debugging_ntt_failures/problems.ipynb",
        "notebooks/professional/06_debugging_ntt_failures/studio.ipynb",
        "notebooks/COURSE_COMPLETE.ipynb"
      ]
    }
  },
  "nbformat": 4,
  "nbformat_minor": 5
}