Repository: scipy/scipy
Pull request: DOC: `special.riccati_yn`: highlight sign convention
#### Reference issue
Closes gh-12895
Closes gh-17920

#### What does this implement/fix?
gh-12895 requests that the sign convention for `special.riccati_yn` be changed from $xy_n(x)$ to $-xy_n(x)$. Both conventions are valid, and SciPy's convention can be found in reputable references including Abramowitz and Stegun and DLMF (https://github.com/scipy/scipy/issues/12895#issuecomment-2365361502), so I don't think we would change it now to please some and disrupt others. This PR modifies the documentation to highlight the convention used by SciPy.

Problem statement:
BUG: `special.riccati_yn`: Definition missing minus sign
Please consider using the definition -xy_n(x) instead of xy_n(x).

The minus sign is important!

Thanks!

BUG: special: Riccati Bessel function of the second kind lacks a minus sign
The Riccati Bessel function of the second kind: scipy.special.riccati_yn(n, x) is coded as xy_n(x) whereas it should be **-**xy_n(x) leading to errors in calculations.

Thank you for taking this into account

Hints from issue discussion:
Please do consider this query, the minus sign not being implemented leads to loads of errors in calculations.
The Riccati-Bessel function of second kind **is** -xy_n(x)
Thank you in advance for considering this !
It does seem to be the more common convention to include the minus sign. However, it is noted in [Barnett 1996](https://citeseerx.ist.psu.edu/document?repid=rep1&type=pdf&doi=fd8b1b4c3549edbec7f05d4d72271d4c5d5d8e3e) that there is another sign convention:

<img width="1097" alt="image" src="https://github.com/user-attachments/assets/8bb69030-cdff-4164-9fbe-16a9b47bad2d">

Noteable uses of this convention are [Abramowitz and Stegun 10.3](https://personal.math.ubc.ca/~cbm/aands/abramowitz_and_stegun.pdf) and [DLMF 10.21xi](https://dlmf.nist.gov/10.21#xi) (besides the [original Fortran implementation](https://people.sc.fsu.edu/~jburkardt/f77_src/special_functions/special_functions.f) SciPy wrapped).

> the minus sign not being implemented leads to loads of errors in calculations.

Consider all the errors in calculations we would introduce by changing it now (after decades of people adapting to this convention). I'm not seeing an palateable strategy we can follow in this case to change the behavior in a graceful way, either. (I've considered some options, but not all possibilities - LMK if there is a strategy that is in line with SciPy's typical standards for changes that doesn't, say, introduce a new argument to the function to control the sign convention - unless we really *want* that.)

Here's what we can do:

- I will submit a PR to emphasize the sign convention being used in the documentation.
- Reconsider the sign convention if this becomes a ufunc, presumably with a different name.

@steppi @izaid thought I should ping you as something to keep in mind as xsf develops.
A comment from 30000 feet: these sorts of suggestions are best backed up with some more details of commonly used conventions for phases, links to classic texts or other resources. 

As written, it is full well possible that it is just a different convention for the global phase. If there are several, then the best course of action could be to document the one we use. 
Sorry about this, I am new to github !
However it is true that this comment would be better documented.
Hence, here is some litterature showing that scipy.special.riccati_yn(n, x) should be -xy_n(x):
**Wikipedia:**
https://en.wikipedia.org/wiki/Bessel_function
**Book:**
Absorption and Scattering of Light by Small Particles - C. Bohren, D. Huffman https://onlinelibrary.wiley.com/doi/book/10.1002/9783527618156
**Research report:**
MATLAB Functions for Mie Scattering and Absorption Version 2 - C. Mätzler
http://www.atmo.arizona.edu/students/courselinks/spring09/atmo656b/maetzler_mie_v2.pdf
**Book**:
Light Scattering by Small Particles - H. C. van de Hulst 
https://books.google.fr/books?id=777DAgAAQBAJ&hl=fr
**Article**:
On the computation of Riccati-Bessel functions - P. Malicky, M. Malicka
https://eudml.org/doc/15649

I haven't found any litterature with scipy.special.riccati_yn(n, x) = xy_n(x) but if I do i will post the references here.

Commit message: DOC: special.riccati-yn: highlight sign convention

[docs only]

Patch to review:
diff --git a/scipy/special/_basic.py b/scipy/special/_basic.py
index 24ed153d28f0..f5b27476bd6c 100644
--- a/scipy/special/_basic.py
+++ b/scipy/special/_basic.py
@@ -1337,9 +1337,10 @@ def riccati_jn(n, x):
 def riccati_yn(n, x):
     """Compute Ricatti-Bessel function of the second kind and its derivative.
 
-    The Ricatti-Bessel function of the second kind is defined as :math:`x
+    The Ricatti-Bessel function of the second kind is defined here as :math:`+x
     y_n(x)`, where :math:`y_n` is the spherical Bessel function of the second
-    kind of order :math:`n`.
+    kind of order :math:`n`. _Note that this is in contrast to a common convention
+    that includes a minus sign in the definition._
 
     This function computes the value and first derivative of the function for
     all orders up to and including `n`.


Code review comments:
diff_hunk: @@ -1337,9 +1337,10 @@ def riccati_jn(n, x):
 def riccati_yn(n, x):
     """Compute Ricatti-Bessel function of the second kind and its derivative.
 
-    The Ricatti-Bessel function of the second kind is defined as :math:`x
+    The Ricatti-Bessel function of the second kind is defined here as :math:`+x
     y_n(x)`, where :math:`y_n` is the spherical Bessel function of the second
-    kind of order :math:`n`.
+    kind of order :math:`n`. _Note that this is in contrast to a common convention
+    that includes a minus sign in the definition._
path: scipy/special/_basic.py
text: @user1:
The DLMF reference seems to support the current usage, I wasn't smart enough to read the older PDF reference. I guess the negation convention is related to the singularity.

Is the `_` notation doing what you intend in the rendered version?

![image](https://github.com/user-attachments/assets/bac82c76-db14-453d-9091-bbf4b348d678)


@author:
No, I guess I was mixing up with markdown


@author:
<img width="899" alt="image" src="https://github.com/user-attachments/assets/0aa30f4a-5822-4fb1-816e-13ac969bf8d2">

Thanks @user1. Fixed.