import { VecN } from '@holotope/core';
import { type DistanceCoordinateEvaluationN } from './distance-coordinate-n.js';
/** One point generalized coordinate consumed by the XPBD reference kernel. */
export interface XpbdPointN {
    /** Mutable Float64 position. The solver updates this vector in place. */
    readonly position: VecN;
    /** Zero fixes the point; positive values are inverse mass. */
    readonly inverseMass: number;
}
/** One scalar relation C(x) and its gradients in `points` order. */
export interface XpbdScalarConstraintEvaluationN {
    readonly value: number;
    readonly gradients: readonly VecN[];
}
export type XpbdConstraintRelationN = 'equality' | 'greater-than-or-equal';
/** Dimension-explicit scalar relation with physical compliance. */
export interface XpbdScalarConstraintN {
    /** Stable identity, retained in solver evidence across substeps. */
    readonly id: string;
    /** Ambient Euclidean dimension shared by every constrained point. */
    readonly dimension: number;
    /** Exact points the scalar coordinate reads, in authored order. */
    readonly points: readonly XpbdPointN[];
    /** Default `equality`; inequalities declare `C(x) >= 0`. */
    readonly relation?: XpbdConstraintRelationN;
    /** Inverse stiffness alpha. Zero is a hard positional relation. */
    readonly compliance: number;
    /** Must observe current point positions without mutating them. */
    evaluate(): XpbdScalarConstraintEvaluationN;
}
export type XpbdConstraintStatusN = 'solved' | 'inactive' | 'no-dynamic-response';
/** Final evidence for one constraint after one XPBD time-step solve. */
export interface XpbdConstraintResultN {
    readonly id: string;
    readonly status: XpbdConstraintStatusN;
    readonly relation: XpbdConstraintRelationN;
    /** True exactly when a projected inequality has positive multiplier. */
    readonly active: boolean;
    readonly initialValue: number;
    readonly finalValue: number;
    /** Total position-level multiplier accumulated during this solve. */
    readonly totalMultiplier: number;
    /** `totalMultiplier / deltaTime^2`, signed along the declared gradients. */
    readonly signedForce: number;
    /** `C(x) + (compliance / deltaTime^2) * totalMultiplier`. */
    readonly compliantResidual: number;
    /** Equality residual or projected coordinate-unit KKT violation. */
    readonly projectedKktResidual: number;
    /** Final `sum_i inverseMass_i * |gradient_i|^2`. */
    readonly weightedInverseMass: number;
}
export interface XpbdSolveResultN {
    readonly dimension: number;
    readonly deltaTime: number;
    readonly iterations: number;
    readonly constraints: readonly XpbdConstraintResultN[];
    readonly maxAbsConstraintValue: number;
    readonly maxAbsCompliantResidual: number;
    readonly maxAbsProjectedKktResidual: number;
    readonly noDynamicResponseIds: readonly string[];
    readonly inactiveInequalityIds: readonly string[];
}
export interface XpbdConstraintSolverNOptions {
    readonly dimension: number;
    /** Sequential Gauss-Seidel visits per constraint. Default 8. */
    readonly iterations?: number;
    /** Weighted-gradient response at or below this is immovable. Default 1e-15. */
    readonly responseEpsilon?: number;
}
/**
 * Auditable Float64 Gauss-Seidel implementation of the scalar XPBD update.
 *
 * The total multiplier starts at zero for every `solve()` call: one call is
 * one XPBD time-step projection. Point positions are restored atomically if a
 * malformed custom constraint throws during any visit.
 */
export declare class XpbdConstraintSolverN {
    readonly dimension: number;
    readonly iterations: number;
    readonly responseEpsilon: number;
    constructor(options: XpbdConstraintSolverNOptions);
    solve(constraints: readonly XpbdScalarConstraintN[], deltaTime: number): XpbdSolveResultN;
    private preflight;
}
export interface XpbdDistanceConstraintNOptions {
    readonly id: string;
    readonly pointA: XpbdPointN;
    readonly pointB: XpbdPointN;
    readonly restLength: number;
    readonly compliance?: number;
    /** Coherent distance gradient used only when the points coincide. */
    readonly directionHint?: VecN | ArrayLike<number>;
}
export interface XpbdDistanceConstraintEvaluationN extends XpbdScalarConstraintEvaluationN, DistanceCoordinateEvaluationN {
    readonly error: number;
}
/** Exact RN distance equality consumed by the generic XPBD kernel. */
export declare class XpbdDistanceConstraintN implements XpbdScalarConstraintN {
    readonly id: string;
    readonly dimension: number;
    readonly points: readonly [XpbdPointN, XpbdPointN];
    readonly compliance: number;
    readonly restLength: number;
    private directionHint;
    constructor(options: XpbdDistanceConstraintNOptions);
    evaluate(): XpbdDistanceConstraintEvaluationN;
}
//# sourceMappingURL=xpbd-constraint.d.ts.map