qube-core (v0.2.0)

Powerful JavaScript quantum simulator core with advanced algorithms and high-performance math utilities for AI optimization and secure backend services.

🚀 Version 0.2.0: The Big Update

This release marks a significant expansion of qube-core from a basic simulator to a full-featured quantum computing toolkit. The focus is on optimization, scheduling, and quantum-inspired machine learning.

| Feature Area | Key Improvement | Stability Impact | | :--- | :--- | :--- | | Optimization (VQE/QAOA) | FIXED CRITICAL BUG: Simulator.measureExpectation() now correctly returns a real number (the expected energy value $\langle H \rangle$), making it compatible with all standard optimizers. | High | | Grover Optimizer | buildGroverCircuit now accepts a custom fitness function for general search problems and complex scheduling constraints. | New Feature | | Code Structure | Complete modularization of source files into src/algorithms, src/optimization, src/ai, and src/security. | High | | QFT/IQFT | Added robust input validation to qftMatrix and inverseQftMatrix to prevent runtime errors. | High | | Hashing | quantumHash logic was generalized to guarantee a fixed 64-character hash output for all valid qubit counts. | Medium |

✨ Core Features

• Core Engine: Pure-JS state-vector simulator (no native dependencies).
• High-Performance Math: Dedicated Math module with matrix operations (dot, transpose, conjugateTranspose) for robust linear algebra.
• Advanced Gates: Includes rotation gates (RY, RZ) for variational algorithms, and the multi-qubit Toffoli gate.
• AI & Optimization:
  • Variational Algorithms: Calculates Expectation Values ($\langle H \rangle$) crucial for VQE/QAOA cost functions.
  • QAOA Builder: Functions to construct Cost Layers and Mixer Layers for solving optimization problems (e.g., Max-Cut).
  • Q-KMeans: Includes the qKMeansCompute function for quantum-inspired distance calculation in clustering tasks.
• Backend Scheduling & Security:
  • Grover Optimizer: Updated buildGroverCircuit to accept a custom fitness function for general search and scheduling.
  • Quantum-Inspired Hashing: New, highly collision-resistant quantumHash function for secure backend operations.
• Algorithms: QFT and Inverse QFT matrix builders.

Note: This is a simulator. Real quantum speedups require hardware and problem-specific constraints.

Quickstart

1. Installation

Assuming you are in the project root with the package files:

# install dependencies (if any) and link the package
npm install 
# To run the example:
npm run example
# To run the basic test:
npm run test
# To run the full test suite (including new features):
npm run full-test

2. Usage Example: Grover Optimizer (Custom Fitness Function)

This example demonstrates using the updated Grover circuit to find the state that satisfies a scheduling constraint (e.g., finding all states where Qubit 0 is $|1\rangle$ AND Qubit 2 is $|0\rangle$).

import { buildGroverCircuit, Simulator, basis } from 'qube-core';

// 3 qubits = 8 possible states (0 to 7)
const nQubits = 3;

// Define the fitness/scheduling constraint: 
// We want to mark all states 'i' where:
// 1. The LSB (qubit 0) is ON (|1>).
// 2. The MSB (qubit 2) is OFF (|0>).
// The target marked states (intersection) are index 1 (|001>) and index 3 (|011>).
const constraintFunction = (stateIndex) => {
    // Check if Qubit 0 (LSB) is 1
    const q0_is_1 = (stateIndex & 1) === 1;
    // Check if Qubit 2 (MSB) is 0
    const q2_is_0 = ((stateIndex >> 2) & 1) === 0;

    return q0_is_1 && q2_is_0; 
};

// Build the Grover circuit using the custom function
const circ = buildGroverCircuit(nQubits, constraintFunction);
const sim = new Simulator(nQubits);

// Load the initial state |000>
sim.loadState(basis(1 << nQubits, 0)); 

// Run the circuit
sim.runCircuit(circ);

// Sample the result 1024 times
const results = sim.sample(1024);

console.log('Grover Optimizer Sample Histogram (Index: Counts):');
console.log(Object.fromEntries([...results.entries()].map(([k,v]) => [k, v])));
// Expected high counts for index 1 (|001>) and 3 (|011|).

📦 Package Structure (v0.2.0)

The package structure was significantly reorganized for this update:

├── README.md
├── examples
│   └── grover-example.js
├── index.js              <-- Main Entry Point
├── package.json
├── src
│   ├── ai
│   │   └── qkmeans.js    <-- Quantum Machine Learning
│   ├── algorithms
│   │   ├── grover.js     <-- Search & Optimization
│   │   └── qft.js        <-- Fourier Transform
│   ├── circuit.js        <-- Circuit Builder
│   ├── complex.js        <-- Complex Number Library
│   ├── gates.js          <-- Gate Definitions (H, X, RZ, Toffoli, etc.)
│   ├── math
│   │   └── matrix.js     <-- Vector/Matrix Utilities
│   ├── optimization
│   │   └── qaoa.js       <-- Variational Algorithm Tools
│   ├── security
│   │   └── hash.js       <-- Quantum Hash Implementation
│   └── simulator.js      <-- State-Vector Simulator (Critical Fix applied here)
└── test
    ├── basic.test.js
    └── full.test.js      <-- Tests all v0.2.0 features

📜 License

qube-core is released under the MIT License.