The previous benchmark results showed that the GA was failing to find accurate roots (high MAE) for many polynomials. This was because the fixed default search range ([-100, 100]) was often incorrect, and the GA was searching in the wrong place.
This commit introduces a significantly more robust solution:
1. Adds a `_get_cauchy_bound` helper function to mathematically calculate a search radius that is guaranteed to contain all real roots.
2. Updates `_solve_x_numpy` and `_solve_x_cuda` with new logic:
* If the user provides a *custom* `min_range` or `max_range`, we treat them as an expert and use their specified range.
* If the user is using the *default* range, we silently discard it and use the smarter, automatically-calculated Cauchy bound instead.
This provides the best of both worlds: a powerful, smart default for most users and an "expert override" for those who need to fine-tune the search area.
The `_solve_x_numpy` method was correctly using `np.where(error == 0, ...)` to handle perfect roots. However, NumPy eagerly calculates `1.0 / error` for the entire array before applying the `where` condition, which was causing a `RuntimeWarning: divide by zero` when a perfect root was found.
This warning was harmless but created unnecessary console noise during testing and use.
This commit wraps the `ranks = ...` assignments in a `with np.errstate(divide='ignore'):` block to silence this specific, expected warning. The CUDA kernel is unaffected as its ternary operator already prevents this calculation.
This commit introduces a major enhancement to the genetic algorithm's convergence logic and refactors key parts of the API for better clarity and usability.
- **feat(ga):** Re-implements the GA solver (CPU & CUDA) to use a more robust strategy based on Elitism, Crossover, and Mutation. This replaces the previous, less efficient model and is designed to significantly improve accuracy and convergence speed.
- **feat(api):** Updates `GA_Options` to expose the new GA strategy parameters:
- Renames `mutation_percentage` to `mutation_strength` for clarity.
- Adds `elite_ratio`, `crossover_ratio`, and `mutation_ratio`.
- Includes a `__post_init__` validator to ensure ratios are valid.
- **refactor(api):** Moves `quadratic_solve` from a standalone function to a method of the `Function` class (`f1.quadratic_solve()`). This provides a cleaner, more object-oriented API.
- **docs:** Updates the README, `GA_Options` doc page, and `quadratic_solve` doc page to reflect all API changes, new parameters, and updated usage examples.
- **chore:** Bumps version to 0.4.0.
Reviewed-on: #16
Co-authored-by: Jonathan Rampersad <rampersad.jonathan@gmail.com>
Co-committed-by: Jonathan Rampersad <rampersad.jonathan@gmail.com>
