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

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

/**
 * Constraint Projection Utilities
 *
 * Collection of utility functions for projecting solutions onto constraint sets,
 * commonly used in mathematical optimization and portfolio analysis.
 */
/**
 * Project a solution vector onto equality constraints Ax = b
 *
 * @param x - Current solution vector
 * @param A - Constraint matrix (m×n)
 * @param b - Right-hand side vector (m×1)
 * @returns Projected solution vector
 *
 * @example
 * ```typescript
 * const x = [0.5, 0.3, 0.2];
 * const A = [[1, 1, 1]];
 * const b = [1];
 * const projected = projectOntoEqualityConstraints(x, A, b);
 * ```
 */
export declare function projectOntoEqualityConstraints(x: number[], A: number[][], b: number[]): number[];
/**
 * Project a solution vector onto non-negativity constraints x ≥ 0
 *
 * @param x - Current solution vector
 * @returns Projected solution vector with non-negative elements
 *
 * @example
 * ```typescript
 * const x = [-0.1, 0.5, -0.2];
 * const projected = projectOntoNonNegativityConstraints(x); // [0, 0.5, 0]
 * ```
 */
export declare function projectOntoNonNegativityConstraints(x: number[]): number[];
/**
 * Project a solution vector onto box constraints l ≤ x ≤ u
 *
 * @param x - Current solution vector
 * @param lowerBounds - Lower bounds (n×1)
 * @param upperBounds - Upper bounds (n×1)
 * @returns Projected solution vector within bounds
 *
 * @example
 * ```typescript
 * const x = [0.1, 0.8, 0.05];
 * const lower = [0.1, 0.1, 0.1];
 * const upper = [0.5, 0.5, 0.5];
 * const projected = projectOntoBoxConstraints(x, lower, upper);
 * ```
 */
export declare function projectOntoBoxConstraints(x: number[], lowerBounds: number[], upperBounds: number[]): number[];
/**
 * Project a solution vector onto the unit simplex (x ≥ 0, sum(x) = 1)
 *
 * @param x - Current solution vector
 * @returns Projected solution vector on unit simplex
 *
 * @example
 * ```typescript
 * const x = [0.5, 0.3, 0.4];
 * const projected = projectOntoSimplex(x); // [0.416, 0.25, 0.333]
 * ```
 */
export declare function projectOntoSimplex(x: number[]): number[];
/**
 * Project a gradient onto the null space of equality constraints
 *
 * @param gradient - Gradient vector
 * @param A - Constraint matrix (m×n)
 * @returns Projected gradient
 *
 * @example
 * ```typescript
 * const gradient = [1, 2, 3];
 * const A = [[1, 1, 1]];
 * const projected = projectGradientOntoEqualityConstraints(gradient, A);
 * ```
 */
export declare function projectGradientOntoEqualityConstraints(gradient: number[], A: number[][]): number[];
/**
 * Project a gradient onto non-negativity constraints
 *
 * @param gradient - Gradient vector
 * @param x - Current solution vector
 * @returns Projected gradient respecting non-negativity constraints
 *
 * @example
 * ```typescript
 * const gradient = [1, -2, 3];
 * const x = [0.1, 0, 0.5];
 * const projected = projectGradientOntoNonNegativityConstraints(gradient, x);
 * ```
 */
export declare function projectGradientOntoNonNegativityConstraints(gradient: number[], x: number[]): number[];
/**
 * Calculate constraint violation for equality constraints
 *
 * @param x - Solution vector
 * @param A - Constraint matrix (m×n)
 * @param b - Right-hand side vector (m×1)
 * @returns Maximum constraint violation
 *
 * @example
 * ```typescript
 * const x = [0.5, 0.3, 0.4];
 * const A = [[1, 1, 1]];
 * const b = [1];
 * const violation = calculateEqualityConstraintViolation(x, A, b);
 * ```
 */
export declare function calculateEqualityConstraintViolation(x: number[], A: number[][], b: number[]): number;
/**
 * Calculate constraint violation for inequality constraints
 *
 * @param x - Solution vector
 * @param G - Inequality constraint matrix (m×n)
 * @param h - Right-hand side vector (m×1)
 * @returns Maximum constraint violation (positive if violated)
 *
 * @example
 * ```typescript
 * const x = [0.5, 0.3];
 * const G = [[1, 0], [0, 1]]; // x ≥ 0
 * const h = [0, 0];
 * const violation = calculateInequalityConstraintViolation(x, G, h);
 * ```
 */
export declare function calculateInequalityConstraintViolation(x: number[], G: number[][], h: number[]): number;
/**
 * Check if a solution is feasible with respect to constraints
 *
 * @param x - Solution vector
 * @param equalityConstraints - Equality constraints {A, b}
 * @param inequalityConstraints - Inequality constraints {G, h}
 * @param tolerance - Feasibility tolerance (default: 1e-6)
 * @returns True if solution is feasible
 *
 * @example
 * ```typescript
 * const x = [0.3, 0.3, 0.4];
 * const eq = { A: [[1, 1, 1]], b: [1] };
 * const ineq = { G: [[1, 0, 0], [0, 1, 0], [0, 0, 1]], h: [0, 0, 0] };
 * const feasible = isSolutionFeasible(x, eq, ineq);
 * ```
 */
export declare function isSolutionFeasible(x: number[], equalityConstraints?: {
    A: number[][];
    b: number[];
}, inequalityConstraints?: {
    G: number[][];
    h: number[];
}, tolerance?: number): boolean;