deepbox 0.1.0

package/dist/index-DyZ4QQf5.d.cts

@@ -0,0 +1,456 @@
+import { D as DType, a as Device, S as Shape } from './tensor-B96jjJLQ.cjs';
+import { T as Tensor } from './Tensor-BQLk1ltW.cjs';
+
+type RandomOptions = {
+    readonly dtype?: DType;
+    readonly device?: Device;
+};
+/**
+ * Set global random seed.
+ *
+ * @param seed - Random seed value (any finite number). The seed is coerced to a uint64
+ *               internally, so the same seed always produces the same sequence.
+ *
+ * @throws {InvalidParameterError} When seed is not finite (NaN or ±Infinity)
+ *
+ * @remarks
+ * - Setting a seed makes all random operations deterministic and reproducible.
+ * - The seed is truncated to uint64 range (0 to 2^64-1) for internal state.
+ * - Use {@link getSeed} to retrieve the currently set seed.
+ * - When no seed is set, random sampling uses a cryptographically secure RNG.
+ *   Seeded mode is deterministic and **not** intended for cryptographic use.
+ *
+ * @example
+ * ```js
+ * import { setSeed, rand } from 'deepbox/random';
+ *
+ * setSeed(42);
+ * const a = rand([5]);
+ * setSeed(42);
+ * const b = rand([5]);
+ * // a and b contain identical values
+ * ```
+ */
+declare function setSeed(seed: number): void;
+/**
+ * Get current random seed.
+ *
+ * @returns Current seed value or undefined if not set
+ *
+ * @example
+ * ```js
+ * import { setSeed, getSeed } from 'deepbox/random';
+ *
+ * setSeed(12345);
+ * console.log(getSeed()); // 12345
+ * ```
+ */
+declare function getSeed(): number | undefined;
+/**
+ * Clear the current random seed and revert to cryptographically secure randomness.
+ *
+ * @remarks
+ * - After calling this, random sampling uses `crypto.getRandomValues`.
+ * - Use this to leave deterministic mode after {@link setSeed}.
+ *
+ * @example
+ * ```js
+ * import { clearSeed, rand } from 'deepbox/random';
+ *
+ * clearSeed();
+ * const x = rand([3]);  // cryptographically secure randomness
+ * ```
+ */
+declare function clearSeed(): void;
+/**
+ * Random values in half-open interval [0, 1).
+ *
+ * @param shape - Output shape
+ * @param opts - Options (dtype, device)
+ *
+ * @remarks
+ * - Values are uniformly distributed in [0, 1) (inclusive lower, exclusive upper bound).
+ * - Uses deterministic PRNG when seed is set via {@link setSeed}.
+ * - Default dtype is float32; use float64 for higher precision.
+ * - Only float32 and float64 dtypes are supported.
+ *
+ * @example
+ * ```js
+ * import { rand, setSeed } from 'deepbox/random';
+ *
+ * const x = rand([2, 3]);  // 2x3 matrix of random values
+ *
+ * // Deterministic generation
+ * setSeed(42);
+ * const a = rand([5]);
+ * setSeed(42);
+ * const b = rand([5]);
+ * // a and b are identical
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.rand.html | NumPy random.rand}
+ */
+declare function rand(shape: Shape, opts?: RandomOptions): Tensor;
+/**
+ * Random samples from standard normal distribution.
+ *
+ * @param shape - Output shape
+ * @param opts - Options (dtype, device)
+ *
+ * @remarks
+ * - Uses Box-Muller transform to generate normally distributed values.
+ * - Mean = 0, standard deviation = 1.
+ * - All values are finite (no infinities from tail behavior).
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - Only float32 and float64 dtypes are supported.
+ *
+ * @example
+ * ```js
+ * import { randn } from 'deepbox/random';
+ *
+ * const x = randn([2, 3]);  // 2x3 matrix of normal random values
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.randn.html | NumPy random.randn}
+ */
+declare function randn(shape: Shape, opts?: RandomOptions): Tensor;
+/**
+ * Random integers in half-open interval [low, high).
+ *
+ * @param low - Lowest integer (inclusive)
+ * @param high - Highest integer (exclusive)
+ * @param shape - Output shape
+ * @param opts - Options (dtype, device)
+ *
+ * @throws {InvalidParameterError} When low or high is not finite
+ * @throws {InvalidParameterError} When low or high is not an integer
+ * @throws {InvalidParameterError} When high <= low
+ *
+ * @remarks
+ * - Generates integers uniformly in [low, high) range.
+ * - Both low and high must be safe integers (within ±2^53-1).
+ * - dtype must be int32 or int64; int32 output requires bounds within int32 range.
+ * - Deterministic when seed is set via {@link setSeed}.
+ *
+ * @example
+ * ```js
+ * import { randint } from 'deepbox/random';
+ *
+ * const x = randint(0, 10, [5]);  // 5 random integers from 0 to 9
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.randint.html | NumPy random.randint}
+ */
+declare function randint(low: number, high: number, shape: Shape, opts?: RandomOptions): Tensor;
+/**
+ * Random samples from continuous uniform distribution.
+ *
+ * @param low - Lower boundary (default: 0)
+ * @param high - Upper boundary (default: 1)
+ * @param shape - Output shape
+ * @param opts - Options
+ *
+ * @throws {InvalidParameterError} When low or high is not finite
+ * @throws {InvalidParameterError} When high < low
+ *
+ * @remarks
+ * - Values are uniformly distributed in [low, high).
+ * - For very large ranges, floating-point precision may affect uniformity.
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - Only float32 and float64 dtypes are supported.
+ *
+ * @example
+ * ```js
+ * import { uniform } from 'deepbox/random';
+ *
+ * const x = uniform(-1, 1, [3, 3]);  // Values between -1 and 1
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.uniform.html | NumPy random.uniform}
+ */
+declare function uniform(low?: number, high?: number, shape?: Shape, opts?: RandomOptions): Tensor;
+/**
+ * Random samples from normal (Gaussian) distribution.
+ *
+ * @param mean - Mean of distribution (default: 0)
+ * @param std - Standard deviation (default: 1)
+ * @param shape - Output shape
+ * @param opts - Options
+ *
+ * @throws {InvalidParameterError} When mean or std is not finite
+ * @throws {InvalidParameterError} When std < 0
+ *
+ * @remarks
+ * - Uses Box-Muller transform internally.
+ * - All values are finite due to RNG resolution (no infinities from log(0)).
+ * - std=0 produces constant values equal to mean.
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - Only float32 and float64 dtypes are supported.
+ *
+ * @example
+ * ```js
+ * import { normal } from 'deepbox/random';
+ *
+ * const x = normal(0, 2, [100]);  // Mean 0, std 2
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.normal.html | NumPy random.normal}
+ */
+declare function normal(mean?: number, std?: number, shape?: Shape, opts?: RandomOptions): Tensor;
+/**
+ * Random samples from binomial distribution.
+ *
+ * @param n - Number of trials (non-negative integer)
+ * @param p - Probability of success (in [0, 1])
+ * @param shape - Output shape
+ * @param opts - Options
+ *
+ * @throws {InvalidParameterError} When n is not finite, not an integer, or < 0
+ * @throws {InvalidParameterError} When p is not finite or not in [0, 1]
+ *
+ * @remarks
+ * - Generates number of successes in n independent Bernoulli trials.
+ * - Uses an exact geometric waiting-time method for small means and
+ *   a mode-centered chop-down inversion for larger means.
+ * - Results are in range [0, n].
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - Only int32 and int64 dtypes are supported.
+ *
+ * @example
+ * ```js
+ * import { binomial } from 'deepbox/random';
+ *
+ * const x = binomial(10, 0.5, [100]);  // 10 coin flips, 100 times
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.binomial.html | NumPy random.binomial}
+ */
+declare function binomial(n: number, p: number, shape?: Shape, opts?: RandomOptions): Tensor;
+/**
+ * Random samples from Poisson distribution.
+ *
+ * @param lambda - Expected number of events (rate, must be >= 0)
+ * @param shape - Output shape
+ * @param opts - Options
+ *
+ * @throws {InvalidParameterError} When lambda is not finite or < 0
+ *
+ * @remarks
+ * - Uses Knuth's method for lambda < 30, transformed rejection for lambda >= 30.
+ * - Stable and efficient for all lambda values (tested up to lambda=1000+).
+ * - lambda=0 always produces 0.
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - Only int32 and int64 dtypes are supported.
+ *
+ * @example
+ * ```js
+ * import { poisson } from 'deepbox/random';
+ *
+ * const x = poisson(5, [100]);  // Rate = 5 events
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.poisson.html | NumPy random.poisson}
+ */
+declare function poisson(lambda: number, shape?: Shape, opts?: RandomOptions): Tensor;
+/**
+ * Random samples from exponential distribution.
+ *
+ * @param scale - Scale parameter (1/lambda, default: 1, must be > 0)
+ * @param shape - Output shape
+ * @param opts - Options
+ *
+ * @throws {InvalidParameterError} When scale is not finite or <= 0
+ *
+ * @remarks
+ * - Uses inverse transform sampling: -scale * log(U).
+ * - All values are positive (u=0 is avoided to prevent infinities).
+ * - Mean = scale, variance = scale^2.
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - Only float32 and float64 dtypes are supported.
+ *
+ * @example
+ * ```js
+ * import { exponential } from 'deepbox/random';
+ *
+ * const x = exponential(2, [100]);
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.exponential.html | NumPy random.exponential}
+ */
+declare function exponential(scale?: number, shape?: Shape, opts?: RandomOptions): Tensor;
+/**
+ * Random samples from gamma distribution.
+ *
+ * @param shape_param - Shape parameter (k, must be > 0)
+ * @param scale - Scale parameter (theta, default: 1, must be > 0)
+ * @param shape - Output shape
+ * @param opts - Options
+ *
+ * @throws {InvalidParameterError} When shape_param is not finite or <= 0
+ * @throws {InvalidParameterError} When scale is not finite or <= 0
+ *
+ * @remarks
+ * - Uses Marsaglia and Tsang's method (2000) for efficient sampling.
+ * - All values are positive.
+ * - Mean = shape_param * scale, variance = shape_param * scale^2.
+ * - For shape_param < 1, uses a transformation to handle the case.
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - Only float32 and float64 dtypes are supported.
+ *
+ * @example
+ * ```js
+ * import { gamma } from 'deepbox/random';
+ *
+ * const x = gamma(2, 2, [100]);
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.gamma.html | NumPy random.gamma}
+ */
+declare function gamma(shape_param: number, scale?: number, shape?: Shape, opts?: RandomOptions): Tensor;
+/**
+ * Random samples from beta distribution.
+ *
+ * @param alpha - Alpha parameter (must be > 0)
+ * @param beta_param - Beta parameter (must be > 0)
+ * @param shape - Output shape
+ * @param opts - Options
+ *
+ * @throws {InvalidParameterError} When alpha is not finite or <= 0
+ * @throws {InvalidParameterError} When beta_param is not finite or <= 0
+ *
+ * @remarks
+ * - Uses ratio of two gamma distributions: X / (X + Y).
+ * - All values are in the open interval (0, 1) up to floating-point rounding.
+ * - Mean = alpha / (alpha + beta), useful for modeling proportions.
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - Only float32 and float64 dtypes are supported.
+ *
+ * @example
+ * ```js
+ * import { beta } from 'deepbox/random';
+ *
+ * const x = beta(2, 5, [100]);
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.beta.html | NumPy random.beta}
+ */
+declare function beta(alpha: number, beta_param: number, shape?: Shape, opts?: RandomOptions): Tensor;
+/**
+ * Random sample from array.
+ *
+ * @param a - Input array or integer (if integer, sample from arange(a))
+ * @param size - Number of samples or output shape
+ * @param replace - Whether to sample with replacement (default: true)
+ * @param p - Optional probability weights for weighted sampling
+ *
+ * @throws {InvalidParameterError} When population size is invalid (not finite, not integer, or < 0)
+ * @throws {InvalidParameterError} When size > population and replace is false
+ * @throws {InvalidParameterError} When tensor is not contiguous (offset !== 0 or non-standard strides)
+ * @throws {DTypeError} When input tensor has string dtype
+ *
+ * @remarks
+ * - Input tensor must be contiguous (no slicing/striding).
+ * - With replacement: can sample more elements than population size.
+ * - Without replacement: size must be <= population size.
+ * - Does NOT modify the input tensor (returns a new tensor).
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - If `a` is a number, the population is `0..a-1` and output dtype is int32.
+ * - Numeric populations are limited to `a <= 2^31` for int32 output.
+ *
+ * @example
+ * ```js
+ * import { choice, tensor } from 'deepbox/random';
+ *
+ * const x = tensor([1, 2, 3, 4, 5]);
+ * const sample = choice(x, 3);  // Pick 3 elements with replacement
+ *
+ * // Without replacement
+ * const unique = choice(x, 3, false);  // All different elements
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.choice.html | NumPy random.choice}
+ */
+declare function choice(a: Tensor | number, size?: number | Shape, replace?: boolean, p?: Tensor): Tensor;
+/**
+ * Randomly shuffle array in-place.
+ *
+ * @param x - Input tensor (**MODIFIED IN-PLACE**)
+ *
+ * @throws {InvalidParameterError} When tensor is not contiguous (offset !== 0 or non-standard strides)
+ * @throws {DTypeError} When input tensor has string dtype
+ *
+ * @remarks
+ * - **WARNING: This function mutates the input tensor directly.**
+ * - Uses Fisher-Yates shuffle algorithm (O(n) time, optimal).
+ * - Input tensor must be contiguous (no slicing/striding).
+ * - All elements are preserved, only their order changes.
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - If you need a shuffled copy without mutation, use {@link permutation} instead.
+ *
+ * @example
+ * ```js
+ * import { shuffle, tensor } from 'deepbox/random';
+ *
+ * const x = tensor([1, 2, 3, 4, 5]);
+ * shuffle(x);  // x is now shuffled IN-PLACE
+ * console.log(x);  // e.g., [3, 1, 5, 2, 4]
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.shuffle.html | NumPy random.shuffle}
+ */
+declare function shuffle(x: Tensor): void;
+/**
+ * Return random permutation of array.
+ *
+ * @param x - Input tensor or integer
+ *
+ * @throws {DTypeError} When input tensor has string dtype
+ *
+ * @remarks
+ * - Returns a NEW tensor (does NOT modify input).
+ * - If x is an integer, returns permutation of arange(x).
+ * - If x is a tensor, returns a shuffled copy with the same shape.
+ * - Tensor inputs must be contiguous (no slicing/striding).
+ * - Uses Fisher-Yates shuffle algorithm internally.
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - Numeric input is limited to `x <= 2^31` for int32 output.
+ *
+ * @example
+ * ```js
+ * import { permutation, tensor } from 'deepbox/random';
+ *
+ * // Permutation of integers
+ * const x = permutation(10);  // Random permutation of [0...9]
+ *
+ * // Permutation of tensor (does not modify original)
+ * const original = tensor([1, 2, 3, 4, 5]);
+ * const shuffled = permutation(original);
+ * // original is unchanged
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.permutation.html | NumPy random.permutation}
+ */
+declare function permutation(x: Tensor | number): Tensor;
+
+type index_RandomOptions = RandomOptions;
+declare const index_beta: typeof beta;
+declare const index_binomial: typeof binomial;
+declare const index_choice: typeof choice;
+declare const index_clearSeed: typeof clearSeed;
+declare const index_exponential: typeof exponential;
+declare const index_gamma: typeof gamma;
+declare const index_getSeed: typeof getSeed;
+declare const index_normal: typeof normal;
+declare const index_permutation: typeof permutation;
+declare const index_poisson: typeof poisson;
+declare const index_rand: typeof rand;
+declare const index_randint: typeof randint;
+declare const index_randn: typeof randn;
+declare const index_setSeed: typeof setSeed;
+declare const index_shuffle: typeof shuffle;
+declare const index_uniform: typeof uniform;
+declare namespace index {
+  export { type index_RandomOptions as RandomOptions, index_beta as beta, index_binomial as binomial, index_choice as choice, index_clearSeed as clearSeed, index_exponential as exponential, index_gamma as gamma, index_getSeed as getSeed, index_normal as normal, index_permutation as permutation, index_poisson as poisson, index_rand as rand, index_randint as randint, index_randn as randn, index_setSeed as setSeed, index_shuffle as shuffle, index_uniform as uniform };
+}
+
+export { type RandomOptions as R, randn as a, randint as b, clearSeed as c, binomial as d, exponential as e, gamma as f, getSeed as g, beta as h, index as i, choice as j, shuffle as k, permutation as l, normal as n, poisson as p, rand as r, setSeed as s, uniform as u };