@pawells/math-extended 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +319 -0
- package/build/angles.d.ts +31 -0
- package/build/angles.d.ts.map +1 -0
- package/build/angles.js +85 -0
- package/build/angles.js.map +1 -0
- package/build/angles.spec.d.ts +2 -0
- package/build/angles.spec.d.ts.map +1 -0
- package/build/angles.spec.js +147 -0
- package/build/angles.spec.js.map +1 -0
- package/build/clamp.d.ts +17 -0
- package/build/clamp.d.ts.map +1 -0
- package/build/clamp.js +19 -0
- package/build/clamp.js.map +1 -0
- package/build/clamp.spec.d.ts +2 -0
- package/build/clamp.spec.d.ts.map +1 -0
- package/build/clamp.spec.js +19 -0
- package/build/clamp.spec.js.map +1 -0
- package/build/documentation-validation.spec.d.ts +11 -0
- package/build/documentation-validation.spec.d.ts.map +1 -0
- package/build/documentation-validation.spec.js +401 -0
- package/build/documentation-validation.spec.js.map +1 -0
- package/build/index.d.ts +8 -0
- package/build/index.d.ts.map +1 -0
- package/build/index.js +8 -0
- package/build/index.js.map +1 -0
- package/build/interpolation.d.ts +175 -0
- package/build/interpolation.d.ts.map +1 -0
- package/build/interpolation.js +369 -0
- package/build/interpolation.js.map +1 -0
- package/build/interpolation.spec.d.ts +2 -0
- package/build/interpolation.spec.d.ts.map +1 -0
- package/build/interpolation.spec.js +480 -0
- package/build/interpolation.spec.js.map +1 -0
- package/build/matrices/arithmetic.d.ts +411 -0
- package/build/matrices/arithmetic.d.ts.map +1 -0
- package/build/matrices/arithmetic.js +954 -0
- package/build/matrices/arithmetic.js.map +1 -0
- package/build/matrices/arithmetic.spec.d.ts +2 -0
- package/build/matrices/arithmetic.spec.d.ts.map +1 -0
- package/build/matrices/arithmetic.spec.js +915 -0
- package/build/matrices/arithmetic.spec.js.map +1 -0
- package/build/matrices/asserts.d.ts +306 -0
- package/build/matrices/asserts.d.ts.map +1 -0
- package/build/matrices/asserts.js +396 -0
- package/build/matrices/asserts.js.map +1 -0
- package/build/matrices/asserts.spec.d.ts +2 -0
- package/build/matrices/asserts.spec.d.ts.map +1 -0
- package/build/matrices/asserts.spec.js +565 -0
- package/build/matrices/asserts.spec.js.map +1 -0
- package/build/matrices/core.d.ts +168 -0
- package/build/matrices/core.d.ts.map +1 -0
- package/build/matrices/core.js +457 -0
- package/build/matrices/core.js.map +1 -0
- package/build/matrices/core.spec.d.ts +2 -0
- package/build/matrices/core.spec.d.ts.map +1 -0
- package/build/matrices/core.spec.js +634 -0
- package/build/matrices/core.spec.js.map +1 -0
- package/build/matrices/decompositions.d.ts +326 -0
- package/build/matrices/decompositions.d.ts.map +1 -0
- package/build/matrices/decompositions.js +816 -0
- package/build/matrices/decompositions.js.map +1 -0
- package/build/matrices/decompositions.spec.d.ts +2 -0
- package/build/matrices/decompositions.spec.d.ts.map +1 -0
- package/build/matrices/decompositions.spec.js +195 -0
- package/build/matrices/decompositions.spec.js.map +1 -0
- package/build/matrices/index.d.ts +9 -0
- package/build/matrices/index.d.ts.map +1 -0
- package/build/matrices/index.js +9 -0
- package/build/matrices/index.js.map +1 -0
- package/build/matrices/linear-algebra.d.ts +64 -0
- package/build/matrices/linear-algebra.d.ts.map +1 -0
- package/build/matrices/linear-algebra.js +253 -0
- package/build/matrices/linear-algebra.js.map +1 -0
- package/build/matrices/linear-algebra.spec.d.ts +2 -0
- package/build/matrices/linear-algebra.spec.d.ts.map +1 -0
- package/build/matrices/linear-algebra.spec.js +355 -0
- package/build/matrices/linear-algebra.spec.js.map +1 -0
- package/build/matrices/normalization.d.ts +62 -0
- package/build/matrices/normalization.d.ts.map +1 -0
- package/build/matrices/normalization.js +167 -0
- package/build/matrices/normalization.js.map +1 -0
- package/build/matrices/normalization.spec.d.ts +2 -0
- package/build/matrices/normalization.spec.d.ts.map +1 -0
- package/build/matrices/normalization.spec.js +335 -0
- package/build/matrices/normalization.spec.js.map +1 -0
- package/build/matrices/transformations.d.ts +484 -0
- package/build/matrices/transformations.d.ts.map +1 -0
- package/build/matrices/transformations.js +592 -0
- package/build/matrices/transformations.js.map +1 -0
- package/build/matrices/transformations.spec.d.ts +2 -0
- package/build/matrices/transformations.spec.d.ts.map +1 -0
- package/build/matrices/transformations.spec.js +755 -0
- package/build/matrices/transformations.spec.js.map +1 -0
- package/build/matrices/types.d.ts +134 -0
- package/build/matrices/types.d.ts.map +1 -0
- package/build/matrices/types.js +6 -0
- package/build/matrices/types.js.map +1 -0
- package/build/quaternions/asserts.d.ts +77 -0
- package/build/quaternions/asserts.d.ts.map +1 -0
- package/build/quaternions/asserts.js +175 -0
- package/build/quaternions/asserts.js.map +1 -0
- package/build/quaternions/asserts.spec.d.ts +2 -0
- package/build/quaternions/asserts.spec.d.ts.map +1 -0
- package/build/quaternions/asserts.spec.js +320 -0
- package/build/quaternions/asserts.spec.js.map +1 -0
- package/build/quaternions/conversions.d.ts +73 -0
- package/build/quaternions/conversions.d.ts.map +1 -0
- package/build/quaternions/conversions.js +179 -0
- package/build/quaternions/conversions.js.map +1 -0
- package/build/quaternions/conversions.spec.d.ts +2 -0
- package/build/quaternions/conversions.spec.d.ts.map +1 -0
- package/build/quaternions/conversions.spec.js +344 -0
- package/build/quaternions/conversions.spec.js.map +1 -0
- package/build/quaternions/core.d.ts +203 -0
- package/build/quaternions/core.d.ts.map +1 -0
- package/build/quaternions/core.js +374 -0
- package/build/quaternions/core.js.map +1 -0
- package/build/quaternions/core.spec.d.ts +2 -0
- package/build/quaternions/core.spec.d.ts.map +1 -0
- package/build/quaternions/core.spec.js +294 -0
- package/build/quaternions/core.spec.js.map +1 -0
- package/build/quaternions/index.d.ts +7 -0
- package/build/quaternions/index.d.ts.map +1 -0
- package/build/quaternions/index.js +7 -0
- package/build/quaternions/index.js.map +1 -0
- package/build/quaternions/interpolation.d.ts +54 -0
- package/build/quaternions/interpolation.d.ts.map +1 -0
- package/build/quaternions/interpolation.js +201 -0
- package/build/quaternions/interpolation.js.map +1 -0
- package/build/quaternions/interpolation.spec.d.ts +2 -0
- package/build/quaternions/interpolation.spec.d.ts.map +1 -0
- package/build/quaternions/interpolation.spec.js +64 -0
- package/build/quaternions/interpolation.spec.js.map +1 -0
- package/build/quaternions/predefined.d.ts +36 -0
- package/build/quaternions/predefined.d.ts.map +1 -0
- package/build/quaternions/predefined.js +42 -0
- package/build/quaternions/predefined.js.map +1 -0
- package/build/quaternions/predefined.spec.d.ts +2 -0
- package/build/quaternions/predefined.spec.d.ts.map +1 -0
- package/build/quaternions/predefined.spec.js +35 -0
- package/build/quaternions/predefined.spec.js.map +1 -0
- package/build/quaternions/types.d.ts +55 -0
- package/build/quaternions/types.d.ts.map +1 -0
- package/build/quaternions/types.js +7 -0
- package/build/quaternions/types.js.map +1 -0
- package/build/random.d.ts +66 -0
- package/build/random.d.ts.map +1 -0
- package/build/random.js +115 -0
- package/build/random.js.map +1 -0
- package/build/random.spec.d.ts +2 -0
- package/build/random.spec.d.ts.map +1 -0
- package/build/random.spec.js +267 -0
- package/build/random.spec.js.map +1 -0
- package/build/vectors/asserts.d.ts +182 -0
- package/build/vectors/asserts.d.ts.map +1 -0
- package/build/vectors/asserts.js +285 -0
- package/build/vectors/asserts.js.map +1 -0
- package/build/vectors/asserts.spec.d.ts +2 -0
- package/build/vectors/asserts.spec.d.ts.map +1 -0
- package/build/vectors/asserts.spec.js +260 -0
- package/build/vectors/asserts.spec.js.map +1 -0
- package/build/vectors/core.d.ts +507 -0
- package/build/vectors/core.d.ts.map +1 -0
- package/build/vectors/core.js +825 -0
- package/build/vectors/core.js.map +1 -0
- package/build/vectors/core.spec.d.ts +2 -0
- package/build/vectors/core.spec.d.ts.map +1 -0
- package/build/vectors/core.spec.js +343 -0
- package/build/vectors/core.spec.js.map +1 -0
- package/build/vectors/index.d.ts +6 -0
- package/build/vectors/index.d.ts.map +1 -0
- package/build/vectors/index.js +6 -0
- package/build/vectors/index.js.map +1 -0
- package/build/vectors/interpolation.d.ts +404 -0
- package/build/vectors/interpolation.d.ts.map +1 -0
- package/build/vectors/interpolation.js +585 -0
- package/build/vectors/interpolation.js.map +1 -0
- package/build/vectors/interpolation.spec.d.ts +2 -0
- package/build/vectors/interpolation.spec.d.ts.map +1 -0
- package/build/vectors/interpolation.spec.js +378 -0
- package/build/vectors/interpolation.spec.js.map +1 -0
- package/build/vectors/predefined.d.ts +191 -0
- package/build/vectors/predefined.d.ts.map +1 -0
- package/build/vectors/predefined.js +191 -0
- package/build/vectors/predefined.js.map +1 -0
- package/build/vectors/predefined.spec.d.ts +2 -0
- package/build/vectors/predefined.spec.d.ts.map +1 -0
- package/build/vectors/predefined.spec.js +333 -0
- package/build/vectors/predefined.spec.js.map +1 -0
- package/build/vectors/types.d.ts +62 -0
- package/build/vectors/types.d.ts.map +1 -0
- package/build/vectors/types.js +6 -0
- package/build/vectors/types.js.map +1 -0
- package/package.json +75 -0
|
@@ -0,0 +1,411 @@
|
|
|
1
|
+
import { IMatrix, IMatrix1, IMatrix2, IMatrix3, IMatrix4, TMatrixResult } from './types.js';
|
|
2
|
+
import { TVector, TVector2, TVector3, TVector4 } from '../vectors/types.js';
|
|
3
|
+
/**
|
|
4
|
+
* Performs element-wise addition of two matrices.
|
|
5
|
+
*
|
|
6
|
+
* This function implements matrix addition using the standard mathematical definition:
|
|
7
|
+
* `C[i,j] = A[i,j] + B[i,j]` for all valid indices i,j
|
|
8
|
+
*
|
|
9
|
+
* The operation requires both matrices to have identical dimensions and produces
|
|
10
|
+
* a new matrix without modifying the input matrices. Matrix addition is both
|
|
11
|
+
* commutative (A + B = B + A) and associative ((A + B) + C = A + (B + C)).
|
|
12
|
+
*
|
|
13
|
+
* **Properties:**
|
|
14
|
+
* - Commutative: A + B = B + A
|
|
15
|
+
* - Associative: (A + B) + C = A + (B + C)
|
|
16
|
+
* - Identity element: A + 0 = A (where 0 is the zero matrix)
|
|
17
|
+
* - Inverse element: A + (-A) = 0
|
|
18
|
+
*
|
|
19
|
+
* **Time Complexity:** O(m×n) where m and n are the matrix dimensions
|
|
20
|
+
* **Space Complexity:** O(m×n) for the result matrix
|
|
21
|
+
*
|
|
22
|
+
* @template T - The matrix type extending IMatrix interface
|
|
23
|
+
* @param a - First matrix (addend) - must have same dimensions as b
|
|
24
|
+
* @param b - Second matrix (addend) - must have same dimensions as a
|
|
25
|
+
* @returns {TMatrixResult<T>} A new matrix where each element is the sum of corresponding elements
|
|
26
|
+
* @throws {Error} If matrices have different dimensions or contain invalid values
|
|
27
|
+
*
|
|
28
|
+
* @example
|
|
29
|
+
* ```typescript
|
|
30
|
+
* // Adding 2×2 matrices
|
|
31
|
+
* MatrixAdd([[1, 2], [3, 4]], [[5, 6], [7, 8]]) // Returns [[6, 8], [10, 12]]
|
|
32
|
+
*
|
|
33
|
+
* // Adding 1×3 row vectors
|
|
34
|
+
* MatrixAdd([[1, 2, 3]], [[4, 5, 6]]) // Returns [[5, 7, 9]]
|
|
35
|
+
*
|
|
36
|
+
* // Type-safe matrix addition with specific matrix types
|
|
37
|
+
* const matrixA: IMatrix2 = [[1, 2], [3, 4]];
|
|
38
|
+
* const matrixB: IMatrix2 = [[5, 6], [7, 8]];
|
|
39
|
+
* const result: IMatrix2 = MatrixAdd(matrixA, matrixB);
|
|
40
|
+
* ```
|
|
41
|
+
*/
|
|
42
|
+
export declare function MatrixAdd<T extends IMatrix>(a: T, b: T): TMatrixResult<T>;
|
|
43
|
+
/**
|
|
44
|
+
* Performs element-wise subtraction of two matrices (a - b).
|
|
45
|
+
*
|
|
46
|
+
* This function implements matrix subtraction using the standard mathematical definition:
|
|
47
|
+
* `C[i,j] = A[i,j] - B[i,j]` for all valid indices i,j
|
|
48
|
+
*
|
|
49
|
+
* The operation requires both matrices to have identical dimensions and produces
|
|
50
|
+
* a new matrix without modifying the input matrices. Note that matrix subtraction
|
|
51
|
+
* is **not commutative**: A - B ≠ B - A in general.
|
|
52
|
+
*
|
|
53
|
+
* **Properties:**
|
|
54
|
+
* - Non-commutative: A - B ≠ B - A (in general)
|
|
55
|
+
* - Non-associative: (A - B) - C ≠ A - (B - C) (in general)
|
|
56
|
+
* - Relationship to addition: A - B = A + (-B)
|
|
57
|
+
* - Self-subtraction: A - A = 0 (zero matrix)
|
|
58
|
+
*
|
|
59
|
+
* **Time Complexity:** O(m×n) where m and n are the matrix dimensions
|
|
60
|
+
* **Space Complexity:** O(m×n) for the result matrix
|
|
61
|
+
*
|
|
62
|
+
* @template T - The matrix type extending IMatrix interface
|
|
63
|
+
* @param a - First matrix (minuend) - the matrix being subtracted from
|
|
64
|
+
* @param b - Second matrix (subtrahend) - the matrix being subtracted
|
|
65
|
+
* @returns {TMatrixResult<T>} A new matrix where each element is the difference of corresponding elements
|
|
66
|
+
* @throws {Error} If matrices have different dimensions or contain invalid values
|
|
67
|
+
*
|
|
68
|
+
* @example
|
|
69
|
+
* ```typescript
|
|
70
|
+
* // Subtracting 2×2 matrices
|
|
71
|
+
* MatrixSubtract([[10, 8], [6, 4]], [[3, 2], [1, 1]]) // Returns [[7, 6], [5, 3]]
|
|
72
|
+
*
|
|
73
|
+
* // Order matters: A - B ≠ B - A
|
|
74
|
+
* MatrixSubtract([[1, 2]], [[3, 4]]) // Returns [[-2, -2]]
|
|
75
|
+
* MatrixSubtract([[3, 4]], [[1, 2]]) // Returns [[2, 2]]
|
|
76
|
+
*
|
|
77
|
+
* // Self-subtraction produces zero matrix
|
|
78
|
+
* MatrixSubtract([[5, 6]], [[5, 6]]) // Returns [[0, 0]]
|
|
79
|
+
* ```
|
|
80
|
+
*/
|
|
81
|
+
export declare function MatrixSubtract<T extends IMatrix>(a: T, b: T): TMatrixResult<T>;
|
|
82
|
+
/**
|
|
83
|
+
* Performs matrix multiplication with comprehensive type-safe overloads for matrices, vectors, and scalars.
|
|
84
|
+
*
|
|
85
|
+
* This function serves as a smart dispatcher that automatically routes to the most
|
|
86
|
+
* appropriate multiplication algorithm based on the type and characteristics of the
|
|
87
|
+
* second operand. The function provides extensive overloaded signatures for complete
|
|
88
|
+
* type safety and optimal performance across different operation types and matrix sizes.
|
|
89
|
+
*
|
|
90
|
+
* **Type-Safe Overloads:**
|
|
91
|
+
* - **Scalar Multiplication:**
|
|
92
|
+
* - `IMatrix1 × number → IMatrix1` (1×1 matrix scalar multiplication)
|
|
93
|
+
* - `IMatrix2 × number → IMatrix2` (2×2 matrix scalar multiplication)
|
|
94
|
+
* - `IMatrix3 × number → IMatrix3` (3×3 matrix scalar multiplication)
|
|
95
|
+
* - `IMatrix4 × number → IMatrix4` (4×4 matrix scalar multiplication)
|
|
96
|
+
* - `IMatrix × number → IMatrix` (general matrix scalar multiplication)
|
|
97
|
+
*
|
|
98
|
+
* - **Vector Multiplication:**
|
|
99
|
+
* - `IMatrix2 × TVector2 → TVector2` (2×2 matrix × 2D vector)
|
|
100
|
+
* - `IMatrix3 × TVector3 → TVector3` (3×3 matrix × 3D vector)
|
|
101
|
+
* - `IMatrix4 × TVector4 → TVector4` (4×4 matrix × 4D vector)
|
|
102
|
+
* - `IMatrix × TVector → TVector` (general matrix × vector)
|
|
103
|
+
*
|
|
104
|
+
* - **Matrix Multiplication:**
|
|
105
|
+
* - `IMatrix1 × IMatrix1 → IMatrix1` (1×1 matrix multiplication)
|
|
106
|
+
* - `IMatrix2 × IMatrix2 → IMatrix2` (2×2 matrix multiplication)
|
|
107
|
+
* - `IMatrix3 × IMatrix3 → IMatrix3` (3×3 matrix multiplication)
|
|
108
|
+
* - `IMatrix4 × IMatrix4 → IMatrix4` (4×4 matrix multiplication)
|
|
109
|
+
* - `IMatrix × IMatrix → IMatrix` (general matrix multiplication)
|
|
110
|
+
*
|
|
111
|
+
* **Operation Types:**
|
|
112
|
+
* - **Matrix × Scalar:** Element-wise multiplication by scalar value
|
|
113
|
+
* - **Matrix × Vector:** Matrix-vector multiplication producing a column vector
|
|
114
|
+
* - **Matrix × Matrix:** Full matrix multiplication with algorithm optimization
|
|
115
|
+
*
|
|
116
|
+
* **Algorithm Selection (for matrix-matrix multiplication):**
|
|
117
|
+
* - 1×1 to 4×4 square matrices: Hardcoded optimized formulas
|
|
118
|
+
* - Large square matrices (≥32×32): Strassen's algorithm O(n^2.807)
|
|
119
|
+
* - All other cases: Standard algorithm O(n³)
|
|
120
|
+
*
|
|
121
|
+
* **Mathematical Properties:**
|
|
122
|
+
* - Matrix multiplication is associative: (AB)C = A(BC)
|
|
123
|
+
* - Matrix multiplication is generally not commutative: AB ≠ BA
|
|
124
|
+
* - Scalar multiplication is commutative: kA = Ak
|
|
125
|
+
* - Distributive over addition: A(B + C) = AB + AC
|
|
126
|
+
*
|
|
127
|
+
* @param a - First matrix (left operand) with dimensions m×n
|
|
128
|
+
* @param b - Second operand: matrix (n×p), vector (n elements), or scalar number
|
|
129
|
+
* @returns {IMatrix | TVector} The product result:
|
|
130
|
+
* - For scalar: m×n matrix with each element multiplied by scalar
|
|
131
|
+
* - For vector: m×1 column vector matrix
|
|
132
|
+
* - For matrix: m×p product matrix
|
|
133
|
+
* @throws {Error} If matrix dimensions are incompatible for multiplication
|
|
134
|
+
*
|
|
135
|
+
* @example
|
|
136
|
+
* ```typescript
|
|
137
|
+
* // Type-safe scalar multiplication with specific matrix types
|
|
138
|
+
* const matrix2: IMatrix2 = [[1, 2], [3, 4]];
|
|
139
|
+
* const scalar2Result: IMatrix2 = MatrixMultiply(matrix2, 2); // [[2, 4], [6, 8]]
|
|
140
|
+
*
|
|
141
|
+
* const matrix3: IMatrix3 = [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
|
|
142
|
+
* const scalar3Result: IMatrix3 = MatrixMultiply(matrix3, 5); // Identity × 5
|
|
143
|
+
*
|
|
144
|
+
* // Type-safe vector multiplication with specific matrix/vector types
|
|
145
|
+
* const matrix2x2: IMatrix2 = [[1, 2], [3, 4]];
|
|
146
|
+
* const vector2: TVector2 = [5, 6];
|
|
147
|
+
* const vectorResult: TVector2 = MatrixMultiply(matrix2x2, vector2); // [17, 39]
|
|
148
|
+
*
|
|
149
|
+
* const matrix4x4: IMatrix4 = [[1,0,0,0], [0,1,0,0], [0,0,1,0], [0,0,0,1]];
|
|
150
|
+
* const vector4: TVector4 = [1, 2, 3, 4];
|
|
151
|
+
* const vector4Result: TVector4 = MatrixMultiply(matrix4x4, vector4); // [1, 2, 3, 4]
|
|
152
|
+
*
|
|
153
|
+
* // Type-safe matrix multiplication with specific matrix types
|
|
154
|
+
* const matrixA: IMatrix2 = [[1, 2], [3, 4]];
|
|
155
|
+
* const matrixB: IMatrix2 = [[5, 6], [7, 8]];
|
|
156
|
+
* const matrixResult: IMatrix2 = MatrixMultiply(matrixA, matrixB); // [[19, 22], [43, 50]]
|
|
157
|
+
*
|
|
158
|
+
* // General matrix operations (fallback to generic types)
|
|
159
|
+
* MatrixMultiply([[1, 2]], [[3], [4]]) // Returns [[11]]
|
|
160
|
+
* MatrixMultiply([[1], [2]], [[3, 4]]) // Returns [[3, 4], [6, 8]]
|
|
161
|
+
*
|
|
162
|
+
* // Type detection is automatic - no need to specify operation type
|
|
163
|
+
* const scalarResult = MatrixMultiply(matrixA, 5); // Scalar multiplication
|
|
164
|
+
* const vectorResult2 = MatrixMultiply(matrixA, vector2); // Vector multiplication
|
|
165
|
+
* const matrixResult2 = MatrixMultiply(matrixA, matrixB); // Matrix multiplication
|
|
166
|
+
* ```
|
|
167
|
+
*/
|
|
168
|
+
export declare function MatrixMultiply(a: IMatrix1, b: number): IMatrix1;
|
|
169
|
+
export declare function MatrixMultiply(a: IMatrix2, b: number): IMatrix2;
|
|
170
|
+
export declare function MatrixMultiply(a: IMatrix3, b: number): IMatrix3;
|
|
171
|
+
export declare function MatrixMultiply(a: IMatrix4, b: number): IMatrix4;
|
|
172
|
+
export declare function MatrixMultiply(a: IMatrix2, b: TVector2): TVector2;
|
|
173
|
+
export declare function MatrixMultiply(a: IMatrix3, b: TVector3): TVector3;
|
|
174
|
+
export declare function MatrixMultiply(a: IMatrix4, b: TVector4): TVector4;
|
|
175
|
+
export declare function MatrixMultiply(a: IMatrix1, b: IMatrix1): IMatrix1;
|
|
176
|
+
export declare function MatrixMultiply(a: IMatrix2, b: IMatrix2): IMatrix2;
|
|
177
|
+
export declare function MatrixMultiply(a: IMatrix3, b: IMatrix3): IMatrix3;
|
|
178
|
+
export declare function MatrixMultiply(a: IMatrix4, b: IMatrix4): IMatrix4;
|
|
179
|
+
export declare function MatrixMultiply(a: IMatrix, b: TVector): TVector;
|
|
180
|
+
export declare function MatrixMultiply(a: IMatrix, b: IMatrix): IMatrix;
|
|
181
|
+
export declare function MatrixMultiply(a: IMatrix, b: number): IMatrix;
|
|
182
|
+
/**
|
|
183
|
+
* Extracts a rectangular submatrix from a larger matrix.
|
|
184
|
+
*
|
|
185
|
+
* This function creates a new matrix containing a specified rectangular region from
|
|
186
|
+
* the source matrix. It performs a deep copy of the selected elements, ensuring the
|
|
187
|
+
* original matrix remains unmodified. This operation is fundamental for matrix
|
|
188
|
+
* partitioning algorithms, block operations, and data analysis workflows.
|
|
189
|
+
*
|
|
190
|
+
* Coordinate System:
|
|
191
|
+
* - startRow, startCol: Top-left corner of the extraction region (0-based, inclusive)
|
|
192
|
+
* - width, height: Dimensions of the region to extract
|
|
193
|
+
* - Extraction bounds: [startRow, startRow+height) × [startCol, startCol+width)
|
|
194
|
+
*
|
|
195
|
+
* NOTE: parameter order is (startCol, startRow) — reversed from typical convention
|
|
196
|
+
*
|
|
197
|
+
* Applications:
|
|
198
|
+
* - Block matrix algorithms (Strassen, block LU decomposition)
|
|
199
|
+
* - Image processing (extracting regions of interest)
|
|
200
|
+
* - Data analysis (extracting subsets of datasets)
|
|
201
|
+
* - Sparse matrix operations (extracting dense blocks)
|
|
202
|
+
* - Machine learning (feature selection, data windowing)
|
|
203
|
+
*
|
|
204
|
+
* Bounds Checking:
|
|
205
|
+
* - Validates that extraction region fits within source matrix
|
|
206
|
+
* - Ensures all parameters are non-negative integers
|
|
207
|
+
* - Checks for valid matrix structure and element values
|
|
208
|
+
*
|
|
209
|
+
* Memory Efficiency:
|
|
210
|
+
* - Creates new matrix with minimal required size
|
|
211
|
+
* - Performs element-by-element copying with validation
|
|
212
|
+
* - No unnecessary memory allocation or copying
|
|
213
|
+
*
|
|
214
|
+
* Time Complexity: O(width × height) - linear in extracted region size
|
|
215
|
+
* Space Complexity: O(width × height) - size of extracted submatrix
|
|
216
|
+
*
|
|
217
|
+
* @param matrix - Source matrix to extract from
|
|
218
|
+
* @param startCol - Starting column index (0-based, inclusive) — note reversed order
|
|
219
|
+
* @param startRow - Starting row index (0-based, inclusive) — note reversed order
|
|
220
|
+
* @param width - Number of columns to extract (must be positive)
|
|
221
|
+
* @param height - Number of rows to extract (must be positive)
|
|
222
|
+
* @returns {IMatrix} The extracted submatrix with dimensions height×width
|
|
223
|
+
* @throws {Error} If extraction bounds exceed matrix dimensions or contain invalid values
|
|
224
|
+
* @example
|
|
225
|
+
* ```typescript
|
|
226
|
+
* const matrix = [
|
|
227
|
+
* [1, 2, 3, 4],
|
|
228
|
+
* [5, 6, 7, 8],
|
|
229
|
+
* [9, 10, 11, 12]
|
|
230
|
+
* ]; // 3×4 matrix
|
|
231
|
+
*
|
|
232
|
+
* // Extract 2×2 submatrix from top-left corner
|
|
233
|
+
* MatrixSubmatrix(matrix, 0, 0, 2, 2) // Returns [[1, 2], [5, 6]]
|
|
234
|
+
*
|
|
235
|
+
* // Extract 2×2 submatrix from center-right region
|
|
236
|
+
* MatrixSubmatrix(matrix, 2, 1, 2, 2) // Returns [[7, 8], [11, 12]]
|
|
237
|
+
*
|
|
238
|
+
* // Extract single column (column vector)
|
|
239
|
+
* MatrixSubmatrix(matrix, 1, 0, 1, 3) // Returns [[2], [6], [10]]
|
|
240
|
+
*
|
|
241
|
+
* // Extract single row (row vector)
|
|
242
|
+
* MatrixSubmatrix(matrix, 0, 1, 4, 1) // Returns [[5, 6, 7, 8]]
|
|
243
|
+
*
|
|
244
|
+
* // Block matrix partitioning for algorithms
|
|
245
|
+
* const large = MatrixCreate(8, 8); // 8×8 matrix
|
|
246
|
+
* const topLeft = MatrixSubmatrix(large, 0, 0, 4, 4); // Top-left 4×4 block
|
|
247
|
+
* const topRight = MatrixSubmatrix(large, 4, 0, 4, 4); // Top-right 4×4 block
|
|
248
|
+
* const bottomLeft = MatrixSubmatrix(large, 0, 4, 4, 4); // Bottom-left 4×4 block
|
|
249
|
+
* const bottomRight = MatrixSubmatrix(large, 4, 4, 4, 4); // Bottom-right 4×4 block
|
|
250
|
+
* ```
|
|
251
|
+
*/
|
|
252
|
+
export declare function MatrixSubmatrix(matrix: IMatrix, startCol: number, startRow: number, width: number, height: number): IMatrix;
|
|
253
|
+
/**
|
|
254
|
+
* Pads a matrix with zeros to reach the specified dimensions.
|
|
255
|
+
*
|
|
256
|
+
* This function extends a matrix by adding rows and/or columns filled with zeros,
|
|
257
|
+
* preserving the original matrix content in the top-left corner. This operation
|
|
258
|
+
* is essential for algorithms that require matrices of specific sizes or when
|
|
259
|
+
* preparing matrices for operations that need dimension alignment.
|
|
260
|
+
*
|
|
261
|
+
* Padding Strategy:
|
|
262
|
+
* - Original content remains in top-left corner at [0,0]
|
|
263
|
+
* - Additional rows/columns are filled with zeros
|
|
264
|
+
* - New dimensions must be greater than or equal to current dimensions
|
|
265
|
+
* - Supports both symmetric and asymmetric padding
|
|
266
|
+
*
|
|
267
|
+
* Common Use Cases:
|
|
268
|
+
* - Algorithm requirements (power-of-2 sizes for FFT-based algorithms)
|
|
269
|
+
* - Block matrix operations (ensuring uniform block sizes)
|
|
270
|
+
* - Strassen algorithm (handling odd-sized matrices)
|
|
271
|
+
* - Image processing (border padding for convolution operations)
|
|
272
|
+
* - Signal processing (zero-padding for frequency domain analysis)
|
|
273
|
+
* - Machine learning (batch size alignment, tensor operations)
|
|
274
|
+
*
|
|
275
|
+
* Padding Preservation Property:
|
|
276
|
+
* If A is the original matrix and A' is the padded matrix, then:
|
|
277
|
+
* A'[i,j] = A[i,j] for all valid i,j in A
|
|
278
|
+
* A'[i,j] = 0 for all other positions
|
|
279
|
+
*
|
|
280
|
+
* Memory Efficiency:
|
|
281
|
+
* - Creates new matrix only of the target size
|
|
282
|
+
* - Copies only existing elements (no redundant operations)
|
|
283
|
+
* - Zero-fills remaining positions efficiently
|
|
284
|
+
*
|
|
285
|
+
* Time Complexity: O(newRows × newCols) - must initialize entire new matrix
|
|
286
|
+
* Space Complexity: O(newRows × newCols) - size of padded result
|
|
287
|
+
*
|
|
288
|
+
* @param matrix - Source matrix to pad
|
|
289
|
+
* @param newRows - Target number of rows (must be ≥ current rows)
|
|
290
|
+
* @param newCols - Target number of columns (must be ≥ current columns)
|
|
291
|
+
* @returns {IMatrix} The padded matrix with dimensions newRows×newCols
|
|
292
|
+
* @throws {Error} If new dimensions are smaller than current dimensions
|
|
293
|
+
* @example
|
|
294
|
+
* ```typescript
|
|
295
|
+
* const matrix = [[1, 2], [3, 4]]; // 2×2 matrix
|
|
296
|
+
*
|
|
297
|
+
* // Pad to 4×4 matrix (symmetric padding)
|
|
298
|
+
* MatrixPad(matrix, 4, 4)
|
|
299
|
+
* // Returns:
|
|
300
|
+
* // [[1, 2, 0, 0],
|
|
301
|
+
* // [3, 4, 0, 0],
|
|
302
|
+
* // [0, 0, 0, 0],
|
|
303
|
+
* // [0, 0, 0, 0]]
|
|
304
|
+
*
|
|
305
|
+
* // Pad to 3×4 matrix (asymmetric padding)
|
|
306
|
+
* MatrixPad(matrix, 3, 4)
|
|
307
|
+
* // Returns:
|
|
308
|
+
* // [[1, 2, 0, 0],
|
|
309
|
+
* // [3, 4, 0, 0],
|
|
310
|
+
* // [0, 0, 0, 0]]
|
|
311
|
+
*
|
|
312
|
+
* // Prepare for power-of-2 algorithm (e.g., FFT-based convolution)
|
|
313
|
+
* const data = [[1, 2, 3], [4, 5, 6]]; // 2×3 matrix
|
|
314
|
+
* const powerOf2 = MatrixPad(data, 4, 4); // Pad to 4×4 for FFT
|
|
315
|
+
*
|
|
316
|
+
* // Batch size alignment in machine learning
|
|
317
|
+
* const features = MatrixCreate(7, 10); // 7 samples, 10 features
|
|
318
|
+
* const aligned = MatrixPad(features, 8, 10); // Align to batch size 8
|
|
319
|
+
*
|
|
320
|
+
* // Image border padding for convolution
|
|
321
|
+
* const image = MatrixCreate(28, 28); // 28×28 image
|
|
322
|
+
* const padded = MatrixPad(image, 32, 32); // Add border for valid convolution
|
|
323
|
+
* ```
|
|
324
|
+
*/
|
|
325
|
+
export declare function MatrixPad(matrix: IMatrix, newRows: number, newCols: number): IMatrix;
|
|
326
|
+
/**
|
|
327
|
+
* Combines four square submatrices into a single matrix (2×2 block structure).
|
|
328
|
+
*
|
|
329
|
+
* This function reconstructs a larger matrix from four quadrant submatrices using
|
|
330
|
+
* a 2×2 block structure. It serves as the inverse operation of matrix partitioning
|
|
331
|
+
* and is essential for divide-and-conquer algorithms like Strassen multiplication,
|
|
332
|
+
* block matrix operations, and hierarchical matrix constructions.
|
|
333
|
+
*
|
|
334
|
+
* **Block Matrix Structure:**
|
|
335
|
+
* ```
|
|
336
|
+
* Result = [C11 C12] where each Cij is an n×n submatrix
|
|
337
|
+
* [C21 C22]
|
|
338
|
+
* ```
|
|
339
|
+
*
|
|
340
|
+
* The resulting matrix has dimensions 2n×2n when each input quadrant is n×n.
|
|
341
|
+
*
|
|
342
|
+
* **Quadrant Placement:**
|
|
343
|
+
* - c11 (top-left): positioned at [0:n, 0:n]
|
|
344
|
+
* - c12 (top-right): positioned at [0:n, n:2n]
|
|
345
|
+
* - c21 (bottom-left): positioned at [n:2n, 0:n]
|
|
346
|
+
* - c22 (bottom-right): positioned at [n:2n, n:2n]
|
|
347
|
+
*
|
|
348
|
+
* **Applications:**
|
|
349
|
+
* - Strassen algorithm result reconstruction
|
|
350
|
+
* - Block matrix operations and algebra
|
|
351
|
+
* - Hierarchical matrix assembly (multigrid methods)
|
|
352
|
+
* - Sparse matrix construction from dense blocks
|
|
353
|
+
* - Parallel matrix computation result merging
|
|
354
|
+
* - Image processing (combining processed image quadrants)
|
|
355
|
+
* - Scientific computing (domain decomposition methods)
|
|
356
|
+
*
|
|
357
|
+
* **Validation Requirements:**
|
|
358
|
+
* - All four input matrices must be square
|
|
359
|
+
* - All four input matrices must have identical dimensions
|
|
360
|
+
* - All elements must be valid numbers
|
|
361
|
+
* - No null or undefined matrices allowed
|
|
362
|
+
*
|
|
363
|
+
* **Memory Layout:**
|
|
364
|
+
* The function performs efficient copying by iterating through each quadrant
|
|
365
|
+
* sequentially, minimizing cache misses and ensuring optimal memory access patterns.
|
|
366
|
+
*
|
|
367
|
+
* **Time Complexity:** O(n²) where n is the dimension of each input quadrant
|
|
368
|
+
* **Space Complexity:** O(4n²) for the combined result matrix
|
|
369
|
+
*
|
|
370
|
+
* @param c11 - Top-left quadrant (upper-left block)
|
|
371
|
+
* @param c12 - Top-right quadrant (upper-right block)
|
|
372
|
+
* @param c21 - Bottom-left quadrant (lower-left block)
|
|
373
|
+
* @param c22 - Bottom-right quadrant (lower-right block)
|
|
374
|
+
* @returns {IMatrix} The combined matrix with dimensions 2n×2n (where each input is n×n)
|
|
375
|
+
* @throws {Error} If quadrants have mismatched dimensions or invalid values
|
|
376
|
+
*
|
|
377
|
+
* @example
|
|
378
|
+
* ```typescript
|
|
379
|
+
* // Basic 2×2 quadrant combination
|
|
380
|
+
* const topLeft = [[1, 2], [3, 4]];
|
|
381
|
+
* const topRight = [[5, 6], [7, 8]];
|
|
382
|
+
* const bottomLeft = [[9, 10], [11, 12]];
|
|
383
|
+
* const bottomRight = [[13, 14], [15, 16]];
|
|
384
|
+
*
|
|
385
|
+
* MatrixCombine(topLeft, topRight, bottomLeft, bottomRight)
|
|
386
|
+
* // Returns:
|
|
387
|
+
* // [[1, 2, 5, 6],
|
|
388
|
+
* // [3, 4, 7, 8],
|
|
389
|
+
* // [9, 10, 13, 14],
|
|
390
|
+
* // [11,12, 15, 16]]
|
|
391
|
+
*
|
|
392
|
+
* // Strassen algorithm result reconstruction
|
|
393
|
+
* const m1 = computeStrassenProduct1(); // Computed Strassen intermediate results
|
|
394
|
+
* const m2 = computeStrassenProduct2();
|
|
395
|
+
* const m3 = computeStrassenProduct3();
|
|
396
|
+
* const m4 = computeStrassenProduct4();
|
|
397
|
+
* const finalResult = MatrixCombine(m1, m2, m3, m4); // Assemble final result
|
|
398
|
+
*
|
|
399
|
+
* // Image processing: combining processed quadrants
|
|
400
|
+
* const processedTopLeft = processImageQuadrant(imageTopLeft);
|
|
401
|
+
* const processedTopRight = processImageQuadrant(imageTopRight);
|
|
402
|
+
* const processedBottomLeft = processImageQuadrant(imageBottomLeft);
|
|
403
|
+
* const processedBottomRight = processImageQuadrant(imageBottomRight);
|
|
404
|
+
* const reconstructedImage = MatrixCombine(
|
|
405
|
+
* processedTopLeft, processedTopRight,
|
|
406
|
+
* processedBottomLeft, processedBottomRight
|
|
407
|
+
* );
|
|
408
|
+
* ```
|
|
409
|
+
*/
|
|
410
|
+
export declare function MatrixCombine(c11: IMatrix, c12: IMatrix, c21: IMatrix, c22: IMatrix): IMatrix;
|
|
411
|
+
//# sourceMappingURL=arithmetic.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"arithmetic.d.ts","sourceRoot":"","sources":["../../src/matrices/arithmetic.ts"],"names":[],"mappings":"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"}
|