Initial Commit

README.md

@@ -1,3 +1,97 @@
-# PolySolve
+# polysolve
 
-A Python polynomial solver using a genetic algorithm with optional CUDA/GPU acceleration.
+[![PyPI version](https://img.shields.io/pypi/v/polysolve.svg)](https://pypi.org/project/polysolve/)
+[![PyPI pyversions](https://img.shields.io/pypi/pyversions/polysolve.svg)](https://pypi.org/project/polysolve/)
+
+A Python library for representing, manipulating, and solving polynomial equations using a high-performance genetic algorithm, with optional CUDA/GPU acceleration.
+
+---
+
+## Key Features
+
+* **Create and Manipulate Polynomials**: Easily define polynomials of any degree and perform arithmetic operations like addition, subtraction, and scaling.
+* **Genetic Algorithm Solver**: Find approximate real roots for complex polynomials where analytical solutions are difficult or impossible.
+* **CUDA Accelerated**: Leverage NVIDIA GPUs for a massive performance boost when finding roots in large solution spaces.
+* **Analytical Solvers**: Includes standard, exact solvers for simple cases (e.g., `quadratic_solve`).
+* **Simple API**: Designed to be intuitive and easy to integrate into any project.
+
+---
+
+## Installation
+
+Install the base package from PyPI:
+
+```bash
+pip install polysolve
+```
+
+### CUDA Acceleration
+
+To enable GPU acceleration, install the extra that matches your installed NVIDIA CUDA Toolkit version. This provides a significant speedup for the genetic algorithm.
+
+**For CUDA 12.x users:**
+```bash
+pip install polysolve[cuda12]
+```
+
+**For CUDA 11.x users:**
+```bash
+pip install polysolve[cuda11]
+```
+
+---
+
+## Quick Start
+
+Here is a simple example of how to define a quadratic function, find its properties, and solve for its roots.
+
+```python
+from polysolve import Function, GA_Options, quadratic_solve
+
+# 1. Define the function f(x) = 2x^2 - 3x - 5
+f1 = Function(largest_exponent=2)
+f1.set_constants([2, -3, -5])
+
+print(f"Function f1: {f1}")
+# > Function f1: 2x^2 - 3x - 5
+
+# 2. Solve for y at a given x
+y_val = f1.solve_y(5)
+print(f"Value of f1 at x=5 is: {y_val}")
+# > Value of f1 at x=5 is: 30.0
+
+# 3. Get the derivative: 4x - 3
+df1 = f1.differential()
+print(f"Derivative of f1: {df1}")
+# > Derivative of f1: 4x - 3
+
+# 4. Find roots analytically using the quadratic formula
+#    This is exact and fast for degree-2 polynomials.
+roots_analytic = quadratic_solve(f1)
+print(f"Analytic roots: {sorted(roots_analytic)}")
+# > Analytic roots: [-1.0, 2.5]
+
+# 5. Find roots with the genetic algorithm (CPU)
+#    This can solve polynomials of any degree.
+ga_opts = GA_Options(num_of_generations=20)
+roots_ga = f1.get_real_roots(ga_opts, use_cuda=False)
+print(f"Approximate roots from GA: {roots_ga[:2]}")
+# > Approximate roots from GA: [-1.000..., 2.500...]
+
+# If you installed a CUDA extra, you can run it on the GPU:
+# roots_ga_gpu = f1.get_real_roots(ga_opts, use_cuda=True)
+# print(f"Approximate roots from GA (GPU): {roots_ga_gpu[:2]}")
+
+```
+
+---
+
+## Contributing
+
+Contributions are welcome! Whether it's a bug report, a feature request, or a pull request, please feel free to get involved.
+
+Please read our `CONTRIBUTING.md` file for details on our code of conduct and the process for submitting pull requests.
+
+## License
+
+This project is licensed under the MIT License - see the `LICENSE` file for details.