Estimators

Useful building blocks for implementing update rules. These are the estimators used by and available in the QuantAMM V1 protocol.

calc_gradients(update_rule_parameter_dict, chunkwise_price_values, chunk_period, max_memory_days, use_alt_lamb, cap_lamb=True, safety_margin_multiplier=5.0)[source]

Calculate time-weighted price gradients for TFMM strategy implementation.

Computes gradients of price movements using exponentially weighted moving averages (EWMA), with support for both CPU and GPU acceleration via JAX. Implements the gradient calculation described in the TFMM litepaper, with additional features for alternative memory lengths.

Parameters:

  • update_rule_parameter_dict (dict) – Dictionary containing strategy parameters including: - ‘logit_lamb’: Controls the base memory length - ‘logit_delta_lamb’: Optional, controls alternative memory length if use_alt_lamb=True

  • chunkwise_price_values (ndarray) – Array of shape (time_steps, n_assets) containing price values for each asset over time

  • chunk_period (float) – Time period between chunks in minutes

  • max_memory_days (float) – Maximum allowed memory length in days, used to cap lambda parameters

  • use_alt_lamb (bool) – Whether to use an alternative lambda parameter for part of the calculation. Enables different parts of update rules to act over different memory lengths

  • cap_lamb (bool, optional) – Whether to apply maximum memory day restriction to lambda parameters. Defaults to True

  • safety_margin_multiplier (float, optional) – Multiplier for padding length in GPU/conv path. Higher values ensure EWMA convergence but use more memory. Theoretical minimum is ~1.9x for 99.9% convergence. Defaults to 5.0

Returns:

Array of shape (time_steps-1, n_assets) containing calculated gradients. For each asset, represents the time-weighted rate of change of prices.

Return type:

ndarray

Notes

The function implements two calculation paths:

  1. GPU path: Uses convolution operations for efficient parallel computation - Pads input data to handle initialization - Creates specialized kernels for EWMA calculation - Leverages GPU parallelism for efficient computation

  2. CPU path: Uses scan operations for sequential computation - More memory efficient - Uses a scan operation, so is fundamentally sequential

The gradient calculation follows the methodology described in the TFMM litepaper, using exponential weighting to estimate price trends while avoiding look-ahead bias.

calc_ewma_pair(memory_days_1, memory_days_2, chunkwise_price_values, chunk_period, max_memory_days, cap_lamb=True)[source]

Calculate two exponentially weighted moving averages (EWMAs) with different memory lengths.

Core estimator for Difference Momentum strategies, implementing the MACD-like comparison:

\[1 - \frac{E_2(\mathbf{p}(t))}{E_1(\mathbf{p}(t))}\]

where E₁ and E₂ are EWMAs with memory lengths m₁ and m₂ respectively. Typically m₂ > m₁ for trend comparison.

This function outputs the EWMAs for the two memory lengths used in the above formula. It supports both CPU and GPU paths, with GPU being more efficient for larger datasets.

Parameters:

  • memory_days_1 (float) – Memory length for first EWMA in days. Typically shorter period (m₁), making it more responsive to recent price changes.

  • memory_days_2 (float) – Memory length for second EWMA in days. Typically longer period (m₂), providing baseline for trend comparison.

  • chunkwise_price_values (jnp.ndarray) – Price/oracle values of shape (time, assets). Can be any oracle value, not just prices (see Notes).

  • chunk_period (float) – Time period between chunks in minutes. Used to convert between memory_days and λ parameters.

  • max_memory_days (float) – Maximum allowed memory length in days. Prevents numerical instability from extremely long memory periods.

  • cap_lamb (bool, optional) – Whether to cap λ values to prevent numerical issues, by default True. Recommended for numerical stability.

Returns:

  • tuple[jnp.ndarray, jnp.ndarray] – Two EWMA arrays of shape (time - 1, assets) (each same shape as calc_gradients). Notes

  • —–

  • Implementation details

  • 1. Converts memory_days to λ values using – λ = memory_days_to_lamb(memory_days, chunk_period)

  • 2. GPU acceleration –

    • Uses convolution for parallel computation

    • Adds 5 * max_memory_days padding for initialization

    • Returns padded arrays for consistent calculations

  • 3. CPU computation –

    • Uses sequential scan operations

    • More memory efficient for smaller datasets

  • The function ensures

  • - Non-negative memory lengths

  • - Numerical stability through λ capping

See also

DifferenceMomentumPool

Primary user of this function

calc_gradients

Alternative trend estimation approach

calc_return_variances(update_rule_parameter_dict, chunkwise_price_values, chunk_period, max_memory_days, cap_lamb)[source]

Calculate time-weighted return variances for TFMM strategy implementation.

Computes the variance of asset returns using exponentially weighted moving averages (EWMA), with support for both CPU and GPU acceleration via JAX. Essential for minimum variance portfolio calculations and related risk estimation.

Parameters:

  • update_rule_parameter_dict (dict) – Dictionary containing strategy parameters, supporting two parameterizations: 1. Direct memory specification: - ‘memory_days_1’: Direct specification of memory length in days 2. Logit parameterization: - ‘logit_lamb’: Controls memory length through logit transform

  • chunkwise_price_values (ndarray) – Array of shape (time_steps, n_assets) containing price values for each asset over time

  • chunk_period (float) – Time period between chunks in minutes

  • max_memory_days (float) – Maximum allowed memory length in days, used to cap lambda parameters

  • cap_lamb (bool) – Whether to apply maximum memory day restriction to lambda parameters

Returns:

Array of shape (time_steps-1, n_assets) containing calculated variances. For each asset, represents the time-weighted variance of returns.

Return type:

ndarray

Notes

The function implements two calculation paths:

1. GPU path: Uses convolution operations for efficient parallel computation - Pads input data to handle initialization - Creates specialized kernels for variance calculation - Combines EWMA and covariance kernels for efficient computation

2. CPU path: Uses scan operations for sequential computation - More memory efficient for smaller datasets - Direct implementation of variance formula

The variance calculation follows the methodology described in the TFMM litepaper, using exponential weighting to estimate return variances while avoiding look-ahead bias.

See also

MinVariancePool

Primary user of this function

calc_gradients

Calculates price gradients using similar EWMA methodology

calc_ewma_pair

Calculates EWMA pairs for difference momentum strategies