numopt-js 0.1.0

package/dist/core/createGradientFunction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createGradientFunction.js","sourceRoot":"","sources":["../../src/core/createGradientFunction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AASzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,wBAAwB,CACpC,YAAoB,EACpB,OAAyC;IAEzC,OAAO,CAAC,MAAoB,EAAgB,EAAE;QAC1C,OAAO,kBAAkB,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;IAC7D,CAAC,CAAC;AACN,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,wBAAwB,CACpC,gBAA4B,EAC5B,OAAyC;IAEzC,OAAO,CAAC,MAAoB,EAAE,EAAE;QAC5B,OAAO,kBAAkB,CAAC,gBAAgB,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACjE,CAAC,CAAC;AACN,CAAC"}

package/dist/core/effectiveJacobian.d.ts

@@ -0,0 +1,90 @@
+/**
+ * This file implements the effective Jacobian computation for constrained optimization.
+ *
+ * The effective Jacobian J_eff = dr/dp = r_p - r_x C_x^+ C_p captures all constraint
+ * effects, allowing constrained least squares problems to be solved using the same
+ * structure as unconstrained problems.
+ *
+ * Mathematical background:
+ * - For constrained residual r(p, x) where c(p, x) = 0, the implicit function
+ *   theorem gives: dr/dp = r_p - r_x C_x^+ C_p
+ * - We compute this efficiently by solving C_x dx = (C_p)_j for each parameter j,
+ *   then (J_eff)_j = (r_p)_j - r_x dx
+ * - This reuses the C_x decomposition across all columns for efficiency.
+ *
+ * Role in system:
+ * - Core component for constrained Gauss-Newton and Levenberg-Marquardt methods
+ * - Enables efficient constrained least squares optimization
+ * - Uses direct linear solve to avoid explicit matrix inversion
+ *
+ * For first-time readers:
+ * - Start with computeEffectiveJacobian function
+ * - Understand how each column is computed efficiently
+ * - Note the reuse of C_x decomposition for performance
+ */
+import { Matrix } from 'ml-matrix';
+import type { ConstrainedResidualFn, ConstraintFn } from './types.js';
+import { Logger } from './logger.js';
+/**
+ * Options for effective Jacobian computation.
+ */
+export interface EffectiveJacobianOptions {
+    /**
+     * Analytical partial derivative of residual function with respect to parameters.
+     * If provided, this will be used instead of numerical differentiation.
+     * Returns a Matrix of size (residualCount × parameterCount).
+     */
+    drdp?: (parameters: Float64Array, states: Float64Array) => Matrix;
+    /**
+     * Analytical partial derivative of residual function with respect to states.
+     * If provided, this will be used instead of numerical differentiation.
+     * Returns a Matrix of size (residualCount × stateCount).
+     */
+    drdx?: (parameters: Float64Array, states: Float64Array) => Matrix;
+    /**
+     * Analytical partial derivative of constraint function with respect to parameters.
+     * If provided, this will be used instead of numerical differentiation.
+     * Returns a Matrix of size (constraintCount × parameterCount).
+     */
+    dcdp?: (parameters: Float64Array, states: Float64Array) => Matrix;
+    /**
+     * Analytical partial derivative of constraint function with respect to states.
+     * If provided, this will be used instead of numerical differentiation.
+     * Returns a Matrix of size (constraintCount × stateCount).
+     */
+    dcdx?: (parameters: Float64Array, states: Float64Array) => Matrix;
+    /**
+     * Step size for numerical differentiation with respect to parameters.
+     * Default: 1e-6
+     */
+    stepSizeP?: number;
+    /**
+     * Step size for numerical differentiation with respect to states.
+     * Default: 1e-6
+     */
+    stepSizeX?: number;
+}
+/**
+ * Computes the effective Jacobian J_eff = r_p - r_x C_x^+ C_p.
+ *
+ * Algorithm:
+ * 1. Compute partial derivatives: r_p, r_x, C_p, C_x
+ * 2. For each column j (parameter j):
+ *    a. Extract j-th column of C_p: (C_p)_j
+ *    b. Solve: C_x dx = (C_p)_j to get dx = C_x^-1 (C_p)_j
+ *    c. Compute column: (J_eff)_j = (r_p)_j - r_x dx
+ * 3. Return effective Jacobian matrix
+ *
+ * The C_x decomposition is reused across all columns for efficiency.
+ *
+ * @param parameters - Parameter vector p
+ * @param states - State vector x (satisfies c(p, x) = 0)
+ * @param residualFunction - Residual function r(p, x)
+ * @param constraintFunction - Constraint function c(p, x) = 0
+ * @param options - Options for Jacobian computation
+ * @param logger - Logger instance for error reporting
+ * @param algorithmName - Name of calling algorithm (for error messages)
+ * @returns Effective Jacobian matrix J_eff (residualCount × parameterCount)
+ */
+export declare function computeEffectiveJacobian(parameters: Float64Array, states: Float64Array, residualFunction: ConstrainedResidualFn, constraintFunction: ConstraintFn, options: EffectiveJacobianOptions | undefined, logger: Logger, algorithmName?: string): Matrix;
+//# sourceMappingURL=effectiveJacobian.d.ts.map

package/dist/core/effectiveJacobian.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effectiveJacobian.d.ts","sourceRoot":"","sources":["../../src/core/effectiveJacobian.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,KAAK,EACV,qBAAqB,EACrB,YAAY,EACb,MAAM,YAAY,CAAC;AAOpB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAOrC;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,UAAU,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,KAAK,MAAM,CAAC;IAElE;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,UAAU,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,KAAK,MAAM,CAAC;IAElE;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,UAAU,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,KAAK,MAAM,CAAC;IAElE;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,UAAU,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,KAAK,MAAM,CAAC;IAElE;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,YAAY,EACxB,MAAM,EAAE,YAAY,EACpB,gBAAgB,EAAE,qBAAqB,EACvC,kBAAkB,EAAE,YAAY,EAChC,OAAO,EAAE,wBAAwB,YAAK,EACtC,MAAM,EAAE,MAAM,EACd,aAAa,GAAE,MAAkC,GAChD,MAAM,CAqER"}

package/dist/core/effectiveJacobian.js

@@ -0,0 +1,128 @@
+/**
+ * This file implements the effective Jacobian computation for constrained optimization.
+ *
+ * The effective Jacobian J_eff = dr/dp = r_p - r_x C_x^+ C_p captures all constraint
+ * effects, allowing constrained least squares problems to be solved using the same
+ * structure as unconstrained problems.
+ *
+ * Mathematical background:
+ * - For constrained residual r(p, x) where c(p, x) = 0, the implicit function
+ *   theorem gives: dr/dp = r_p - r_x C_x^+ C_p
+ * - We compute this efficiently by solving C_x dx = (C_p)_j for each parameter j,
+ *   then (J_eff)_j = (r_p)_j - r_x dx
+ * - This reuses the C_x decomposition across all columns for efficiency.
+ *
+ * Role in system:
+ * - Core component for constrained Gauss-Newton and Levenberg-Marquardt methods
+ * - Enables efficient constrained least squares optimization
+ * - Uses direct linear solve to avoid explicit matrix inversion
+ *
+ * For first-time readers:
+ * - Start with computeEffectiveJacobian function
+ * - Understand how each column is computed efficiently
+ * - Note the reuse of C_x decomposition for performance
+ */
+import { Matrix } from 'ml-matrix';
+import { finiteDiffResidualPartialP, finiteDiffResidualPartialX, finiteDiffConstraintPartialP, finiteDiffConstraintPartialX } from './finiteDiff.js';
+import { float64ArrayToMatrix } from '../utils/matrix.js';
+import { solveLeastSquares } from './constrainedUtils.js';
+const DEFAULT_STEP_SIZE_P = 1e-6;
+const DEFAULT_STEP_SIZE_X = 1e-6;
+/**
+ * Computes the effective Jacobian J_eff = r_p - r_x C_x^+ C_p.
+ *
+ * Algorithm:
+ * 1. Compute partial derivatives: r_p, r_x, C_p, C_x
+ * 2. For each column j (parameter j):
+ *    a. Extract j-th column of C_p: (C_p)_j
+ *    b. Solve: C_x dx = (C_p)_j to get dx = C_x^-1 (C_p)_j
+ *    c. Compute column: (J_eff)_j = (r_p)_j - r_x dx
+ * 3. Return effective Jacobian matrix
+ *
+ * The C_x decomposition is reused across all columns for efficiency.
+ *
+ * @param parameters - Parameter vector p
+ * @param states - State vector x (satisfies c(p, x) = 0)
+ * @param residualFunction - Residual function r(p, x)
+ * @param constraintFunction - Constraint function c(p, x) = 0
+ * @param options - Options for Jacobian computation
+ * @param logger - Logger instance for error reporting
+ * @param algorithmName - Name of calling algorithm (for error messages)
+ * @returns Effective Jacobian matrix J_eff (residualCount × parameterCount)
+ */
+export function computeEffectiveJacobian(parameters, states, residualFunction, constraintFunction, options = {}, logger, algorithmName = 'constrainedOptimization') {
+    const stepSizeP = options.stepSizeP ?? DEFAULT_STEP_SIZE_P;
+    const stepSizeX = options.stepSizeX ?? DEFAULT_STEP_SIZE_X;
+    // Compute partial derivatives
+    const r_p = options.drdp
+        ? options.drdp(parameters, states)
+        : finiteDiffResidualPartialP(parameters, states, residualFunction, { stepSize: stepSizeP });
+    const r_x = options.drdx
+        ? options.drdx(parameters, states)
+        : finiteDiffResidualPartialX(parameters, states, residualFunction, { stepSize: stepSizeX });
+    const c_p = options.dcdp
+        ? options.dcdp(parameters, states)
+        : finiteDiffConstraintPartialP(parameters, states, constraintFunction, { stepSize: stepSizeP });
+    const c_x = options.dcdx
+        ? options.dcdx(parameters, states)
+        : finiteDiffConstraintPartialX(parameters, states, constraintFunction, { stepSize: stepSizeX });
+    // Get dimensions
+    const residualCount = r_p.rows;
+    const parameterCount = r_p.columns;
+    const stateCount = c_x.columns;
+    // Note: Constraint Jacobian ∂c/∂x can be non-square.
+    // The adjoint method now supports both square and non-square constraint Jacobians.
+    // Dimension validation removed to allow non-square matrices.
+    if (r_x.columns !== stateCount) {
+        const errorMsg = `Residual Jacobian ∂r/∂x must have stateCount columns. ` +
+            `Got ${r_x.rows} × ${r_x.columns}, expected ${r_x.rows} × ${stateCount}. Algorithm: ${algorithmName}`;
+        logger.warn(algorithmName, undefined, errorMsg);
+        throw new Error(errorMsg);
+    }
+    if (c_p.columns !== parameterCount) {
+        const errorMsg = `Constraint Jacobian ∂c/∂p must have parameterCount columns. ` +
+            `Got ${c_p.rows} × ${c_p.columns}, expected ${c_p.rows} × ${parameterCount}. Algorithm: ${algorithmName}`;
+        logger.warn(algorithmName, undefined, errorMsg);
+        throw new Error(errorMsg);
+    }
+    // Initialize effective Jacobian matrix (residualCount × parameterCount)
+    const effectiveJacobianData = [];
+    for (let i = 0; i < residualCount; i++) {
+        effectiveJacobianData.push(new Array(parameterCount).fill(0));
+    }
+    // Compute each column of effective Jacobian
+    for (let paramIndex = 0; paramIndex < parameterCount; paramIndex++) {
+        const column = computeEffectiveJacobianColumn(paramIndex, c_p, c_x, r_p, r_x, stateCount, residualCount, logger, algorithmName);
+        for (let i = 0; i < residualCount; i++) {
+            effectiveJacobianData[i][paramIndex] = column[i];
+        }
+    }
+    return new Matrix(effectiveJacobianData);
+}
+/**
+ * Computes a single column of the effective Jacobian.
+ * For parameter j: (J_eff)_j = (r_p)_j - r_x dx, where dx solves C_x dx = (C_p)_j
+ */
+function computeEffectiveJacobianColumn(paramIndex, constraintJacobianP, constraintJacobianX, residualJacobianP, residualJacobianX, stateCount, residualCount, logger, algorithmName) {
+    // Extract j-th column of C_p: (C_p)_j
+    const constraintCount = constraintJacobianP.rows;
+    const constraintJacobianPColumn = new Float64Array(constraintCount);
+    for (let k = 0; k < constraintCount; k++) {
+        constraintJacobianPColumn[k] = constraintJacobianP.get(k, paramIndex);
+    }
+    // Solve: C_x dx = (C_p)_j to get dx = C_x^+ (C_p)_j
+    // Uses hierarchical solver that handles both square and non-square matrices
+    const constraintJacobianPColumnMatrix = float64ArrayToMatrix(constraintJacobianPColumn);
+    const stateSensitivity = solveLeastSquares(constraintJacobianX, constraintJacobianPColumnMatrix, logger, algorithmName);
+    // Compute: (J_eff)_j = (r_p)_j - r_x dx
+    const effectiveJacobianColumn = new Float64Array(residualCount);
+    for (let i = 0; i < residualCount; i++) {
+        let residualJacobianXTimesStateSensitivity = 0;
+        for (let k = 0; k < stateCount; k++) {
+            residualJacobianXTimesStateSensitivity += residualJacobianX.get(i, k) * stateSensitivity[k];
+        }
+        effectiveJacobianColumn[i] = residualJacobianP.get(i, paramIndex) - residualJacobianXTimesStateSensitivity;
+    }
+    return effectiveJacobianColumn;
+}
+//# sourceMappingURL=effectiveJacobian.js.map

package/dist/core/effectiveJacobian.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effectiveJacobian.js","sourceRoot":"","sources":["../../src/core/effectiveJacobian.ts"],"names":[],"mappings":"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"}

package/dist/core/finiteDiff.d.ts

@@ -0,0 +1,171 @@
+/**
+ * This file implements numerical differentiation methods for computing
+ * gradients and Jacobian matrices when analytical derivatives are not available.
+ *
+ * Role in system:
+ * - Provides automatic gradient/Jacobian computation via finite differences
+ * - Used when users don't provide analytical derivatives
+ * - Critical for algorithms that require gradient information
+ *
+ * For first-time readers:
+ * - Start with finiteDiffGradient for general optimization
+ * - finiteDiffJacobian is for nonlinear least squares problems
+ * - Central difference is used for better accuracy than forward difference
+ */
+import { Matrix } from 'ml-matrix';
+import type { CostFn, ResidualFn, NumericalDifferentiationOptions, ConstrainedCostFn, ConstraintFn, ConstrainedResidualFn } from './types.js';
+/**
+ * Computes the gradient vector using central difference method.
+ *
+ * Central difference formula: f'(x) ≈ (f(x+h) - f(x-h)) / (2h)
+ *
+ * This is more accurate than forward difference but requires two function
+ * evaluations per parameter. The trade-off is worth it for better convergence.
+ *
+ * @param parameters - The point at which to evaluate the gradient
+ * @param costFunction - The cost function to differentiate
+ * @param options - Optional numerical differentiation settings
+ * @returns The gradient vector at the given parameters
+ *
+ * @example
+ * ```typescript
+ * // Standalone usage - compute gradient at a specific point
+ * const costFn = (params) => params[0] ** 2 + params[1] ** 2;
+ * const params = new Float64Array([1.0, 2.0]);
+ * const gradient = finiteDiffGradient(params, costFn);
+ * // gradient ≈ [2.0, 4.0]
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Usage with gradientDescent - note the parameter order!
+ * import { gradientDescent, finiteDiffGradient } from 'numopt-js';
+ *
+ * const costFn = (params) => Math.pow(params[0] - 3, 2) + Math.pow(params[1] - 2, 2);
+ *
+ * const result = gradientDescent(
+ *   new Float64Array([0, 0]),
+ *   costFn,
+ *   (params) => finiteDiffGradient(params, costFn),  // ✅ Correct: params first!
+ *   { maxIterations: 100, tolerance: 1e-6 }
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // For easier usage with optimizers, consider using createFiniteDiffGradient:
+ * import { gradientDescent, createFiniteDiffGradient } from 'numopt-js';
+ *
+ * const costFn = (params) => Math.pow(params[0] - 3, 2) + Math.pow(params[1] - 2, 2);
+ * const gradientFn = createFiniteDiffGradient(costFn);  // No parameter order confusion!
+ *
+ * const result = gradientDescent(
+ *   new Float64Array([0, 0]),
+ *   costFn,
+ *   gradientFn,
+ *   { maxIterations: 100, tolerance: 1e-6 }
+ * );
+ * ```
+ *
+ * @remarks
+ * **Important:** When using with optimization algorithms, note the parameter order:
+ * - ✅ Correct: `(params) => finiteDiffGradient(params, costFn)`
+ * - ❌ Wrong: `(params) => finiteDiffGradient(costFn, params)`
+ *
+ * Consider using {@link createFiniteDiffGradient} for a more intuitive API.
+ */
+export declare function finiteDiffGradient(parameters: Float64Array, costFunction: CostFn, options?: NumericalDifferentiationOptions): Float64Array;
+/**
+ * Computes the Jacobian matrix using central difference method.
+ *
+ * The Jacobian J has dimensions (residualCount × parameterCount) where:
+ * - Each row corresponds to a residual component
+ * - Each column corresponds to a parameter
+ * - J[i][j] = ∂r_i / ∂p_j
+ *
+ * Central difference is used for each partial derivative.
+ */
+export declare function finiteDiffJacobian(residualFunction: ResidualFn, parameters: Float64Array, options?: NumericalDifferentiationOptions): Matrix;
+/**
+ * Computes the partial derivative of a constrained cost function with respect to parameters.
+ * Uses central difference method while keeping states fixed.
+ *
+ * Formula: ∂f/∂p_i ≈ (f(p+h·e_i, x) - f(p-h·e_i, x)) / (2h)
+ *
+ * @param parameters - Parameter vector p
+ * @param states - State vector x (kept fixed)
+ * @param costFunction - Constrained cost function f(p, x)
+ * @param options - Optional numerical differentiation settings
+ * @returns Gradient vector ∂f/∂p
+ */
+export declare function finiteDiffPartialP(parameters: Float64Array, states: Float64Array, costFunction: ConstrainedCostFn, options?: NumericalDifferentiationOptions): Float64Array;
+/**
+ * Computes the partial derivative of a constrained cost function with respect to states.
+ * Uses central difference method while keeping parameters fixed.
+ *
+ * Formula: ∂f/∂x_i ≈ (f(p, x+h·e_i) - f(p, x-h·e_i)) / (2h)
+ *
+ * @param parameters - Parameter vector p (kept fixed)
+ * @param states - State vector x
+ * @param costFunction - Constrained cost function f(p, x)
+ * @param options - Optional numerical differentiation settings
+ * @returns Gradient vector ∂f/∂x
+ */
+export declare function finiteDiffPartialX(parameters: Float64Array, states: Float64Array, costFunction: ConstrainedCostFn, options?: NumericalDifferentiationOptions): Float64Array;
+/**
+ * Computes the partial derivative of a constraint function with respect to parameters.
+ * Uses central difference method while keeping states fixed.
+ * Returns a Jacobian matrix of size (constraintCount × parameterCount).
+ *
+ * Formula: ∂c/∂p_ij ≈ (c_i(p+h·e_j, x) - c_i(p-h·e_j, x)) / (2h)
+ *
+ * @param parameters - Parameter vector p
+ * @param states - State vector x (kept fixed)
+ * @param constraintFunction - Constraint function c(p, x)
+ * @param options - Optional numerical differentiation settings
+ * @returns Jacobian matrix ∂c/∂p
+ */
+export declare function finiteDiffConstraintPartialP(parameters: Float64Array, states: Float64Array, constraintFunction: ConstraintFn, options?: NumericalDifferentiationOptions): Matrix;
+/**
+ * Computes the partial derivative of a constraint function with respect to states.
+ * Uses central difference method while keeping parameters fixed.
+ * Returns a Jacobian matrix of size (constraintCount × stateCount).
+ *
+ * Formula: ∂c/∂x_ij ≈ (c_i(p, x+h·e_j) - c_i(p, x-h·e_j)) / (2h)
+ *
+ * @param parameters - Parameter vector p (kept fixed)
+ * @param states - State vector x
+ * @param constraintFunction - Constraint function c(p, x)
+ * @param options - Optional numerical differentiation settings
+ * @returns Jacobian matrix ∂c/∂x
+ */
+export declare function finiteDiffConstraintPartialX(parameters: Float64Array, states: Float64Array, constraintFunction: ConstraintFn, options?: NumericalDifferentiationOptions): Matrix;
+/**
+ * Computes the partial derivative of a constrained residual function with respect to parameters.
+ * Uses central difference method while keeping states fixed.
+ * Returns a Jacobian matrix of size (residualCount × parameterCount).
+ *
+ * Formula: ∂r/∂p_ij ≈ (r_i(p+h·e_j, x) - r_i(p-h·e_j, x)) / (2h)
+ *
+ * @param parameters - Parameter vector p
+ * @param states - State vector x (kept fixed)
+ * @param residualFunction - Constrained residual function r(p, x)
+ * @param options - Optional numerical differentiation settings
+ * @returns Jacobian matrix ∂r/∂p
+ */
+export declare function finiteDiffResidualPartialP(parameters: Float64Array, states: Float64Array, residualFunction: ConstrainedResidualFn, options?: NumericalDifferentiationOptions): Matrix;
+/**
+ * Computes the partial derivative of a constrained residual function with respect to states.
+ * Uses central difference method while keeping parameters fixed.
+ * Returns a Jacobian matrix of size (residualCount × stateCount).
+ *
+ * Formula: ∂r/∂x_ij ≈ (r_i(p, x+h·e_j) - r_i(p, x-h·e_j)) / (2h)
+ *
+ * @param parameters - Parameter vector p (kept fixed)
+ * @param states - State vector x
+ * @param residualFunction - Constrained residual function r(p, x)
+ * @param options - Optional numerical differentiation settings
+ * @returns Jacobian matrix ∂r/∂x
+ */
+export declare function finiteDiffResidualPartialX(parameters: Float64Array, states: Float64Array, residualFunction: ConstrainedResidualFn, options?: NumericalDifferentiationOptions): Matrix;
+//# sourceMappingURL=finiteDiff.d.ts.map

package/dist/core/finiteDiff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finiteDiff.d.ts","sourceRoot":"","sources":["../../src/core/finiteDiff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,KAAK,EACV,MAAM,EACN,UAAU,EACV,+BAA+B,EAC/B,iBAAiB,EACjB,YAAY,EACZ,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAKpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,YAAY,EACxB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,+BAAoC,GAC5C,YAAY,CAqBd;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,gBAAgB,EAAE,UAAU,EAC5B,UAAU,EAAE,YAAY,EACxB,OAAO,GAAE,+BAAoC,GAC5C,MAAM,CAkCR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,YAAY,EACxB,MAAM,EAAE,YAAY,EACpB,YAAY,EAAE,iBAAiB,EAC/B,OAAO,GAAE,+BAAoC,GAC5C,YAAY,CAqBd;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,YAAY,EACxB,MAAM,EAAE,YAAY,EACpB,YAAY,EAAE,iBAAiB,EAC/B,OAAO,GAAE,+BAAoC,GAC5C,YAAY,CAqBd;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,YAAY,EACxB,MAAM,EAAE,YAAY,EACpB,kBAAkB,EAAE,YAAY,EAChC,OAAO,GAAE,+BAAoC,GAC5C,MAAM,CAkCR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,YAAY,EACxB,MAAM,EAAE,YAAY,EACpB,kBAAkB,EAAE,YAAY,EAChC,OAAO,GAAE,+BAAoC,GAC5C,MAAM,CAkCR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,YAAY,EACxB,MAAM,EAAE,YAAY,EACpB,gBAAgB,EAAE,qBAAqB,EACvC,OAAO,GAAE,+BAAoC,GAC5C,MAAM,CAkCR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,YAAY,EACxB,MAAM,EAAE,YAAY,EACpB,gBAAgB,EAAE,qBAAqB,EACvC,OAAO,GAAE,+BAAoC,GAC5C,MAAM,CAkCR"}