From 721904422a8b51a4729f502976403f76defd7dab Mon Sep 17 00:00:00 2001
From: olivier <olivier.lebot22@gmail.com>
Date: Sun, 17 Aug 2025 15:05:16 +0200
Subject: [PATCH 1/2] DOC: Add polynomial evaluation examples and improve
 polyval docs

- Add evaluation examples to polynomial quick reference table
- Enhance polyval docstring with clearer examples
- Add warning about domain/window scaling with fitted polynomials
- Show comparison between legacy and new polynomial APIs

Fixes #25587"
---
 doc/source/reference/routines.polynomials.rst | 34 +++++++++++--------
 numpy/polynomial/polynomial.py                |  5 +++
 2 files changed, 24 insertions(+), 15 deletions(-)

diff --git a/doc/source/reference/routines.polynomials.rst b/doc/source/reference/routines.polynomials.rst
index 0763a1cf719a..0da51e57a308 100644
--- a/doc/source/reference/routines.polynomials.rst
+++ b/doc/source/reference/routines.polynomials.rst
@@ -47,23 +47,27 @@ The `~numpy.polynomial.polynomial.Polynomial` class is imported for brevity::
     from numpy.polynomial import Polynomial
 
 
-+------------------------+------------------------------+---------------------------------------+
-|  **How to...**         | Legacy (`numpy.poly1d`)      | `numpy.polynomial`                    |
-+------------------------+------------------------------+---------------------------------------+
-| Create a               | ``p = np.poly1d([1, 2, 3])`` | ``p = Polynomial([3, 2, 1])``         |
-| polynomial object      |                              |                                       |
-| from coefficients [1]_ |                              |                                       |
-+------------------------+------------------------------+---------------------------------------+
-| Create a polynomial    | ``r = np.poly([-1, 1])``     | ``p = Polynomial.fromroots([-1, 1])`` |
-| object from roots      | ``p = np.poly1d(r)``         |                                       |
-+------------------------+------------------------------+---------------------------------------+
-| Fit a polynomial of    |                              |                                       |
-| degree ``deg`` to data | ``np.polyfit(x, y, deg)``    | ``Polynomial.fit(x, y, deg)``         |
-+------------------------+------------------------------+---------------------------------------+
-
++------------------------+----------------------------------------+---------------------------------------+
+|  **How to...**         | Legacy (`numpy.poly1d`)                | `numpy.polynomial`                    |
++------------------------+----------------------------------------+---------------------------------------+
+| Create a               | ``p = np.poly1d([1, 2, 3])``           | ``p = Polynomial([3, 2, 1])``         |
+| polynomial object      |                                        |                                       |
+| from coefficients [1]_ |                                        |                                       |
++------------------------+----------------------------------------+---------------------------------------+
+| Create a polynomial    | ``r = np.poly([-1, 1])``               | ``p = Polynomial.fromroots([-1, 1])`` |
+| object from roots      | ``p = np.poly1d(r)``                   |                                       |
++------------------------+----------------------------------------+---------------------------------------+
+| Fit a polynomial of    |                                        |                                       |
+| degree ``deg`` to data | ``np.polyfit(x, y, deg)``              | ``Polynomial.fit(x, y, deg)``         |
++------------------------+----------------------------------------+---------------------------------------+
+| Evaluate a polynomial  | ``p(2.0)`` or                          | ``p(2.0)`` or ``polyval(2.0, p.coef)``|
+| at a point [2]_        | ``np.polyval([1, 2, 3], 2.0)``         | (use ``p.convert().coef`` after fit)  |
++------------------------+----------------------------------------+---------------------------------------+
 
 .. [1] Note the reversed ordering of the coefficients
 
+.. [2] When evaluating polynomials created with ``fit()``, use ``p(x)`` or ``polyval(x, p.convert().coef)`` to handle domain/window scaling correctly.
+
 Transition Guide
 ~~~~~~~~~~~~~~~~
 
@@ -187,4 +191,4 @@ Documentation for legacy polynomials
 .. toctree::
    :maxdepth: 2
 
-   routines.polynomials.poly1d
+   routines.polynomials.poly1d
\ No newline at end of file
diff --git a/numpy/polynomial/polynomial.py b/numpy/polynomial/polynomial.py
index 6ec0dc58a1de..e015ffbf20c5 100644
--- a/numpy/polynomial/polynomial.py
+++ b/numpy/polynomial/polynomial.py
@@ -716,6 +716,11 @@ def polyval(x, c, tensor=True):
     Notes
     -----
     The evaluation uses Horner's method.
+    
+    .. warning::
+   When using coefficients from polynomials created with ``Polynomial.fit()``,
+   use ``p(x)`` or ``polyval(x, p.convert().coef)`` to handle domain/window
+   scaling correctly, not ``polyval(x, p.coef)``.
 
     Examples
     --------

From ff9c06be00d6f913f2e0ceee83a14dea2cf56a64 Mon Sep 17 00:00:00 2001
From: olivier <olivier.lebot22@gmail.com>
Date: Sun, 17 Aug 2025 15:39:13 +0200
Subject: [PATCH 2/2] Fix: Remove whitespace from line 719 in polynomial.py

---
 numpy/polynomial/polynomial.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/numpy/polynomial/polynomial.py b/numpy/polynomial/polynomial.py
index e015ffbf20c5..d9427b199fea 100644
--- a/numpy/polynomial/polynomial.py
+++ b/numpy/polynomial/polynomial.py
@@ -716,8 +716,7 @@ def polyval(x, c, tensor=True):
     Notes
     -----
     The evaluation uses Horner's method.
-    
-    .. warning::
+
    When using coefficients from polynomials created with ``Polynomial.fit()``,
    use ``p(x)`` or ``polyval(x, p.convert().coef)`` to handle domain/window
    scaling correctly, not ``polyval(x, p.coef)``.