WHALE ENGINE
Documentation

Momentum (mom)

[[mom]] measures the raw change in its source between the current candle and its value length candles ago. It produces one unbounded series expressed in the same unit as the source.

A positive value means the source is above its past value, a negative value means it is below it, and zero means the two values are equal. Distance from zero represents the size of the change. Because the result is not normalized, its magnitude also depends on the scale of the source: momentum is a raw difference in source units, not a percentage.

Block declaration

A strategy can contain multiple [[mom]] blocks. Each block outputs one numeric series: the gap between the source and its value length candles earlier.

Examples

Minimal setup

This block measures the momentum of the close series over 10 candles. Since source is omitted, it defaults to close. It uses the main symbol and timeframe defined in [backtest].

[[mom]]
id     = "mom"
length = 10

Specific source

This block computes momentum on the hlc3 source (average of high, low, and close) instead of close.

[[mom]]
id     = "mom"
source = "hlc3"
length = 10

Source from another indicator

This block measures the momentum of the series produced by the rsi block, that is, how far the RSI has moved over 5 candles.

[[rsi]]
id     = "rsi"
length = 14

[[mom]]
id     = "rsi_mom"
source = "rsi"
length = 5

Search for the optimal length

This block explores a range of length values to identify the best-performing distance.

[[mom]]
id           = "mom"
length.start = 5
length.stop  = 30
length.step  = 5

Dedicated symbol and timeframe

In this configuration, momentum runs on the daily series from BINANCE:ETHUSDT, independently of the primary symbol and timeframe used by the rest of the strategy. See Exchanges, Symbols and Timeframes for alignment rules.

[[mom]]
id        = "mom"
length    = 10
symbol    = "BINANCE:ETHUSDT"
timeframe = "D"

Parameters

ParameterDescription
id
 String
 Required		Unique name identifying the mom series; the block exposes one numeric series with this identifier.
source
 String
 or Array
 Optional		Input series used for the calculation.
Accepted forms: source = "hlc3" or source = ["close", "hlc3"].
Each value can be either a standard price source (open, close, high, low, hl2, hlc3, ohlc4, hlcc4, volume) or the id of another indicator.
Default value: "close"
length
 Integer
 Required		Number of candles separating the current value from the past value it is compared with; must be between 1 and 10000.

Usage:
• Fixed: length = value
• Grid search:
– length.start = min_value
– length.stop = max_value
– length.step = value (optional, default 1)
symbol
 String
 or Array
 Optional		Market symbol(s) that provide the source series when source contains standard prices (open, close, high, low, hl2, hlc3, ohlc4, hlcc4, volume).
If source mixes standard prices and indicator ids, symbol is applied only to combinations based on standard prices.
If source contains only indicator ids, symbol is ignored.
For format and alignment details, see Exchanges, Symbols and Timeframes.
timeframe
 String
 or Array
 Optional		Timeframe on which this indicator is computed.
If timeframe is omitted, the computation uses the grid’s main timeframe defined in [backtest].
For accepted formats and timeframe alignment rules, see Exchanges, Symbols and Timeframes.

Available variables

The mom block exposes one numeric series, its calculation length, and metadata about the input source, symbol, and timeframe. You can use these identifiers directly inside your expressions.

Assume the block is configured as:

[[mom]]
id     = "mom"
source = "close"
length = 10

Then:

VariableDescription
mom or mom[0]
Decimal		Current momentum value (gap between the source and its value length candles ago).
mom[n]
Decimal		Momentum value from n candles ago.
mom.length
Decimal		Distance in candles used for the calculation.
mom.source
String		Name of the input source series (e.g., close, hlc3, or another indicator id).
mom.symbol
String		Symbol from which the input data is read.
mom.timeframe
String		Timeframe on which the mom is computed.

Notes

  • During warm-up, the first length candles have no past value available and the series is NaN. If any value inside the window is NaN, the result for that candle is NaN as well.
  • Numeric variables support arithmetic, comparisons, and logical operators.
  • Text variables are strings intended for equality/inequality checks only.
Prev
Mode (mode)
Next
Moving Average Convergence Divergence (macd)