@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.
Files changed (195) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +319 -0
  3. package/build/angles.d.ts +31 -0
  4. package/build/angles.d.ts.map +1 -0
  5. package/build/angles.js +85 -0
  6. package/build/angles.js.map +1 -0
  7. package/build/angles.spec.d.ts +2 -0
  8. package/build/angles.spec.d.ts.map +1 -0
  9. package/build/angles.spec.js +147 -0
  10. package/build/angles.spec.js.map +1 -0
  11. package/build/clamp.d.ts +17 -0
  12. package/build/clamp.d.ts.map +1 -0
  13. package/build/clamp.js +19 -0
  14. package/build/clamp.js.map +1 -0
  15. package/build/clamp.spec.d.ts +2 -0
  16. package/build/clamp.spec.d.ts.map +1 -0
  17. package/build/clamp.spec.js +19 -0
  18. package/build/clamp.spec.js.map +1 -0
  19. package/build/documentation-validation.spec.d.ts +11 -0
  20. package/build/documentation-validation.spec.d.ts.map +1 -0
  21. package/build/documentation-validation.spec.js +401 -0
  22. package/build/documentation-validation.spec.js.map +1 -0
  23. package/build/index.d.ts +8 -0
  24. package/build/index.d.ts.map +1 -0
  25. package/build/index.js +8 -0
  26. package/build/index.js.map +1 -0
  27. package/build/interpolation.d.ts +175 -0
  28. package/build/interpolation.d.ts.map +1 -0
  29. package/build/interpolation.js +369 -0
  30. package/build/interpolation.js.map +1 -0
  31. package/build/interpolation.spec.d.ts +2 -0
  32. package/build/interpolation.spec.d.ts.map +1 -0
  33. package/build/interpolation.spec.js +480 -0
  34. package/build/interpolation.spec.js.map +1 -0
  35. package/build/matrices/arithmetic.d.ts +411 -0
  36. package/build/matrices/arithmetic.d.ts.map +1 -0
  37. package/build/matrices/arithmetic.js +954 -0
  38. package/build/matrices/arithmetic.js.map +1 -0
  39. package/build/matrices/arithmetic.spec.d.ts +2 -0
  40. package/build/matrices/arithmetic.spec.d.ts.map +1 -0
  41. package/build/matrices/arithmetic.spec.js +915 -0
  42. package/build/matrices/arithmetic.spec.js.map +1 -0
  43. package/build/matrices/asserts.d.ts +306 -0
  44. package/build/matrices/asserts.d.ts.map +1 -0
  45. package/build/matrices/asserts.js +396 -0
  46. package/build/matrices/asserts.js.map +1 -0
  47. package/build/matrices/asserts.spec.d.ts +2 -0
  48. package/build/matrices/asserts.spec.d.ts.map +1 -0
  49. package/build/matrices/asserts.spec.js +565 -0
  50. package/build/matrices/asserts.spec.js.map +1 -0
  51. package/build/matrices/core.d.ts +168 -0
  52. package/build/matrices/core.d.ts.map +1 -0
  53. package/build/matrices/core.js +457 -0
  54. package/build/matrices/core.js.map +1 -0
  55. package/build/matrices/core.spec.d.ts +2 -0
  56. package/build/matrices/core.spec.d.ts.map +1 -0
  57. package/build/matrices/core.spec.js +634 -0
  58. package/build/matrices/core.spec.js.map +1 -0
  59. package/build/matrices/decompositions.d.ts +326 -0
  60. package/build/matrices/decompositions.d.ts.map +1 -0
  61. package/build/matrices/decompositions.js +816 -0
  62. package/build/matrices/decompositions.js.map +1 -0
  63. package/build/matrices/decompositions.spec.d.ts +2 -0
  64. package/build/matrices/decompositions.spec.d.ts.map +1 -0
  65. package/build/matrices/decompositions.spec.js +195 -0
  66. package/build/matrices/decompositions.spec.js.map +1 -0
  67. package/build/matrices/index.d.ts +9 -0
  68. package/build/matrices/index.d.ts.map +1 -0
  69. package/build/matrices/index.js +9 -0
  70. package/build/matrices/index.js.map +1 -0
  71. package/build/matrices/linear-algebra.d.ts +64 -0
  72. package/build/matrices/linear-algebra.d.ts.map +1 -0
  73. package/build/matrices/linear-algebra.js +253 -0
  74. package/build/matrices/linear-algebra.js.map +1 -0
  75. package/build/matrices/linear-algebra.spec.d.ts +2 -0
  76. package/build/matrices/linear-algebra.spec.d.ts.map +1 -0
  77. package/build/matrices/linear-algebra.spec.js +355 -0
  78. package/build/matrices/linear-algebra.spec.js.map +1 -0
  79. package/build/matrices/normalization.d.ts +62 -0
  80. package/build/matrices/normalization.d.ts.map +1 -0
  81. package/build/matrices/normalization.js +167 -0
  82. package/build/matrices/normalization.js.map +1 -0
  83. package/build/matrices/normalization.spec.d.ts +2 -0
  84. package/build/matrices/normalization.spec.d.ts.map +1 -0
  85. package/build/matrices/normalization.spec.js +335 -0
  86. package/build/matrices/normalization.spec.js.map +1 -0
  87. package/build/matrices/transformations.d.ts +484 -0
  88. package/build/matrices/transformations.d.ts.map +1 -0
  89. package/build/matrices/transformations.js +592 -0
  90. package/build/matrices/transformations.js.map +1 -0
  91. package/build/matrices/transformations.spec.d.ts +2 -0
  92. package/build/matrices/transformations.spec.d.ts.map +1 -0
  93. package/build/matrices/transformations.spec.js +755 -0
  94. package/build/matrices/transformations.spec.js.map +1 -0
  95. package/build/matrices/types.d.ts +134 -0
  96. package/build/matrices/types.d.ts.map +1 -0
  97. package/build/matrices/types.js +6 -0
  98. package/build/matrices/types.js.map +1 -0
  99. package/build/quaternions/asserts.d.ts +77 -0
  100. package/build/quaternions/asserts.d.ts.map +1 -0
  101. package/build/quaternions/asserts.js +175 -0
  102. package/build/quaternions/asserts.js.map +1 -0
  103. package/build/quaternions/asserts.spec.d.ts +2 -0
  104. package/build/quaternions/asserts.spec.d.ts.map +1 -0
  105. package/build/quaternions/asserts.spec.js +320 -0
  106. package/build/quaternions/asserts.spec.js.map +1 -0
  107. package/build/quaternions/conversions.d.ts +73 -0
  108. package/build/quaternions/conversions.d.ts.map +1 -0
  109. package/build/quaternions/conversions.js +179 -0
  110. package/build/quaternions/conversions.js.map +1 -0
  111. package/build/quaternions/conversions.spec.d.ts +2 -0
  112. package/build/quaternions/conversions.spec.d.ts.map +1 -0
  113. package/build/quaternions/conversions.spec.js +344 -0
  114. package/build/quaternions/conversions.spec.js.map +1 -0
  115. package/build/quaternions/core.d.ts +203 -0
  116. package/build/quaternions/core.d.ts.map +1 -0
  117. package/build/quaternions/core.js +374 -0
  118. package/build/quaternions/core.js.map +1 -0
  119. package/build/quaternions/core.spec.d.ts +2 -0
  120. package/build/quaternions/core.spec.d.ts.map +1 -0
  121. package/build/quaternions/core.spec.js +294 -0
  122. package/build/quaternions/core.spec.js.map +1 -0
  123. package/build/quaternions/index.d.ts +7 -0
  124. package/build/quaternions/index.d.ts.map +1 -0
  125. package/build/quaternions/index.js +7 -0
  126. package/build/quaternions/index.js.map +1 -0
  127. package/build/quaternions/interpolation.d.ts +54 -0
  128. package/build/quaternions/interpolation.d.ts.map +1 -0
  129. package/build/quaternions/interpolation.js +201 -0
  130. package/build/quaternions/interpolation.js.map +1 -0
  131. package/build/quaternions/interpolation.spec.d.ts +2 -0
  132. package/build/quaternions/interpolation.spec.d.ts.map +1 -0
  133. package/build/quaternions/interpolation.spec.js +64 -0
  134. package/build/quaternions/interpolation.spec.js.map +1 -0
  135. package/build/quaternions/predefined.d.ts +36 -0
  136. package/build/quaternions/predefined.d.ts.map +1 -0
  137. package/build/quaternions/predefined.js +42 -0
  138. package/build/quaternions/predefined.js.map +1 -0
  139. package/build/quaternions/predefined.spec.d.ts +2 -0
  140. package/build/quaternions/predefined.spec.d.ts.map +1 -0
  141. package/build/quaternions/predefined.spec.js +35 -0
  142. package/build/quaternions/predefined.spec.js.map +1 -0
  143. package/build/quaternions/types.d.ts +55 -0
  144. package/build/quaternions/types.d.ts.map +1 -0
  145. package/build/quaternions/types.js +7 -0
  146. package/build/quaternions/types.js.map +1 -0
  147. package/build/random.d.ts +66 -0
  148. package/build/random.d.ts.map +1 -0
  149. package/build/random.js +115 -0
  150. package/build/random.js.map +1 -0
  151. package/build/random.spec.d.ts +2 -0
  152. package/build/random.spec.d.ts.map +1 -0
  153. package/build/random.spec.js +267 -0
  154. package/build/random.spec.js.map +1 -0
  155. package/build/vectors/asserts.d.ts +182 -0
  156. package/build/vectors/asserts.d.ts.map +1 -0
  157. package/build/vectors/asserts.js +285 -0
  158. package/build/vectors/asserts.js.map +1 -0
  159. package/build/vectors/asserts.spec.d.ts +2 -0
  160. package/build/vectors/asserts.spec.d.ts.map +1 -0
  161. package/build/vectors/asserts.spec.js +260 -0
  162. package/build/vectors/asserts.spec.js.map +1 -0
  163. package/build/vectors/core.d.ts +507 -0
  164. package/build/vectors/core.d.ts.map +1 -0
  165. package/build/vectors/core.js +825 -0
  166. package/build/vectors/core.js.map +1 -0
  167. package/build/vectors/core.spec.d.ts +2 -0
  168. package/build/vectors/core.spec.d.ts.map +1 -0
  169. package/build/vectors/core.spec.js +343 -0
  170. package/build/vectors/core.spec.js.map +1 -0
  171. package/build/vectors/index.d.ts +6 -0
  172. package/build/vectors/index.d.ts.map +1 -0
  173. package/build/vectors/index.js +6 -0
  174. package/build/vectors/index.js.map +1 -0
  175. package/build/vectors/interpolation.d.ts +404 -0
  176. package/build/vectors/interpolation.d.ts.map +1 -0
  177. package/build/vectors/interpolation.js +585 -0
  178. package/build/vectors/interpolation.js.map +1 -0
  179. package/build/vectors/interpolation.spec.d.ts +2 -0
  180. package/build/vectors/interpolation.spec.d.ts.map +1 -0
  181. package/build/vectors/interpolation.spec.js +378 -0
  182. package/build/vectors/interpolation.spec.js.map +1 -0
  183. package/build/vectors/predefined.d.ts +191 -0
  184. package/build/vectors/predefined.d.ts.map +1 -0
  185. package/build/vectors/predefined.js +191 -0
  186. package/build/vectors/predefined.js.map +1 -0
  187. package/build/vectors/predefined.spec.d.ts +2 -0
  188. package/build/vectors/predefined.spec.d.ts.map +1 -0
  189. package/build/vectors/predefined.spec.js +333 -0
  190. package/build/vectors/predefined.spec.js.map +1 -0
  191. package/build/vectors/types.d.ts +62 -0
  192. package/build/vectors/types.d.ts.map +1 -0
  193. package/build/vectors/types.js +6 -0
  194. package/build/vectors/types.js.map +1 -0
  195. 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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"}