Repository: sympy/sympy
File: sympy/physics/hydrogen.py (Python)

Code before:


def Y_lm(l, m, phi, theta):
    """
    Returns the spherical harmonic or angular function Y_{l}^{m}.

    Parameters
    ==========

    l : integer
        ``l`` is the Angular Momentum Quantum Number with
        values ranging from 0 to ``n-1``.
    m : iteger
        ``m`` is the Magnetic Quantum Number with values
        ranging from ``-l`` to ``l``.
    phi :
        azimuthal angle
    theta :
        polar angle

    Notes
    =====

    This function follows the Condon-Shortley phase convention and may return
    real or complex values depending on values for ``l`` and ``m``. See Z_lm()
    for real-valued spherical harmonics.

    Examples
    ========

    >>> import sympy
    >>> from sympy.physics.hydrogen import Y_lm
    >>> phi, theta = sympy.symbols('phi theta', real=True)
    >>> Y_lm(1, 0, phi, theta)
    sqrt(3)*cos(theta)/(2*sqrt(pi))
    >>> Y_lm(2, -1, phi, theta).simplify()
    sqrt(30)*exp(-I*phi)*sin(2*theta)/(8*sqrt(pi))
    >>> Y_lm(1, -1, phi, theta).simplify()
    sqrt(6)*exp(-I*phi)*sin(theta)/(4*sqrt(pi))
    >>> Y_lm(1, 1, 0, 1).evalf()
    -0.290723302201011

    Find angular nodes in dz2 atomic orbital by solving for zero probability.
    This returns the node theta angles in radians.

    >>> dz2 = Y_lm(2, 0, phi, theta)**2
    >>> [sol.evalf() for sol in sympy.solve(dz2)]
    [4.0969092717143, 5.32786868905508, 2.18627603546528, 0.955316618124509]

    """
    return Ynm(l, m, theta, phi).expand(func=True)

Review comment (suggestion):
The reference to `Z_lm` should ideally be a clickable link in the html docs. The usual way to do this though is to have a See Also section in the docstring:
https://docs.sympy.org/latest/contributing/docstring.html#see-also-section

It would be good also to have See Also for the Ynm function that this calls especially if you say that you were previously unaware of it. I would also add the See Also in Ynm pointing back towards here.

Code after:


def Y_lm(l, m, phi, theta):
    """
    Returns the spherical harmonic or angular function Y_{l}^{m}.

    Parameters
    ==========

    l : integer
        ``l`` is the Angular Momentum Quantum Number with
        values ranging from 0 to ``n-1``.
    m : iteger
        ``m`` is the Magnetic Quantum Number with values
        ranging from ``-l`` to ``l``.
    phi :
        azimuthal angle
    theta :
        polar angle

    Notes
    =====

    This function follows the Condon-Shortley phase convention and may return
    real or complex values depending on values for ``l`` and ``m``.

    Examples
    ========

    >>> import sympy
    >>> from sympy.physics.hydrogen import Y_lm
    >>> phi, theta = sympy.symbols('phi theta', real=True)
    >>> Y_lm(1, 0, phi, theta)
    sqrt(3)*cos(theta)/(2*sqrt(pi))
    >>> Y_lm(2, -1, phi, theta).simplify()
    sqrt(30)*exp(-I*phi)*sin(2*theta)/(8*sqrt(pi))
    >>> Y_lm(1, -1, phi, theta).simplify()
    sqrt(6)*exp(-I*phi)*sin(theta)/(4*sqrt(pi))
    >>> Y_lm(1, 1, 0, 1).evalf()
    -0.290723302201011

    Find angular nodes in dz2 atomic orbital by solving for zero probability.
    This returns the node theta angles in radians.

    >>> dz2 = Y_lm(2, 0, phi, theta)**2
    >>> [sol.evalf() for sol in sympy.solve(dz2)]
    [4.0969092717143, 5.32786868905508, 2.18627603546528, 0.955316618124509]

    See Also
    ========