GA_Options API

The GA_Options dataclass allows you to fine-tune the genetic algorithm used in the solve_x and get_real_roots methods. You can trade speed for accuracy and tune the algorithm‘s strategy for finding single vs. multiple roots.

from polysolve import Function, GA_Options

# Configure a robust search for finding *all* real roots
custom_options = GA_Options(
    num_of_generations=20,
    data_size=500000,
    
    # Widen the parent pool to 75% to keep all
    # "niches" (solution clouds) alive.
    selection_percentile=0.75,
    
    # Increase blend factor to 0.75 to allow
    # crossover to explore *outside* the parent range.
    blend_alpha=0.75,
    
    # Standard ratios
    elite_ratio=0.05,
    crossover_ratio=0.45,
    mutation_ratio=0.40
)

f = Function(5)
f.set_coeffs([1, 0, -15, 0, 10, 0])
# This search is now optimized for finding all roots
roots = f.get_real_roots(options=custom_options)

Parameters

• min_range / max_range

  The lower and upper bounds for the algorithm‘s random search space.

  Important: If you leave the defaults, PolySolve will automatically ignore them and instead calculate a guaranteed, mathematically-correct range using Cauchy‘s bound. This is the recommended behavior for most use cases.

  You should only set a custom range if you know your roots are in a specific, narrow area (e.g., [0, 5]). This will act as an "expert override" and can significantly speed up convergence.

  Type: float | Default: 0.0 / 0.0

• num_of_generations

  The number of iterations (generations) the algorithm will run. More generations can lead to more accurate results.

  Type: int | Default: 10

• data_size

  The total number of "solutions" (the population size) generated in each generation. A larger size increases the chance of finding all roots but is more computationally expensive.

  Type: int | Default: 100000

• mutation_strength

  The percentage (e.g., 0.01 for 1%) by which a solution‘s value is randomly altered during a mutation.

  Type: float | Default: 0.01 (1%)

• elite_ratio

  The percentage (e.g., 0.05 for 5%) of the best solutions to carry over to the next generation unchanged (elitism).

  Type: float | Default: 0.05 (5%)

• crossover_ratio

  The percentage (e.g., 0.45 for 45%) of the next generation to be created by "breeding" two solutions from the parent pool.

  Type: float | Default: 0.45 (45%)

• mutation_ratio

  The percentage (e.g., 0.40 for 40%) of the next generation to be created by mutating solutions from the parent pool.

  Type: float | Default: 0.40 (40%)

• selection_percentile

  The top percentage (e.g., 0.66 for 66%) of solutions to use as the "parent pool" for crossover.

  This is a key parameter for multi-root finding. A smaller value (e.g., 0.5) is aggressive and converges quickly on a single root. A larger value (e.g., 0.75) preserves diversity and is much better at finding all real roots.

  Type: float | Default: 0.66 (66%)

• blend_alpha

  The expansion factor for Blend Crossover (BLX-α). This controls how far "outside" the parent‘s range a new child solution can be created.

  A value of 0.0 is purely interpolative (child is always between parents). A value of 0.5 (the default) allows the new search range to be 50% larger than the parent range, which is excellent for exploration.

  Type: float | Default: 0.5

• root_precision

  The number of decimal places to round roots to when clustering unique results. A smaller number (e.g., 3) groups roots more aggressively. A larger number (e.g., 7) is more precise but may return multiple near-identical roots.

  Precision Warning

  Values above 15 are not recommended. PolySolve uses standard 64-bit floats (`float64`), which are limited to about 15-16 significant digits of precision (machine epsilon).

  Setting root_precision higher than 15 demands an accuracy that is physically impossible for floating-point math, and the solver will likely find no roots.

  Type: int | Default: 5

Note: The sum of elite_ratio, crossover_ratio, and mutation_ratio must be less than or equal to 1.0. The remaining percentage of the population will be filled with new random solutions to ensure diversity.