numopt-js 0.1.0

package/dist/core/adjointGradientDescent.d.ts

@@ -0,0 +1,61 @@
+/**
+ * This file implements the adjoint method for constrained optimization problems.
+ *
+ * The adjoint method efficiently computes gradients for constrained optimization
+ * by solving for an adjoint variable λ instead of explicitly inverting matrices.
+ *
+ * Mathematical background:
+ * - For constraint c(p, x) = 0, the implicit function theorem gives:
+ *   df/dp = ∂f/∂p - ∂f/∂x (∂c/∂x)^-1 ∂c/∂p
+ * - Instead of computing (∂c/∂x)^-1 ∂c/∂p explicitly, we solve:
+ *   (∂c/∂x)^T λ = (∂f/∂x)^T
+ *   Then: df/dp = ∂f/∂p - λ^T ∂c/∂p
+ * - This requires solving only one linear system per iteration instead of
+ *   paramCount systems, making it much more efficient.
+ *
+ * For residual functions r(p, x) where f = 1/2 r^T r:
+ * - Solve: (∂c/∂x)^T λ = r^T ∂r/∂x
+ * - Then: df/dp = r^T ∂r/∂p - λ^T ∂c/∂p
+ *
+ * References:
+ * - Nocedal & Wright, "Numerical Optimization" (2nd ed.), Chapter 12 (constrained optimization)
+ * - Adjoint method is widely used in optimal control and shape optimization
+ *
+ * Role in system:
+ * - Provides efficient constrained optimization using adjoint method
+ * - Supports both cost functions and residual functions
+ * - Uses finite differences or analytical derivatives
+ * - For residual functions r(p, x), can compute dr/dp (Jacobian matrix) efficiently
+ *   by reusing ∂c/∂x decomposition for all residual components. This is more efficient
+ *   than BFGS or Lagrange multiplier methods. The Jacobian enables Gauss-Newton or
+ *   Levenberg-Marquardt methods for quadratic convergence in constrained optimization
+ *
+ * For first-time readers:
+ * - Start with adjointGradientDescent function
+ * - Understand how adjoint variable λ is computed
+ * - Check how states x are updated using linear approximation
+ */
+import type { ConstrainedCostFn, ConstrainedResidualFn, ConstraintFn, AdjointGradientDescentOptions, AdjointGradientDescentResult } from './types.js';
+/**
+ * Performs adjoint gradient descent optimization to minimize a constrained cost function.
+ *
+ * Algorithm:
+ * 1. Start with initial parameters p0 and states x0 (satisfying c(p0, x0) = 0)
+ * 2. Compute partial derivatives ∂f/∂p, ∂f/∂x, ∂c/∂p, ∂c/∂x
+ * 3. Solve adjoint equation: (∂c/∂x)^T λ = (∂f/∂x)^T
+ * 4. Compute gradient: df/dp = ∂f/∂p - λ^T ∂c/∂p
+ * 5. Update parameters: p_new = p_old - stepSize * df/dp
+ * 6. Update states: x_new = x_old - (∂c/∂x)^-1 ∂c/∂p · Δp (linear approximation)
+ * 7. Repeat until convergence or max iterations
+ *
+ * Supports both cost functions f(p,x) and residual functions r(p,x) where f = 1/2 r^T r.
+ *
+ * @param initialParameters - Initial parameter vector p0
+ * @param initialStates - Initial state vector x0 (should satisfy c(p0, x0) = 0)
+ * @param costFunction - Cost function f(p, x) or residual function r(p, x)
+ * @param constraintFunction - Constraint function c(p, x) = 0
+ * @param options - Optimization options
+ * @returns Optimization result with final parameters, states, and constraint norm
+ */
+export declare function adjointGradientDescent(initialParameters: Float64Array, initialStates: Float64Array, costFunction: ConstrainedCostFn | ConstrainedResidualFn, constraintFunction: ConstraintFn, options?: AdjointGradientDescentOptions): AdjointGradientDescentResult;
+//# sourceMappingURL=adjointGradientDescent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adjointGradientDescent.d.ts","sourceRoot":"","sources":["../../src/core/adjointGradientDescent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAKH,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EACrB,YAAY,EACZ,6BAA6B,EAC7B,4BAA4B,EAC7B,MAAM,YAAY,CAAC;AAssCpB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,CACpC,iBAAiB,EAAE,YAAY,EAC/B,aAAa,EAAE,YAAY,EAC3B,YAAY,EAAE,iBAAiB,GAAG,qBAAqB,EACvD,kBAAkB,EAAE,YAAY,EAChC,OAAO,GAAE,6BAAkC,GAC1C,4BAA4B,CA6D9B"}