.. _calculation.logics.mxparser:

==========================
mXparser Calculation Logic
==========================

When you select the mXparser logic engine, you define expressions using standard mXparser syntax. mXparser is a powerful and flexible mathematical expression parser and evaluator library.

For more information, refer to the official documentation:
`mXparser Math Collection <https://mathparser.org/mxparser-math-collection/>`_.

Common mXparser Expressions
***************************


**Binary Relations**

These operators are used to compare values:

- ``=`` or ``==`` : Equality
- ``<>`` or ``!=`` : Inequality
- ``<`` : Less than
- ``>`` : Greater than
- ``<=`` : Less than or equal to
- ``>=`` : Greater than or equal to

**Boolean Operators**

These operators are used to combine logical conditions:

- ``&`` or ``&&`` : Logical AND
- ``|`` or ``||`` : Logical OR

**Conditional Expressions**

Conditional logic can be implemented using `if` and `iff` functions:

- ``if(condition, value-if-true, value-if-false)``

  Example:
  
  .. code-block:: text

     RESULT = if(INPUT == 1, 1, 0);

- ``iff(condition1, value1; condition2, value2; ...; conditionN, valueN)``

  Examples:
  
  .. code-block:: text

     RESULT = iff(INPUT == 1, 1; INPUT > 1, 2; INPUT < 1, 0);
     RESULT = iff(INPUT >= 1 && INPUT < 5, 1; INPUT >= 5, 2; INPUT < 1, 0);

**Random Variables and Common Uses**

mXparser supports random number generation for simulation or variability:

- ``[Uni]`` : Uniform continuous distribution U(0,1)
- ``[Int]`` : Random integer

  Example:

  .. code-block:: text

     RESULT = 100 * [Uni] + 1;


Using Input and Output Quality Value in Equations
*************************************************

FunctionBlock Formula Expressions (mXparser) support the use of **Input Pin Quality values** as arguments in equations. This is particularly useful for implementing logic that depends on the quality of input data, such as conditional comparisons. This is useful for comparison operations involving Quality checks. Additionally, Output Pin Quality values can be set within the expression to override the default derived quality.


**Quality Handling Logic**

- In the calculation logic, each input and output pin automatically receives an implicit argument with a ``xQV`` suffix.
  - For **inputs pins**, the value will be set to the related Pin's input quality value.
  - For **output pins**, the value will be initialised to ``NaN``.
- The implicit arguments can be used in the Formula Expression. For output pins, the implicit argument can be assigned a specific quality value to override the default behavior.
- On the resulting output pin updates, if its implicit argument was set in the Formula Expression (that is, not ``NaN``), then the output Pin Quality will be set to its corresponding implicit argument value.

**Example**

.. image:: images/wip.calc.mxparser.example.png

|

.. code-block:: text

   // Set PinC Quality to Good when PinA Quality is better than PinB Quality, else set to Bad.
   PinCxQV = if(PinAxQV < PinBxQV, 1, 30);
   PinC = PinA + PinB;

Explanation:

- This example uses two input pins and one output pin.
- ``PinAxQV``, ``PinBxQV``, and ``PinCxQV`` are implicit arguments automatically created by the calculation service.
- If you do not set ``PinCxQV`` to a value (that is, eliminate expression line 2), then its value remains ``NaN``, and the quality of ``PinC`` will default to the worst quality of PinA and PinB (default functionality).

.. note::

   The Output Pin Quality (e.g., ``PinCxQV``) must be set **before** the Output Pin Value (e.g., ``PinC``) in the expression.

When setting an Output Pin Quality value, the system checks the value against the valid quality values as shown in :ref:`data.quality`.

If the assigned value does not match a valid code, then the Quality value would be set to **Good** (1), **Suspect** (10), or **Bad** (30) based on based on the range it falls into. For example, a value of ``7`` would be adjusted to ``1`` since it is in the **Good** range of 0 to 9.

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

   * - Quality Range
     - Interpreted As
   * - 0-5
     - Good (1)
   * - 10-16
     - Suspect (10)
   * - 30-54
     - Bad (30)