@railpath/finance-toolkit/dist/utils/vectorOperations.d.ts

Production-ready finance library for portfolio construction, risk analytics, quantitative metrics, and ML-based regime detection

/**
 * Vector Operations Utilities
 *
 * Collection of utility functions for vector operations commonly used in
 * mathematical optimization and portfolio analysis.
 */
/**
 * Calculate the Euclidean norm (magnitude) of a vector
 *
 * @param v - Input vector
 * @returns Euclidean norm of the vector
 *
 * @example
 * ```typescript
 * const norm = vectorNorm([3, 4]); // 5
 * const norm2 = vectorNorm([1, 1, 1]); // √3 ≈ 1.732
 * ```
 */
export declare function vectorNorm(v: number[]): number;
/**
 * Add two vectors element-wise
 *
 * @param a - First vector
 * @param b - Second vector
 * @returns Vector sum a + b
 *
 * @example
 * ```typescript
 * const sum = vectorAdd([1, 2, 3], [4, 5, 6]); // [5, 7, 9]
 * ```
 */
export declare function vectorAdd(a: number[], b: number[]): number[];
/**
 * Subtract two vectors element-wise
 *
 * @param a - First vector (minuend)
 * @param b - Second vector (subtrahend)
 * @returns Vector difference a - b
 *
 * @example
 * ```typescript
 * const diff = vectorSubtract([5, 7, 9], [1, 2, 3]); // [4, 5, 6]
 * ```
 */
export declare function vectorSubtract(a: number[], b: number[]): number[];
/**
 * Scale a vector by a scalar value
 *
 * @param v - Input vector
 * @param scalar - Scalar multiplier
 * @returns Scaled vector
 *
 * @example
 * ```typescript
 * const scaled = vectorScale([1, 2, 3], 2); // [2, 4, 6]
 * const scaled2 = vectorScale([1, 2, 3], -1); // [-1, -2, -3]
 * ```
 */
export declare function vectorScale(v: number[], scalar: number): number[];
/**
 * Calculate the dot product (inner product) of two vectors
 *
 * @param a - First vector
 * @param b - Second vector
 * @returns Dot product a · b
 *
 * @example
 * ```typescript
 * const dot = vectorDot([1, 2, 3], [4, 5, 6]); // 1*4 + 2*5 + 3*6 = 32
 * ```
 */
export declare function vectorDot(a: number[], b: number[]): number;
/**
 * Calculate the cross product of two 3D vectors
 *
 * @param a - First 3D vector
 * @param b - Second 3D vector
 * @returns Cross product a × b
 *
 * @example
 * ```typescript
 * const cross = vectorCross([1, 0, 0], [0, 1, 0]); // [0, 0, 1]
 * ```
 */
export declare function vectorCross(a: number[], b: number[]): number[];
/**
 * Normalize a vector to unit length
 *
 * @param v - Input vector
 * @returns Normalized vector (unit vector)
 *
 * @example
 * ```typescript
 * const normalized = vectorNormalize([3, 4]); // [0.6, 0.8]
 * ```
 */
export declare function vectorNormalize(v: number[]): number[];
/**
 * Calculate the distance between two vectors
 *
 * @param a - First vector
 * @param b - Second vector
 * @returns Euclidean distance between vectors
 *
 * @example
 * ```typescript
 * const distance = vectorDistance([0, 0], [3, 4]); // 5
 * ```
 */
export declare function vectorDistance(a: number[], b: number[]): number;
/**
 * Check if two vectors are approximately equal within tolerance
 *
 * @param a - First vector
 * @param b - Second vector
 * @param tolerance - Tolerance for comparison (default: 1e-12)
 * @returns True if vectors are approximately equal
 *
 * @example
 * ```typescript
 * const equal = vectorEquals([1.0000001, 2], [1, 2.0000001], 1e-6); // true
 * ```
 */
export declare function vectorEquals(a: number[], b: number[], tolerance?: number): boolean;
/**
 * Create a zero vector of specified length
 *
 * @param length - Length of the vector
 * @returns Zero vector
 *
 * @example
 * ```typescript
 * const zero = createZeroVector(3); // [0, 0, 0]
 * ```
 */
export declare function createZeroVector(length: number): number[];
/**
 * Create a vector filled with a constant value
 *
 * @param length - Length of the vector
 * @param value - Value to fill
 * @returns Vector filled with constant value
 *
 * @example
 * ```typescript
 * const ones = createConstantVector(3, 1); // [1, 1, 1]
 * ```
 */
export declare function createConstantVector(length: number, value: number): number[];