Document and type simple_functions.py (#2674)

* 🏷️ Add types to simple_functions.py

* 💄 Neaten binary_search()

Add spacing between signature and code.
Remove and expressions and address IDE warnings

* 📝 Add docstrings for functions in simple_functions.py

* 🎨 Reorder functions alphabetically

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* 🐛 Reformat code examples

These were causing checks to fail due to missing spaces after `>>>`
I had wanted to change these to be more consistent with iterables.py anyway.

* 🎨 Change single tics to double

Change \` to \`` - this ensures that the variable names are actually
displayed as code (and not italics)

* improved docstrings, rewrote examples as doctests

* fix (???) unrelated failing doctest

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fixed typo

* Update manim/utils/simple_functions.py

Co-authored-by: Luca <[email protected]>

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Benjamin Hackl <[email protected]>

Author: 3 people

manim/mobject/opengl/opengl_vectorized_mobject.py

@@ -1629,7 +1629,9 @@ class OpenGLVGroup(OpenGLVMobject):
     can subtract elements of a OpenGLVGroup via :meth:`~.OpenGLVGroup.remove` method, or
     `-` and `-=` operators:
 
-        >>> from manim import Triangle, Square, OpenGLVGroup
+        >>> from manim import Triangle, Square, config
+        >>> config.renderer = "opengl"
+        >>> from manim.opengl import OpenGLVGroup
         >>> vg = OpenGLVGroup()
         >>> triangle, square = Triangle(), Square()
         >>> vg.add(triangle)

manim/utils/simple_functions.py

@@ -3,59 +3,146 @@
 from __future__ import annotations
 
 __all__ = [
-    "sigmoid",
+    "binary_search",
     "choose",
+    "clip",
     "get_parameters",
-    "binary_search",
+    "sigmoid",
 ]
 
 
 import inspect
 from functools import lru_cache
+from types import MappingProxyType
+from typing import Callable
 
 import numpy as np
 from scipy import special
 
 
-def sigmoid(x):
-    return 1.0 / (1 + np.exp(-x))
+def binary_search(
+    function: Callable[[int | float], int | float],
+    target: int | float,
+    lower_bound: int | float,
+    upper_bound: int | float,
+    tolerance: int | float = 1e-4,
+) -> int | float | None:
+    """Searches for a value in a range by repeatedly dividing the range in half.
 
+    To be more precise, performs numerical binary search to determine the
+    input to ``function``, between the bounds given, that outputs ``target``
+    to within ``tolerance`` (default of 0.0001).
+    Returns ``None`` if no input can be found within the bounds.
 
-@lru_cache(maxsize=10)
-def choose(n, k):
-    return special.comb(n, k, exact=True)
-
+    Examples
+    --------
 
-def get_parameters(function):
-    return inspect.signature(function).parameters
+    Consider the polynomial :math:`x^2 + 3x + 1` where we search for
+    a target value of :math:`11`. An exact solution is :math:`x = 2`.
 
+    ::
 
-def clip(a, min_a, max_a):
-    if a < min_a:
-        return min_a
-    elif a > max_a:
-        return max_a
-    return a
+        >>> solution = binary_search(lambda x: x**2 + 3*x + 1, 11, 0, 5)
+        >>> abs(solution - 2) < 1e-4
+        True
+        >>> solution = binary_search(lambda x: x**2 + 3*x + 1, 11, 0, 5, tolerance=0.01)
+        >>> abs(solution - 2) < 0.01
+        True
 
+    Searching in the interval :math:`[0, 5]` for a target value of :math:`71`
+    does not yield a solution::
 
-def binary_search(function, target, lower_bound, upper_bound, tolerance=1e-4):
+        >>> binary_search(lambda x: x**2 + 3*x + 1, 71, 0, 5) is None
+        True
+    """
     lh = lower_bound
     rh = upper_bound
+    mh = np.mean(np.array([lh, rh]))
     while abs(rh - lh) > tolerance:
-        mh = np.mean([lh, rh])
+        mh = np.mean(np.array([lh, rh]))
         lx, mx, rx = (function(h) for h in (lh, mh, rh))
         if lx == target:
             return lh
         if rx == target:
             return rh
 
-        if lx <= target and rx >= target:
+        if lx <= target <= rx:
             if mx > target:
                 rh = mh
             else:
                 lh = mh
-        elif lx > target and rx < target:
+        elif lx > target > rx:
             lh, rh = rh, lh
         else:
             return None
+
     return mh
+
+
+@lru_cache(maxsize=10)
+def choose(n: int, k: int) -> int:
+    r"""The binomial coefficient n choose k.
+
+    :math:`\binom{n}{k}` describes the number of possible choices of
+    :math:`k` elements from a set of :math:`n` elements.
+
+    References
+    ----------
+    - https://en.wikipedia.org/wiki/Combination
+    - https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.comb.html
+    """
+    return special.comb(n, k, exact=True)
+
+
+def clip(a, min_a, max_a):
+    """Clips ``a`` to the interval [``min_a``, ``max_a``].
+
+    Accepts any comparable objects (i.e. those that support <, >).
+    Returns ``a`` if it is between ``min_a`` and ``max_a``.
+    Otherwise, whichever of ``min_a`` and ``max_a`` is closest.
+
+    Examples
+    --------
+    ::
+
+        >>> clip(15, 11, 20)
+        15
+        >>> clip('a', 'h', 'k')
+        'h'
+    """
+    if a < min_a:
+        return min_a
+    elif a > max_a:
+        return max_a
+    return a
+
+
+def get_parameters(function: Callable) -> MappingProxyType[str, inspect.Parameter]:
+    """Return the parameters of ``function`` as an ordered mapping of parameters'
+    names to their corresponding ``Parameter`` objects.
+
+    Examples
+    --------
+    ::
+
+        >>> get_parameters(get_parameters)
+        mappingproxy(OrderedDict([('function', <Parameter "function: 'Callable'">)]))
+
+        >>> tuple(get_parameters(choose))
+        ('n', 'k')
+    """
+    return inspect.signature(function).parameters
+
+
+def sigmoid(x: float) -> float:
+    r"""Returns the output of the logistic function.
+
+    The logistic function, a common example of a sigmoid function, is defined
+    as :math:`\frac{1}{1 + e^{-x}}`.
+
+    References
+    ----------
+    - https://en.wikipedia.org/wiki/Sigmoid_function
+    - https://en.wikipedia.org/wiki/Logistic_function
+    """
+    return 1.0 / (1 + np.exp(-x))