Mathematical Functions
======================

.. currentmodule:: numpycore

Mathematical functions operating element-wise on arrays.

Trigonometric Functions
-----------------------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Function
     - Description
     - Example
   * - sin(x)
     - Sine
     - 
   * - cos(x)
     - Cosine
     - 
   * - tan(x)
     - Tangent
     - 
   * - arcsin(x)
     - Inverse sine
     - 
   * - arccos(x)
     - Inverse cosine
     - 
   * - arctan(x)
     - Inverse tangent
     - 
   * - arctan2(y, x)
     - Four-quadrant inverse tangent
     - 
   * - hypot(x1, x2)
     - Hypotenuse
     - 
   * - degrees(x)
     - Convert radians to degrees
     - 
   * - radians(x)
     - Convert degrees to radians
     - 

Hyperbolic Functions
--------------------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Function
     - Description
     - Example
   * - sinh(x)
     - Hyperbolic sine
     - 
   * - cosh(x)
     - Hyperbolic cosine
     - 
   * - tanh(x)
     - Hyperbolic tangent
     - 
   * - arcsinh(x)
     - Inverse hyperbolic sine
     - 
   * - arccosh(x)
     - Inverse hyperbolic cosine
     - 
   * - arctanh(x)
     - Inverse hyperbolic tangent
     - 

Exponential and Logarithmic
---------------------------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Function
     - Description
     - Example
   * - exp(x)
     - Exponential
     - 
   * - expm1(x)
     - exp(x) - 1
     - 
   * - exp2(x)
     - 2**x
     - 
   * - log(x)
     - Natural logarithm
     - 
   * - log10(x)
     - Base-10 logarithm
     - 
   * - log2(x)
     - Base-2 logarithm
     - 
   * - log1p(x)
     - log(1 + x)
     - 
   * - logaddexp(x1, x2)
     - Log of sum of exponentials
     - 
   * - logaddexp2(x1, x2)
     - Log base 2 of sum of exponentials
     - 

Arithmetic Operations
---------------------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Function
     - Description
     - Example
   * - add(x1, x2)
     - Add arguments element-wise
     - 
   * - subtract(x1, x2)
     - Subtract arguments element-wise
     - 
   * - multiply(x1, x2)
     - Multiply arguments element-wise
     - 
   * - divide(x1, x2)
     - Divide arguments element-wise
     - 
   * - floor_divide(x1, x2)
     - Floor division
     - 
   * - negative(x)
     - Numerical negative
     - 
   * - positive(x)
     - Numerical positive
     - 
   * - power(x1, x2)
     - First array elements raised to powers
     - 
   * - remainder(x1, x2)
     - Remainder of division
     - 
   * - mod(x1, x2)
     - Remainder (alias for remainder)
     - 

Rounding
--------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Function
     - Description
     - Example
   * - around(a, decimals)
     - Round to given decimals
     - 
   * - round_(a, decimals)
     - Round to given decimals
     - 
   * - rint(x)
     - Round to nearest integer
     - 
   * - floor(x)
     - Floor of input
     - 
   * - ceil(x)
     - Ceiling of input
     - 
   * - trunc(x)
     - Truncate to integer
     - 

Miscellaneous
-------------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Function
     - Description
     - Example
   * - sqrt(x)
     - Square root
     - :ref:`View <example-math-misc-sqrt-0>`
   * - cbrt(x)
     - Cube root
     - 
   * - square(x)
     - Square of input
     - 
   * - absolute(x)
     - Absolute value
     - 
   * - fabs(x)
     - Absolute value (floats)
     - 
   * - sign(x)
     - Sign of elements
     - 
   * - maximum(x1, x2)
     - Element-wise maximum
     - 
   * - minimum(x1, x2)
     - Element-wise minimum
     - 
   * - clip(a, a_min, a_max)
     - Clip values to range
     - 

Code Examples
-------------

The following examples are extracted from the test suite.

.. _example-math-misc-sqrt-0:

.. dropdown:: sqrt (test_sqrt_type_promotion.py:26)
   :class-title: example-dropdown

   .. code-block:: python
      :linenos:
      :lineno-start: 16
      :emphasize-lines: 11

      tests_run = 0
      tests_passed = 0
      tests_failed = 0
      
      def test_sqrt_int8_to_float64():
          """Test int8 array promotes to float64"""
          global tests_run, tests_passed, tests_failed
          tests_run += 1
      
          arr = test_bind.np.array([4, 9, 16, 25], dtype=test_bind.np.int8)
          result = test_bind.numpycore.sqrt(arr)
      
          if result.dtype != test_bind.np.float64:
              test_bind.f_print_error(f"int8->float64: Expected float64, got {result.dtype}")
              tests_failed += 1
              return
      
          if not (abs(result[0] - 2.0) < 1e-10 and abs(result[1] - 3.0) < 1e-10
                  and abs(result[2] - 4.0) < 1e-10 and abs(result[3] - 5.0) < 1e-10):
              test_bind.f_print_error(f"int8->float64: Values incorrect")
              tests_failed += 1