numpy-ts 0.11.0 → 0.13.0

package/dist/types/common/ops/formatting.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Array printing and formatting operations
+ *
+ * Functions for converting arrays and numbers to string representations.
+ * @module ops/formatting
+ */
+import { ArrayStorage } from '../storage';
+/**
+ * Print options configuration
+ */
+export interface PrintOptions {
+    /** Total number of array elements that trigger summarization (default: 1000) */
+    threshold: number;
+    /** Number of elements to print at edges when summarizing (default: 3) */
+    edgeitems: number;
+    /** Number of digits of precision for floating point output (default: 8) */
+    precision: number;
+    /** Characters per line for array output (default: 75) */
+    linewidth: number;
+    /** If true, always use exponential format; if false, never; if null, auto (default: null) */
+    floatmode: 'fixed' | 'unique' | 'maxprec' | 'maxprec_equal';
+    /** If true, suppress printing of small floating point values (default: true) */
+    suppress: boolean;
+    /** String inserted between elements (default: ' ') */
+    separator: string;
+    /** Prefix for array string */
+    prefix: string;
+    /** Suffix for array string */
+    suffix: string;
+    /** String representation of nan (default: 'nan') */
+    nanstr: string;
+    /** String representation of inf (default: 'inf') */
+    infstr: string;
+    /** If true, use legacy printing mode (default: false) */
+    legacy: string | false;
+    /** Whether to print the sign of positive values (default: false) */
+    sign: ' ' | '+' | '-';
+}
+/**
+ * Set printing options for array output
+ *
+ * These options determine how arrays are converted to strings.
+ *
+ * @param options - Options to set
+ *
+ * @example
+ * ```typescript
+ * set_printoptions({ precision: 4, threshold: 100 });
+ * ```
+ */
+export declare function set_printoptions(options: Partial<PrintOptions>): void;
+/**
+ * Get current print options
+ *
+ * @returns Current print options
+ *
+ * @example
+ * ```typescript
+ * const opts = get_printoptions();
+ * console.log(opts.precision); // 8
+ * ```
+ */
+export declare function get_printoptions(): PrintOptions;
+/**
+ * Context manager for temporarily setting print options
+ *
+ * In JavaScript, this returns an object with enter/exit methods
+ * that can be used with try/finally.
+ *
+ * @param options - Options to set temporarily
+ * @returns Object with enter() and exit() methods
+ *
+ * @example
+ * ```typescript
+ * const ctx = printoptions({ precision: 2 });
+ * ctx.enter();
+ * try {
+ *   console.log(array2string(arr));
+ * } finally {
+ *   ctx.exit();
+ * }
+ * ```
+ */
+export declare function printoptions(options: Partial<PrintOptions>): {
+    enter: () => void;
+    exit: () => void;
+    apply: <T>(fn: () => T) => T;
+    _savedOptions: PrintOptions | null;
+};
+/**
+ * Format a floating-point number in positional notation
+ *
+ * @param x - Value to format
+ * @param precision - Number of digits after decimal point (default: from printoptions)
+ * @param unique - If true, use shortest representation (default: true)
+ * @param fractional - If true, always include fractional part (default: true)
+ * @param trim - Trim trailing zeros: 'k' (keep), '.' (trim after decimal), '0' (trim zeros), '-' (trim point and zeros)
+ * @param sign - Sign handling: '-' (only negative), '+' (always), ' ' (space for positive)
+ * @param pad_left - Pad left with spaces to this width
+ * @param pad_right - Pad right with zeros to this width
+ * @param min_digits - Minimum digits after decimal point
+ * @returns Formatted string
+ *
+ * @example
+ * ```typescript
+ * format_float_positional(3.14159265, 4); // '3.1416'
+ * format_float_positional(1000.0, 2);     // '1000.00'
+ * ```
+ */
+export declare function format_float_positional(x: number, precision?: number | null, unique?: boolean, fractional?: boolean, trim?: 'k' | '.' | '0' | '-', sign?: '-' | '+' | ' ', pad_left?: number | null, pad_right?: number | null, min_digits?: number | null): string;
+/**
+ * Format a floating-point number in scientific notation
+ *
+ * @param x - Value to format
+ * @param precision - Number of digits after decimal point (default: from printoptions)
+ * @param unique - If true, use shortest representation (default: true)
+ * @param trim - Trim trailing zeros: 'k' (keep), '.' (trim after decimal), '0' (trim zeros), '-' (trim point and zeros)
+ * @param sign - Sign handling: '-' (only negative), '+' (always), ' ' (space for positive)
+ * @param pad_left - Pad left with spaces to this width
+ * @param exp_digits - Minimum digits in exponent
+ * @param min_digits - Minimum digits after decimal point
+ * @returns Formatted string
+ *
+ * @example
+ * ```typescript
+ * format_float_scientific(3.14159265, 4); // '3.1416e+00'
+ * format_float_scientific(12345.0, 2);    // '1.23e+04'
+ * ```
+ */
+export declare function format_float_scientific(x: number, precision?: number | null, _unique?: boolean, trim?: 'k' | '.' | '0' | '-', sign?: '-' | '+' | ' ', pad_left?: number | null, exp_digits?: number, min_digits?: number | null): string;
+/**
+ * Return a string representation of a number in the given base
+ *
+ * For base 2, -36. Negative numbers are represented using two's complement
+ * if padding is specified, otherwise prefixed with '-'.
+ *
+ * @param number - Number to convert
+ * @param base - Base for representation (2-36, default: 2)
+ * @param padding - Minimum number of digits (pads with zeros)
+ * @returns String representation in the given base
+ *
+ * @example
+ * ```typescript
+ * base_repr(10, 2);      // '1010'
+ * base_repr(10, 16);     // 'A'
+ * base_repr(-10, 2, 8);  // '11110110' (two's complement)
+ * ```
+ */
+export declare function base_repr(number: number, base?: number, padding?: number): string;
+/**
+ * Return the binary representation of the input number as a string
+ *
+ * For negative numbers, two's complement is used if width is specified,
+ * otherwise a minus sign is prefixed.
+ *
+ * @param num - Integer to convert
+ * @param width - Minimum width of the result (pads with zeros, uses two's complement for negatives)
+ * @returns Binary string representation
+ *
+ * @example
+ * ```typescript
+ * binary_repr(10);      // '1010'
+ * binary_repr(-10);     // '-1010'
+ * binary_repr(-10, 8);  // '11110110' (two's complement)
+ * ```
+ */
+export declare function binary_repr(num: number, width?: number | null): string;
+/**
+ * Convert an array to a string representation
+ *
+ * @param a - Input array storage
+ * @param max_line_width - Maximum line width (default: from printoptions)
+ * @param precision - Number of digits of precision (default: from printoptions)
+ * @param suppress_small - Suppress small floating point values (default: from printoptions)
+ * @param separator - Separator between elements (default: from printoptions)
+ * @param prefix - Prefix string (default: '')
+ * @param suffix - Suffix string (default: '')
+ * @param threshold - Threshold for summarization (default: from printoptions)
+ * @param edgeitems - Number of edge items when summarizing (default: from printoptions)
+ * @returns String representation of the array
+ *
+ * @example
+ * ```typescript
+ * const arr = array([[1, 2, 3], [4, 5, 6]]);
+ * console.log(array2string(arr.storage));
+ * // [[1 2 3]
+ * //  [4 5 6]]
+ * ```
+ */
+export declare function array2string(a: ArrayStorage, max_line_width?: number | null, precision?: number | null, suppress_small?: boolean | null, separator?: string, prefix?: string, suffix?: string, threshold?: number | null, edgeitems?: number | null): string;
+/**
+ * Return the string representation of an array
+ *
+ * Similar to array2string but includes the 'array(' prefix.
+ *
+ * @param a - Input array storage
+ * @param max_line_width - Maximum line width
+ * @param precision - Number of digits of precision
+ * @param suppress_small - Suppress small floating point values
+ * @returns String representation
+ *
+ * @example
+ * ```typescript
+ * const arr = array([1, 2, 3]);
+ * console.log(array_repr(arr.storage));
+ * // array([1, 2, 3])
+ * ```
+ */
+export declare function array_repr(a: ArrayStorage, max_line_width?: number | null, precision?: number | null, suppress_small?: boolean | null): string;
+/**
+ * Return a string representation of the data in an array
+ *
+ * Similar to array2string but returns just the data without array() wrapper.
+ *
+ * @param a - Input array storage
+ * @param max_line_width - Maximum line width
+ * @param precision - Number of digits of precision
+ * @param suppress_small - Suppress small floating point values
+ * @returns String representation of the data
+ *
+ * @example
+ * ```typescript
+ * const arr = array([1, 2, 3]);
+ * console.log(array_str(arr.storage));
+ * // [1 2 3]
+ * ```
+ */
+export declare function array_str(a: ArrayStorage, max_line_width?: number | null, precision?: number | null, suppress_small?: boolean | null): string;
+//# sourceMappingURL=formatting.d.ts.map

package/dist/types/{ops → common/ops}/gradient.d.ts

@@ -7,7 +7,7 @@
  * These functions are used by NDArray methods but are separated
  * to keep the codebase modular and testable.
  */
-import { ArrayStorage } from '../core/storage';
+import { ArrayStorage } from '../storage';
 /**
  * Calculate the n-th discrete difference along the given axis.
  *

package/dist/types/{ops → common/ops}/hyperbolic.d.ts

@@ -7,7 +7,7 @@
  * These functions are used by NDArray methods but are separated
  * to keep the codebase modular and testable.
  */
-import { ArrayStorage } from '../core/storage';
+import { ArrayStorage } from '../storage';
 /**
  * Hyperbolic sine of each element (element-wise)
  * NumPy behavior: Always promotes to float64 for integer types

package/dist/types/{ops → common/ops}/linalg.d.ts

@@ -4,8 +4,8 @@
  * Pure functions for matrix operations (matmul, etc.).
  * @module ops/linalg
  */
-import { ArrayStorage } from '../core/storage';
-import { Complex } from '../core/complex';
+import { ArrayStorage } from '../storage';
+import { Complex } from '../complex';
 /**
  * Dot product of two arrays (fully NumPy-compatible)
  *
@@ -158,7 +158,7 @@ export declare function kron(a: ArrayStorage, b: ArrayStorage): ArrayStorage;
  * @param axis - If defined, the axis of a, b and c that defines the vectors
  * @returns Cross product of a and b
  */
-export declare function cross(a: ArrayStorage, b: ArrayStorage, axisa?: number, axisb?: number, axisc?: number, axis?: number): ArrayStorage | number;
+export declare function cross(a: ArrayStorage, b: ArrayStorage, axisa?: number, axisb?: number, axisc?: number, axis?: number): ArrayStorage | number | Complex;
 /**
  * Vector norm.
  *
@@ -364,4 +364,149 @@ export declare function eigvals(a: ArrayStorage): ArrayStorage;
  * @returns Array of eigenvalues (sorted ascending)
  */
 export declare function eigvalsh(a: ArrayStorage, UPLO?: 'L' | 'U'): ArrayStorage;
+/**
+ * Return the dot product of two vectors (flattened).
+ *
+ * Unlike dot(), vdot flattens both inputs before computing the dot product.
+ * For complex numbers, vdot uses the complex conjugate of the first argument.
+ *
+ * @param a - First input array (will be flattened)
+ * @param b - Second input array (will be flattened)
+ * @returns Scalar dot product
+ */
+export declare function vdot(a: ArrayStorage, b: ArrayStorage): number | bigint | Complex;
+/**
+ * Vector dot product along the last axis.
+ *
+ * Computes the dot product of vectors along the last axis of both inputs.
+ * The last dimensions of a and b must match.
+ *
+ * @param a - First input array
+ * @param b - Second input array
+ * @param axis - Axis along which to compute (default: -1, meaning last axis)
+ * @returns Result with last dimension removed
+ */
+export declare function vecdot(a: ArrayStorage, b: ArrayStorage, axis?: number): ArrayStorage | number | bigint | Complex;
+/**
+ * Transpose the last two axes of an array.
+ *
+ * Equivalent to swapaxes(a, -2, -1) or transpose with axes that swap the last two.
+ * For a 2D array, this is the same as transpose.
+ *
+ * @param a - Input array with at least 2 dimensions
+ * @returns Array with last two axes transposed
+ */
+export declare function matrix_transpose(a: ArrayStorage): ArrayStorage;
+/**
+ * Permute the dimensions of an array.
+ *
+ * This is an alias for transpose to match the Array API standard.
+ *
+ * @param a - Input array
+ * @param axes - Permutation of axes. If not specified, reverses the axes.
+ * @returns Transposed array
+ */
+export declare function permute_dims(a: ArrayStorage, axes?: number[]): ArrayStorage;
+/**
+ * Matrix-vector multiplication.
+ *
+ * Computes the matrix-vector product over the last two axes of x1 and
+ * the last axis of x2.
+ *
+ * @param x1 - First input array (matrix) with shape (..., M, N)
+ * @param x2 - Second input array (vector) with shape (..., N)
+ * @returns Result with shape (..., M)
+ */
+export declare function matvec(x1: ArrayStorage, x2: ArrayStorage): ArrayStorage;
+/**
+ * Vector-matrix multiplication.
+ *
+ * Computes the vector-matrix product over the last axis of x1 and
+ * the second-to-last axis of x2.
+ *
+ * @param x1 - First input array (vector) with shape (..., M)
+ * @param x2 - Second input array (matrix) with shape (..., M, N)
+ * @returns Result with shape (..., N)
+ */
+export declare function vecmat(x1: ArrayStorage, x2: ArrayStorage): ArrayStorage;
+/**
+ * Compute sign and (natural) logarithm of the determinant.
+ *
+ * Returns (sign, logabsdet) where sign is the sign of the determinant
+ * and logabsdet is the natural log of the absolute value of the determinant.
+ *
+ * This is useful for computing determinants of large matrices where the
+ * determinant itself might overflow or underflow.
+ *
+ * @param a - Square matrix
+ * @returns { sign, logabsdet }
+ */
+export declare function slogdet(a: ArrayStorage): {
+    sign: number;
+    logabsdet: number;
+};
+/**
+ * Compute singular values of a matrix.
+ *
+ * This is equivalent to svd(a, compute_uv=False) but more efficient
+ * as it doesn't compute the U and V matrices.
+ *
+ * @param a - Input matrix (m x n)
+ * @returns 1D array of singular values in descending order
+ */
+export declare function svdvals(a: ArrayStorage): ArrayStorage;
+/**
+ * Compute the dot product of two or more arrays in a single function call.
+ *
+ * Optimizes the order of multiplications to minimize computation.
+ * For example, for three arrays A, B, C with shapes (10, 100), (100, 5), (5, 50),
+ * it's more efficient to compute (A @ B) @ C than A @ (B @ C).
+ *
+ * @param arrays - List of arrays to multiply
+ * @returns Result of multiplying all arrays
+ */
+export declare function multi_dot(arrays: ArrayStorage[]): ArrayStorage;
+/**
+ * Compute the 'inverse' of an N-dimensional array.
+ *
+ * The inverse is defined such that tensordot(tensorinv(a), a, ind) == I
+ * where I is the identity operator.
+ *
+ * @param a - Input array to invert
+ * @param ind - Number of first indices that are involved in the inverse sum (default: 2)
+ * @returns Tensor inverse
+ */
+export declare function tensorinv(a: ArrayStorage, ind?: number): ArrayStorage;
+/**
+ * Solve the tensor equation a x = b for x.
+ *
+ * This is equivalent to solve after reshaping a and b appropriately.
+ *
+ * @param a - Coefficient tensor
+ * @param b - Target tensor
+ * @param axes - Axes of a to be summed over in the contraction (default based on b.ndim)
+ * @returns Solution tensor x
+ */
+export declare function tensorsolve(a: ArrayStorage, b: ArrayStorage, axes?: number[] | null): ArrayStorage;
+/**
+ * Evaluate the lowest cost contraction order for an einsum expression
+ *
+ * This function analyzes an einsum expression and finds an optimized contraction
+ * path that minimizes the total number of operations (FLOPs).
+ *
+ * @param subscripts - Einsum subscript string (e.g., 'ij,jk,kl->il')
+ * @param operands - Input arrays (or their shapes)
+ * @param optimize - Optimization strategy: 'greedy' (default), 'optimal', or false for no optimization
+ * @returns A tuple of [path, string_representation] where path is an array of index pairs
+ *
+ * @example
+ * ```typescript
+ * const a = ones([10, 10]);
+ * const b = ones([10, 10]);
+ * const c = ones([10, 10]);
+ * const [path, info] = einsum_path('ij,jk,kl->il', a.storage, b.storage, c.storage);
+ * // path: [[0, 1], [0, 1]] - contract first two, then result with third
+ * ```
+ */
+export declare function einsum_path(subscripts: string, ...operands: (ArrayStorage | number[])[]): [Array<[number, number] | number[]>, string];
 //# sourceMappingURL=linalg.d.ts.map

package/dist/types/{ops → common/ops}/logic.d.ts

@@ -8,8 +8,8 @@
  * These operations convert values to boolean (non-zero = true, zero = false)
  * and return boolean arrays (dtype: 'bool').
  */
-import { ArrayStorage } from '../core/storage';
-import { type DType } from '../core/dtype';
+import { ArrayStorage } from '../storage';
+import { type DType } from '../dtype';
 /**
  * Logical AND of two arrays or array and scalar
  *