import { XpbdIncrementalPotentialProblemN, type XpbdPackedIncrementalPotentialEvaluationN } from './xpbd-incremental-potential-problem.js';
import { type XpbdConservativeCurvatureOperatorProviderN } from './xpbd-incremental-potential-analytic-curvature.js';
import type { XpbdConservativeCurvatureApplicationN, XpbdIncrementalPotentialCurvaturePolicyKindN, XpbdIncrementalPotentialCurvaturePolicyN } from './xpbd-incremental-potential-curvature-policy.js';
declare const METHOD: "preconditioned-conjugate-gradient";
/** Available positive preconditioners for the packed Newton equation. */
export type XpbdIncrementalPotentialNewtonPreconditionerN = 'identity' | 'mass-diagonal';
/** Options for one bounded, non-mutating matrix-free Newton-direction solve. */
export interface SolveXpbdIncrementalPotentialNewtonDirectionNOptions {
    /** Compiled objective supplying packing, mass, and analytic provider curvature. */
    readonly problem: XpbdIncrementalPotentialProblemN;
    /** Packed free-particle coordinates at the linearization point. */
    readonly coordinates: ArrayLike<number>;
    /** Positive preconditioner policy; default `mass-diagonal`. */
    readonly preconditioner?: XpbdIncrementalPotentialNewtonPreconditionerN;
    /**
     * Exact provider Hessians by default, or explicit dense PSD block policy.
     */
    readonly curvaturePolicy?: XpbdIncrementalPotentialCurvaturePolicyN;
    /** Residual tolerance relative to the initial gradient norm; default `1e-8`. */
    readonly relativeResidualTolerance?: number;
    /** Absolute packed residual tolerance; default zero. */
    readonly absoluteResidualTolerance?: number;
    /**
     * Relative positive-curvature threshold against `||d|| ||H d||`.
     *
     * Defaults to `256 * Number.EPSILON`.
     */
    readonly relativeCurvatureTolerance?: number;
    /** Krylov iteration budget; default `min(variableCount, 128)`. */
    readonly maximumIterations?: number;
}
/** Auditable evidence for one completed conjugate-gradient iteration. */
export interface XpbdIncrementalPotentialNewtonIterationN {
    /** Zero-based Krylov iteration index. */
    readonly index: number;
    /** Residual norm before the Hessian-vector product. */
    readonly residualNormBefore: number;
    /** Residual norm after the accepted linear update. */
    readonly residualNormAfter: number;
    /** Positive search curvature `d^T H d`. */
    readonly quadraticForm: number;
    /** Scale-relative lower threshold applied to the search curvature. */
    readonly curvatureThreshold: number;
    /** Conjugate-gradient step coefficient `alpha`. */
    readonly stepLength: number;
    /** Next-direction coefficient `beta`, or `null` on terminal convergence. */
    readonly conjugacyCoefficient: number | null;
    /**
     * Provider construction behind this iteration's operator product.
     *
     * Projected spectra may be the same immutable compilation reused by several
     * iterations; the direction-specific block audit remains fresh.
     */
    readonly providerCurvatures: readonly {
        /** Stable conservative-provider identity. */
        readonly providerId: string;
        /** Exact or projected construction used for this product. */
        readonly curvature: XpbdConservativeCurvatureApplicationN;
    }[];
}
/** Evidence common to every matrix-free Newton-direction outcome. */
export interface XpbdIncrementalPotentialNewtonDirectionBaseN {
    /** Bounded linear-solver construction used by the result. */
    readonly method: typeof METHOD;
    /** Complete incremental objective at the unperturbed coordinates. */
    readonly base: XpbdPackedIncrementalPotentialEvaluationN;
    /** Defensive packed coordinate copy at the linearization point. */
    readonly coordinates: Float64Array;
    /** Linear right-hand side `-gradient(Phi)`. */
    readonly rightHandSide: Float64Array;
    /** Accumulated candidate Newton direction. */
    readonly direction: Float64Array;
    /** Initial Euclidean residual norm, equal to the gradient norm. */
    readonly initialResidualNorm: number;
    /** Euclidean residual norm at termination. */
    readonly residualNorm: number;
    /** Effective absolute-or-relative residual threshold. */
    readonly residualTolerance: number;
    /** Positive packed preconditioner used by the iteration. */
    readonly preconditioner: XpbdIncrementalPotentialNewtonPreconditionerN;
    /** Exact or explicitly modified curvature used by every operator query. */
    readonly curvaturePolicy: XpbdIncrementalPotentialCurvaturePolicyKindN;
    /** Authored or default Krylov iteration budget. */
    readonly maximumIterations: number;
    /** Completed positive-curvature iterations in execution order. */
    readonly iterations: readonly XpbdIncrementalPotentialNewtonIterationN[];
    /** Number of complete analytic objective Hessian-vector evaluations. */
    readonly operatorEvaluations: number;
    /** Provider basis HVPs paid once to compile projected curvature. */
    readonly curvatureConstructionOperatorEvaluations: number;
    /** Aggregate provider HVPs paid across nonzero operator applications. */
    readonly curvatureApplicationOperatorEvaluations: number;
    /** Fixed provider constructions reused by every Krylov iteration. */
    readonly curvatureProviders: readonly XpbdConservativeCurvatureOperatorProviderN[];
    /** Authored relative residual tolerance. */
    readonly relativeResidualTolerance: number;
    /** Authored absolute residual tolerance. */
    readonly absoluteResidualTolerance: number;
    /** Authored relative positive-curvature threshold. */
    readonly relativeCurvatureTolerance: number;
}
/** Exact stationary result requiring no curvature-provider capability. */
export interface XpbdIncrementalPotentialNewtonDirectionZeroGradientN extends XpbdIncrementalPotentialNewtonDirectionBaseN {
    /** Confirms that the packed objective gradient is exactly zero. */
    readonly status: 'zero-gradient';
}
/** Direction whose linear residual met the authored tolerance. */
export interface XpbdIncrementalPotentialNewtonDirectionConvergedN extends XpbdIncrementalPotentialNewtonDirectionBaseN {
    /** Confirms convergence of the linearized Newton equation only. */
    readonly status: 'converged';
    /** Whether tolerance held initially or after a Krylov update. */
    readonly convergencePoint: 'initial-residual' | 'iteration';
}
/** Bounded result that exhausted its Krylov iteration budget. */
export interface XpbdIncrementalPotentialNewtonDirectionIterationLimitN extends XpbdIncrementalPotentialNewtonDirectionBaseN {
    /** Distinguishes a finite incomplete solve from convergence or refusal. */
    readonly status: 'iteration-limit';
}
/** Explicit refusal when the complete objective lacks analytic curvature. */
export interface XpbdIncrementalPotentialNewtonDirectionUnsupportedN extends XpbdIncrementalPotentialNewtonDirectionBaseN {
    /** Identifies an incomplete analytic provider mixture. */
    readonly status: 'unsupported-provider';
    /** Every incapable conservative provider id in authored order. */
    readonly providerIds: readonly string[];
}
/** Explicit refusal at an indefinite or numerically unresolved Krylov ray. */
export interface XpbdIncrementalPotentialNewtonDirectionNonPositiveCurvatureN extends XpbdIncrementalPotentialNewtonDirectionBaseN {
    /** Distinguishes curvature refusal from an iteration-budget limit. */
    readonly status: 'non-positive-curvature';
    /** Zero-based rejected Krylov iteration. */
    readonly iterationIndex: number;
    /** Defensive search direction whose curvature was rejected. */
    readonly krylovDirection: Float64Array;
    /** Complete objective Hessian product along the rejected direction. */
    readonly product: Float64Array;
    /** Rejected directional curvature `d^T H d`. */
    readonly quadraticForm: number;
    /** Required scale-relative positive-curvature threshold. */
    readonly curvatureThreshold: number;
}
/** Bounded evidence from one matrix-free Newton-direction attempt. */
export type XpbdIncrementalPotentialNewtonDirectionResultN = XpbdIncrementalPotentialNewtonDirectionZeroGradientN | XpbdIncrementalPotentialNewtonDirectionConvergedN | XpbdIncrementalPotentialNewtonDirectionIterationLimitN | XpbdIncrementalPotentialNewtonDirectionUnsupportedN | XpbdIncrementalPotentialNewtonDirectionNonPositiveCurvatureN;
/**
 * Solves the packed linearized Newton equation with bounded preconditioned CG.
 *
 * The operator is P35/P36's complete exact analytic objective
 * Hessian-vector composition. The routine neither assembles a matrix nor
 * mutates particles. It refuses incomplete provider mixtures and
 * non-positive curvature instead of returning a falsely certified Newton
 * direction.
 *
 * At the fixed linearization coordinate, explicit PSD provider/block matrices
 * are reconstructed and diagonalized once, then reused by every Krylov
 * iteration. Exact providers remain matrix-free. Provider-block PSD retains
 * one aggregate decomposition audit per applied direction.
 *
 * This result is only a direction diagnostic. It does not choose an admissible
 * nonlinear step, modify definiteness, invoke Armijo, or apply state.
 *
 * @example
 * On a problem whose only curvature is the mass block, the linearized Newton
 * equation is diagonal and converges immediately:
 * ```ts
 * const particle = new XpbdParticleN({ id: 'p', position: new VecN([0, 0.3, 0]) });
 * const problem = compileXpbdIncrementalPotentialProblemN({
 *   dimension: 3,
 *   particles: [particle],
 *   predictedPositions: [new VecN([0, 0.9, 0])],
 *   deltaTime: 1 / 60,
 *   providers: []
 * });
 *
 * const solved = solveXpbdIncrementalPotentialNewtonDirectionN({
 *   problem,
 *   coordinates: [0, 0.3, 0]
 * });
 *
 * solved.status; // 'converged'
 * solved.preconditioner; // 'mass-diagonal', the default
 * ```
 *
 * @example
 * A refusal is not a failure to compute — it is the solve declining to
 * certify a direction it cannot stand behind. An incomplete provider mixture
 * names every incapable provider before any partial product is requested:
 * ```ts
 * const particle = new XpbdParticleN({ id: 'p', position: new VecN([0, 0.3, 0]) });
 * const problem = compileXpbdIncrementalPotentialProblemN({
 *   dimension: 3,
 *   particles: [particle],
 *   predictedPositions: [new VecN([0, 0.9, 0])],
 *   deltaTime: 1 / 60,
 *   providers: []
 * });
 *
 * const solved = solveXpbdIncrementalPotentialNewtonDirectionN({
 *   problem,
 *   coordinates: [0, 0.3, 0],
 *   maximumIterations: 0
 * });
 *
 * solved.status; // 'iteration-limit' — a bounded solve, not a broken one
 * solved.iterations.length; // 0
 * ```
 */
export declare function solveXpbdIncrementalPotentialNewtonDirectionN(options: SolveXpbdIncrementalPotentialNewtonDirectionNOptions): XpbdIncrementalPotentialNewtonDirectionResultN;
export {};
//# sourceMappingURL=xpbd-incremental-potential-newton-direction.d.ts.map