001// Copyright (c) FIRST and other WPILib contributors.
002// Open Source Software; you can modify and/or share it under the terms of
003// the WPILib BSD license file in the root directory of this project.
004
005package org.wpilib.math.optimization.solver;
006
007/** Solver options. */
008public class Options {
009  /** The solver will stop once the error is below this tolerance. */
010  public double tolerance = 1e-8;
011
012  /** The maximum number of solver iterations before returning a solution. */
013  public int maxIterations = 5000;
014
015  /** The maximum elapsed wall clock time in seconds before returning a solution. */
016  public double timeout = Double.POSITIVE_INFINITY;
017
018  /**
019   * Enables the feasible interior-point method.
020   *
021   * <p>When the inequality constraints are all feasible, step sizes are reduced when necessary to
022   * prevent them becoming infeasible again. This is useful when parts of the problem are
023   * ill-conditioned in infeasible regions (e.g., square root of a negative value). This can slow or
024   * prevent progress toward a solution though, so only enable it if necessary.
025   */
026  public boolean feasibleIPM = false;
027
028  /**
029   * Enables diagnostic output.
030   *
031   * <p>See <a
032   * href="https://sleipnirgroup.github.io/Sleipnir/md_usage.html#output">https://sleipnirgroup.github.io/Sleipnir/md_usage.html#output</a>
033   * for more information.
034   */
035  public boolean diagnostics = false;
036
037  /** Default options. */
038  public Options() {}
039
040  /**
041   * Sets the tolerance.
042   *
043   * @param tolerance The solver will stop once the error is below this tolerance.
044   * @return This Options object.
045   */
046  public Options withTolerance(double tolerance) {
047    this.tolerance = tolerance;
048    return this;
049  }
050
051  /**
052   * Sets the max iterations.
053   *
054   * @param maxIterations The maximum number of solver iterations before returning a solution.
055   * @return This Options object.
056   */
057  public Options withMaxIterations(int maxIterations) {
058    this.maxIterations = maxIterations;
059    return this;
060  }
061
062  /**
063   * Sets the timeout.
064   *
065   * @param timeout The maximum elapsed wall clock time in seconds before returning a solution.
066   * @return This Options object.
067   */
068  public Options withTimeout(double timeout) {
069    this.timeout = timeout;
070    return this;
071  }
072
073  /**
074   * Enables or disables the feasible interior-point method.
075   *
076   * <p>When the inequality constraints are all feasible, step sizes are reduced when necessary to
077   * prevent them becoming infeasible again. This is useful when parts of the problem are
078   * ill-conditioned in infeasible regions (e.g., square root of a negative value). This can slow or
079   * prevent progress toward a solution though, so only enable it if necessary.
080   *
081   * @param feasibleIPM Enables or disables the feasible interior-point method.
082   * @return This Options object.
083   */
084  public Options withFeasibleIPM(boolean feasibleIPM) {
085    this.feasibleIPM = feasibleIPM;
086    return this;
087  }
088
089  /**
090   * Enables or disables diagnostic output.
091   *
092   * @param diagnostics Enables or disables diagnostic output.
093   * @return This Options object.
094   */
095  public Options withDiagnostics(boolean diagnostics) {
096    this.diagnostics = diagnostics;
097    return this;
098  }
099}