Quantum Factor Lab

Quantum Factor Lab is a single-page interactive lesson that demonstrates how Shor’s algorithm can factor 15 using base 2.

The project is a polished conceptual MVP focused on helping learners understand the flow of Shor’s algorithm through guided steps and an interactive Three.js visualization. It is not a real quantum hardware simulation.

Implemented

• React + TypeScript + Vite
• Interactive Three.js visualization
• Five guided learning phases:
  1. Select target N = 15
  2. Choose base a = 2
  3. Find modular period r = 4
  4. Visualize QFT probability peaks
  5. Recover factors: 15 = 3 × 5
• Responsive desktop and mobile layout
• Keyboard navigation and semantic controls
• Reduced-motion support
• Tested modular arithmetic and factor extraction

Setup

Requirements

• Node.js 22 or newer
• npm

Install and run

npm install
npm run dev

Vite will print the local development URL in the terminal.

Validate

npm test
npm run build

The production bundle is written to dist/.

How Shor’s algorithm works here

The lesson uses the standard small example N = 15.

1. Choose a base

Choose a = 2. Because gcd(2, 15) = 1, the base is suitable for period finding.

2. Find the modular period

Calculate powers of 2 modulo 15:

x	2ˣ mod 15
0	1
1	2
2	4
3	8
4	1

The output returns to 1 after four steps, so the period is r = 4.

In Shor’s algorithm, quantum superposition and the quantum Fourier transform are used to reveal this periodic structure efficiently. The current visualization teaches that concept; it does not execute a quantum circuit.

3. Recover the factors

Because r is even, calculate:

gcd(2^(r/2) - 1, 15) = gcd(3, 15) = 3
gcd(2^(r/2) + 1, 15) = gcd(5, 15) = 5

Therefore:

15 = 3 × 5

Project structure

src/
├── App.tsx             Guided lesson interface and phase content
├── QuantumScene.tsx    Three.js scene and phase visualizations
├── shor.ts             Modular orbit, gcd, and factor extraction
├── shor.test.ts        Factor-15 regression test
├── styles.css          Responsive visual system and accessibility states
└── main.tsx            React entry point

Current status

• Tests: 1/1 passing
• Production build: successful
• Current production JavaScript bundle: approximately 732 KB before gzip

Remaining work

• Add a custom-number simulator
• Add examples such as 21 and 35
• Build full Quantum Basics and Research sections
• Add real circuit or Qiskit integration
• Add project screenshots
• Optionally split the Three.js code to reduce the initial bundle size