.. _mathematical-functions:

Mathematical Functions Reference
==================================

Every function and constant available in ToFUL expression fields is
listed here. The same namespace applies to both the PMF/PDF field and
— where relevant — to the range field.

.. contents:: On this page
   :local:
   :depth: 2

----

Constants
---------

.. list-table::
   :header-rows: 1
   :widths: 15 20 65

   * - Name
     - Value
     - Notes
   * - ``pi``
     - 3.14159265…
     - Mathematical constant π. Also accepted as ``π`` (Unicode).
   * - ``e``
     - 2.71828182…
     - Euler's number. Do **not** use ``e`` as a variable name.
   * - ``inf``
     - ∞
     - Positive infinity. Use in bounds fields only.
   * - ``nan``
     - Not a Number
     - Returned by undefined operations. Avoid in PMF/PDF.

----

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

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Function
     - Description
   * - ``exp(x)``
     - Exponential function :math:`e^x`. Alias: ``e^x``, ``Exp(x)``.
   * - ``log(x)``
     - Natural logarithm :math:`\ln x`. Alias: ``ln(x)``, ``Ln(x)``.
       Undefined for :math:`x \leq 0`.
   * - ``log2(x)``
     - Base-2 logarithm :math:`\log_2 x`.
   * - ``log10(x)``
     - Base-10 logarithm :math:`\log_{10} x`. Alias: ``log10(x)``.
   * - ``sqrt(x)``
     - Square root :math:`\sqrt{x}`. Alias: ``√(x)``, ``√x``.
       Undefined for :math:`x < 0`.

----

Trigonometric
--------------

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Function
     - Description
   * - ``sin(x)``
     - Sine (argument in radians).
   * - ``cos(x)``
     - Cosine (argument in radians).
   * - ``tan(x)``
     - Tangent (argument in radians). Undefined at :math:`x = \pi/2 + k\pi`.
   * - ``asin(x)``
     - Arcsine. Range :math:`[-\pi/2, \pi/2]`. Alias: ``arcsin(x)``.
   * - ``acos(x)``
     - Arccosine. Range :math:`[0, \pi]`. Alias: ``arccos(x)``.
   * - ``atan(x)``
     - Arctangent. Range :math:`(-\pi/2, \pi/2)`. Alias: ``arctan(x)``.
   * - ``atan2(y, x)``
     - Four-quadrant arctangent. Returns angle in :math:`(-\pi, \pi]`.
   * - ``sinh(x)``
     - Hyperbolic sine.
   * - ``cosh(x)``
     - Hyperbolic cosine.
   * - ``tanh(x)``
     - Hyperbolic tangent.

----

Rounding and Sign
------------------

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Function
     - Description
   * - ``abs(x)``
     - Absolute value :math:`|x|`. Alias: ``|x|``.
   * - ``ceil(x)``
     - Ceiling — smallest integer ≥ x.
   * - ``floor(x)``
     - Floor — largest integer ≤ x.
   * - ``sign(x)``
     - Sign function: −1 for negative, 0 for zero, +1 for positive.
   * - ``round(x)``
     - Round to nearest integer (banker's rounding for .5).
   * - ``min(a, b)``
     - Minimum of two values.
   * - ``max(a, b)``
     - Maximum of two values.

----

Special Functions
------------------

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Function
     - Description
   * - ``factorial(n)``
     - Factorial :math:`n!`. Integer argument only. For real-valued
       generalisation, use ``gamma(n+1)``.
   * - ``gamma(x)``
     - Gamma function :math:`\Gamma(x) = \int_0^\infty t^{x-1}e^{-t}\,dt`.
       Satisfies :math:`\Gamma(n) = (n-1)!` for positive integers.
   * - ``erf(x)``
     - Error function :math:`\text{erf}(x) = \frac{2}{\sqrt{\pi}}\int_0^x e^{-t^2}\,dt`.
   * - ``erfc(x)``
     - Complementary error function :math:`\text{erfc}(x) = 1 - \text{erf}(x)`.

----

Operator Reference
-------------------

.. list-table::
   :header-rows: 1
   :widths: 20 20 60

   * - Operator
     - Unicode alias
     - Meaning
   * - ``+``
     - —
     - Addition
   * - ``-``
     - ``−`` (U+2212)
     - Subtraction / negation
   * - ``*``
     - ``×``, ``·``
     - Multiplication
   * - ``/``
     - ``÷``
     - Division (true division, always returns float)
   * - ``**``
     - ``^``, superscripts
     - Exponentiation
   * - ``<=``
     - ``≤``
     - Less than or equal
   * - ``>=``
     - ``≥``
     - Greater than or equal
   * - ``==``
     - —
     - Equal (use in conditionals: ``if x == 0``)
   * - ``!=``
     - ``≠``
     - Not equal
   * - ``and``
     - ``∧``
     - Logical and (for compound conditions)
   * - ``or``
     - ``∨``
     - Logical or
   * - ``not``
     - ``¬``
     - Logical not

----

Examples
---------

.. code-block:: python

   # Gamma(alpha=3, beta=2) PDF
   (x**2 * exp(-x/2)) / (2**3 * gamma(3))  if x >= 0  else 0

   # Standard Normal PDF
   exp(-(x**2)/2) / sqrt(2*pi)

   # Poisson(lambda=4) PMF
   (exp(-4) * 4**x) / factorial(x)  if x >= 0  else 0

   # Beta(2,3) PDF — check: normalising constant = B(2,3)^-1 = 12
   12 * x * (1-x)**2  if  0 <= x <= 1  else  0

   # Laplace(mu=0, b=1) PDF
   exp(-abs(x)) / 2

See also
--------

* :doc:`/getting-started/input-syntax` — full parser auto-correction table
* :doc:`/troubleshooting/debugging-functions` — fixing syntax errors