chrome/browser/ash/power/auto_screen_brightness/gaussian_trainer.cc

// Copyright 2018 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#include "chrome/browser/ash/power/auto_screen_brightness/gaussian_trainer.h"

#include <algorithm>
#include <cmath>
#include <limits>

#include "ash/constants/ash_features.h"
#include "base/logging.h"
#include "base/metrics/field_trial_params.h"
#include "base/metrics/histogram_functions.h"
#include "base/metrics/histogram_macros.h"
#include "chrome/browser/ash/power/auto_screen_brightness/utils.h"

namespace ash {
namespace power {
namespace auto_screen_brightness {

namespace {

// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
// Logs whether a new brightness exceeded the reasonable distance from the old
// brightness. A reasonable distance is defined by the params
// |brightness_step_size| and |model_brightness_step_size|.
enum class BoundedBrightnessChange {
  // User's chosen new brightness is within their [lower_bound, upper_bound].
  kUserWithinBounds = 0,
  // Target brightness has a reasonable distance model's predicted brightness.
  kModelWithinBounds = 1,
  // User's chosen new brightness is below their lower bound.
  kUserLower = 2,
  // User's chosen new brightness is above their upper bound.
  kUserUpper = 3,
  // Target brightness is below model's predicted brightness and exceeded the
  // bound.
  kModelLower = 4,
  // Target brightness is above model's predicted brightness and exceeded the
  // bound.
  kModelUpper = 5,
  kMaxValue = kModelUpper
};

// Returns a |BoundedBrightnessChange| to be logged to UMA.
// |is_lower_bound_exceeded| is nullopt if the new brightness is within the
// bounds.
BoundedBrightnessChange GetBoundedBrightnessChange(
    std::optional<bool> is_lower_bound_exceeded,
    bool is_user) {
  if (!is_lower_bound_exceeded.has_value()) {
    if (is_user) {
      return BoundedBrightnessChange::kUserWithinBounds;
    }
    return BoundedBrightnessChange::kModelWithinBounds;
  }

  if (*is_lower_bound_exceeded) {
    if (is_user) {
      return BoundedBrightnessChange::kUserLower;
    }
    return BoundedBrightnessChange::kModelLower;
  }

  if (is_user) {
    return BoundedBrightnessChange::kUserUpper;
  }
  return BoundedBrightnessChange::kModelUpper;
}

constexpr double kTol = 1e-10;

// Calculates lower bound from |reference_brightness| using the min of
// 1. Division by a scaling factor and
// 2. Subtraction of an offset.
double BrightnessLowerBound(double reference_brightness,
                            double scale,
                            double offset) {
  DCHECK_GT(scale, 0.0);
  DCHECK_GE(offset, 0.0);

  return std::clamp(reference_brightness / scale, 0.0,
                     std::max(reference_brightness - offset, 0.0));
}

// Calculates upper bound from |reference_brightness| using the max of
// 1. Multiplication by a scaling factor and
// 2. Addition of an offset.
// The upper bound is also capped at 100.0.
double BrightnessUpperBound(double reference_brightness,
                            double scale,
                            double offset) {
  DCHECK_GT(scale, 0.0);
  DCHECK_GE(offset, 0.0);

  return std::clamp(reference_brightness * scale,
                     std::min(reference_brightness + offset, 100.0), 100.0);
}

// Returns whether |brightness| is an outlier from a |reference_brightness|.
bool IsBrightnessOutlier(double brightness,
                         double reference_brightness,
                         const GaussianTrainer::Params& params) {
  DCHECK_GE(reference_brightness, 0.0);
  DCHECK_LE(reference_brightness, 100.0);
  return brightness < BrightnessLowerBound(reference_brightness,
                                           params.brightness_bound_scale,
                                           params.brightness_bound_offset) ||
         brightness > BrightnessUpperBound(reference_brightness,
                                           params.brightness_bound_scale,
                                           params.brightness_bound_offset);
}

// User's selected |brightness_new| may not be the value that the user needs for
// various reasons, e.g. they could overshoot. Hence this function calculates
// the bounded brightness change based on a heuristic magnitude. The new
// brightness is bounded within a factor of 1+|brightness_step_size| from
// |brightness_old|.
double BoundedBrightnessAdjustment(double brightness_old,
                                   double brightness_new,
                                   double brightness_step_size,
                                   bool is_user) {
  const double lower_bound = brightness_old / (1.0 + brightness_step_size);
  const double upper_bound = brightness_old * (1.0 + brightness_step_size);

  const bool exceeded_upper = brightness_new > upper_bound;
  const bool exceeded_lower = brightness_new < lower_bound;

  const BoundedBrightnessChange change = GetBoundedBrightnessChange(
      exceeded_lower || exceeded_upper ? std::optional<bool>(exceeded_lower)
                                       : std::nullopt,
      is_user);
  UMA_HISTOGRAM_ENUMERATION(
      "AutoScreenBrightness.ModelTraining.BrightnessChange", change);

  return std::clamp(brightness_new, lower_bound, upper_bound) - brightness_old;
}

// Calculates recommended brightness change, given old brightness, user's
// selected new brghtness and model's predicted brightness.
double ModelPredictionAdjustment(double brightness_old,
                                 double brightness_new,
                                 double model_brightness,
                                 const GaussianTrainer::Params& params) {
  DCHECK_GE(brightness_old, 0.0);
  DCHECK_LE(brightness_old, 100.0);
  DCHECK_GE(brightness_new, 0.0);
  DCHECK_LE(brightness_new, 100.0);
  DCHECK_GE(model_brightness, 0.0);
  DCHECK_LE(model_brightness, 100.0);

  const double bounded_user_adjustment = BoundedBrightnessAdjustment(
      brightness_old, brightness_new, params.brightness_step_size,
      true /* is_user */);

  DCHECK_GE(bounded_user_adjustment, -100.0);
  DCHECK_LE(bounded_user_adjustment, 100.0);

  const double target_brightness = brightness_old + bounded_user_adjustment;
  DCHECK_GE(target_brightness, 0.0);
  DCHECK_LE(target_brightness, 100.0);

  // Check if model prediction and user adjustment are consistent.
  const bool is_consistent =
      (model_brightness >= target_brightness && bounded_user_adjustment >= 0) ||
      (model_brightness <= target_brightness && bounded_user_adjustment <= 0);
  UMA_HISTOGRAM_BOOLEAN(
      "AutoScreenBrightness.ModelTraining.ModelUserConsistent", is_consistent);

  // If model's prediction is consistent with user's selection, then no
  // brightness change will be necessary.
  if (is_consistent) {
    return 0.0;
  }

  // Model prediction is incorrect, calculate the change we need to make by
  // treating |model_brightness| as the old brightness and |target_brightness|
  // as the new brightness.
  return BoundedBrightnessAdjustment(model_brightness, target_brightness,
                                     params.model_brightness_step_size,
                                     false /* is_user */);
}

double Gaussian(double x, double sigma) {
  double xs = x / sigma;
  return std::exp(-xs * xs);
}

void LogModelCurveError(double error, bool model_updated) {
  DCHECK_GE(error, 0.0);
  const std::string histogram_name =
      std::string("AutoScreenBrightness.ModelTraining.Inaccuracy.") +
      (model_updated ? "Update" : "NoUpdate");
  base::UmaHistogramPercentageObsoleteDoNotUse(histogram_name,
                                               std::round(error));
}

}  // namespace

TrainingResult::TrainingResult() = default;
TrainingResult::TrainingResult(
    const std::optional<MonotoneCubicSpline>& new_curve,
    double error)
    : new_curve(new_curve), error(error) {}

TrainingResult::TrainingResult(const TrainingResult& result) = default;
TrainingResult::~TrainingResult() = default;

GaussianTrainer::Params::Params() = default;

GaussianTrainer::GaussianTrainer() {
  params_.brightness_bound_scale = GetFieldTrialParamByFeatureAsDouble(
      features::kAutoScreenBrightness, "brightness_bound_scale",
      params_.brightness_bound_scale);
  if (params_.brightness_bound_scale <= 0.0) {
    valid_params_ = false;
    LogParameterError(ParameterError::kModelError);
    return;
  }

  params_.brightness_bound_offset = GetFieldTrialParamByFeatureAsDouble(
      features::kAutoScreenBrightness, "brightness_bound_offset",
      params_.brightness_bound_offset);
  if (params_.brightness_bound_offset < 0.0) {
    valid_params_ = false;
    LogParameterError(ParameterError::kModelError);
    return;
  }

  params_.brightness_step_size = GetFieldTrialParamByFeatureAsDouble(
      features::kAutoScreenBrightness, "brightness_step_size",
      params_.brightness_step_size);
  if (params_.brightness_step_size <= 0.0) {
    valid_params_ = false;
    LogParameterError(ParameterError::kModelError);
    return;
  }

  params_.model_brightness_step_size = GetFieldTrialParamByFeatureAsDouble(
      features::kAutoScreenBrightness, "model_brightness_step_size",
      params_.model_brightness_step_size);
  if (params_.model_brightness_step_size <= 0.0) {
    valid_params_ = false;
    LogParameterError(ParameterError::kModelError);
    return;
  }

  params_.sigma = GetFieldTrialParamByFeatureAsDouble(
      features::kAutoScreenBrightness, "sigma", params_.sigma);
  if (params_.sigma <= 0.0) {
    valid_params_ = false;
    LogParameterError(ParameterError::kModelError);
    return;
  }

  params_.low_log_lux_threshold = GetFieldTrialParamByFeatureAsDouble(
      features::kAutoScreenBrightness, "low_log_lux_threshold",
      params_.low_log_lux_threshold);
  params_.high_log_lux_threshold = GetFieldTrialParamByFeatureAsDouble(
      features::kAutoScreenBrightness, "high_log_lux_threshold",
      params_.high_log_lux_threshold);
  if (params_.low_log_lux_threshold >= params_.high_log_lux_threshold) {
    valid_params_ = false;
    LogParameterError(ParameterError::kModelError);
    return;
  }

  params_.min_grad_low_lux = GetFieldTrialParamByFeatureAsDouble(
      features::kAutoScreenBrightness, "min_grad_low_lux",
      params_.min_grad_low_lux);
  params_.min_grad_high_lux = GetFieldTrialParamByFeatureAsDouble(
      features::kAutoScreenBrightness, "min_grad_high_lux",
      params_.min_grad_high_lux);

  params_.min_grad = GetFieldTrialParamByFeatureAsDouble(
      features::kAutoScreenBrightness, "min_grad", params_.min_grad);
  params_.max_grad = GetFieldTrialParamByFeatureAsDouble(
      features::kAutoScreenBrightness, "max_grad", params_.max_grad);

  if (params_.min_grad_low_lux < 0.0 || params_.min_grad_low_lux >= 1.0) {
    valid_params_ = false;
    LogParameterError(ParameterError::kModelError);
    return;
  }

  if (params_.min_grad_high_lux < 0.0 || params_.min_grad_high_lux >= 1.0) {
    valid_params_ = false;
    LogParameterError(ParameterError::kModelError);
    return;
  }

  if (params_.min_grad < 0.0 || params_.min_grad >= 1.0) {
    valid_params_ = false;
    LogParameterError(ParameterError::kModelError);
    return;
  }

  if (params_.min_grad < params_.min_grad_low_lux) {
    valid_params_ = false;
    LogParameterError(ParameterError::kModelError);
    return;
  }

  if (params_.min_grad < params_.min_grad_high_lux) {
    valid_params_ = false;
    LogParameterError(ParameterError::kModelError);
    return;
  }

  if (params_.max_grad < 1.0) {
    valid_params_ = false;
    LogParameterError(ParameterError::kModelError);
    return;
  }

  params_.min_brightness = GetFieldTrialParamByFeatureAsDouble(
      features::kAutoScreenBrightness, "min_brightness",
      params_.min_brightness);
  if (params_.min_brightness < 0.0) {
    valid_params_ = false;
    LogParameterError(ParameterError::kModelError);
    return;
  }
}

GaussianTrainer::~GaussianTrainer() = default;

bool GaussianTrainer::HasValidConfiguration() const {
  return valid_params_;
}

bool GaussianTrainer::SetInitialCurves(
    const MonotoneCubicSpline& global_curve,
    const MonotoneCubicSpline& current_curve) {
  DCHECK(valid_params_);

  // This function could be called again if the caller wants to reset the
  // curves.
  global_curve_.emplace(global_curve);
  current_curve_.emplace(current_curve);

  ambient_log_lux_ = current_curve_->GetControlPointsX();
  brightness_ = current_curve_->GetControlPointsY();
  const size_t num_points = ambient_log_lux_.size();

  // Global curve and personal curve should have the same ambient log lux.
  const std::vector<double> global_log_lux = global_curve_->GetControlPointsX();
  DCHECK_EQ(global_log_lux.size(), num_points);

  for (size_t i = 0; i < num_points; ++i) {
    DCHECK_LE(std::abs(global_log_lux[i] - ambient_log_lux_[i]), kTol);
  }

  // Calculate |min_ratios_| and |max_ratios_| from global curve.
  min_ratios_.resize(num_points - 1);
  max_ratios_.resize(num_points - 1);
  const std::vector<double> global_brightness =
      global_curve_->GetControlPointsY();

  // TODO(jiameng): may revise to allow 0 as a control point.
  DCHECK_GT(global_brightness[0], 0);

  for (size_t i = 0; i < num_points - 1; ++i) {
    double min_grad = params_.min_grad;
    if (global_log_lux[i] < params_.low_log_lux_threshold) {
      min_grad = params_.min_grad_low_lux;
    } else if (global_log_lux[i] > params_.high_log_lux_threshold) {
      min_grad = params_.min_grad_high_lux;
    }

    const double ratio = global_brightness[i + 1] / global_brightness[i];
    DCHECK_GE(ratio, 1);
    min_ratios_[i] = std::pow(ratio, min_grad);
    max_ratios_[i] = std::pow(ratio, params_.max_grad);
  }

  if (!IsInitialPersonalCurveValid()) {
    // Use global curve instead if personal curve isn't valid.
    current_curve_.emplace(global_curve);
    brightness_ = current_curve_->GetControlPointsY();
    return false;
  }

  return true;
}

MonotoneCubicSpline GaussianTrainer::GetGlobalCurve() const {
  DCHECK(valid_params_);
  DCHECK(global_curve_);
  return *global_curve_;
}

MonotoneCubicSpline GaussianTrainer::GetCurrentCurve() const {
  DCHECK(valid_params_);
  DCHECK(current_curve_);
  return *current_curve_;
}

TrainingResult GaussianTrainer::Train(
    const std::vector<TrainingDataPoint>& data) {
  DCHECK(global_curve_);
  DCHECK(current_curve_);
  DCHECK(!data.empty());

  for (const auto& data_point : data) {
    AdjustCurveWithSingleDataPoint(data_point);
  }

  if (!need_to_update_curve_) {
    const double error = CalculateCurveError(data);
    LogModelCurveError(error, false /* model_updated */);
    return TrainingResult(std::nullopt, error);
  }

  need_to_update_curve_ = false;

  const auto new_curve = MonotoneCubicSpline::CreateMonotoneCubicSpline(
      ambient_log_lux_, brightness_);
  if (!new_curve) {
    return TrainingResult(std::nullopt, 0 /* error */);
  }

  current_curve_ = new_curve;

  const double error = CalculateCurveError(data);
  LogModelCurveError(error, true /* model_updated */);
  return TrainingResult(current_curve_, error);
}

bool GaussianTrainer::IsInitialPersonalCurveValid() const {
  // |global_curve_| is valid by construction.
  if (*global_curve_ == *current_curve_)
    return true;

  for (size_t i = 0; i < brightness_.size() - 1; ++i) {
    const double ratio = brightness_[i + 1] / brightness_[i];
    if (ratio < min_ratios_[i] || ratio > max_ratios_[i])
      return false;
  }

  return true;
}

void GaussianTrainer::AdjustCurveWithSingleDataPoint(
    const TrainingDataPoint& data) {
  const double brightness_global =
      global_curve_->Interpolate(data.ambient_log_lux);

  // Check if this |data| is an outlier and should be ignored. It's an outlier
  // if its original/old brightness is too far off from the brightness as
  // predicted by the global curve. This assumes the global curve is reasonably
  // accurate.
  const bool is_brightness_outlier =
      IsBrightnessOutlier(data.brightness_old, brightness_global, params_);
  UMA_HISTOGRAM_BOOLEAN("AutoScreenBrightness.ModelTraining.BrightnessOutlier",
                        is_brightness_outlier);

  if (is_brightness_outlier) {
    return;
  }

  // Calculate how much adjustment we need to make to the current personal
  // curve at |data.ambient_log_lux|.
  const double model_brightness =
      current_curve_->Interpolate(data.ambient_log_lux);
  const double brightness_adjustment = ModelPredictionAdjustment(
      data.brightness_old, data.brightness_new, model_brightness, params_);

  if (std::abs(brightness_adjustment) <= kTol)
    return;

  need_to_update_curve_ = true;

  // Index of the log-lux in |ambient_log_lux_| that's closest to
  // |data.ambient_log_lux|.
  size_t center_index = 0;
  double min_dist = std::numeric_limits<double>::max();
  for (size_t i = 0; i < ambient_log_lux_.size(); ++i) {
    // Adjust brightness of each control point in the current brightness curve.
    const double dist = std::abs(data.ambient_log_lux - ambient_log_lux_[i]);
    brightness_[i] += brightness_adjustment * Gaussian(dist, params_.sigma);

    if (dist < min_dist) {
      center_index = i;
      min_dist = dist;
    }
  }

  EnforceMonotonicity(center_index);
}

void GaussianTrainer::EnforceMonotonicity(size_t center_index) {
  DCHECK_LT(center_index, ambient_log_lux_.size());
  brightness_[center_index] =
      std::clamp(brightness_[center_index], params_.min_brightness, 100.0);

  // Updates control points to the left of |center_index| so that brightness
  // values satisfy min/max ratio requirement.
  for (size_t i = center_index; i > 0; --i) {
    const double min_value = brightness_[i] / max_ratios_[i - 1];
    const double max_value = brightness_[i] / min_ratios_[i - 1];
    brightness_[i - 1] = std::clamp(brightness_[i - 1], min_value, max_value);
    if (brightness_[i - 1] > 100.0) {
      brightness_[i - 1] = 100.0;
    }
  }

  // Updates control points to the right of |center_index| so that brightness
  // values satisfy min/max ratio requirement.
  for (size_t i = center_index; i < ambient_log_lux_.size() - 1; ++i) {
    const double min_value = brightness_[i] * min_ratios_[i];
    const double max_value = brightness_[i] * max_ratios_[i];
    brightness_[i + 1] = std::clamp(brightness_[i + 1], min_value, max_value);
    if (brightness_[i + 1] > 100.0) {
      brightness_[i + 1] = 100.0;
    }
  }

#ifndef NDEBUG
  // Check that final |brightness_| array is monotonic across whole range and
  // each value is in [0, 100].
  for (size_t i = 0; i < ambient_log_lux_.size() - 1; ++i) {
    DCHECK_GE(brightness_[i], 0);
    DCHECK_LE(brightness_[i], 100);
    DCHECK_LE(brightness_[i], brightness_[i + 1]);
  }

  DCHECK_GE(brightness_.back(), 0);
  DCHECK_LE(brightness_.back(), 100);
#endif
}

double GaussianTrainer::CalculateCurveError(
    const std::vector<TrainingDataPoint>& data) const {
  DCHECK(current_curve_);
  double error = 0.0;
  for (const auto& data_point : data) {
    error += std::abs(data_point.brightness_new -
                      current_curve_->Interpolate(data_point.ambient_log_lux));
  }
  return error / data.size();
}

}  // namespace auto_screen_brightness
}  // namespace power
}  // namespace ash