qft-wasm 1.0.0

package/README.md

@@ -0,0 +1,299 @@
+# qft-wasm - Quantum File Type WebAssembly SDK
+
+Production-grade WebAssembly bindings for the Quantum File Type (.qft) format.
+
+## Installation
+
+### npm
+
+```bash
+npm install qft-wasm
+```
+
+### From Source
+
+```bash
+# Requires wasm-pack
+cargo install wasm-pack
+cd crates/qft-wasm
+wasm-pack build --target web --release
+```
+
+## Quick Start
+
+### Browser (ES Modules)
+
+```javascript
+import init, { QftFile, createBellState, version } from 'qft-wasm';
+
+async function main() {
+  await init();
+  
+  console.log(`QFT WASM v${version()}`);
+  
+  // Create a 4-qubit state
+  const file = new QftFile(4);
+  console.log(`Qubits: ${file.numQubits}`);
+  console.log(`Dimension: ${file.dimension}`);
+  
+  // Set Bell-like state |0000⟩ + |1111⟩
+  const real = new Float64Array(16);
+  const imag = new Float64Array(16);
+  real[0] = 1 / Math.sqrt(2);
+  real[15] = 1 / Math.sqrt(2);
+  file.setAmplitudes(real, imag);
+  
+  // Serialize to bytes
+  const bytes = file.toBytes();
+  console.log(`Serialized: ${bytes.length} bytes`);
+  
+  // Download as file
+  downloadQft(bytes, 'state.qft');
+}
+
+function downloadQft(bytes, filename) {
+  const blob = new Blob([bytes], { type: 'application/octet-stream' });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+
+main();
+```
+
+### Node.js
+
+```javascript
+const { QftFile, version } = require('qft-wasm');
+
+// Create state
+const file = new QftFile(4);
+console.log(`Version: ${version()}`);
+
+// Export to JSON
+const json = file.toJson();
+console.log(json);
+
+// Save to file
+const fs = require('fs');
+fs.writeFileSync('state.qft', Buffer.from(file.toBytes()));
+```
+
+### TypeScript
+
+```typescript
+import init, { QftFile, Encoding, StreamingConverter } from 'qft-wasm';
+
+async function processLargeFile(file: File): Promise<void> {
+  await init();
+  
+  const converter = new StreamingConverter(
+    file.size,
+    1024 * 1024,  // 1MB chunks
+    Encoding.Amplitude
+  );
+  
+  const reader = file.stream().getReader();
+  
+  while (!converter.isComplete) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    
+    const chunk = new Uint8Array(value);
+    const state = converter.processChunk(chunk);
+    console.log(`Progress: ${(converter.progress * 100).toFixed(1)}%`);
+    
+    // Process state...
+  }
+}
+```
+
+## API Reference
+
+### QftFile Class
+
+```typescript
+class QftFile {
+  constructor(numQubits: number);
+  
+  // Properties
+  readonly numQubits: number;
+  readonly dimension: number;
+  bondDimension: number;
+  golayEnabled: boolean;
+  
+  // Amplitude access
+  getAmplitudesReal(): Float64Array;
+  getAmplitudesImag(): Float64Array;
+  setAmplitudes(real: Float64Array, imag: Float64Array): void;
+  getAmplitude(index: number): { real: number; imag: number };
+  setAmplitude(index: number, real: number, imag: number): void;
+  
+  // Validation
+  isNormalized(tolerance?: number): boolean;
+  normalize(): void;
+  normSquared(): number;
+  fidelity(other: QftFile): number;
+  
+  // Metadata
+  setMetadata(key: string, value: string): void;
+  getMetadata(key: string): string | undefined;
+  getMetadataObject(): Record<string, string>;
+  
+  // Serialization
+  toBytes(): Uint8Array;
+  static fromBytes(data: Uint8Array): QftFile;
+  toJson(): string;
+  static fromJson(json: string): QftFile;
+}
+```
+
+### StreamingConverter Class
+
+```typescript
+class StreamingConverter {
+  constructor(
+    totalSize: number,
+    chunkSize?: number,
+    encoding?: Encoding
+  );
+  
+  processChunk(data: Uint8Array): QftFile;
+  
+  readonly progress: number;
+  readonly isComplete: boolean;
+  readonly chunkSize: number;
+}
+```
+
+### Encoding Enum
+
+```typescript
+enum Encoding {
+  Amplitude = 0,
+  BasisState = 1,
+  Qram = 2,
+  Angle = 3,
+  Block = 4,
+}
+```
+
+### Utility Functions
+
+```typescript
+function version(): string;
+function verify(data: Uint8Array): boolean;
+function fidelityFromBytes(data1: Uint8Array, data2: Uint8Array): number;
+function createBellState(): QftFile;
+function createGhzState(numQubits: number): QftFile;
+function createUniformState(numQubits: number): QftFile;
+```
+
+## Examples
+
+### Create Bell State
+
+```javascript
+import { createBellState } from 'qft-wasm';
+
+const bell = createBellState();
+console.log(bell.getAmplitudesReal());
+// Float64Array [0.707..., 0, 0, 0.707...]
+```
+
+### Calculate Fidelity
+
+```javascript
+import { QftFile } from 'qft-wasm';
+
+const state1 = new QftFile(2);
+const state2 = new QftFile(2);
+
+// Both initialized to |00⟩
+const fidelity = state1.fidelity(state2);
+console.log(`Fidelity: ${fidelity}`);  // 1.0
+```
+
+### File Upload Handler
+
+```javascript
+async function handleFileUpload(event) {
+  const file = event.target.files[0];
+  const buffer = await file.arrayBuffer();
+  const bytes = new Uint8Array(buffer);
+  
+  try {
+    const qft = QftFile.fromBytes(bytes);
+    console.log(`Loaded ${qft.numQubits}-qubit state`);
+    console.log(`Normalized: ${qft.isNormalized()}`);
+  } catch (e) {
+    console.error('Invalid QFT file:', e.message);
+  }
+}
+```
+
+### React Component
+
+```tsx
+import React, { useState, useEffect } from 'react';
+import init, { QftFile, createBellState } from 'qft-wasm';
+
+export function QuantumStateViewer() {
+  const [state, setState] = useState<QftFile | null>(null);
+  const [ready, setReady] = useState(false);
+  
+  useEffect(() => {
+    init().then(() => setReady(true));
+  }, []);
+  
+  const createBell = () => {
+    const bell = createBellState();
+    setState(bell);
+  };
+  
+  if (!ready) return <div>Loading WASM...</div>;
+  
+  return (
+    <div>
+      <button onClick={createBell}>Create Bell State</button>
+      {state && (
+        <div>
+          <p>Qubits: {state.numQubits}</p>
+          <p>Dimension: {state.dimension}</p>
+          <p>Normalized: {state.isNormalized() ? 'Yes' : 'No'}</p>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+## Bundle Size
+
+| Build | Size (gzip) |
+|-------|-------------|
+| Web | ~45 KB |
+| Node.js | ~50 KB |
+
+## Browser Support
+
+- Chrome 89+
+- Firefox 89+
+- Safari 15+
+- Edge 89+
+
+## Performance
+
+| Operation | 10 qubits | 20 qubits |
+|-----------|-----------|-----------|
+| Create | 0.1 ms | 2 ms |
+| Serialize | 0.2 ms | 20 ms |
+| Deserialize | 0.1 ms | 15 ms |
+| Fidelity | 0.1 ms | 10 ms |
+
+## License
+
+MIT OR Apache-2.0

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "qft-wasm",
+  "type": "module",
+  "collaborators": [
+    "MACROHARD Quantum OS Team"
+  ],
+  "description": "Production-grade WebAssembly bindings for Quantum File Type (.qft) format",
+  "version": "1.0.0",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/WeaveITMeta/Quantum-Operating-System"
+  },
+  "files": [
+    "qft_wasm_bg.wasm",
+    "qft_wasm.js",
+    "qft_wasm.d.ts"
+  ],
+  "main": "qft_wasm.js",
+  "types": "qft_wasm.d.ts",
+  "sideEffects": [
+    "./snippets/*"
+  ],
+  "keywords": [
+    "quantum",
+    "wasm",
+    "webassembly",
+    "qft",
+    "mps"
+  ]
+}

package/qft_wasm.d.ts

@@ -0,0 +1,288 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Encoding strategies for file conversion.
+ */
+export enum Encoding {
+    Amplitude = 0,
+    BasisState = 1,
+    Qram = 2,
+    Angle = 3,
+    Block = 4,
+}
+
+/**
+ * A Quantum File Type (.qft) file handle for JavaScript/TypeScript.
+ *
+ * @example
+ * ```javascript
+ * import { QftFile } from 'qft-wasm';
+ *
+ * // Create a 4-qubit state
+ * const file = new QftFile(4);
+ * console.log(file.numQubits);  // 4
+ * console.log(file.dimension);  // 16
+ *
+ * // Set Bell-like state
+ * const real = new Float64Array(16);
+ * const imag = new Float64Array(16);
+ * real[0] = 1 / Math.sqrt(2);
+ * real[15] = 1 / Math.sqrt(2);
+ * file.setAmplitudes(real, imag);
+ *
+ * // Save to bytes
+ * const bytes = file.toBytes();
+ * ```
+ */
+export class QftFile {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Calculate fidelity with another state: |⟨self|other⟩|².
+     *
+     * @param other - Another QftFile
+     * @returns Fidelity between 0 and 1
+     */
+    fidelity(other: QftFile): number;
+    /**
+     * Create from Uint8Array.
+     */
+    static fromBytes(data: Uint8Array): QftFile;
+    /**
+     * Create from JSON string.
+     */
+    static fromJson(json: string): QftFile;
+    /**
+     * Get a single amplitude by basis state index.
+     *
+     * @param index - Basis state index (0 to 2^n - 1)
+     * @returns Object with real and imag properties
+     */
+    getAmplitude(index: number): any;
+    /**
+     * Get the imaginary parts of amplitudes as Float64Array.
+     */
+    getAmplitudesImag(): Float64Array;
+    /**
+     * Get the real parts of amplitudes as Float64Array.
+     */
+    getAmplitudesReal(): Float64Array;
+    /**
+     * Get metadata value by key.
+     */
+    getMetadata(key: string): string | undefined;
+    /**
+     * Get all metadata as a JavaScript object.
+     */
+    getMetadataObject(): any;
+    /**
+     * Check if the state is normalized.
+     *
+     * @param tolerance - Tolerance for check (default: 1e-10)
+     * @returns true if normalized within tolerance
+     */
+    isNormalized(tolerance?: number | null): boolean;
+    /**
+     * Create a new QFT file with the specified number of qubits.
+     *
+     * @param numQubits - Number of qubits (1-30)
+     * @returns A new QftFile initialized to |0...0⟩
+     * @throws Error if numQubits is not in range 1-30
+     */
+    constructor(num_qubits: number);
+    /**
+     * Calculate the norm squared.
+     */
+    normSquared(): number;
+    /**
+     * Normalize the state vector in place.
+     */
+    normalize(): void;
+    /**
+     * Set a single amplitude by basis state index.
+     *
+     * @param index - Basis state index (0 to 2^n - 1)
+     * @param real - Real part of amplitude
+     * @param imag - Imaginary part of amplitude
+     */
+    setAmplitude(index: number, real: number, imag: number): void;
+    /**
+     * Set amplitudes from Float64Arrays.
+     *
+     * @param real - Real parts of amplitudes
+     * @param imag - Imaginary parts of amplitudes
+     */
+    setAmplitudes(real: Float64Array, imag: Float64Array): void;
+    /**
+     * Set metadata key-value pair.
+     */
+    setMetadata(key: string, value: string): void;
+    /**
+     * Serialize to Uint8Array.
+     */
+    toBytes(): Uint8Array;
+    /**
+     * Export to JSON string.
+     */
+    toJson(): string;
+    /**
+     * Bond dimension for MPS compression.
+     */
+    bondDimension: number;
+    /**
+     * Dimension of the state vector (2^numQubits).
+     */
+    readonly dimension: number;
+    /**
+     * Whether Golay error correction is enabled.
+     */
+    golayEnabled: boolean;
+    /**
+     * Number of qubits in the quantum state.
+     */
+    readonly numQubits: number;
+}
+
+/**
+ * Streaming converter for large files.
+ */
+export class StreamingConverter {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Create a new streaming converter.
+     *
+     * @param totalSize - Total size of input data in bytes
+     * @param chunkSize - Size of each chunk (default: 1MB)
+     * @param encoding - Encoding strategy (default: Amplitude)
+     */
+    constructor(total_size: number, chunk_size?: number | null, encoding?: Encoding | null);
+    /**
+     * Process a chunk of data.
+     *
+     * @param data - Uint8Array chunk
+     * @returns QftFile for this chunk
+     */
+    processChunk(data: Uint8Array): QftFile;
+    /**
+     * Get recommended chunk size.
+     */
+    readonly chunkSize: number;
+    /**
+     * Check if conversion is complete.
+     */
+    readonly isComplete: boolean;
+    /**
+     * Get conversion progress (0.0 to 1.0).
+     */
+    readonly progress: number;
+}
+
+/**
+ * Create a Bell state for testing.
+ */
+export function createBellState(): QftFile;
+
+/**
+ * Create a GHZ state for testing.
+ */
+export function createGhzState(num_qubits: number): QftFile;
+
+/**
+ * Create a uniform superposition state.
+ */
+export function createUniformState(num_qubits: number): QftFile;
+
+/**
+ * Calculate fidelity between two states from bytes.
+ */
+export function fidelityFromBytes(data1: Uint8Array, data2: Uint8Array): number;
+
+/**
+ * Initialize the WASM module with better error messages
+ */
+export function init(): void;
+
+/**
+ * Verify a QFT file's integrity from bytes.
+ */
+export function verify(data: Uint8Array): boolean;
+
+/**
+ * Get library version.
+ */
+export function version(): string;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_qftfile_free: (a: number, b: number) => void;
+    readonly __wbg_streamingconverter_free: (a: number, b: number) => void;
+    readonly createBellState: () => [number, number, number];
+    readonly createGhzState: (a: number) => [number, number, number];
+    readonly createUniformState: (a: number) => [number, number, number];
+    readonly fidelityFromBytes: (a: any, b: any) => [number, number, number];
+    readonly qftfile_bondDimension: (a: number) => number;
+    readonly qftfile_dimension: (a: number) => number;
+    readonly qftfile_fidelity: (a: number, b: number) => [number, number, number];
+    readonly qftfile_fromBytes: (a: any) => [number, number, number];
+    readonly qftfile_fromJson: (a: number, b: number) => [number, number, number];
+    readonly qftfile_getAmplitude: (a: number, b: number) => [number, number, number];
+    readonly qftfile_getAmplitudesImag: (a: number) => any;
+    readonly qftfile_getAmplitudesReal: (a: number) => any;
+    readonly qftfile_getMetadata: (a: number, b: number, c: number) => [number, number];
+    readonly qftfile_getMetadataObject: (a: number) => [number, number, number];
+    readonly qftfile_golayEnabled: (a: number) => number;
+    readonly qftfile_isNormalized: (a: number, b: number, c: number) => number;
+    readonly qftfile_new: (a: number) => [number, number, number];
+    readonly qftfile_normSquared: (a: number) => number;
+    readonly qftfile_normalize: (a: number) => [number, number];
+    readonly qftfile_numQubits: (a: number) => number;
+    readonly qftfile_setAmplitude: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly qftfile_setAmplitudes: (a: number, b: any, c: any) => [number, number];
+    readonly qftfile_setMetadata: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly qftfile_set_bondDimension: (a: number, b: number) => [number, number];
+    readonly qftfile_set_golayEnabled: (a: number, b: number) => void;
+    readonly qftfile_toBytes: (a: number) => any;
+    readonly qftfile_toJson: (a: number) => [number, number, number, number];
+    readonly streamingconverter_chunkSize: (a: number) => number;
+    readonly streamingconverter_isComplete: (a: number) => number;
+    readonly streamingconverter_new: (a: number, b: number, c: number) => number;
+    readonly streamingconverter_processChunk: (a: number, b: any) => [number, number, number];
+    readonly streamingconverter_progress: (a: number) => number;
+    readonly verify: (a: any) => number;
+    readonly version: () => [number, number];
+    readonly init: () => void;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_exn_store: (a: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;