deepbox 0.1.0

package/dist/CSRMatrix-KzNt6QpS.d.ts

@@ -0,0 +1,219 @@
+import { S as Shape } from './tensor-B96jjJLQ.js';
+import { T as Tensor } from './Tensor-g8mUClel.js';
+
+type CSRMatrixInit = {
+    readonly data: Float64Array;
+    readonly indices: Int32Array;
+    readonly indptr: Int32Array;
+    readonly shape: Shape;
+};
+/**
+ * Compressed Sparse Row (CSR) matrix representation.
+ *
+ * CSR format stores a sparse matrix using three arrays:
+ * - `data`: Non-zero values in row-major order
+ * - `indices`: Column indices of non-zero values
+ * - `indptr`: Row pointers (indptr[i] to indptr[i+1] gives the range of data/indices for row i)
+ *
+ * This format is efficient for:
+ * - Row slicing
+ * - Matrix-vector products
+ * - Arithmetic operations
+ *
+ * @example
+ * ```ts
+ * import { CSRMatrix } from 'deepbox/ndarray';
+ *
+ * // Create a 3x3 sparse matrix with values at (0,0)=1, (1,2)=2, (2,1)=3
+ * const sparse = CSRMatrix.fromCOO({
+ *   rows: 3, cols: 3,
+ *   rowIndices: new Int32Array([0, 1, 2]),
+ *   colIndices: new Int32Array([0, 2, 1]),
+ *   values: new Float64Array([1, 2, 3])
+ * });
+ *
+ * // Convert to dense for operations
+ * const dense = sparse.toDense();
+ * ```
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_row_(CSR,_CRS_or_Yale_format) | Wikipedia: CSR}
+ */
+declare class CSRMatrix {
+    readonly data: Float64Array;
+    readonly indices: Int32Array;
+    readonly indptr: Int32Array;
+    readonly shape: Shape;
+    constructor(init: CSRMatrixInit);
+    /** Number of non-zero elements in the matrix */
+    get nnz(): number;
+    /** Number of rows in the matrix */
+    get rows(): number;
+    /** Number of columns in the matrix */
+    get cols(): number;
+    /**
+     * Convert the sparse matrix to a dense Tensor.
+     *
+     * @returns Dense 2D Tensor representation
+     *
+     * @example
+     * ```ts
+     * const dense = sparse.toDense();
+     * console.log(dense.shape);  // [rows, cols]
+     * ```
+     */
+    toDense(): Tensor;
+    /**
+     * Add two sparse matrices element-wise.
+     *
+     * Both matrices must have the same shape.
+     *
+     * @param other - Matrix to add
+     * @returns New CSRMatrix containing the sum
+     * @throws {ShapeError} If shapes don't match
+     *
+     * @example
+     * ```ts
+     * const c = a.add(b);  // c = a + b
+     * ```
+     */
+    add(other: CSRMatrix): CSRMatrix;
+    /**
+     * Subtract another sparse matrix element-wise.
+     *
+     * Both matrices must have the same shape.
+     *
+     * @param other - Matrix to subtract
+     * @returns New CSRMatrix containing the difference
+     * @throws {ShapeError} If shapes don't match
+     *
+     * @example
+     * ```ts
+     * const c = a.sub(b);  // c = a - b
+     * ```
+     */
+    sub(other: CSRMatrix): CSRMatrix;
+    /**
+     * Multiply all elements by a scalar value.
+     *
+     * @param scalar - Value to multiply by
+     * @returns New CSRMatrix with scaled values
+     *
+     * @example
+     * ```ts
+     * const scaled = matrix.scale(2.0);  // Double all values
+     * ```
+     */
+    scale(scalar: number): CSRMatrix;
+    /**
+     * Element-wise multiplication (Hadamard product) with another sparse matrix.
+     *
+     * Both matrices must have the same shape.
+     *
+     * @param other - Matrix to multiply with
+     * @returns New CSRMatrix containing the element-wise product
+     * @throws {ShapeError} If shapes don't match
+     *
+     * @example
+     * ```ts
+     * const c = a.multiply(b);  // c[i,j] = a[i,j] * b[i,j]
+     * ```
+     */
+    multiply(other: CSRMatrix): CSRMatrix;
+    /**
+     * Matrix multiplication with a dense vector.
+     *
+     * Computes y = A * x where A is this sparse matrix and x is a dense vector.
+     *
+     * @param vector - Dense vector (1D Tensor or Float64Array)
+     * @returns Dense result vector as Tensor
+     * @throws {ShapeError} If vector length doesn't match matrix columns
+     *
+     * @example
+     * ```ts
+     * const x = tensor([1, 2, 3]);
+     * const y = sparse.matvec(x);  // y = A * x
+     * ```
+     */
+    matvec(vector: Tensor | Float64Array): Tensor;
+    /**
+     * Matrix multiplication with a dense matrix.
+     *
+     * Computes C = A * B where A is this sparse matrix and B is a dense matrix.
+     *
+     * @param dense - Dense matrix (2D Tensor)
+     * @returns Dense result matrix as Tensor
+     * @throws {ShapeError} If inner dimensions don't match
+     *
+     * @example
+     * ```ts
+     * const B = tensor([[1, 2], [3, 4], [5, 6]]);
+     * const C = sparse.matmul(B);  // C = A * B
+     * ```
+     */
+    matmul(dense: Tensor): Tensor;
+    /**
+     * Transpose the sparse matrix.
+     *
+     * @returns New CSRMatrix representing the transpose
+     *
+     * @example
+     * ```ts
+     * const At = A.transpose();  // At[i,j] = A[j,i]
+     * ```
+     */
+    transpose(): CSRMatrix;
+    /**
+     * Get a specific element from the matrix.
+     *
+     * @param row - Row index
+     * @param col - Column index
+     * @returns Value at the specified position (0 if not stored)
+     * @throws {RangeError} If indices are out of bounds
+     *
+     * @example
+     * ```ts
+     * const value = matrix.get(1, 2);
+     * ```
+     */
+    get(row: number, col: number): number;
+    /**
+     * Create a copy of this matrix.
+     *
+     * @returns New CSRMatrix with copied data
+     */
+    copy(): CSRMatrix;
+    /** Helper to convert Tensor to Float64Array */
+    private tensorToFloat64;
+    /**
+     * Create a sparse matrix from COO (Coordinate List) format.
+     *
+     * @param args - COO format specification
+     * @param args.rows - Number of rows
+     * @param args.cols - Number of columns
+     * @param args.rowIndices - Row indices of non-zero values
+     * @param args.colIndices - Column indices of non-zero values
+     * @param args.values - Non-zero values
+     * @param args.sort - Whether to sort entries (default: true)
+     * @returns New CSRMatrix
+     *
+     * @example
+     * ```ts
+     * const sparse = CSRMatrix.fromCOO({
+     *   rows: 3, cols: 3,
+     *   rowIndices: new Int32Array([0, 1, 2]),
+     *   colIndices: new Int32Array([0, 2, 1]),
+     *   values: new Float64Array([1, 2, 3])
+     * });
+     * ```
+     */
+    static fromCOO(args: {
+        readonly rows: number;
+        readonly cols: number;
+        readonly rowIndices: Int32Array;
+        readonly colIndices: Int32Array;
+        readonly values: Float64Array;
+        readonly sort?: boolean;
+    }): CSRMatrix;
+}
+
+export { CSRMatrix as C, type CSRMatrixInit as a };

package/dist/Tensor-BQLk1ltW.d.cts

@@ -0,0 +1,147 @@
+import { S as Shape, D as DType, T as TensorLike, a as Device, b as TypedArray } from './tensor-B96jjJLQ.cjs';
+
+type TensorOptions = {
+    readonly dtype: DType;
+    readonly device: Device;
+};
+type TensorData<D extends DType> = D extends "string" ? string[] : TypedArray;
+/**
+ * Multi-dimensional array (tensor) with typed storage.
+ *
+ * Core data structure for numerical computing. Supports:
+ * - N-dimensional arrays with any shape
+ * - Multiple data types (float32, float64, int32, etc.)
+ * - Memory-efficient strided views
+ * - Device abstraction (CPU, WebGPU, WASM)
+ *
+ * Inspired by NumPy ndarray and PyTorch Tensor.
+ *
+ * @typeParam S - Shape type (readonly number array)
+ * @typeParam D - Data type (DType literal)
+ *
+ * @example
+ * ```ts
+ * import { tensor } from 'deepbox/ndarray';
+ *
+ * // Create from nested arrays
+ * const t = tensor([[1, 2, 3], [4, 5, 6]]);
+ * console.log(t.shape);  // [2, 3]
+ * console.log(t.dtype);  // 'float32'
+ *
+ * // Access properties
+ * console.log(t.size);   // 6
+ * console.log(t.ndim);   // 2
+ * ```
+ */
+declare class Tensor<S extends Shape = Shape, D extends DType = DType> implements TensorLike<S, D> {
+    readonly shape: S;
+    readonly dtype: D;
+    readonly device: Device;
+    readonly data: TensorData<D>;
+    readonly strides: readonly number[];
+    readonly offset: number;
+    readonly size: number;
+    readonly ndim: number;
+    private constructor();
+    private isStringTensor;
+    private isNumericTensor;
+    static fromTypedArray<S extends Shape, D extends Exclude<DType, "string">>(args: {
+        readonly data: TensorData<D>;
+        readonly shape: S;
+        readonly dtype: D;
+        readonly device: Device;
+        readonly offset?: number;
+        readonly strides?: readonly number[];
+    }): Tensor<S, D>;
+    static fromStringArray<S extends Shape>(args: {
+        readonly data: string[];
+        readonly shape: S;
+        readonly device?: Device;
+        readonly offset?: number;
+        readonly strides?: readonly number[];
+    }): Tensor<S, "string">;
+    static zeros<S extends Shape>(shape: S, opts: TensorOptions & {
+        readonly dtype: "string";
+    }): Tensor<S, "string">;
+    static zeros<S extends Shape, D extends Exclude<DType, "string">>(shape: S, opts: TensorOptions & {
+        readonly dtype: D;
+    }): Tensor<S, D>;
+    /**
+     * Create a view sharing the same underlying data.
+     *
+     * Note: This does not copy data. Mutations (if exposed in the future) would be shared.
+     */
+    view<S2 extends Shape>(this: Tensor<S, "string">, shape: S2, strides?: readonly number[], offset?: number): Tensor<S2, "string">;
+    view<S2 extends Shape>(this: Tensor<S, Exclude<DType, "string">>, shape: S2, strides?: readonly number[], offset?: number): Tensor<S2, Exclude<DType, "string">>;
+    view<S2 extends Shape>(this: Tensor<S, DType>, shape: S2, strides?: readonly number[], offset?: number): Tensor<S2, DType>;
+    /**
+     * Reshape the tensor to a new shape without copying data.
+     *
+     * Returns a new tensor with the specified shape, sharing the same underlying data.
+     * The total number of elements must remain the same.
+     * Requires a contiguous tensor; non-contiguous views will throw.
+     *
+     * This is a convenience method that wraps the standalone `reshape` function,
+     * providing a more intuitive API similar to NumPy and PyTorch.
+     *
+     * @param newShape - The desired shape for the tensor
+     * @returns A new tensor with the specified shape
+     * @throws {ShapeError} If the new shape is incompatible with the tensor's size
+     *
+     * @example
+     * ```ts
+     * const t = tensor([1, 2, 3, 4, 5, 6]);
+     * const reshaped = t.reshape([2, 3]);
+     * console.log(reshaped.shape); // [2, 3]
+     *
+     * const matrix = tensor([[1, 2], [3, 4]]);
+     * const flat = matrix.reshape([4]);
+     * console.log(flat.shape); // [4]
+     * ```
+     *
+     * @see {@link https://numpy.org/doc/stable/reference/generated/numpy.reshape.html | NumPy reshape}
+     * @see {@link https://pytorch.org/docs/stable/generated/torch.reshape.html | PyTorch reshape}
+     */
+    reshape<S2 extends Shape>(this: Tensor<S, "string">, newShape: S2): Tensor<S2, "string">;
+    reshape<S2 extends Shape>(this: Tensor<S, Exclude<DType, "string">>, newShape: S2): Tensor<S2, Exclude<DType, "string">>;
+    reshape<S2 extends Shape>(this: Tensor<S, DType>, newShape: S2): Tensor<S2, DType>;
+    /**
+     * Flatten the tensor to a 1-dimensional array.
+     *
+     * Returns a new 1D tensor containing all elements, sharing the same underlying data.
+     *
+     * @returns A 1D tensor with shape [size]
+     *
+     * @example
+     * ```ts
+     * const matrix = tensor([[1, 2, 3], [4, 5, 6]]);
+     * const flat = matrix.flatten();
+     * console.log(flat.shape); // [6]
+     * ```
+     */
+    flatten(this: Tensor<S, "string">): Tensor<[number], "string">;
+    flatten(this: Tensor<S, Exclude<DType, "string">>): Tensor<[number], Exclude<DType, "string">>;
+    flatten(this: Tensor<S, DType>): Tensor<[number], DType>;
+    at(...indices: number[]): unknown;
+    toArray(): unknown;
+    /**
+     * Return a human-readable string representation of this tensor.
+     *
+     * Scalars print as a bare value, 1-D tensors as a bracketed list, and
+     * higher-rank tensors use nested brackets with newline separators.
+     * Large dimensions are summarized with an ellipsis.
+     *
+     * @param maxElements - Maximum number of elements to display per
+     *   dimension before summarizing (default: 6).
+     * @returns Formatted string representation
+     *
+     * @example
+     * ```ts
+     * const t = tensor([1, 2, 3]);
+     * t.toString(); // "tensor([1, 2, 3], dtype=float32)"
+     * ```
+     */
+    toString(maxElements?: number): string;
+}
+
+export { Tensor as T, type TensorOptions as a };

package/dist/Tensor-g8mUClel.d.ts

@@ -0,0 +1,147 @@
+import { S as Shape, D as DType, T as TensorLike, a as Device, b as TypedArray } from './tensor-B96jjJLQ.js';
+
+type TensorOptions = {
+    readonly dtype: DType;
+    readonly device: Device;
+};
+type TensorData<D extends DType> = D extends "string" ? string[] : TypedArray;
+/**
+ * Multi-dimensional array (tensor) with typed storage.
+ *
+ * Core data structure for numerical computing. Supports:
+ * - N-dimensional arrays with any shape
+ * - Multiple data types (float32, float64, int32, etc.)
+ * - Memory-efficient strided views
+ * - Device abstraction (CPU, WebGPU, WASM)
+ *
+ * Inspired by NumPy ndarray and PyTorch Tensor.
+ *
+ * @typeParam S - Shape type (readonly number array)
+ * @typeParam D - Data type (DType literal)
+ *
+ * @example
+ * ```ts
+ * import { tensor } from 'deepbox/ndarray';
+ *
+ * // Create from nested arrays
+ * const t = tensor([[1, 2, 3], [4, 5, 6]]);
+ * console.log(t.shape);  // [2, 3]
+ * console.log(t.dtype);  // 'float32'
+ *
+ * // Access properties
+ * console.log(t.size);   // 6
+ * console.log(t.ndim);   // 2
+ * ```
+ */
+declare class Tensor<S extends Shape = Shape, D extends DType = DType> implements TensorLike<S, D> {
+    readonly shape: S;
+    readonly dtype: D;
+    readonly device: Device;
+    readonly data: TensorData<D>;
+    readonly strides: readonly number[];
+    readonly offset: number;
+    readonly size: number;
+    readonly ndim: number;
+    private constructor();
+    private isStringTensor;
+    private isNumericTensor;
+    static fromTypedArray<S extends Shape, D extends Exclude<DType, "string">>(args: {
+        readonly data: TensorData<D>;
+        readonly shape: S;
+        readonly dtype: D;
+        readonly device: Device;
+        readonly offset?: number;
+        readonly strides?: readonly number[];
+    }): Tensor<S, D>;
+    static fromStringArray<S extends Shape>(args: {
+        readonly data: string[];
+        readonly shape: S;
+        readonly device?: Device;
+        readonly offset?: number;
+        readonly strides?: readonly number[];
+    }): Tensor<S, "string">;
+    static zeros<S extends Shape>(shape: S, opts: TensorOptions & {
+        readonly dtype: "string";
+    }): Tensor<S, "string">;
+    static zeros<S extends Shape, D extends Exclude<DType, "string">>(shape: S, opts: TensorOptions & {
+        readonly dtype: D;
+    }): Tensor<S, D>;
+    /**
+     * Create a view sharing the same underlying data.
+     *
+     * Note: This does not copy data. Mutations (if exposed in the future) would be shared.
+     */
+    view<S2 extends Shape>(this: Tensor<S, "string">, shape: S2, strides?: readonly number[], offset?: number): Tensor<S2, "string">;
+    view<S2 extends Shape>(this: Tensor<S, Exclude<DType, "string">>, shape: S2, strides?: readonly number[], offset?: number): Tensor<S2, Exclude<DType, "string">>;
+    view<S2 extends Shape>(this: Tensor<S, DType>, shape: S2, strides?: readonly number[], offset?: number): Tensor<S2, DType>;
+    /**
+     * Reshape the tensor to a new shape without copying data.
+     *
+     * Returns a new tensor with the specified shape, sharing the same underlying data.
+     * The total number of elements must remain the same.
+     * Requires a contiguous tensor; non-contiguous views will throw.
+     *
+     * This is a convenience method that wraps the standalone `reshape` function,
+     * providing a more intuitive API similar to NumPy and PyTorch.
+     *
+     * @param newShape - The desired shape for the tensor
+     * @returns A new tensor with the specified shape
+     * @throws {ShapeError} If the new shape is incompatible with the tensor's size
+     *
+     * @example
+     * ```ts
+     * const t = tensor([1, 2, 3, 4, 5, 6]);
+     * const reshaped = t.reshape([2, 3]);
+     * console.log(reshaped.shape); // [2, 3]
+     *
+     * const matrix = tensor([[1, 2], [3, 4]]);
+     * const flat = matrix.reshape([4]);
+     * console.log(flat.shape); // [4]
+     * ```
+     *
+     * @see {@link https://numpy.org/doc/stable/reference/generated/numpy.reshape.html | NumPy reshape}
+     * @see {@link https://pytorch.org/docs/stable/generated/torch.reshape.html | PyTorch reshape}
+     */
+    reshape<S2 extends Shape>(this: Tensor<S, "string">, newShape: S2): Tensor<S2, "string">;
+    reshape<S2 extends Shape>(this: Tensor<S, Exclude<DType, "string">>, newShape: S2): Tensor<S2, Exclude<DType, "string">>;
+    reshape<S2 extends Shape>(this: Tensor<S, DType>, newShape: S2): Tensor<S2, DType>;
+    /**
+     * Flatten the tensor to a 1-dimensional array.
+     *
+     * Returns a new 1D tensor containing all elements, sharing the same underlying data.
+     *
+     * @returns A 1D tensor with shape [size]
+     *
+     * @example
+     * ```ts
+     * const matrix = tensor([[1, 2, 3], [4, 5, 6]]);
+     * const flat = matrix.flatten();
+     * console.log(flat.shape); // [6]
+     * ```
+     */
+    flatten(this: Tensor<S, "string">): Tensor<[number], "string">;
+    flatten(this: Tensor<S, Exclude<DType, "string">>): Tensor<[number], Exclude<DType, "string">>;
+    flatten(this: Tensor<S, DType>): Tensor<[number], DType>;
+    at(...indices: number[]): unknown;
+    toArray(): unknown;
+    /**
+     * Return a human-readable string representation of this tensor.
+     *
+     * Scalars print as a bare value, 1-D tensors as a bracketed list, and
+     * higher-rank tensors use nested brackets with newline separators.
+     * Large dimensions are summarized with an ellipsis.
+     *
+     * @param maxElements - Maximum number of elements to display per
+     *   dimension before summarizing (default: 6).
+     * @returns Formatted string representation
+     *
+     * @example
+     * ```ts
+     * const t = tensor([1, 2, 3]);
+     * t.toString(); // "tensor([1, 2, 3], dtype=float32)"
+     * ```
+     */
+    toString(maxElements?: number): string;
+}
+
+export { Tensor as T, type TensorOptions as a };