@danielsimonjr/mathts-matrix 0.7.0 → 0.7.2

package/dist/backends/Backend.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Matrix Backend Interface
+ *
+ * Defines the contract for matrix operation backends.
+ * Implementations include JSBackend (pure TypeScript),
+ * WASMBackend (AssemblyScript), and GPUBackend (WebGPU).
+ *
+ * @packageDocumentation
+ */
+import { DenseMatrix } from '../types/DenseMatrix.js';
+/**
+ * Backend type identifier
+ */
+export type BackendType = 'js' | 'wasm' | 'gpu' | 'parallel';
+/**
+ * Backend selection hints
+ */
+export interface BackendHints {
+    /** Minimum size to use WASM backend */
+    wasmThreshold?: number;
+    /** Minimum size to use GPU backend */
+    gpuThreshold?: number;
+    /** Force a specific backend */
+    preferredBackend?: BackendType;
+}
+/**
+ * Default backend hints
+ */
+export declare const DEFAULT_BACKEND_HINTS: Required<BackendHints>;
+/**
+ * Abstract backend interface for matrix operations
+ *
+ * Each backend implements the same operations but may use different
+ * underlying implementations (pure JS, WASM SIMD, WebGPU compute shaders).
+ */
+export interface MatrixBackend {
+    /**
+     * Backend identifier
+     */
+    readonly type: BackendType;
+    /**
+     * Whether the backend is available in the current environment
+     */
+    isAvailable(): boolean;
+    /**
+     * Initialize the backend (may be async for WASM/GPU)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Matrix addition: C = A + B
+     */
+    add(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    /**
+     * Matrix subtraction: C = A - B
+     */
+    subtract(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    /**
+     * Element-wise multiplication: C = A .* B
+     */
+    multiplyElementwise(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    /**
+     * Element-wise division: C = A ./ B
+     */
+    divideElementwise(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    /**
+     * Scalar multiplication: C = A * s
+     */
+    scale(a: DenseMatrix, scalar: number): DenseMatrix;
+    /**
+     * Element-wise absolute value
+     */
+    abs(a: DenseMatrix): DenseMatrix;
+    /**
+     * Element-wise negation
+     */
+    negate(a: DenseMatrix): DenseMatrix;
+    /**
+     * Matrix multiplication: C = A * B
+     */
+    multiply(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    /**
+     * Matrix transpose
+     */
+    transpose(a: DenseMatrix): DenseMatrix;
+    /**
+     * Sum of all elements (may be async for parallel backends)
+     */
+    sum(a: DenseMatrix): number | Promise<number>;
+    /**
+     * Sum along an axis (0 = columns, 1 = rows)
+     */
+    sumAxis(a: DenseMatrix, axis: 0 | 1): DenseMatrix;
+    /**
+     * Frobenius norm
+     */
+    norm(a: DenseMatrix): number;
+    /**
+     * Dot product of two vectors (may be async for parallel backends)
+     */
+    dot(a: DenseMatrix, b: DenseMatrix): number | Promise<number>;
+}
+/**
+ * Registry of available backends
+ */
+export declare class BackendRegistry {
+    private backends;
+    private initialized;
+    private hints;
+    /**
+     * Register a backend
+     */
+    register(backend: MatrixBackend): void;
+    /**
+     * Get a backend by type
+     */
+    get(type: BackendType): MatrixBackend | undefined;
+    /**
+     * Check if a backend is registered and available
+     */
+    has(type: BackendType): boolean;
+    /**
+     * Initialize a backend
+     */
+    initialize(type: BackendType): Promise<void>;
+    /**
+     * Get all available backends
+     */
+    available(): BackendType[];
+    /**
+     * Update selection hints
+     */
+    setHints(hints: BackendHints): void;
+    /**
+     * Get current hints
+     */
+    getHints(): Required<BackendHints>;
+    /**
+     * Select the best backend for a given operation size
+     */
+    selectBackend(elementCount: number): MatrixBackend;
+}
+/**
+ * Global backend registry
+ */
+export declare const backendRegistry: BackendRegistry;
+//# sourceMappingURL=Backend.d.ts.map

package/dist/backends/Backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Backend.d.ts","sourceRoot":"","sources":["../../src/backends/Backend.ts"],"names":[],"mappings":"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"}

package/dist/backends/BackendManager.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Backend Manager
+ *
+ * Centralized management for matrix operation backends with automatic
+ * selection based on matrix size, operation type, and availability.
+ * Includes adaptive threshold tuning based on runtime profiling.
+ *
+ * @packageDocumentation
+ */
+import { DenseMatrix } from '../types/DenseMatrix.js';
+import type { MatrixBackend, BackendType, BackendHints } from './Backend.js';
+import { type OperationType } from '../config.js';
+import './register-backends.js';
+export type { OperationType };
+/**
+ * Extended backend hints with operation-specific thresholds
+ */
+export interface ExtendedBackendHints extends BackendHints {
+    /** Specific thresholds by operation type */
+    operationThresholds?: Partial<Record<OperationType, {
+        wasm?: number;
+        gpu?: number;
+    }>>;
+    /** Enable automatic SIMD detection for WASM */
+    autoSIMD?: boolean;
+    /** Fallback to JS on backend failure */
+    fallbackOnError?: boolean;
+}
+/**
+ * Default extended hints
+ */
+export declare const DEFAULT_EXTENDED_HINTS: Required<ExtendedBackendHints>;
+/**
+ * Centralized Backend Manager
+ *
+ * Provides a unified interface for executing matrix operations with
+ * automatic backend selection based on matrix size and operation type.
+ * Features adaptive threshold tuning based on runtime profiling.
+ */
+export declare class BackendManager {
+    private hints;
+    private initialized;
+    private initializationPromise;
+    private adaptiveState;
+    private configUnsubscribe;
+    constructor(hints?: ExtendedBackendHints);
+    /**
+     * Sync manager state with global config
+     */
+    private syncWithConfig;
+    /**
+     * Initialize all available backends
+     */
+    initialize(): Promise<void>;
+    private doInitialize;
+    /**
+     * Update backend hints
+     */
+    setHints(hints: ExtendedBackendHints): void;
+    /**
+     * Get current hints
+     */
+    getHints(): Required<ExtendedBackendHints>;
+    /**
+     * Get the best backend for a given operation and matrix size.
+     *
+     * Selection priority:
+     *   1. Preferred backend (if explicitly set)
+     *   2. Elements > gpuThreshold -> GPU (if available)
+     *   3. Elements > wasmThreshold -> AS WASM (if loaded)
+     *   4. JS fallback
+     */
+    selectBackend(elementCount: number, operation?: OperationType): MatrixBackend;
+    /**
+     * Execute an operation with automatic backend selection
+     */
+    private executeWithFallback;
+    /**
+     * Matrix addition with auto backend selection
+     */
+    add(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    /**
+     * Matrix subtraction with auto backend selection
+     */
+    subtract(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    /**
+     * Element-wise multiplication with auto backend selection
+     */
+    multiplyElementwise(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    /**
+     * Element-wise division with auto backend selection
+     */
+    divideElementwise(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    /**
+     * Scalar multiplication with auto backend selection
+     */
+    scale(a: DenseMatrix, scalar: number): DenseMatrix;
+    /**
+     * Element-wise absolute value with auto backend selection
+     */
+    abs(a: DenseMatrix): DenseMatrix;
+    /**
+     * Element-wise negation with auto backend selection
+     */
+    negate(a: DenseMatrix): DenseMatrix;
+    /**
+     * Matrix multiplication with auto backend selection
+     */
+    multiply(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    /**
+     * Matrix transpose with auto backend selection
+     */
+    transpose(a: DenseMatrix): DenseMatrix;
+    /**
+     * Sum of all elements with auto backend selection
+     */
+    sum(a: DenseMatrix): Promise<number>;
+    /**
+     * Sum along axis with auto backend selection
+     */
+    sumAxis(a: DenseMatrix, axis: 0 | 1): DenseMatrix;
+    /**
+     * Frobenius norm with auto backend selection
+     */
+    norm(a: DenseMatrix): number;
+    /**
+     * Dot product with auto backend selection
+     */
+    dot(a: DenseMatrix, b: DenseMatrix): Promise<number>;
+    /**
+     * Get list of available backends
+     */
+    getAvailableBackends(): BackendType[];
+    /**
+     * Check if a specific backend is available
+     */
+    hasBackend(type: BackendType): boolean;
+    /**
+     * Get current active backend for a given operation size
+     */
+    getActiveBackend(elementCount: number, operation?: OperationType): BackendType;
+    /**
+     * Force a specific backend for all operations
+     */
+    forceBackend(type: BackendType | null): void;
+    /**
+     * Record a performance sample for adaptive tuning
+     */
+    recordSample(operation: OperationType, elementCount: number, backend: BackendType, durationMs: number): void;
+    /**
+     * Adjust thresholds based on collected samples
+     */
+    private maybeAdjustThresholds;
+    /**
+     * Get current adaptive thresholds
+     */
+    getAdaptiveThresholds(): Map<OperationType, {
+        wasm: number;
+        gpu: number;
+    }>;
+    /**
+     * Reset adaptive tuning state
+     */
+    resetAdaptiveState(): void;
+    /**
+     * Get performance statistics
+     */
+    getPerformanceStats(): {
+        sampleCount: number;
+        operationStats: Map<OperationType, {
+            avgDuration: number;
+            samples: number;
+            backendUsage: Record<BackendType, number>;
+        }>;
+    };
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+}
+/**
+ * Default backend manager instance
+ */
+export declare const backendManager: BackendManager;
+/**
+ * Create a new backend manager with custom hints
+ */
+export declare function createBackendManager(hints?: ExtendedBackendHints): BackendManager;
+//# sourceMappingURL=BackendManager.d.ts.map

package/dist/backends/BackendManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BackendManager.d.ts","sourceRoot":"","sources":["../../src/backends/BackendManager.ts"],"names":[],"mappings":"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"}

package/dist/backends/GPUBackend.d.ts

@@ -0,0 +1,128 @@
+/**
+ * GPU Backend for Matrix Operations
+ *
+ * WebGPU-accelerated matrix operations for large matrices.
+ */
+import { GPUContext, type GPUContextOptions, BufferPool, ShaderManager, type GPUCapabilities } from '@danielsimonjr/mathts-gpu';
+/**
+ * GPU Backend status
+ */
+export type GPUBackendStatus = 'uninitialized' | 'initializing' | 'ready' | 'error' | 'unsupported';
+/**
+ * Options for GPU backend
+ */
+export interface GPUBackendOptions extends GPUContextOptions {
+    /** Use global GPU context instead of creating a new one */
+    useGlobalContext?: boolean;
+    /** Buffer pool options */
+    bufferPoolOptions?: {
+        maxCacheSize?: number;
+        evictionTimeout?: number;
+    };
+    /** Threshold for using GPU (matrix size) */
+    threshold?: number;
+}
+/**
+ * GPU Backend for accelerated matrix operations
+ */
+export declare class GPUBackend {
+    private context;
+    private bufferPool;
+    private shaderManager;
+    private _status;
+    private _capabilities;
+    private _lastError;
+    private threshold;
+    private workgroupSize;
+    private useGlobalContext;
+    constructor(options?: GPUBackendOptions);
+    /**
+     * Get the current status
+     */
+    get status(): GPUBackendStatus;
+    /**
+     * Check if backend is ready
+     */
+    get isReady(): boolean;
+    /**
+     * Get capabilities
+     */
+    get capabilities(): GPUCapabilities | null;
+    /**
+     * Get last error
+     */
+    get lastError(): Error | null;
+    /**
+     * Initialize the GPU backend
+     */
+    initialize(options?: GPUBackendOptions): Promise<boolean>;
+    /**
+     * Check if GPU should be used for the given matrix size
+     */
+    shouldUseGPU(rows: number, cols: number): boolean;
+    /**
+     * Calculate workgroup counts for a matrix
+     */
+    calculateWorkgroups(rows: number, cols: number): [number, number, number];
+    /**
+     * Get the GPU context
+     */
+    getContext(): GPUContext;
+    /**
+     * Get the buffer pool
+     */
+    getBufferPool(): BufferPool;
+    /**
+     * Get the shader manager
+     */
+    getShaderManager(): ShaderManager;
+    /**
+     * Add two matrices element-wise
+     */
+    add(a: Float32Array, b: Float32Array, rows: number, cols: number): Promise<Float32Array>;
+    /**
+     * Multiply two matrices
+     */
+    matmul(a: Float32Array, b: Float32Array, M: number, K: number, N: number): Promise<Float32Array>;
+    /**
+     * Transpose a matrix
+     */
+    transpose(a: Float32Array, rows: number, cols: number): Promise<Float32Array>;
+    /**
+     * Scale a matrix by a scalar
+     */
+    scale(a: Float32Array, scalar: number): Promise<Float32Array>;
+    /**
+     * Get backend statistics
+     */
+    getStats(): {
+        status: GPUBackendStatus;
+        capabilities: GPUCapabilities | null;
+        bufferPool: {
+            totalBuffers: number;
+            inUseBuffers: number;
+            cachedBuffers: number;
+        } | null;
+        shaders: {
+            cachedShaders: number;
+            cachedPipelines: number;
+        } | null;
+    };
+    /**
+     * Destroy the backend
+     */
+    destroy(): void;
+}
+/**
+ * Get the global GPU backend
+ */
+export declare function getGlobalGPUBackend(): GPUBackend;
+/**
+ * Initialize the global GPU backend
+ */
+export declare function initializeGlobalGPUBackend(options?: GPUBackendOptions): Promise<boolean>;
+/**
+ * Destroy the global GPU backend
+ */
+export declare function destroyGlobalGPUBackend(): void;
+//# sourceMappingURL=GPUBackend.d.ts.map

package/dist/backends/GPUBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUBackend.d.ts","sourceRoot":"","sources":["../../src/backends/GPUBackend.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,UAAU,EACV,KAAK,iBAAiB,EAEtB,UAAU,EACV,aAAa,EAIb,KAAK,eAAe,EACrB,MAAM,2BAA2B,CAAC;AAGnC;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,eAAe,GAAG,cAAc,GAAG,OAAO,GAAG,OAAO,GAAG,aAAa,CAAC;AAEpG;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,0BAA0B;IAC1B,iBAAiB,CAAC,EAAE;QAClB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID;;GAEG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,aAAa,CAA8B;IACnD,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,UAAU,CAAsB;IACxC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,aAAa,CAAyC;IAC9D,OAAO,CAAC,gBAAgB,CAAU;IAElC,YAAY,OAAO,GAAE,iBAAsB,EAG1C;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,gBAAgB,CAE7B;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,eAAe,GAAG,IAAI,CAEzC;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,KAAK,GAAG,IAAI,CAE5B;IAED;;OAEG;IACG,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,OAAO,CAAC,CA6DlE;IAED;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAKhD;IAED;;OAEG;IACH,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAGxE;IAED;;OAEG;IACH,UAAU,IAAI,UAAU,CAKvB;IAED;;OAEG;IACH,aAAa,IAAI,UAAU,CAK1B;IAED;;OAEG;IACH,gBAAgB,IAAI,aAAa,CAKhC;IAED;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CA0C7F;IAED;;OAEG;IACG,MAAM,CACV,CAAC,EAAE,YAAY,EACf,CAAC,EAAE,YAAY,EACf,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR,OAAO,CAAC,YAAY,CAAC,CA4CvB;IAED;;OAEG;IACG,SAAS,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAsClF;IAED;;OAEG;IACG,KAAK,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAuClE;IAED;;OAEG;IACH,QAAQ,IAAI;QACV,MAAM,EAAE,gBAAgB,CAAC;QACzB,YAAY,EAAE,eAAe,GAAG,IAAI,CAAC;QACrC,UAAU,EAAE;YAAE,YAAY,EAAE,MAAM,CAAC;YAAC,YAAY,EAAE,MAAM,CAAC;YAAC,aAAa,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAC;QACzF,OAAO,EAAE;YAAE,aAAa,EAAE,MAAM,CAAC;YAAC,eAAe,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAC;KACpE,CAOA;IAED;;OAEG;IACH,OAAO,IAAI,IAAI,CAiBd;CACF;AAOD;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,UAAU,CAKhD;AAED;;GAEG;AACH,wBAAsB,0BAA0B,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAG9F;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAK9C"}

package/dist/backends/GPUMatrixBackend.d.ts

@@ -0,0 +1,123 @@
+/**
+ * GPU Matrix Backend Adapter
+ *
+ * Adapts GPUBackend to implement the MatrixBackend interface,
+ * enabling seamless integration with the backend selection system.
+ *
+ * @packageDocumentation
+ */
+import type { MatrixBackend, BackendType } from './Backend.js';
+import { DenseMatrix } from '../types/DenseMatrix.js';
+import { GPUBackend, type GPUBackendOptions } from './GPUBackend.js';
+import { type GPUCapabilities } from '@danielsimonjr/mathts-gpu';
+/**
+ * Configuration for GPU Matrix Backend
+ */
+export interface GPUMatrixBackendConfig {
+    /** Minimum elements to use GPU (default: 65536 = 256x256) */
+    minElements?: number;
+    /** Use global GPU backend instance */
+    useGlobalBackend?: boolean;
+    /** GPU backend options */
+    gpuOptions?: GPUBackendOptions;
+    /** Fall back to JS on GPU errors */
+    fallbackOnError?: boolean;
+}
+/**
+ * GPU Matrix Backend
+ *
+ * Implements MatrixBackend interface using WebGPU compute shaders.
+ * Provides significant acceleration for large matrices.
+ *
+ * @example
+ * ```typescript
+ * const gpu = new GPUMatrixBackend();
+ * await gpu.initialize();
+ *
+ * const result = gpu.multiply(matrixA, matrixB);
+ * ```
+ */
+export declare class GPUMatrixBackend implements MatrixBackend {
+    readonly type: BackendType;
+    private config;
+    private backend;
+    private capabilities;
+    private initPromise;
+    private _available;
+    constructor(config?: GPUMatrixBackendConfig);
+    /**
+     * Check if GPU is available in the current environment
+     */
+    isAvailable(): boolean;
+    /**
+     * Initialize the GPU backend
+     */
+    initialize(): Promise<void>;
+    private doInitialize;
+    /**
+     * Check if operation should use GPU
+     */
+    private shouldUseGPU;
+    /**
+     * Execute GPU operation with fallback
+     */
+    private executeWithFallback;
+    /**
+     * Get GPU capabilities
+     */
+    getCapabilities(): GPUCapabilities | null;
+    /**
+     * Get backend statistics
+     */
+    getStats(): ReturnType<GPUBackend['getStats']> | null;
+    add(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    /**
+     * Async add operation using GPU
+     */
+    addAsync(a: DenseMatrix, b: DenseMatrix): Promise<DenseMatrix>;
+    subtract(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    multiplyElementwise(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    divideElementwise(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    scale(a: DenseMatrix, scalar: number): DenseMatrix;
+    /**
+     * Async scale operation using GPU
+     */
+    scaleAsync(a: DenseMatrix, scalar: number): Promise<DenseMatrix>;
+    abs(a: DenseMatrix): DenseMatrix;
+    negate(a: DenseMatrix): DenseMatrix;
+    multiply(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    /**
+     * Async matrix multiplication using GPU
+     */
+    multiplyAsync(a: DenseMatrix, b: DenseMatrix): Promise<DenseMatrix>;
+    transpose(a: DenseMatrix): DenseMatrix;
+    /**
+     * Async transpose using GPU
+     */
+    transposeAsync(a: DenseMatrix): Promise<DenseMatrix>;
+    sum(a: DenseMatrix): number;
+    sumAxis(a: DenseMatrix, axis: 0 | 1): DenseMatrix;
+    norm(a: DenseMatrix): number;
+    dot(a: DenseMatrix, b: DenseMatrix): number;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<GPUMatrixBackendConfig>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): Required<GPUMatrixBackendConfig>;
+    /**
+     * Destroy the backend
+     */
+    destroy(): void;
+}
+/**
+ * Global GPU matrix backend instance
+ */
+export declare const gpuMatrixBackend: GPUMatrixBackend;
+/**
+ * Create a GPU matrix backend with custom configuration
+ */
+export declare function createGPUMatrixBackend(config?: GPUMatrixBackendConfig): GPUMatrixBackend;
+//# sourceMappingURL=GPUMatrixBackend.d.ts.map

package/dist/backends/GPUMatrixBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUMatrixBackend.d.ts","sourceRoot":"","sources":["../../src/backends/GPUMatrixBackend.ts"],"names":[],"mappings":"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"}