Add Val{true} option for complex roots in HomotopyContinuationJL

[ChrisRackauckas-Claude]

Summary

This PR implements the feature requested in issue #688 by adding a ComplexRoots type parameter to HomotopyContinuationJL that accepts Val{true} or Val{false} to control whether complex roots are returned.

Changes

• API Enhancement: Modified HomotopyContinuationJL{AllRoots} to HomotopyContinuationJL{AllRoots, ComplexRoots} where ComplexRoots defaults to Val{false} for backward compatibility
• Solve Method Updates: Updated both all-roots and single-root solve methods to handle complex solutions when ComplexRoots = Val{true}
• Solution Processing: Enhanced solution processing logic to preserve complex numbers instead of filtering to real parts
• Comprehensive Tests: Added tests for scalar and vector polynomial systems with complex roots
• Documentation: Updated docstrings to explain the new parameter

Usage

# Enable complex roots (new feature)
alg_complex = HomotopyContinuationJL{true, Val{true}}()  # All complex roots
alg_single_complex = HomotopyContinuationJL{false, Val{true}}()  # Single complex root

# Default behavior (backward compatible)
alg_real = HomotopyContinuationJL{true}()  # Real roots only
alg_default = HomotopyContinuationJL()     # Real roots only

# Example: Find complex roots of u² + 1 = 0
rhs(u, p) = u * u + 1
prob = NonlinearProblem(rhs, 1.0 + 0.0im)
sol = solve(prob, alg_complex)  # Returns [i, -i]

Technical Details

• Uses Val{Bool} for compile-time dispatch as requested in the issue
• Maintains full backward compatibility - existing code unchanged
• Properly handles complex number arithmetic throughout solution pipeline
• Added comprehensive test coverage for both scalar and vector cases

Test plan

• Scalar polynomial test: u² + 1 = 0 correctly finds roots ±i
• Vector polynomial test: [u₁² + 1, u₂² + 4] = 0 finds all 4 complex roots
• Single root method works with complex roots
• Backward compatibility maintained for real-only solutions
• Run CI tests to ensure no regressions

Files Modified

• lib/NonlinearSolveHomotopyContinuation/src/NonlinearSolveHomotopyContinuation.jl
• lib/NonlinearSolveHomotopyContinuation/src/solve.jl
• lib/NonlinearSolveHomotopyContinuation/test/runtests.jl
• lib/NonlinearSolveHomotopyContinuation/test/complex_roots_test.jl (new)

Closes #688

🤖 Generated with Claude Code

Co-Authored-By: Claude [email protected]