The **Math Node** (`MathNode`) provides a high-performance numerical calculation and signal conditioning engine, supporting basic arithmetic, logical bounding, range mapping, custom JavaScript mathematical expressions, and multi-element sequence processing.

![Math Node](https://unilighter.cc/info/docs/node-graphs/math/math_node_final_221e4ed8.png)

---

## 🧮 Numeric & Sequence Polymorphism

The Math Node operates as a **numeric-polymorphic** processor across both scalar numbers and sequences:

- **Scalar Operations**: When all connected inputs are scalar numbers, the result is a scalar number.
- **Sequence Vectorization**: When any input is a sequence (array of numbers), the operation produces an output sequence whose length matches the longest input sequence.
- **Scalar Broadcasting**: Single scalar inputs are automatically broadcast to every element of the sequence (e.g. `[1, 2, 3] * 0.5` yields `[0.5, 1, 1.5]`).
- **Cyclic Sequence Alignment**: Shorter sequences automatically repeat cyclically to fill the length of the longest sequence (e.g. `[1, 2] + [10, 20, 30, 40]` yields `[11, 22, 31, 42]`).
- **Empty Sequence Handling**: If any connected sequence input is empty, the calculation produces an empty sequence output.

---

## ⚙️ Operation Modes

### 1. Basic Arithmetic
- `Add (A + B)`: Sum two signals (e.g. adding a scalar baseline offset to an oscillator sequence).
- `Subtract (A - B)`: Subtract signal B from A.
- `Multiply (A × B)`: Amplitude scaling (e.g. Master Dimmer multiplying a chasing wave sequence).
- `Divide (A ÷ B)`: Frequency scaling or ratio calculations.
- `Power (A ^ B)`: Exponential curves for perceptual LED brightness correction.

### 2. Logic, Clamping & Bounding
- `Minimum / Maximum`: Limit signals to lowest or highest peak.
- `Mean`: Average between two inputs or sequences.
- `Blend (A to B)`: Crossfade between signals using a float weight (`0.0 – 1.0`).
- `Clamp (Min/Max)`: Constrains output strictly between lower and upper boundaries.
- `Map Range`: Linearly maps an input range (`fromMin..fromMax`) to a target range (`toMin..toMax`).

### 3. Custom JavaScript Equations
Select **Custom Equation** to evaluate arbitrary mathematical expressions using native JavaScript:

- **Per-Element Evaluation**: Custom equations are evaluated once for each element in the resulting sequence.
- **Scalar Element Variables**: `a`, `b`, `factor`, `min`, `max`, `fromMin`, `fromMax`, `toMin`, `toMax` provide the current scalar values for element `i`.
- **Index & Length Variables**:
  - `i`: Zero-based index of the current element (`0, 1, 2, ..., n - 1`).
  - `n`: Total length of the result sequence.
- **Full Sequence Access**: `seq.<name>` exposes full normalized input sequences. For example, `seq.a` gives access to the entire array of input `A`:
```javascript
// Cyclic spatial neighbor modulation
a + seq.a[(i + 1) % n]

// Index-based phase progression
Math.sin(a * Math.PI * 2 + (i / n) * Math.PI) * 0.5 + 0.5
```

> [!NOTE]
> Custom equations must return a finite number for each element. Non-finite or invalid results evaluate to zero and flag the equation as invalid in the UI.

---

## 🔌 Sockets Reference

| Socket | Direction | Data Type | Description |
| :--- | :--- | :--- | :--- |
| **A** | Input | `Number` / `Sequence` | Primary operand (scalar or sequence). |
| **B** | Input | `Number` / `Sequence` | Secondary operand (scalar or sequence). |
| **Result** | Output | `Number` / `Sequence` | Calculated scalar number or polymorphic sequence. |