grover-explorer-engine

A framework-independent TypeScript engine for simulating Grover search.

It powers Grover Explorer's classical comparison, exact state-vector simulation, analytical large-problem model, Oracle and Diffusion transitions, measurement, history, and query accounting.

Install

npm install grover-explorer-engine

Run one Grover iteration

import {
  createProblemInstance,
  createQuantumState,
  groverStep,
  measure
} from "grover-explorer-engine";

const { instance, target } = createProblemInstance(16, 6, "example-1");
let state = createQuantumState(instance);

const stepped = groverStep(state, instance);
if (!stepped.ok) throw new Error(stepped.error.message);
state = stepped.state;

console.log(state.iteration);       // 1
console.log(state.oracleQueries);   // 1

const measured = measure(state, instance, Math.random());
if (!measured.ok) throw new Error(measured.error.message);

console.log(measured.state.measuredIndex, target);

The measurement sample is supplied explicitly. The engine does not import its own random source, which makes simulations deterministic when you provide a fixed sample.

Apply Oracle and Diffusion separately

import {
  applyDiffusion,
  applyOracle,
  createProblemInstance,
  createQuantumState
} from "grover-explorer-engine";

const { instance } = createProblemInstance(8, 3, "step-by-step");
const initial = createQuantumState(instance);

if (initial.mode !== "exact") throw new Error("Expected exact mode");

const marked = applyOracle(initial, instance);
if (!marked.ok) throw new Error(marked.error.message);

const amplified = applyDiffusion(marked.state, instance);
if (!amplified.ok) throw new Error(amplified.error.message);

console.log(amplified.state.iteration); // 1

Exact and analytical modes

• N <= 256: full complex state-vector simulation.
• N > 256: constant-size analytical model using sin²((2k+1)θ).

Use distributionView(state, instance) to obtain a rendering-safe probability view for either mode.

Transition results

State-changing functions return a discriminated result:

const result = groverStep(state, instance);

if (result.ok) {
  state = result.state;
} else {
  console.error(result.error.tag, result.error.message);
}

Invalid transitions return the unchanged canonical state alongside a typed audit error.

Public API

The package exposes:

• problem and state creation;
• exact Oracle and Diffusion operations;
• complete Grover steps;
• measurement and step-back transitions;
• classical sequential-search state and transitions;
• exact and analytical probability views;
• optimal-iteration and Grover-angle helpers;
• validation results and TypeScript state types.

Scope and limitations

This is an educational simulation engine, not a quantum-hardware interface. Exact simulation is intentionally limited to N = 256; larger problems use the documented analytical model.

License

Licensed under the MIT License.

Free to use, modify, and distribute, including commercially. Attribution is required by the licence terms.