import { XpbdIncrementalPotentialProblemN, type XpbdPackedIncrementalPotentialEvaluationN } from './xpbd-incremental-potential-problem.js';
declare const METHOD: "centered-gradient-difference";
/** Options for one matrix-free incremental-potential curvature estimate. */
export interface EstimateXpbdIncrementalPotentialHessianVectorNOptions {
    /** Compiled particle-identity objective to differentiate. */
    readonly problem: XpbdIncrementalPotentialProblemN;
    /** Packed free-particle coordinates at the differentiation point. */
    readonly coordinates: ArrayLike<number>;
    /** Packed direction multiplied by the objective Hessian. */
    readonly direction: ArrayLike<number>;
    /**
     * Positive parameter-space probe step.
     *
     * The physical coordinate perturbation is `stepSize * direction`. When
     * omitted, a deterministic scale-relative `cbrt(Number.EPSILON)` step is
     * chosen.
     */
    readonly stepSize?: number;
}
/** Typed mathematical-domain refusal encountered by one signed probe. */
export interface XpbdIncrementalPotentialHessianVectorDomainRefusalN {
    /** Stable identifier of the potential law or provider. */
    readonly lawId: string;
    /** Machine-readable reason within that law's domain vocabulary. */
    readonly reason: string;
    /** Human-readable explanation of the refused candidate. */
    readonly message: string;
}
interface XpbdIncrementalPotentialHessianVectorBaseN {
    /** Differential construction used for this result. */
    readonly method: typeof METHOD;
    /** Valid objective and gradient at the unperturbed coordinates. */
    readonly base: XpbdPackedIncrementalPotentialEvaluationN;
    /** Defensive copy of the packed input direction. */
    readonly direction: Float64Array;
}
/** Successful centered matrix-free Hessian-vector estimate. */
export interface XpbdIncrementalPotentialHessianVectorEvaluatedN extends XpbdIncrementalPotentialHessianVectorBaseN {
    /** Confirms that both signed probes produced finite objective gradients. */
    readonly status: 'evaluated';
    /** Positive parameter-space step used for both signed probes. */
    readonly stepSize: number;
    /** Objective evidence at `coordinates + stepSize * direction`. */
    readonly plus: XpbdPackedIncrementalPotentialEvaluationN;
    /** Objective evidence at `coordinates - stepSize * direction`. */
    readonly minus: XpbdPackedIncrementalPotentialEvaluationN;
    /** Centered estimate of `H(coordinates) * direction`. */
    readonly product: Float64Array;
    /** Directional curvature `directionᵀ * product`. */
    readonly quadraticForm: number;
}
/** Exact zero curvature product for a zero packed direction. */
export interface XpbdIncrementalPotentialHessianVectorZeroDirectionN extends XpbdIncrementalPotentialHessianVectorBaseN {
    /** Confirms that no offset probes were needed for the zero direction. */
    readonly status: 'zero-direction';
    /** Exact all-zero product with the compiled problem's packed length. */
    readonly product: Float64Array;
    /** Exact zero directional curvature. */
    readonly quadraticForm: 0;
}
/** Recoverable typed refusal from one signed curvature probe. */
export interface XpbdIncrementalPotentialHessianVectorProbeRefusedN extends XpbdIncrementalPotentialHessianVectorBaseN {
    /** Reports a typed open-domain refusal rather than a numeric product. */
    readonly status: 'probe-refused';
    /** Positive parameter-space step requested for the centered estimate. */
    readonly stepSize: number;
    /** Signed probe that left a potential's open mathematical domain. */
    readonly side: 'plus' | 'minus';
    /** Typed refusal supplied by the potential law. */
    readonly refusal: XpbdIncrementalPotentialHessianVectorDomainRefusalN;
    /** Valid plus evidence retained when only the minus probe was refused. */
    readonly plus?: XpbdPackedIncrementalPotentialEvaluationN;
}
/** Float64 refusal when a requested nonzero displacement is unrepresentable. */
export interface XpbdIncrementalPotentialHessianVectorIndeterminateN extends XpbdIncrementalPotentialHessianVectorBaseN {
    /** Reports that Float64 could not realize the requested centered probes. */
    readonly status: 'indeterminate';
    /** Stable refusal vocabulary for a rounded-away coordinate displacement. */
    readonly reason: 'coordinate-resolution';
    /** Positive parameter-space step requested for the centered estimate. */
    readonly stepSize: number;
    /** First packed component whose signed displacement rounded away. */
    readonly coordinateIndex: number;
}
/** Evidence returned by the matrix-free curvature reference. */
export type XpbdIncrementalPotentialHessianVectorResultN = XpbdIncrementalPotentialHessianVectorEvaluatedN | XpbdIncrementalPotentialHessianVectorZeroDirectionN | XpbdIncrementalPotentialHessianVectorProbeRefusedN | XpbdIncrementalPotentialHessianVectorIndeterminateN;
/**
 * Estimates one incremental-potential Hessian-vector product without assembly.
 *
 * The reference evaluates
 * `[gradient(x + h v) - gradient(x - h v)] / (2 h)`. It is intended as a
 * deterministic Float64 oracle for analytic, assembled, GPU, and solver paths;
 * it is not a promise that the estimate is positive semidefinite.
 *
 * A typed potential-domain error from an offset probe is returned as
 * `probe-refused`. A typed refusal at the base point, an ordinary provider
 * error, or a non-finite result remains fatal.
 *
 * Being matrix-free is what makes it a usable oracle: it costs two gradient
 * evaluations regardless of how many coordinates the problem has, so it can
 * check a path that does form products analytically without needing to form
 * the Hessian itself.
 *
 * @example
 * A single particle above a barrier floor, and the curvature the packed
 * objective presents along the vertical:
 * ```ts
 * const particle = new XpbdParticleN({ id: 'p', position: new VecN([0, 0.3, 0]) });
 * const barrier = new XpbdParticleHyperplaneBarrierN({
 *   id: 'floor',
 *   particle,
 *   plane: new HyperplaneColliderN(new VecN([0, 1, 0]), 0),
 *   activationDistance: 0.5,
 *   stiffness: 1
 * });
 * const problem = compileXpbdIncrementalPotentialProblemN({
 *   dimension: 3,
 *   particles: [particle],
 *   predictedPositions: [new VecN([0, 0.3, 0])],
 *   deltaTime: 1 / 60,
 *   providers: [barrier]
 * });
 *
 * const estimate = estimateXpbdIncrementalPotentialHessianVectorN({
 *   problem,
 *   coordinates: [0, 0.3, 0],
 *   direction: [0, 1, 0]
 * });
 *
 * estimate.status; // 'evaluated'
 * estimate.method; // 'centered-gradient-difference'
 * if (estimate.status === 'evaluated') {
 *   estimate.quadraticForm; // 1.00114798954… — vᵀHv along the vertical
 * }
 * ```
 *
 * @example
 * A zero direction is answered exactly, without probing the objective at
 * all — there is nothing to difference, so no domain error can arise from
 * an offset that would never have been evaluated:
 * ```ts
 * const particle = new XpbdParticleN({ id: 'p', position: new VecN([0, 0.3, 0]) });
 * const barrier = new XpbdParticleHyperplaneBarrierN({
 *   id: 'floor',
 *   particle,
 *   plane: new HyperplaneColliderN(new VecN([0, 1, 0]), 0),
 *   activationDistance: 0.5,
 *   stiffness: 1
 * });
 * const problem = compileXpbdIncrementalPotentialProblemN({
 *   dimension: 3,
 *   particles: [particle],
 *   predictedPositions: [new VecN([0, 0.3, 0])],
 *   deltaTime: 1 / 60,
 *   providers: [barrier]
 * });
 *
 * const estimate = estimateXpbdIncrementalPotentialHessianVectorN({
 *   problem,
 *   coordinates: [0, 0.3, 0],
 *   direction: [0, 0, 0]
 * });
 *
 * estimate.status; // 'zero-direction'
 * if (estimate.status === 'zero-direction') {
 *   estimate.quadraticForm; // 0, exactly
 * }
 * ```
 */
export declare function estimateXpbdIncrementalPotentialHessianVectorN(options: EstimateXpbdIncrementalPotentialHessianVectorNOptions): XpbdIncrementalPotentialHessianVectorResultN;
export {};
//# sourceMappingURL=xpbd-incremental-potential-curvature.d.ts.map