From 727ec3fe46671dcc38f62e4886a5e86701f0c91c Mon Sep 17 00:00:00 2001 From: Laurens Valk Date: Wed, 14 Jul 2021 10:04:05 +0200 Subject: [PATCH] umath: Redo module docs. This reworks the documentation for the umath module, as done previously as per https://github.com/pybricks/pybricks-api/pull/64 and https://github.com/pybricks/pybricks-api/issues/63 The presentation and docstrings are inspired by the Python 3 math module documentation instead of the MicroPython math module documentation. Functions are grouped roughly by use case. --- doc/api/umath.rst | 79 +++++++- src/umath/__init__.py | 459 +++++++++++++++++++++++++++--------------- 2 files changed, 374 insertions(+), 164 deletions(-) diff --git a/doc/api/umath.rst b/doc/api/umath.rst index 5dc141e..bfbadba 100644 --- a/doc/api/umath.rst +++ b/doc/api/umath.rst @@ -1,4 +1,77 @@ -:mod:`umath` -- Mathematical functions -====================================== +:mod:`umath ` -- Math functions +============================================================ -.. automodule:: umath +This module is available on the the City Hub, Technic Hub, +Prime Hub, and Inventor Hub. + +This MicroPython module is similar to the `math module`_ in Python. + +.. module:: umath + +Rounding and sign +------------------------------------- + +.. autofunction:: umath.ceil + +.. autofunction:: umath.floor + +.. autofunction:: umath.trunc + +.. autofunction:: umath.fmod + +.. autofunction:: umath.fabs + +.. autofunction:: umath.copysign + +Powers and logarithms +------------------------------- + +.. autodata:: umath.e + +.. autofunction:: umath.exp + +.. autofunction:: umath.pow + +.. autofunction:: umath.log + +.. autofunction:: umath.sqrt + +Trigonomety +------------------------------- + +.. autodata:: umath.pi + +.. autofunction:: umath.degrees + +.. autofunction:: umath.radians + +.. autofunction:: umath.sin + +.. autofunction:: umath.asin + +.. autofunction:: umath.cos + +.. autofunction:: umath.acos + +.. autofunction:: umath.tan + +.. autofunction:: umath.atan + +.. autofunction:: umath.atan2 + +Other math functions +------------------------------- + +.. autofunction:: umath.isfinite + +.. autofunction:: umath.isinfinite + +.. autofunction:: umath.isnan + +.. autofunction:: umath.modf + +.. autofunction:: umath.frexp + +.. autofunction:: umath.ldexp + +.. _math module: https://docs.python.org/3.5/library/math.html#module-math diff --git a/src/umath/__init__.py b/src/umath/__init__.py index c09008b..60dd18c 100644 --- a/src/umath/__init__.py +++ b/src/umath/__init__.py @@ -1,190 +1,327 @@ # SPDX-License-Identifier: MIT +# SPDX-License-Identifier: PSF-2.0 # Copyright (c) 2021 The Pybricks Authors # -# Portions of documentation copied from: -# https://raw.githubusercontent.com/micropython/micropython/1e6d18c915ccea0b6a19ffec9710d33dd7e5f866/docs/library/math.rst -# Copyright (c) 2014-2021, Damien P. George, Paul Sokolovsky, and contributors +# Portions of the documentation copied and adapted from: +# https://docs.python.org/3/library/math.html +# Copyright (c) 2001-2021 Python Software Foundation + """ -This module provides some basic mathematical functions for -working with floating-point numbers. - -.. note:: This module is not available on the BOOST Move hub. +Math functions. """ -# constants - -from typing import Tuple +from typing import Tuple as _Tuple -e: float -""" -Base of the natural logarithm. -""" - -pi: float -""" -The ratio of a circle's circumference to its diameter. -""" - -# functions +e = 2.718282 +"""The mathematical constant e.""" -def acos(x: float) -> float: - """ - Returns the inverse cosine of ``x``. - """ - - -def asin(x: float) -> float: - """ - Returns the inverse sine of ``x``. - """ - - -def atan(x: float) -> float: - """ - Returns the inverse tangent of ``x``. - """ - - -def atan2(y: float, x: float) -> float: - """ - Returns the principal value of the inverse tangent of ``y/x``. - """ - - -def ceil(x: float) -> int: - """ - Returns an integer, being ``x`` rounded towards positive infinity. - """ - - -def copysign(x: float, y: float) -> float: - """ - Returns ``x`` with the sign of ``y``. - """ - - -def cos(x: float) -> float: - """ - Returns the cosine of ``x``. - """ - - -def degrees(x: float) -> float: - """ - Returns radians ``x`` converted to degrees. - """ - - -def exp(x: float) -> float: - """ - Returns the exponential of ``x``. - """ - - -def fabs(x: float) -> float: - """ - Returns the absolute value of ``x``. - - Use ``abs(x)`` instead for integers. - """ - - -def floor(x: float) -> float: - """ - Returns an integer, being ``x`` rounded towards negative infinity. - """ - - -def fmod(x: float, y: float) -> float: - """ - Returns the remainder of ``x/y``. - - Use ``x % y`` instead for integers. - """ - - -def frexp(x: float) -> Tuple[float, int]: - """ - Decomposes a floating-point number into its mantissa and exponent. - The returned value is the tuple ``(m, e)`` such that ``x == m * 2**e`` - exactly. If ``x == 0`` then the function returns ``(0.0, 0)``, otherwise - the relation ``0.5 <= abs(m) < 1`` holds. - """ - - -def isfinite(x: float) -> bool: - """ - Returns ``True`` if ``x`` is finite. - """ - - -def isinf(x: float) -> bool: - """ - Returns ``True`` if ``x`` is infinite. - """ - - -def isnan(x: float) -> bool: - """ - Returns ``True`` if ``x`` is not-a-number - """ - - -def ldexp(x: float, exp: int) -> float: - """ - Returns ``x * (2**exp)``. - """ - - -def log(x: float) -> float: - """ - Returns the natural logarithm of ``x``. - """ - - -def modf(x: float) -> Tuple[float, float]: - """ - Returns a tuple of two floats, being the fractional and integral parts of - ``x``. Both return values have the same sign as ``x``. - """ - - -def pow(x: float, y: float) -> float: - """ - Returns ``x`` to the power of ``y``. - - Use ``x ** y`` instead for intergers. - """ - - -def radians(x: float) -> float: - """ - Returns degrees ``x`` converted to radians. - """ +pi = 3.141593 +"""The mathematical constant π.""" def sin(x: float) -> float: + """Gets the sine of the given angle ``x``. + + Arguments: + x: Angle in radians. + + Returns: + Sine of ``x``. """ - Returns the sine of ``x``. - """ + pass -def sqrt(x: float) -> float: +def asin(x: float) -> float: + """Applies the inverse sine operation on ``x``. + + Arguments: + x: Opposite / hypotenuse. + + Returns: + Arcsine of ``x``, in radians. """ - Returns the square root of ``x``. + pass + + +def cos(x: float) -> float: + """Gets the cosine of the given angle ``x``. + + Arguments: + x: Angle in radians. + + Returns: + Cosine of ``x``. """ + pass + + +def acos(x: float) -> float: + """Applies the inverse cosine operation on ``x``. + + Arguments: + x: Adjacent / hypotenuse. + + Returns: + Arccosine of ``x``, in radians. + """ + pass def tan(x: float) -> float: + """Gets the tangent of the given angle ``x``. + + Arguments: + x: Angle in radians. + + Returns: + Tangent of ``x``. """ - Returns the tangent of ``x``. + pass + + +def atan(x: float) -> float: + """Applies the inverse tangent operation on ``x``. + + Arguments: + x: Opposite / adjacent. + + Returns: + Arctangent of ``x``, in radians. """ + pass + + +def atan2(b: float, a: float) -> float: + """Applies the inverse tangent operation on ``b / a``, and accounts for + the signs of ``b`` and ``a`` to produce the expected angle. + + Arguments: + b: Opposite side of the triangle. + a: Adjacent side of the triangle. + + Returns: + Arctangent of ``b / a``, in radians. + """ + pass + + +def degrees(x: float) -> float: + """Converts an angle ``x`` from radians to degrees. + + Arguments: + x: Angle in radians. + + Returns: + Angle in degrees. + """ + pass + + +def radians(x: float) -> float: + """Converts an angle ``x`` from degrees to radians. + + Arguments: + x: Angle in degrees. + + Returns: + Angle in radians. + """ + pass + + +def pow(x: float, y: float) -> float: + """Gets ``x`` raised to the power of ``y``. + + Arguments: + x: The base number. + y: The exponent. + + Returns: + ``x`` raised to the power of ``y``. + """ + pass + + +def exp(x: float) -> float: + """Gets :attr:`e` raised to the power of ``x``. + + Arguments: + x: The exponent. + + Returns: + :attr:`e` raised to the power of ``x``. + """ + pass + + +def log(x: float) -> float: + """Gets the natural logarithm of ``x``. + + Arguments: + x: The value ``x``. + + Returns: + The natural logarithm of ``x``. + """ + pass + + +def sqrt(x: float) -> float: + """Gets the square root of ``x``. + + Arguments: + x: The value ``x``. + + Returns: + The square root of ``x``. + """ + pass + + +def ceil(x: float) -> int: + """Rounds up. + + Arguments: + x: The value ``x``. + + Returns: + Value rounded towards positive infinity. + """ + pass + + +def floor(x: float) -> int: + """Rounds down. + + Arguments: + x: The value ``x``. + + Returns: + Value rounded towards negative infinity. + """ + pass def trunc(x: float) -> int: + """Truncates decimals to get the integer part of a value. + + This is the same as rounding towards ``0``. + + Arguments: + x: The value ``x``. + + Returns: + Integer part of the value. """ - Returns an integer, being ``x`` rounded towards 0. + pass + + +def fmod(x: float, y: float) -> float: + """Gets the remainder of ``x / y``. + + Not to be confused with :func:`modf`. + + Arguments: + x: The numerator. + y: The denominator. + + Returns: + Remainder after division """ + pass + + +def fabs(x: float) -> float: + """Gets the absolute value of ``x``. + + Arguments: + x: The value. + + Returns: + Absolute value. + """ + pass + + +def modf(x: float) -> _Tuple[float, float]: + """Gets the fractional and integral parts of ``x``, both with the same sign + as ``x``. + + Not to be confused with :func:`fmod`. + + Arguments: + x: The value to be decomposed. + + Returns: + Tuple of fractional and integral parts. + """ + pass + + +def frexp(x: float) -> _Tuple[float, int]: + """Decomposes a value ``x`` into a + tuple ``(m, p)``, such that ``x == m * (2 ** p)``. + + Arguments: + x: The value to be decomposed. + + Returns: + Tuple of ``m`` and ``p``. + """ + pass + + +def ldexp(m: float, p: int) -> float: + """Computes ``m * (2 ** p)``. + + Arguments: + m: The value. + p: The exponent. + + Returns: + Result of ``m * (2 ** p)``. + """ + pass + + +def copysign(x: float, y: float) -> float: + """Gets ``x`` with the sign of ``y``. + + Arguments: + x: Determines the magnitude of the return value. + y: Determines the sign of the return value. + + Returns: + ``x`` with the sign of ``y``. + """ + pass + + +def isfinite(x: float) -> bool: + """Checks if ``x`` is finite. + + Returns: + ``True`` if ``x`` is finite, else ``False``. + """ + pass + + +def isinfinite(x: float) -> bool: + """Checks if ``x`` is infinite. + + Returns: + ``True`` if ``x`` is infinite, else ``False``. + """ + pass + + +def isnan(x: float) -> bool: + """Checks if ``x`` is not-a-number. + + Returns: + ``True`` if ``x`` is not-a-number, else ``False``. + """ + pass