.. _input-syntax:

Input Syntax Guide
==================

ToFUL accepts natural mathematical notation and automatically corrects
common variants before passing expressions to the computation engine.
This page documents everything the parser understands.

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

----

Basic Syntax Rules
------------------

Expressions are written as single-line Python-style conditionals:

.. code-block:: python

   <value_when_true>  if  <condition>  else  <value_when_false>

The variable is always ``x``. The condition defines the support of
the distribution.

.. code-block:: python

   # Correct
   2 * x  if  0 <= x <= 1  else  0

   # Also correct — no guard needed if the formula is already zero outside
   exp(-x)

----

Auto-Corrections Applied by the Parser
---------------------------------------

The parser normalises your input before evaluation. Corrections are
shown in a collapsible notice above the results.

Exponentiation
~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 35 30

   * - You type
     - Interpreted as
     - Notes
   * - ``x^2``
     - ``x**2``
     - Caret → Python power
   * - ``x²``
     - ``x**2``
     - Unicode superscript
   * - ``2^n``
     - ``2**n``
     - Any base/exponent

Implicit Multiplication
~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 35 30

   * - You type
     - Interpreted as
     - Notes
   * - ``2x``
     - ``2*x``
     - Digit × letter
   * - ``(x+1)(x-1)``
     - ``(x+1)*(x-1)``
     - Adjacent brackets
   * - ``2(x+1)``
     - ``2*(x+1)``
     - Digit × bracket

Exponential Notation
~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 35 30

   * - You type
     - Interpreted as
     - Notes
   * - ``e^x``
     - ``exp(x)``
     - Euler's number raised
   * - ``e^(-2*x)``
     - ``exp(-2*x)``
     - Negative exponent
   * - ``Exp(x)``
     - ``exp(x)``
     - Capitalised alias

Function Aliases
~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 35 30

   * - You type
     - Interpreted as
     - Notes
   * - ``ln(x)``
     - ``log(x)``
     - Natural logarithm
   * - ``arcsin(x)``
     - ``asin(x)``
     - Inverse trig
   * - ``√(x)``
     - ``sqrt(x)``
     - Unicode root sign
   * - ``√x``
     - ``sqrt(x)``
     - Without brackets

Unicode Operators
~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 35 30

   * - You type
     - Interpreted as
     - Notes
   * - ``≤``
     - ``<=``
     - Less-than-or-equal
   * - ``≥``
     - ``>=``
     - Greater-than-or-equal
   * - ``≠``
     - ``!=``
     - Not equal
   * - ``×``
     - ``*``
     - Multiplication sign
   * - ``÷``
     - ``/``
     - Division sign
   * - ``−``
     - ``-``
     - Unicode minus (U+2212)

Absolute Value
~~~~~~~~~~~~~~

.. code-block:: text

   |x - 1|           ->   abs(x - 1)
   |x|               ->   abs(x)

Subscript Variables
~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 35 30

   * - You type
     - Interpreted as
     - Notes
   * - ``x₁``
     - ``x1``
     - Unicode subscript
   * - ``x_1``
     - ``x1``
     - Underscore notation
   * - ``y₂``
     - ``y2``
     - Any letter + digit

Greek Letters
~~~~~~~~~~~~~

Unicode Greek letters are mapped to their conventional parameter names:

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

   * - Symbol
     - Name in eval context
     - Typical use
   * - ``π``
     - ``pi``
     - Mathematical constant
   * - ``λ``
     - ``lam``
     - Rate parameter (Poisson, Exponential)
   * - ``μ``
     - ``mu``
     - Mean parameter
   * - ``σ``
     - ``sigma``
     - Standard deviation
   * - ``α``
     - ``alpha``
     - Shape parameter
   * - ``β``
     - ``beta``
     - Scale parameter
   * - ``θ``
     - ``theta``
     - General parameter

----

Available Functions
-------------------

All standard mathematical functions are available by name:

**Exponential & Logarithmic**

.. code-block:: text

   exp(x)      natural exponential e^x
   log(x)      natural logarithm ln(x)
   log2(x)     base-2 logarithm
   log10(x)    base-10 logarithm
   sqrt(x)     square root

**Trigonometric**

.. code-block:: text

   sin(x)   cos(x)   tan(x)
   asin(x)  acos(x)  atan(x)   atan2(y, x)
   sinh(x)  cosh(x)  tanh(x)

**Rounding & Sign**

.. code-block:: text

   abs(x)     absolute value
   ceil(x)    ceiling
   floor(x)   floor
   sign(x)    sign function (+1, 0, -1)
   round(x)   round to nearest integer

**Special Functions**

.. code-block:: text

   factorial(n)   n!  (integer n only, DRV expressions)
   gamma(x)       Gamma function Γ(x)
   erf(x)         error function
   erfc(x)        complementary error function

**Constants**

.. code-block:: text

   pi    π ≈ 3.14159265…
   e     Euler's number ≈ 2.71828182…
   inf   positive infinity (use in bounds only)

----

Piecewise Expressions
----------------------

All piecewise functions use Python's ternary conditional:

.. code-block:: python

   <result_if_true>  if  <condition>  else  <result_if_false>

Multiple pieces can be chained:

.. code-block:: python

   # Triangular distribution on [0, 2] with peak at 1
   x  if  0 <= x <= 1  else  (2 - x)  if  1 < x <= 2  else  0

Chained comparisons work natively:

.. code-block:: python

   0 <= x <= 1        # equivalent to  0 <= x and x <= 1

----

Range Input Syntax
------------------

**Discrete ranges:**

.. code-block:: text

   1,2,3,4,5          Finite — exactly these values
   0,1,2,3,...        Infinite arithmetic sequence (step detected automatically)
   1,2,4,8,...        Infinite geometric sequence (ratio detected automatically)

**Continuous bounds:**

.. code-block:: text

   0         numeric lower/upper bound
   inf       positive infinity
   -inf      negative infinity
   ∞         Unicode infinity (auto-converted)
   -∞        Unicode negative infinity

----

Common Mistakes
---------------

``factorial`` with float arguments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``factorial`` only accepts non-negative integers. For continuous
distributions, use ``gamma(x+1)`` (which equals ``factorial(x)`` for
integers but is defined on the reals).

.. code-block:: python

   # Wrong — raises TypeError for non-integer x
   factorial(x)

   # Correct for continuous distributions
   gamma(x + 1)

Missing ``else 0``
~~~~~~~~~~~~~~~~~~

If the function is undefined outside the stated range, always include
a guard:

.. code-block:: python

   # Risky — may evaluate to a non-zero value outside the intended support
   exp(-x)

   # Correct
   exp(-x) if x >= 0 else 0

Syntax check before computing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

After entering a function, the interpreted form is shown (in teal
monospace) below the function field before you click Compute. Check
this to verify the parser understood your intent correctly.