Skip to content

armgit / manim

Public Imported from GitHub
0

A community-maintained Python framework for creating mathematical animations.

Document and type `simple_functions.py` (#2674)

Luca8841e39a20b5
diff --git a/manim/mobject/opengl/opengl_vectorized_mobject.py b/manim/mobject/opengl/opengl_vectorized_mobject.py
index 46dffe11b..643a26da9 100644
--- a/manim/mobject/opengl/opengl_vectorized_mobject.py
+++ b/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)
diff --git a/manim/utils/simple_functions.py b/manim/utils/simple_functions.py
index e5f05d2a7..2a4a7afed 100644
--- a/manim/utils/simple_functions.py
+++ b/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))