pid

type Controller interface {
	// Update computes the controller output based on the current process variable.
	// Returns the computed output.
	Update(pv ProcessVariable) Output

	// UpdateValue is a convenience method that takes a raw float64 value.
	// Uses the current time as the timestamp.
	UpdateValue(value float64) Output

	// Reset clears all internal state (integral accumulator, previous values).
	Reset()

	// SetSetpoint updates the target value.
	SetSetpoint(setpoint float64)

	// Setpoint returns the current setpoint.
	Setpoint() float64

	// SetGains updates the PID gains.
	SetGains(kp, ki, kd float64)

	// Gains returns the current PID gains.
	Gains() (kp, ki, kd float64)
}

type Output interface {
	// Value returns the computed output value.
	// The interpretation depends on the application:
	// - For rate limiting: delay in seconds
	// - For PoW difficulty: difficulty adjustment factor
	// - For temperature control: heater power level
	Value() float64

	// Clamped returns true if the output was clamped to limits.
	Clamped() bool

	// Components returns the individual P, I, D contributions for debugging.
	Components() (p, i, d float64)
}

type ProcessVariable interface {
	// Value returns the current process variable value.
	// The value should typically be normalized to a range where the setpoint
	// makes sense (e.g., 0.0-1.0 for percentage-based control, or absolute
	// values for things like hash rate or block time).
	Value() float64

	// Timestamp returns when this measurement was taken.
	// This is used for derivative calculations and staleness detection.
	Timestamp() time.Time
}

type SimpleProcessVariable struct {
	V float64
	T time.Time
}

type Source interface {
	// Sample returns the current process variable measurement.
	// This should be efficient as it may be called frequently.
	Sample() ProcessVariable

	// Name returns a human-readable name for this source (for logging/debugging).
	Name() string
}

type Tuning struct {
	Kp float64 // Proportional gain
	Ki float64 // Integral gain
	Kd float64 // Derivative gain

	Setpoint float64 // Target value

	// Derivative filtering (0.0-1.0, lower = more filtering)
	DerivativeFilterAlpha float64

	// Anti-windup limits for integral term
	IntegralMin float64
	IntegralMax float64

	// Output limits
	OutputMin float64
	OutputMax float64
}