Built-in Functions
Soma provides over 40 built-in functions available in every script without imports. All arithmetic and math functions work element-wise on Float64Array inputs, with scalar-array broadcasting where applicable.
Arithmetic
Element-wise arithmetic. When one operand is a Float64Array and the other is a scalar, the scalar is broadcast across all elements.
| Signature | Returns | Description |
|---|---|---|
| pow(x, y) | num | num[] | x raised to power y, element-wise. |
| min(x, y) | num | num[] | Element-wise minimum of two values or arrays. |
| max(x, y) | num | num[] | Element-wise maximum of two values or arrays. |
| mod(x, y) | num | num[] | x modulo y. Returns NaN when y = 0. |
| clamp(x, lo, hi) | num | num[] | Clamp each element of x to the range [lo, hi]. |
| abs(x) | num | num[] | Absolute value. |
| sqrt(x) | num | num[] | Square root. |
| floor(x) | num | num[] | Round down to nearest integer. |
| ceil(x) | num | num[] | Round up to nearest integer. |
| round(x) | num | num[] | Round to nearest integer (half-up). |
| log(x) | num | num[] | Natural logarithm (base e). |
| log2(x) | num | num[] | Logarithm base 2. |
| log10(x) | num | num[] | Logarithm base 10. |
| exp(x) | num | num[] | e raised to the power x. |
| sign(x) | num | num[] | Returns -1, 0, or 1 depending on the sign of x. |
Trigonometry
All angles in radians. Element-wise when x is an array.
| Signature | Returns | Description |
|---|---|---|
| sin(x) | num | num[] | Sine. |
| cos(x) | num | num[] | Cosine. |
| tan(x) | num | num[] | Tangent. |
| asin(x) | num | num[] | Arc sine. Result in [-π/2, π/2]. |
| acos(x) | num | num[] | Arc cosine. Result in [0, π]. |
| atan(x) | num | num[] | Arc tangent. Result in (-π/2, π/2). |
| atan2(y, x) | num | num[] | Arc tangent of y/x, using the signs of both to determine the quadrant. Result in (-π, π]. |
| hypot(x, y) | num | num[] | Euclidean distance: √(x² + y²). |
Array Utilities
Functions for inspecting, slicing, and constructing arrays.
| Signature | Returns | Description |
|---|---|---|
| len(x) | num | Length of an array. Returns 1 for a scalar. |
| sum(x) | num | Sum of all non-NaN elements. |
| mean(x) | num | Average of all non-NaN elements. Returns NaN if empty. |
| last(x) | num | Last non-NaN element. Returns NaN if none found. |
| first(x) | num | First non-NaN element. Returns NaN if none found. |
| slice(x, start[, end]) | num[] | Sub-array from start (inclusive) to end (exclusive). Negative indices count from the end of the array. |
| fill(n, val) | num[] | Create a Float64Array of length n with every element set to val. |
| zeros(n) | num[] | Create a Float64Array of n zeros. Equivalent to fill(n, 0). |
| concat(a, b) | num[] | Concatenate two arrays end-to-end. A scalar operand is treated as a single-element array. |
| range(n) | num[] | Integer sequence [0, 1, 2, …, n-1]. |
| range(start, stop[, step]) | num[] | Sequence from start (inclusive) to stop (exclusive) with the given step (default 1). Negative step produces descending sequences. |
| linspace(start, stop, n) | num[] | n evenly spaced values from start to stop (both inclusive). |
| reverse(x) | num[] | A reversed copy of x. Does not modify the original. |
| sort(x) | num[] | An ascending-sorted copy of x. NaN values sort to the end. |
Array Reductions
Scalar results from array inputs.
| Signature | Returns | Description |
|---|---|---|
| any(x) | num | Returns 1 if any element of x is non-zero (and non-NaN), otherwise 0. |
| all(x) | num | Returns 1 if all elements of x are non-zero (and non-NaN), otherwise 0. |
| count(x) | num | Number of non-NaN elements in x. |
| nz(x[, replacement]) | num | num[] | Replace NaN values with replacement (default 0). Element-wise when x is an array. |
Type Checks & Cleaning
Functions for testing and filtering NaN values.
| Signature | Returns | Description |
|---|---|---|
| isnan(x) | num | num[] | Returns 1 where x is NaN, 0 elsewhere. Element-wise for arrays. |
| isfinite(x) | num | num[] | Returns 1 where x is finite (not NaN and not ±Infinity), 0 elsewhere. |
| prune(x) | num[] | Remove all NaN values and return a compact array. Useful for stripping warm-up NaNs from indicator outputs before further calculations. |
Time-Series
Shift, difference, and cumulative operations preserving chronological bar order.
| Signature | Returns | Description |
|---|---|---|
| lag(x, n) | num[] | Shift array x forward by n positions. The first n elements become NaN. Equivalent to looking back n bars. |
| diff(x[, n]) | num[] | First difference: x[i] − x[i−n]. Default n = 1. The first n elements are NaN. |
| cumsum(x) | num[] | Cumulative sum. Each element is the running total of all previous non-NaN elements. |
| roc(x, n) | num[] | Rate of change: (x[i] − x[i−n]) / |x[i−n]| × 100. Returns percentage change over n bars. |
Built-in Indicators
Indicator functions that delegate to the same processing passes used by native indicator nodes. Results contain NaN for warm-up bars.
| Signature | Returns | Description |
|---|---|---|
| sma(x, period) | num[] | Simple moving average over a rolling window of size period. The first period−1 values are NaN. |
| ema(x, period) | num[] | Exponential moving average with smoothing factor 2/(period+1). Starts from the first available value. |
| stdev(x, period) | num[] | Rolling population standard deviation over period bars. The first period−1 values are NaN. |
I/O
Logging and debugging output visible in the Soma console.
| Signature | Returns | Description |
|---|---|---|
| print(...args) | null | Log one or more values to the Soma logger panel. Arrays are shown up to 8 elements, with a count suffix for longer arrays (e.g. [1, 2, 3, … (100 total)]). Always returns null. |