Refactor solvers package

Author: raharrison

src/main/java/uk/co/ryanharrison/mathengine/solvers/BisectionSolver.java

@@ -1,12 +1,52 @@
 package uk.co.ryanharrison.mathengine.solvers;
 
 /**
- * Enumeration of convergence criterion which decide whether or not a root
- * finding algorithm has converged
+ * Defines how convergence is determined in root-finding algorithms.
+ * <p>
+ * Different convergence criteria are appropriate for different scenarios:
+ * </p>
+ * <ul>
+ *     <li><b>{@link #NumberOfIterations}</b>: Use when you need a result within a fixed
+ *         computational budget, regardless of accuracy</li>
+ *     <li><b>{@link #WithinTolerance}</b>: Use when you need a result that meets a specific
+ *         accuracy requirement, regardless of computation time</li>
+ * </ul>
  *
- * @author Ryan Harrison
+ * <h2>Tolerance Semantics by Algorithm:</h2>
+ * The specific meaning of "within tolerance" varies by algorithm:
+ * <ul>
+ *     <li><b>Bisection:</b> |upper - lower| / 2 < tolerance (half-bracket width)</li>
+ *     <li><b>Brent:</b> |upper - lower| < tolerance (bracket width)</li>
+ *     <li><b>Newton-Raphson:</b> |f(x)| < tolerance (function value magnitude)</li>
+ *     <li><b>Newton-Bisection:</b> |dx| < tolerance (step size magnitude)</li>
+ * </ul>
  *
+ * @see EquationSolver#getConvergenceCriteria()
  */
 public enum ConvergenceCriteria {
-    NumberOfIterations, WithinTolerance
+
+    /**
+     * Converge after a fixed number of iterations regardless of accuracy.
+     * <p>
+     * The algorithm will stop after completing the specified number of iterations
+     * and return the current estimate, even if the tolerance criterion has not been met.
+     * </p>
+     * <p>
+     * <b>Use when:</b> Computational budget is limited or approximate solutions are acceptable.
+     * </p>
+     */
+    NumberOfIterations,
+
+    /**
+     * Converge when the result satisfies the tolerance condition.
+     * <p>
+     * The algorithm will continue iterating until the tolerance criterion is met,
+     * up to the maximum number of iterations. If tolerance is not achieved within
+     * the iteration limit, a {@link ConvergenceException} is thrown.
+     * </p>
+     * <p>
+     * <b>Use when:</b> Accuracy is critical and you can afford the computational cost.
+     * </p>
+     */
+    WithinTolerance
 }

src/main/java/uk/co/ryanharrison/mathengine/solvers/BrentSolver.java

@@ -0,0 +1,77 @@
+package uk.co.ryanharrison.mathengine.solvers;
+
+/**
+ * Exception thrown when a root-finding algorithm fails to converge within the specified criteria.
+ * <p>
+ * This typically occurs when:
+ * </p>
+ * <ul>
+ *     <li>The maximum number of iterations is exceeded without meeting the tolerance requirement</li>
+ *     <li>The tolerance criterion cannot be satisfied due to numerical precision limits</li>
+ *     <li>The algorithm gets stuck in a cyclic pattern</li>
+ * </ul>
+ *
+ * <h2>Example:</h2>
+ * <pre>{@code
+ * try {
+ *     double root = solver.solve();
+ * } catch (ConvergenceException e) {
+ *     System.err.println("Failed to converge after " + e.getIterations() + " iterations");
+ *     System.err.println("Last estimate: " + e.getLastEstimate());
+ * }
+ * }</pre>
+ *
+ * @see SolverException
+ */
+public class ConvergenceException extends SolverException {
+
+    private final int iterations;
+    private final double lastEstimate;
+    private final double tolerance;
+
+    /**
+     * Constructs a new convergence exception with detailed context.
+     *
+     * @param message      the detail message explaining why convergence failed
+     * @param iterations   the number of iterations completed before failure
+     * @param lastEstimate the last estimated value before giving up
+     * @param tolerance    the tolerance criterion that could not be met
+     */
+    public ConvergenceException(String message, int iterations, double lastEstimate, double tolerance) {
+        super(String.format("%s (iterations: %d, last estimate: %.10g, tolerance: %.2e)",
+                message, iterations, lastEstimate, tolerance));
+        this.iterations = iterations;
+        this.lastEstimate = lastEstimate;
+        this.tolerance = tolerance;
+    }
+
+    /**
+     * Returns the number of iterations completed before convergence failure.
+     *
+     * @return the iteration count at failure
+     */
+    public int getIterations() {
+        return iterations;
+    }
+
+    /**
+     * Returns the last estimated root value before the algorithm gave up.
+     * <p>
+     * This value may be close to the actual root even though convergence criteria were not met.
+     * </p>
+     *
+     * @return the last estimated root value
+     */
+    public double getLastEstimate() {
+        return lastEstimate;
+    }
+
+    /**
+     * Returns the tolerance criterion that could not be satisfied.
+     *
+     * @return the required tolerance
+     */
+    public double getTolerance() {
+        return tolerance;
+    }
+}

src/main/java/uk/co/ryanharrison/mathengine/solvers/ConvergenceCriteria.java

@@ -1,12 +1,120 @@
 package uk.co.ryanharrison.mathengine.solvers;
 
 /**
- * Enumeration representing different methods of retrieving values of the
- * derivative of a target function
+ * Enumeration representing different methods for obtaining derivative values in Newton-based solvers.
+ * <p>
+ * Newton-Raphson and hybrid Newton methods require the derivative f'(x) of the target function.
+ * This enum specifies how those derivative values should be computed.
+ * </p>
  *
- * @author Ryan Harrison
+ * <h2>Method Comparison:</h2>
+ * <table border="1">
+ *     <tr>
+ *         <th>Method</th>
+ *         <th>Accuracy</th>
+ *         <th>Performance</th>
+ *         <th>Use When</th>
+ *     </tr>
+ *     <tr>
+ *         <td>{@link #Numerical}</td>
+ *         <td>Good (O(h⁴))</td>
+ *         <td>Moderate</td>
+ *         <td>Default choice, no derivative available</td>
+ *     </tr>
+ *     <tr>
+ *         <td>{@link #Symbolic}</td>
+ *         <td>Exact</td>
+ *         <td>Fast</td>
+ *         <td>Analytical derivative can be computed</td>
+ *     </tr>
+ *     <tr>
+ *         <td>{@link #Predefined}</td>
+ *         <td>Exact</td>
+ *         <td>Fastest</td>
+ *         <td>Derivative function is known a priori</td>
+ *     </tr>
+ * </table>
  *
+ * @see NewtonRaphsonSolver
+ * @see NewtonBisectionSolver
  */
 public enum DifferentiationMethod {
-    Numerical, Symbolic, Predefined
+
+    /**
+     * Compute derivatives using numerical differentiation.
+     * <p>
+     * Uses the {@link uk.co.ryanharrison.mathengine.differential.ExtendedCentralDifferenceMethod}
+     * which provides O(h⁴) accuracy through a five-point stencil.
+     * </p>
+     * <p>
+     * This is the default method and works for any function, but is slower than symbolic or
+     * predefined derivatives.
+     * </p>
+     *
+     * <h3>Advantages:</h3>
+     * <ul>
+     *     <li>Works for any differentiable function</li>
+     *     <li>No manual derivative specification required</li>
+     *     <li>Good accuracy (better than simple finite differences)</li>
+     * </ul>
+     *
+     * <h3>Disadvantages:</h3>
+     * <ul>
+     *     <li>Slower than exact derivatives (requires multiple function evaluations)</li>
+     *     <li>May have numerical precision issues near discontinuities</li>
+     * </ul>
+     */
+    Numerical,
+
+    /**
+     * Compute derivatives using symbolic differentiation.
+     * <p>
+     * Uses the {@link uk.co.ryanharrison.mathengine.differential.symbolic.Differentiator}
+     * to analytically differentiate the target function's expression tree.
+     * </p>
+     * <p>
+     * This provides exact derivatives for functions that can be symbolically differentiated,
+     * and is faster than numerical differentiation.
+     * </p>
+     *
+     * <h3>Advantages:</h3>
+     * <ul>
+     *     <li>Exact derivatives (no numerical approximation error)</li>
+     *     <li>Faster than numerical differentiation</li>
+     *     <li>Automatically computed from target function</li>
+     * </ul>
+     *
+     * <h3>Disadvantages:</h3>
+     * <ul>
+     *     <li>Only works for functions with symbolic expressions</li>
+     *     <li>May produce complex derivative expressions</li>
+     * </ul>
+     */
+    Symbolic,
+
+    /**
+     * Use a user-provided derivative function.
+     * <p>
+     * The user supplies a {@link uk.co.ryanharrison.mathengine.Function} representing
+     * the derivative of the target function.
+     * </p>
+     * <p>
+     * This is the fastest option as it uses pre-computed derivatives, but requires the
+     * user to provide the correct derivative function.
+     * </p>
+     *
+     * <h3>Advantages:</h3>
+     * <ul>
+     *     <li>Fastest evaluation (single function call per iteration)</li>
+     *     <li>Exact derivatives</li>
+     *     <li>Full control over derivative implementation</li>
+     * </ul>
+     *
+     * <h3>Disadvantages:</h3>
+     * <ul>
+     *     <li>Requires manual specification of derivative</li>
+     *     <li>User responsible for correctness</li>
+     * </ul>
+     */
+    Predefined
 }

src/main/java/uk/co/ryanharrison/mathengine/solvers/ConvergenceException.java

@@ -0,0 +1,79 @@
+package uk.co.ryanharrison.mathengine.solvers;
+
+/**
+ * Exception thrown when an iterative root-finding algorithm diverges.
+ * <p>
+ * Divergence occurs when the algorithm produces increasingly worse approximations instead
+ * of converging to a root. This is most common in polishing methods like Newton-Raphson
+ * when:
+ * </p>
+ * <ul>
+ *     <li>The initial guess is far from the actual root</li>
+ *     <li>The derivative is zero or very small at the current estimate</li>
+ *     <li>The function has a local minimum/maximum near the root</li>
+ *     <li>Numerical overflow occurs during iteration</li>
+ * </ul>
+ *
+ * <h2>Example:</h2>
+ * <pre>{@code
+ * Function f = new Function("1/x"); // Has no roots
+ * NewtonRaphsonSolver solver = NewtonRaphsonSolver.builder()
+ *     .targetFunction(f)
+ *     .initialGuess(1.0)
+ *     .build();
+ *
+ * // Throws DivergenceException as the algorithm produces infinite values
+ * solver.solve();
+ * }</pre>
+ *
+ * @see SolverException
+ */
+public class DivergenceException extends SolverException {
+
+    private final int iteration;
+    private final double lastFiniteValue;
+
+    /**
+     * Constructs a new divergence exception with detailed context.
+     *
+     * @param message         the detail message explaining the divergence
+     * @param iteration       the iteration number at which divergence was detected
+     * @param lastFiniteValue the last finite value before divergence (may be NaN or Infinity)
+     */
+    public DivergenceException(String message, int iteration, double lastFiniteValue) {
+        super(String.format("%s (iteration: %d, last finite value: %.10g)",
+                message, iteration, lastFiniteValue));
+        this.iteration = iteration;
+        this.lastFiniteValue = lastFiniteValue;
+    }
+
+    /**
+     * Constructs a new divergence exception with simple message.
+     *
+     * @param message the detail message explaining the divergence
+     */
+    public DivergenceException(String message) {
+        this(message, -1, Double.NaN);
+    }
+
+    /**
+     * Returns the iteration number at which divergence was detected.
+     *
+     * @return the iteration number, or -1 if not available
+     */
+    public int getIteration() {
+        return iteration;
+    }
+
+    /**
+     * Returns the last finite value computed before divergence.
+     * <p>
+     * This value may be NaN or Infinity if the algorithm diverged catastrophically.
+     * </p>
+     *
+     * @return the last finite value, or NaN if not available
+     */
+    public double getLastFiniteValue() {
+        return lastFiniteValue;
+    }
+}