appsettings.json

/* ============================================================
   GpuPowerControl - External Configuration File
   ============================================================
   This file allows you to customize thermal control behavior
   for your specific GPU model without recompilation.

   Place this file next to the GpuPowerControl.exe.
   Comments (line and block) are automatically stripped before parsing.

   After editing, simply restart the application to apply changes.
   ============================================================ */

{
   /* =========================================
      THERMAL CONTROL
      Temperature thresholds that govern when
      the PID controller engages/disengages.
      ========================================= */
   "thermal": {
     // The temperature (°C) at which PID control activates.
     // When GPU temp >= triggerTemp, the controller starts managing power.
     // Lower values engage cooling earlier; higher values delay engagement.
     "triggerTemp": 80,

     // The desired temperature (°C) the PID controller maintains.
     // PID calculates power adjustments to keep GPU at this target.
     // Typically set 3-5°C below triggerTemp for smooth engagement.
     "targetTemp": 75,

     // Critical temperature (°C) that triggers emergency safety.
     // At or above this temp, power is forced to minimum immediately.
     // This is a hard safety override to prevent hardware damage.
     "emergencyTemp": 90,

     // Hysteresis margin (°C) for disengaging control.
     // Control disengages when temp drops below (targetTemp - exitHysteresis).
     // Prevents rapid toggling between IDLE and CONTROLLING states.
     "exitHysteresis": 5,

     // How many seconds ahead to predict temperature rise.
     // Used for predictive triggering before hitting triggerTemp.
     // Allows the controller to engage before thermal runaway occurs.
     "lookaheadSeconds": 1.5,

     // Minimum temperature (°C) for predictive triggering.
     // Predictive trigger only active when temp >= predictiveFloor.
     // Prevents false triggers at low temperatures.
     "predictiveFloor": 70
   },

   /* =========================================
      PID CONTROLLER
      Proportional-Integral-Derivative tuning.
      =========================================
      PID output is mapped to power adjustments:
        powerDelta = -(Kp * error + Ki * integral + Kd * derivative)
      Positive error (temp > target) → negative delta (reduce power)
      Negative error (temp < target) → positive delta (increase power)
      ========================================= */
   "pid": {
     // Proportional gain. Scales immediate temperature error.
     // Higher Kp = more aggressive power reduction for same overshoot.
     // Default 20.0 means 1°C above target = 20W power reduction.
     // Increase for faster response, decrease for smoother control.
     "kp": 20.0,

     // Integral gain. Scales accumulated error over time.
     // Corrects persistent small offsets that proportional term can't fix.
     // Only accumulates when |error| <= integralBand (15°C).
     // Reset to 0 when control engages to prevent over-correction spikes.
     "ki": 0.5,

     // Derivative gain. Scales rate of temperature change.
     // Provides braking effect when temp is rising (derivative > 0 only).
     // Preemptively reduces power before temperature gets worse.
     // Zero effect when temp is stable or falling.
     "kd": 2.5,

     // Upper clamp for integral term (anti-windup).
     // Prevents integral from growing beyond this value.
     // Limits maximum accumulated correction to prevent overshoot.
     "integralMax": 500,

     // Lower clamp for integral term (anti-windup).
     // Prevents integral from dropping below this value.
     // Symmetric clamping keeps integral in a safe range.
     "integralMin": -500
   },

   /* =========================================
      POWER LIMITS & GATING
      Controls how power adjustments are applied.
      The five-gate system prevents power change spam:
      1. Rate Limiter - caps how fast power can change per second
      2. One-Way Valve - never increases power at/above triggerTemp
      3. Min Delta - filters trivial adjustments
      4. Interval Cooldown - minimum time between changes
      5. Exit Check - disengages when temp drops below threshold
      ========================================= */
   "power": {
     // Default maximum power limit (Watts).
     // Initial power limit, and the value restored when control disengages.
     // CRITICAL: Adjust this to match your GPU's maximum power capability.
     // Common values: GTX 1080 Ti ~250W, RTX 3080 ~340W, RTX 4090 ~450W
     "defaultMaxPower": 600,

     // Default minimum power limit (Watts).
     // Operating floor for PID control: the lowest power the controller will
     // normally set while engaged. Clamped to the GPU's hardware range.
     // NOTE: emergency thermal protection always uses the GPU's hardware
     // minimum (reported by NVML), regardless of this setting.
     // Adjust based on your GPU's minimum sustainable power.
     "defaultMinPower": 150,

     // Minimum power change (Watts) when FAR from target temperature.
     // Filters out trivial adjustments when temperature is outside the
     // near-target band. Prevents noisy power oscillation during active control.
     "minPowerDeltaFarW": 10,

     // Minimum power change (Watts) when NEAR target temperature.
     // Enables finer adjustments when close to target for stable control.
     // Smaller threshold allows micro-adjustments for precision.
     "minPowerDeltaNearW": 3,

     // Minimum interval (ms) between consecutive power limit changes.
     // Prevents rapid power oscillation by enforcing a cooldown period.
     // Bypassed if temperature derivative exceeds the bypass threshold.
     "minAdjustmentIntervalMs": 2500,

     // Maximum rate of power increases (Watts/second) during normal PID control.
     // Caps how fast power can ramp up to prevent thermal runaway.
     // Controls the slope of power restoration after emergency.
     "normalMaxPowerIncreaseRateWps": 15,

     // Maximum rate of power increases (Watts/second) during emergency recovery.
     // Slower recovery rate prevents re-heating after emergency cooling.
     // Gradual restoration gives thermal mass time to dissipate heat.
     "emergencyRecoveryRateWps": 5,

     // Duration (ms) of emergency power hold.
     // GPU stays at minimum power for this long before recovery begins.
     // Allows sufficient cooling time before gradually restoring power.
     "emergencyHoldMs": 5000
   },

   /* =========================================
      TIMING
      Control loop intervals and timing.
      ========================================= */
   "timing": {
     // PID calculation interval (seconds).
     // How often the PID controller computes power adjustments.
     // 0.25s = 4 Hz control loop frequency.
     "defaultDt": 0.25,

     // Sleep duration (ms) while actively controlling temperature.
     // Shorter = more responsive but higher CPU usage.
     // Should match defaultDt * 1000 for consistent timing.
     "controllingSleepMs": 250,

     // Sleep duration (ms) while idle (monitoring, not controlling).
     // Longer idle sleep reduces overhead when GPU is cool.
     // Polling interval for temperature checks in IDLE state.
     "idleSleepMs": 1500
   },

   /* =========================================
      FAULT TOLERANCE
      Error handling and safety behavior.
      ========================================= */
   "faultTolerance": {
     // Number of consecutive NVML read failures before forcing emergency temp.
     // After this many failures, emergencyTemp (90°C) is assumed for safety.
     // Prevents the controller from spinning with no valid data.
     "maxConsecutiveReadFailures": 5
   }
}