LibVelo

Library "LibVelo"
This library provides a sophisticated framework for **Velocity
Profile (Flow Rate)** analysis. It measures the physical
speed of trading at specific price levels by relating volume
to the time spent at those levels.

## Core Concept: Market Velocity

Unlike Volume Profiles, which only answer "how much" traded,
Velocity Profiles answer "how fast" it traded.
It is calculated as:
`Velocity = Volume / Duration`

This metric (contracts per second) reveals hidden market
dynamics invisible to pure Volume or TPO profiles:

1. **High Velocity (Fast Flow):**
* **Aggression:** Initiative buyers/sellers hitting market
orders rapidly.
* **Liquidity Vacuum:** Price slips through a level because
order book depth is thin (low resistance).

2. **Low Velocity (Slow Flow):**
* **Absorption:** High volume but very slow price movement.
Indicates massive passive limit orders ("Icebergs").
* **Apathy:** Little volume over a long time. Lack of
interest from major participants.

## Architecture: Triple-Engine Composition

To ensure maximum performance while offering full statistical
depth for all metrics, this library utilises **object
composition** with a lazy evaluation strategy:

#### Engine A: The Master (`vpVol`)
* **Role:** Standard Volume Profile.
* **Purpose:** Maintains the "ground truth" of volume distribution,
price buckets, and ranges.

#### Engine B: The Time Container (`vpTime`)
* **Role:** specialized container for time duration (in ms).
* **Hack:** It repurposes standard volume arrays (specifically
`aBuy`) to accumulate time duration for each bucket.

#### Engine C: The Calculator (`vpVelo`)
* **Role:** Temporary scratchpad for derived metrics.
* **Purpose:** When complex statistics (like Value Area or Skewness)
are requested for **Velocity**, this engine is assembled
on-demand to leverage the full statistical power of `LibVPrf`
without rewriting complex algorithms.

---

**DISCLAIMER**

This library is provided "AS IS" and for informational and
educational purposes only. It does not constitute financial,
investment, or trading advice.

The author assumes no liability for any errors, inaccuracies,
or omissions in the code. Using this library to build
trading indicators or strategies is entirely at your own risk.

As a developer using this library, you are solely responsible
for the rigorous testing, validation, and performance of any
scripts you create based on these functions. The author shall
not be held liable for any financial losses incurred directly
or indirectly from the use of this library or any scripts
derived from it.

create(buckets, rangeUp, rangeLo, dynamic, valueArea, allot, estimator, cdfSteps, split, trendLen)
  Construct a new `Velo` controller, initializing its engines.
  Parameters:
    buckets (int): series int Number of price buckets ≥ 1.
    rangeUp (float): series float Upper price bound (absolute).
    rangeLo (float): series float Lower price bound (absolute).
    dynamic (bool): series bool Flag for dynamic adaption of profile ranges.
    valueArea (int): series int Percentage for Value Area (1..100).
    allot (series AllotMode): series AllotMode Allocation mode `Classic` or `PDF` (default `PDF`).
    estimator (series PriceEst enum from AustrianTradingMachine/LibBrSt/1): series PriceEst PDF model for distribution attribution (default `Uniform`).
    cdfSteps (int): series int Resolution for PDF integration (default 20).
    split (series SplitMode): series SplitMode Buy/Sell split for the master volume engine (default `Classic`).
    trendLen (int): series int Look‑back for trend factor in dynamic split (default 3).
  Returns: Velo Freshly initialised velocity profile.

method clone(self)
  Create a deep copy of the composite profile.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo Profile object to copy.
  Returns: Velo A completely independent clone.

method clear(self)
  Reset all engines and accumulators.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo Profile object to clear.
  Returns: Velo Cleared profile (chaining).

method merge(self, srcVolBuy, srcVolSell, srcTime, srcRangeUp, srcRangeLo, srcVolCvd, srcVolCvdHi, srcVolCvdLo)
  Merges external data (Volume and Time) into the current profile.
Automatically handles resizing and re-bucketing if ranges differ.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
    srcVolBuy (array<float>): array<float> Source Buy Volume bucket array.
    srcVolSell (array<float>): array<float> Source Sell Volume bucket array.
    srcTime (array<float>): array<float> Source Time bucket array (ms).
    srcRangeUp (float): series float Upper price bound of the source data.
    srcRangeLo (float): series float Lower price bound of the source data.
    srcVolCvd (float): series float Source Volume CVD final value.
    srcVolCvdHi (float): series float Source Volume CVD High watermark.
    srcVolCvdLo (float): series float Source Volume CVD Low watermark.
  Returns: Velo `self` (chaining).

method addBar(self, offset)
  Main data ingestion. Distributes Volume and Time to buckets.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
    offset (int): series int Offset of the bar to add (default 0).
  Returns: Velo `self` (chaining).

method setBuckets(self, buckets)
  Sets the number of buckets for the profile.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
    buckets (int): series int New number of buckets.
  Returns: Velo `self` (chaining).

method setRanges(self, rangeUp, rangeLo)
  Sets the price range for the profile.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
    rangeUp (float): series float New upper price bound.
    rangeLo (float): series float New lower price bound.
  Returns: Velo `self` (chaining).

method setValueArea(self, va)
  Set the percentage of volume/time for the Value Area.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
    va (int): series int New Value Area percentage (0..100).
  Returns: Velo `self` (chaining).

method getBuckets(self)
  Returns the current number of buckets in the profile.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
  Returns: series int The number of buckets.

method getRanges(self)
  Returns the current price range of the profile.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
  Returns: [rangeUp, rangeLo]
rangeUp series float The upper price bound of the profile.
rangeLo series float The lower price bound of the profile.

method getArrayBuyVol(self)
  Returns the internal raw data array for **Buy Volume** directly.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
  Returns: array<float> The internal array for buy volume.

method getArraySellVol(self)
  Returns the internal raw data array for **Sell Volume** directly.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
  Returns: array<float> The internal array for sell volume.

method getArrayTime(self)
  Returns the internal raw data array for **Time** (in ms) directly.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
  Returns: array<float> The internal array for time duration.

method getArrayBuyVelo(self)
  Returns the internal raw data array for **Buy Velocity** directly.
Automatically executes _assemble() if data is dirty.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
  Returns: array<float> The internal array for buy velocity.

method getArraySellVelo(self)
  Returns the internal raw data array for **Sell Velocity** directly.
Automatically executes _assemble() if data is dirty.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
  Returns: array<float> The internal array for sell velocity.

method getBucketBuyVol(self, idx)
  Returns the **Buy Volume** of a specific bucket.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
    idx (int): series int The index of the bucket.
  Returns: series float The buy volume.

method getBucketSellVol(self, idx)
  Returns the **Sell Volume** of a specific bucket.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
    idx (int): series int The index of the bucket.
  Returns: series float The sell volume.

method getBucketTime(self, idx)
  Returns the raw accumulated time (in ms) spent in a specific bucket.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
    idx (int): series int The index of the bucket.
  Returns: series float The time in milliseconds.

method getBucketBuyVelo(self, idx)
  Returns the **Buy Velocity** (Aggressive Buy Flow) of a bucket.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
    idx (int): series int The index of the bucket.
  Returns: series float The buy velocity in [Volume/Second].

method getBucketSellVelo(self, idx)
  Returns the **Sell Velocity** (Aggressive Sell Flow) of a bucket.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
    idx (int): series int The index of the bucket.
  Returns: series float The sell velocity in [Volume/Second].

method getBktBnds(self, idx)
  Returns the price boundaries of a specific bucket.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
    idx (int): series int The index of the bucket.
  Returns: [up, lo]
up series float The upper price bound of the bucket.
lo series float The lower price bound of the bucket.

method getPoc(self, target)
  Returns Point of Control (POC) information for the specified target metric.
Calculates on-demand if the target is 'Velocity' and data changed.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
    target (series Metric): Metric The data aspect to analyse (Volume, Time, Velocity).
  Returns: [pocIdx, pocPrice]
pocIdx series int The index of the POC bucket.
pocPrice series float The mid-price of the POC bucket.

method getVA(self, target)
  Returns Value Area (VA) information for the specified target metric.
Calculates on-demand if the target is 'Velocity' and data changed.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
    target (series Metric): Metric The data aspect to analyse (Volume, Time, Velocity).
  Returns: [vaUpIdx, vaUpPrice, vaLoIdx, vaLoPrice]
vaUpIdx series int The index of the upper VA bucket.
vaUpPrice series float The upper price bound of the VA.
vaLoIdx series int The index of the lower VA bucket.
vaLoPrice series float The lower price bound of the VA.

method getMedian(self, target)
  Returns the Median price for the specified target metric distribution.
Calculates on-demand if the target is 'Velocity' and data changed.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
    target (series Metric): Metric The data aspect to analyse (Volume, Time, Velocity).
  Returns: [medianIdx, medianPrice]
medianIdx series int The index of the bucket containing the median.
medianPrice series float The median price.

method getAverage(self, target)
  Returns the weighted average price (VWAP/TWAP) for the specified target.
Calculates on-demand if the target is 'Velocity' and data changed.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
    target (series Metric): Metric The data aspect to analyse (Volume, Time, Velocity).
  Returns: [avgIdx, avgPrice]
avgIdx series int The index of the bucket containing the average.
avgPrice series float The weighted average price.

method getStdDev(self, target)
  Returns the standard deviation for the specified target distribution.
Calculates on-demand if the target is 'Velocity' and data changed.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
    target (series Metric): Metric The data aspect to analyse (Volume, Time, Velocity).
  Returns: series float The standard deviation.

method getSkewness(self, target)
  Returns the skewness for the specified target distribution.
Calculates on-demand if the target is 'Velocity' and data changed.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
    target (series Metric): Metric The data aspect to analyse (Volume, Time, Velocity).
  Returns: series float The skewness.

method getKurtosis(self, target)
  Returns the excess kurtosis for the specified target distribution.
Calculates on-demand if the target is 'Velocity' and data changed.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
    target (series Metric): Metric The data aspect to analyse (Volume, Time, Velocity).
  Returns: series float The excess kurtosis.

method getSegments(self, target)
  Returns the fundamental unimodal segments for the specified target metric.
Calculates on-demand if the target is 'Velocity' and data changed.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
    target (series Metric): Metric The data aspect to analyse (Volume, Time, Velocity).
  Returns: matrix<int> A 2-column matrix where each row is an [startIndex, endIndex] pair.

method getCvd(self, target)
  Returns Cumulative Volume/Velo Delta (CVD) information for the target metric.
  Namespace types: Velo
  Parameters:
    self (Velo): Velo The profile object.
    target (series Metric): Metric The data aspect to analyse (Volume, Time, Velocity).
  Returns: [cvd, cvdHi, cvdLo]
cvd series float The final delta value.
cvdHi series float The historical high-water mark of the delta.
cvdLo series float The historical low-water mark of the delta.

Velo
  Velo Composite Velocity Profile Controller.
  Fields:
    _vpVol (VPrf type from AustrianTradingMachine/LibVPrf/2): LibVPrf.VPrf Engine A: Master Volume source.
    _vpTime (VPrf type from AustrianTradingMachine/LibVPrf/2): LibVPrf.VPrf Engine B: Time duration container (ms).
    _vpVelo (VPrf type from AustrianTradingMachine/LibVPrf/2): LibVPrf.VPrf Engine C: Scratchpad for velocity stats.
    _aTime (array<float>): array<float> Pointer alias to `vpTime.aBuy` (Time storage).
    _valueArea (series float): int Percentage of total volume to include in the Value Area (1..100)
    _estimator (series PriceEst enum from AustrianTradingMachine/LibBrSt/1): LibBrSt.PriceEst PDF model for distribution attribution.
    _allot (series AllotMode): AllotMode Attribution model (Classic or PDF).
    _cdfSteps (series int): int Integration resolution for PDF.
    _isDirty (series bool): bool Lazy evaluation flag for vpVelo.