Repository: sympy/sympy
File: sympy/functions/elementary/complexes.py (Python)

Code before:
            else:
                from sympy.functions.elementary.exponential import exp_polar
                return Mul(*positive)*exp_polar(0)

    def _eval_evalf(self, prec):
        """ Careful! any evalf of polar numbers is flaky """
        return self.args[0]._eval_evalf(prec)

    def _eval_Abs(self):
        return Abs(self.args[0], evaluate=True)


class periodic_argument(DefinedFunction):
    r"""
    Return the argument of a complex number modulo a given period.

    This represents the argument (angle) of a complex number on a quotient of
    the Riemann surface of the logarithm. Given a period ``P``, the value
    returned is always in the interval ``(-P/2, P/2]``.

    Formally, for a complex number ``z`` and period ``P``:

        periodic_argument(z, P) = arg(z) \bmod P, mapped to ``(-P/2, P/2]``

    Notes
    -----
    - ``arg(z)`` is the usual argument (angle) of a complex number.
    - When ``P = oo`` this gives the unbranched argument.
    - Example of the "wrapping" behavior::

        periodic_argument(exp_polar(5*I*pi), 3*pi) = -pi

      because :math:`5\pi \bmod 3\pi = 2\pi`, which lies outside
      :math:`(-3\pi/2, 3\pi/2]`, and subtracting :math:`3\pi` maps it to
      :math:`-\pi`.

    Examples
    --------
    >>> from sympy import exp_polar, periodic_argument, I, pi
    >>> periodic_argument(exp_polar(10*I*pi), 2*pi)
    0
    >>> periodic_argument(exp_polar(5*I*pi), 4*pi)
    pi
    >>> periodic_argument(exp_polar(5*I*pi), 2*pi)
    pi
    >>> periodic_argument(exp_polar(5*I*pi), 3*pi)
    -pi

    Parameters
    ----------
    ar : Expr

Review comment (suggestion):
Headings should be marked with equals signs rather than minus. See
https://docs.sympy.org/latest/contributing/docstring.html

Code after:
            else:
                from sympy.functions.elementary.exponential import exp_polar
                return Mul(*positive)*exp_polar(0)

    def _eval_evalf(self, prec):
        """ Careful! any evalf of polar numbers is flaky """
        return self.args[0]._eval_evalf(prec)

    def _eval_Abs(self):
        return Abs(self.args[0], evaluate=True)


class periodic_argument(DefinedFunction):
    r"""
    Return the argument of a complex number modulo a given period.

    This represents the argument (angle) of a complex number on a quotient of
    the Riemann surface of the logarithm. Given a period :math:`P`, the value
    returned is always in the interval :math:`(-P/2, P/2]`.

    Formally, for a complex number :math:`z` and period :math:`P`:

    .. math::

        \operatorname{periodic\_argument}(z, P) = \arg(z) \bmod P,
        \text{ mapped to } (-P/2, P/2].

    Parameters
    ==========

    ar : Expr
        A polar number (complex number in polar form).

    period : Expr
        The period :math:`P`. Typically a positive real expression or
        :math:`\infty` for the unbranched argument. Behaviour for
        non-positive or non-real periods is undefined.

    Notes
    =====

    - :math:`\arg(z)` is the usual argument (angle) of a complex number.
    - When :math:`P = \infty` this gives the unbranched argument.
    - Example of the "wrapping" behavior:

      .. code-block:: python

          >>> from sympy import exp_polar, I, pi
          >>> from sympy.functions.elementary.complexes import periodic_argument
          >>> periodic_argument(exp_polar(5*I*pi), 3*pi)
          -pi