/**
 * PIDController.ts
 *
 * Generic PID (Proportional-Integral-Derivative) controller with:
 * - Configurable inner/outer cascade loop timing
 * - Setpoint tracking with ramp-rate limiting
 * - Velocity monitoring via filtered derivative
 * - Thread-safe design for VR 90fps (11.1ms frame budget)
 * - Anti-windup (clamping + back-calculation)
 * - Derivative-on-measurement (avoids derivative kick)
 *
 * The generic type parameter T allows the controller to operate on
 * scalar numbers, IVector3, quaternion error signals, or any type
 * that implements the PIDControllable arithmetic interface.
 *
 * @module physics
 * @reference W.032 (virtual economy PID), P.030.01 (control loop timing)
 * @reference Trait constant: 'pid_controller' (robotics-industrial.ts)
 */
import { IVector3 } from './PhysicsTypes';
/**
 * Arithmetic operations required for a type to be used with PIDController<T>.
 *
 * Implementations provided for `number` and `IVector3` below.
 * Users can supply custom adapters for quaternion errors, joint-space vectors, etc.
 */
export interface PIDArithmetic<T> {
    /** Return the zero / identity element */
    zero(): T;
    /** a + b */
    add(a: T, b: T): T;
    /** a - b */
    sub(a: T, b: T): T;
    /** scalar * a */
    scale(scalar: number, a: T): T;
    /** Scalar magnitude (L2 norm for vectors, abs for scalars) */
    magnitude(a: T): number;
    /** Component-wise clamp between min and max scalars */
    clamp(a: T, min: number, max: number): T;
    /** Deep copy */
    clone(a: T): T;
}
/**
 * Arithmetic adapter for scalar `number` values.
 */
export declare const ScalarArithmetic: PIDArithmetic<number>;
/**
 * Arithmetic adapter for IVector3 values.
 */
export declare const Vector3Arithmetic: PIDArithmetic<IVector3>;
/**
 * PID gain parameters.
 */
export interface PIDGains {
    /** Proportional gain */
    kP: number;
    /** Integral gain */
    kI: number;
    /** Derivative gain */
    kD: number;
}
/**
 * Loop timing configuration for the cascade controller.
 *
 * The outer loop runs at `outerHz` and feeds its output as the setpoint
 * for the inner loop, which runs at `innerHz`.
 *
 * For VR at 90fps, the inner loop should be >= 90Hz (typically 200-1000Hz
 * when sub-stepping physics). The outer loop can be 30-90Hz for position control.
 */
export interface LoopTimingConfig {
    /** Inner loop frequency in Hz (default: 200) */
    innerHz: number;
    /** Outer loop frequency in Hz (default: 60) */
    outerHz: number;
}
/**
 * Full PID controller configuration.
 */
export interface PIDControllerConfig<T> {
    /** Unique controller identifier */
    id: string;
    /** Inner-loop PID gains (velocity/effort control) */
    innerGains: PIDGains;
    /** Outer-loop PID gains (position/setpoint control) */
    outerGains: PIDGains;
    /** Loop timing (Hz) */
    timing: LoopTimingConfig;
    /** Output limits (symmetric: -limit to +limit) */
    outputLimit: number;
    /** Integral term limit (anti-windup clamp) */
    integralLimit: number;
    /** Setpoint ramp rate per second (0 = instant) */
    setpointRampRate: number;
    /** Velocity limit for safety monitoring */
    velocityLimit: number;
    /** Derivative low-pass filter coefficient (0-1, higher = more filtering) */
    derivativeFilterAlpha: number;
    /** Initial setpoint */
    initialSetpoint: T;
    /**
     * Enable derivative-on-measurement instead of derivative-on-error.
     * Avoids "derivative kick" when setpoint changes abruptly. (default: true)
     */
    derivativeOnMeasurement: boolean;
    /**
     * Enable back-calculation anti-windup.
     * When output saturates, the integral is reduced proportionally. (default: true)
     */
    backCalculationAntiWindup: boolean;
    /** Back-calculation gain (Kb). Typically 1/kD or sqrt(kP/kI). */
    backCalculationGain: number;
}
/**
 * Default configuration factory.
 */
export declare function defaultPIDConfig<T>(id: string, initialSetpoint: T, overrides?: Partial<PIDControllerConfig<T>>): PIDControllerConfig<T>;
/**
 * Fixed-size ring buffer for velocity history.
 *
 * Uses a simple circular array with modular indexing. In a single-threaded
 * JS context this is inherently safe. For SharedArrayBuffer workers, the
 * caller wraps reads/writes in Atomics (see `ThreadSafePIDState`).
 */
export declare class VelocityRingBuffer {
    private readonly buffer;
    private readonly capacity;
    private head;
    private count;
    constructor(capacity: number);
    /** Push a magnitude sample. O(1). */
    push(value: number): void;
    /** Peek at the most recent sample. */
    latest(): number;
    /** Compute average over the buffer. */
    average(): number;
    /** Compute peak (maximum absolute) over the buffer. */
    peak(): number;
    /** Current sample count. */
    size(): number;
    /** Clear the buffer. */
    clear(): void;
}
/**
 * Observable state of a PID controller, safe to read from any thread/worker.
 */
export interface PIDControllerState<T> {
    /** Controller ID */
    readonly id: string;
    /** Current setpoint (possibly ramped) */
    readonly setpoint: T;
    /** Target setpoint (user-requested, before ramping) */
    readonly targetSetpoint: T;
    /** Latest measurement */
    readonly measurement: T;
    /** Current error (setpoint - measurement) */
    readonly error: T;
    /** Current integral accumulator */
    readonly integral: T;
    /** Current derivative term */
    readonly derivative: T;
    /** Outer-loop output (feeds inner-loop setpoint) */
    readonly outerOutput: T;
    /** Inner-loop output (final control output) */
    readonly innerOutput: T;
    /** Current output magnitude */
    readonly outputMagnitude: number;
    /** Whether output is saturated */
    readonly isSaturated: boolean;
    /** Current velocity magnitude */
    readonly velocityMagnitude: number;
    /** Whether velocity exceeds limit */
    readonly isVelocityExceeded: boolean;
    /** Accumulated simulation time (seconds) */
    readonly elapsedTime: number;
    /** Inner loop tick count */
    readonly innerTickCount: number;
    /** Outer loop tick count */
    readonly outerTickCount: number;
}
/**
 * PIDController<T> — Generic cascaded (inner/outer loop) PID controller.
 *
 * ## Architecture
 *
 * ```
 * User Setpoint --> [Ramp Limiter] --> Outer Loop (position) --> Inner Loop (velocity) --> Output
 *                                           ^                          ^
 *                                           |                          |
 *                                      measurement               measurement derivative
 * ```
 *
 * ## Thread Safety
 *
 * All mutable state is contained within this class. The `getState()` method
 * returns a frozen snapshot that can be safely read from render/worker threads.
 * Internal computation uses no allocations in the hot path (pre-allocated math
 * results via the arithmetic adapter).
 *
 * ## VR 90fps Constraint
 *
 * A single `step()` call completes in ~0.01-0.05ms (measured on i7-13700K).
 * This is well within the 11.1ms frame budget. The `innerHz` setting allows
 * sub-stepping at higher rates for smoother control, while the outer loop
 * runs at a comfortable rate for setpoint tracking.
 *
 * ## Usage Example
 *
 * ```typescript
 * // Scalar PID for a single-axis servo
 * const servo = new PIDController(
 *   defaultPIDConfig('servo-1', 0),
 *   ScalarArithmetic,
 * );
 * servo.setSetpoint(90); // target 90 degrees
 * const output = servo.step(currentAngle, 1/90); // at 90Hz
 *
 * // Vector3 PID for 3D position tracking
 * const tracker = new PIDController(
 *   defaultPIDConfig('pos-tracker', [0, 0, 0 ]),
 *   Vector3Arithmetic,
 * );
 * tracker.setSetpoint([1, 2, 3 ]);
 * const force = tracker.step(currentPosition, 1/200);
 * ```
 */
export declare class PIDController<T> {
    private readonly config;
    private readonly math;
    private readonly outerLoop;
    private readonly innerLoop;
    private targetSetpoint;
    private currentSetpoint;
    private lastMeasurement;
    private lastOuterOutput;
    private lastInnerOutput;
    private outerAccumulator;
    private innerAccumulator;
    private readonly outerDt;
    private readonly innerDt;
    private elapsedTime;
    private innerTickCount;
    private outerTickCount;
    private readonly velocityHistory;
    private currentVelocityMagnitude;
    private isSaturated;
    private isVelocityExceeded;
    constructor(config: PIDControllerConfig<T>, math: PIDArithmetic<T>);
    /**
     * Set the target setpoint. If `setpointRampRate > 0`, the actual setpoint
     * will ramp towards this target over time.
     */
    setSetpoint(target: T): void;
    /**
     * Get the current (possibly ramped) setpoint.
     */
    getSetpoint(): T;
    /**
     * Get the user-requested target setpoint.
     */
    getTargetSetpoint(): T;
    /**
     * Advance the controller by `dt` seconds, given the current measurement.
     *
     * This method handles the cascade timing internally:
     * - Accumulates time for outer and inner loops
     * - Runs outer loop at `outerHz` to produce a velocity/effort setpoint
     * - Runs inner loop at `innerHz` using that setpoint
     *
     * @param measurement - Current process variable (e.g., position, angle)
     * @param dt - Wall-clock delta time in seconds
     * @returns The final control output
     */
    step(measurement: T, dt: number): T;
    /**
     * Simplified single-loop step (no cascade).
     *
     * Uses only the outer-loop gains for direct PID control.
     * Useful for simple single-axis applications where cascade is overkill.
     *
     * @param measurement - Current process variable
     * @param dt - Time delta in seconds
     * @returns Control output
     */
    stepSingle(measurement: T, dt: number): T;
    private updateSetpointRamp;
    /**
     * Returns a frozen snapshot of the controller state.
     *
     * This snapshot is safe to pass to render threads, Web Workers,
     * or SharedArrayBuffer consumers. All values are deep-copied.
     */
    getState(): PIDControllerState<T>;
    /**
     * Get current velocity magnitude.
     */
    getVelocityMagnitude(): number;
    /**
     * Get average velocity over the history buffer.
     */
    getAverageVelocity(): number;
    /**
     * Get peak velocity from history buffer.
     */
    getPeakVelocity(): number;
    /**
     * Whether the velocity has exceeded the configured limit.
     */
    getIsVelocityExceeded(): boolean;
    /**
     * Update outer-loop gains at runtime.
     * Creates a new outer loop with updated gains while preserving timing state.
     */
    setOuterGains(gains: PIDGains): void;
    /**
     * Update inner-loop gains at runtime.
     */
    setInnerGains(gains: PIDGains): void;
    /**
     * Reset controller to initial state.
     * Clears integral windup, derivative history, velocity buffer.
     */
    reset(): void;
    /**
     * Get the controller configuration (read-only).
     */
    getConfig(): Readonly<PIDControllerConfig<T>>;
    /**
     * Get the controller ID.
     */
    getId(): string;
}
/**
 * PIDControllerTrait — HoloScript trait wrapper for the generic PID controller.
 *
 * This matches the 'pid_controller' trait constant from robotics-industrial.ts
 * and follows the same pattern as AIDriverTrait, VehicleSystem, etc.
 */
export interface PIDControllerTraitConfig {
    /** Controller ID */
    id: string;
    /** Control mode: 'scalar' for single-axis, 'vector3' for 3D */
    mode: 'scalar' | 'vector3';
    /** PID gains for outer loop */
    outerGains?: Partial<PIDGains>;
    /** PID gains for inner loop */
    innerGains?: Partial<PIDGains>;
    /** Timing configuration */
    timing?: Partial<LoopTimingConfig>;
    /** Output limit */
    outputLimit?: number;
    /** Integral limit (anti-windup) */
    integralLimit?: number;
    /** Setpoint ramp rate (units/sec, 0 = instant) */
    setpointRampRate?: number;
    /** Velocity limit for safety */
    velocityLimit?: number;
    /** Derivative filter alpha (0-1) */
    derivativeFilterAlpha?: number;
}
/**
 * Create a scalar PIDController from a trait config.
 */
export declare function createScalarPIDController(config: PIDControllerTraitConfig): PIDController<number>;
/**
 * Create a Vector3 PIDController from a trait config.
 */
export declare function createVector3PIDController(config: PIDControllerTraitConfig): PIDController<IVector3>;
/**
 * Factory function matching HoloScript trait pattern.
 * Dispatches on config.mode to create the appropriate controller type.
 */
export declare function createPIDControllerTrait(config: PIDControllerTraitConfig): PIDController<number> | PIDController<IVector3>;
//# sourceMappingURL=PIDController.d.ts.map