Target Volume Limit

target_volume_limit_args Parameter Explained

Overview

The target_volume_limit_args parameter is an optional argument passed to the Simulator's run method. It is used to configure complex constraints that are applied during the calculation phase of the target position or target trading volume in a backtest. This parameter is provided as a dictionary and can contain configurations for various processors (processors key) as well as other top-level settings that control the constraint application process.

This setting allows for more sophisticated volume constraint logic than the simpler volume_capacity_ratio. It is useful for scenarios such as trading only within a specific universe of stocks, adjusting target volumes based on liquidity, or controlling how target weights are redistributed when constraints are met.

Structure

The target_volume_limit_args dictionary typically has the following structure:

target_volume_limit_args = {
    # Optional: Processor configurations for applying constraints
    "processors": [
        {
            "type": "processor_type_1",
            # Settings specific to processor_type_1...
        },
        {
            "type": "processor_type_2",
            # Settings specific to processor_type_2...
        },
        # ... Add more processors as needed
    ],

    # Optional: Other top-level settings controlling the constraint process
    "redistribute_max_iter": 0,
    # ... other potential top-level keys ...
}

# Example usage when calling the Simulator
simulator_instance.run(
    position=position_data,
    target_volume_limit_args=target_volume_limit_args,
    # Other configuration arguments...
)

Top-Level Settings

These keys exist directly within the target_volume_limit_args dictionary, alongside the processors key.

redistribute_max_iter

• Type: int

• Default: 0 (usually, based on config/templates.py)

• Purpose: Controls the maximum number of iterations for redistributing target values (weights or amounts) when a constraint applied by a processor (like trading_volume) limits the target for a specific asset.

• Details: If an asset's target value is reduced due to a constraint, the "excess" or unallocated portion might be redistributed among other eligible assets according to the remaining weights. This process can be iterative because redistributing to another asset might cause it to hit a constraint. redistribute_max_iter sets a limit on how many rounds of redistribution are attempted.

• A value of 0 typically disables this redistribution logic. Positive integers specify the maximum number of iterations.

Available Processor Types (processors list)

The processors key holds a list of dictionaries, where each dictionary defines a specific constraint processor. Processor type values must be unique within the list.

1. type: "trading_volume"

• Purpose: Limits the target trading volume for individual assets to a certain percentage of their rolling average daily volume over a specified period. This helps prevent setting excessive targets for illiquid stocks and smooths out volume fluctuations.

• Required Settings:

  • limit_ratio: float - The maximum allowable volume ratio (e.g., 0.1 limits the target to 10% of the reference average volume).

  • rolling_window: int - The period (in trading days, e.g., 20 for the past 20 trading days) over which to calculate the rolling average volume that serves as the reference.

• (Note) Internally, the rolling calculation uses min_periods=1, allowing calculation even if fewer data points than the rolling_window are available at the beginning of the simulation.

• Code Example:

# Limit target volume to within 5% of the 20-day rolling average volume
# Processors list within target_volume_limit_args
processors_config = [
    {
        "type": "trading_volume",
        "limit_ratio": 0.05,
        "rolling_window": 20  # Required!
    }
]
target_volume_limit_args = {"processors": processors_config, "redistribute_max_iter": 0}

2. type: "universe"

• Purpose: Restricts target volume calculations to only those assets included in specific universes (e.g., constituents of market indices like Nasdaq 100 or S&P 500). Used to define the eligible set of assets for a particular strategy.

• Key Settings:

  • sub_universe: list[str] - A list of universe names (e.g., ['ndx', 'spx']) for which target volumes should be calculated. Assets belonging to at least one of the specified universes will be considered. The DataHandler must be able to provide constituent data for these universes.

• Code Example:

# Calculate target volumes only for constituents of Nasdaq 100 ('ndx') or S&P 500 ('spx') indices
# Processors list within target_volume_limit_args
processors_config = [
    {
        "type": "universe",
        "sub_universe": ['ndx', 'spx'] # Use relevant universe identifiers
    }
]
target_volume_limit_args = {"processors": processors_config, "redistribute_max_iter": 0}

Combining Multiple Processors

You can combine multiple processor configurations within the processors list. For instance, to apply a volume limit only to S&P 500 ('spx') stocks:

target_volume_limit_args = {
    "processors": [
        {
            "type": "universe",
            "sub_universe": ['spx'] # 1st: Filter for S&P 500 stocks
        },
        {
            "type": "trading_volume",
            "limit_ratio": 0.1,          # 2nd: Apply 10% volume limit to the filtered stocks
            "rolling_window": 20         # Required for trading_volume
        }
    ],
    "redistribute_max_iter": 0 # Example: No redistribution even if limits are hit
}

Internally, the universe processor might filter the target assets first, and then the trading_volume processor could be applied to the filtered set to calculate the final target volume (the exact order and interaction depend on the internal implementation, but generally, constraints are combined, often using the minimum resulting limit). The redistribute_max_iter setting then governs whether any resulting excess target allocation is redistributed.

Difference from volume_capacity_ratio

• target_volume_limit_args: Affects the logic used to calculate the target volume itself, including applying constraints like rolling volume limits and potentially redistributing allocations before the execution phase. It operates during the planning phase.

• volume_capacity_ratio: Applies an additional constraint based on the current day's total volume after the target volume has already been calculated (potentially modified by target_volume_limit_args). It operates during the execution simulation phase, acting as a final check against market liquidity for that specific day.

Therefore, these two options operate at different stages and can be used together.

---

We hope this explanation helps clarify the target_volume_limit_args parameter and its components.