#include <beta_calculator.hpp>

Public Member Functions
	BetaCalculator ()=delete

Static Public Member Functions
static std::optional< BetaVelocity >	fromPriceVelocity (double price_velocity, double max_velocity) noexcept

static std::optional< BetaVelocity >	fromReturn (double period_return, double max_return) noexcept

static std::optional< BetaVelocity >	fromRollingWindow (std::span< const double > prices, std::size_t window, double max_velocity, double time_delta) noexcept

static std::optional< std::vector< BetaVelocity > >	fromPriceVelocityOnline (std::span< const double > prices, double time_delta) noexcept

static std::optional< double >	meanAbsVelocity (std::span< const double > prices, double time_delta) noexcept

static bool	isNewtonian (BetaVelocity beta) noexcept

static bool	isRelativistic (BetaVelocity beta) noexcept

static bool	isValid (BetaVelocity beta) noexcept
	Return true if β is in the valid safe range (\|β\| < BETA_MAX_SAFE).

static BetaVelocity	clamp (double raw_beta) noexcept

static std::optional< double >	kineticEnergy (BetaVelocity beta, double effective_mass, double c_market=constants::SPEED_OF_INFORMATION) noexcept

static std::optional< double >	dopplerFactor (BetaVelocity beta) noexcept

Detailed Description

Maps financial market observables to the β velocity parameter.

All methods are static. BetaCalculator holds no state — it is a transformation namespace in class form.

Definition at line 50 of file beta_calculator.hpp.

Constructor & Destructor Documentation

◆ BetaCalculator()

srfm::lorentz::BetaCalculator::BetaCalculator ( )

delete

Member Function Documentation

◆ clamp()

BetaVelocity srfm::lorentz::BetaCalculator::clamp ( double raw_beta )

staticnoexcept

Clamp an arbitrary raw_beta to the safe range (−BETA_MAX_SAFE, BETA_MAX_SAFE).

Use this as a safety net when β is computed from noisy data that might occasionally exceed 1. Does not return nullopt — always produces a valid β.

Definition at line 217 of file beta_calculator.cpp.

◆ dopplerFactor()

std::optional< double > srfm::lorentz::BetaCalculator::dopplerFactor ( BetaVelocity beta )

staticnoexcept

Relativistic Doppler factor: D = √((1 + β) / (1 − β)).

Models the frequency shift of a signal emitted by a moving market. D > 1: observer sees higher frequency (market approaching — momentum). D < 1: observer sees lower frequency (market receding — mean-reversion).

Returns

Some(D) > 0
None if β is invalid or |β| ≥ 1 (D would be undefined)

Definition at line 258 of file beta_calculator.cpp.

◆ fromPriceVelocity()

std::optional< BetaVelocity > srfm::lorentz::BetaCalculator::fromPriceVelocity	(	double	price_velocity,
		double	max_velocity
	)

staticnoexcept

Compute β = |price_velocity| / max_velocity.

The primary factory: given a computed price velocity (dP/dt) and the maximum reference velocity, returns the normalised β.

Arguments

price_velocity — dP/dt (any finite double, sign preserved for direction)
max_velocity — Reference maximum velocity (must be > 0)

Returns

Some(β) clamped to [0, BETA_MAX_SAFE) if max_velocity > 0
None if max_velocity ≤ 0 or price_velocity is non-finite

Look-Ahead Warning

If max_velocity was computed over the full price series (e.g. the global maximum velocity), then bar 1's β is normalised by a quantity that includes information from bar N — a form of look-ahead bias. This is acceptable for offline research / backtesting where the full series is known. For streaming or walk-forward applications, use fromPriceVelocityOnline instead.

Definition at line 32 of file beta_calculator.cpp.

◆ fromPriceVelocityOnline()

std::optional< std::vector< BetaVelocity > > srfm::lorentz::BetaCalculator::fromPriceVelocityOnline	(	std::span< const double >	prices,
		double	time_delta
	)

staticnoexcept

Compute a β series online — no look-ahead bias.

For bar i, β_i is normalised by the maximum instantaneous velocity observed from bar 0 to bar i only. This means future bars have no influence on earlier β values — causal, streaming-safe.

Contrast with fromPriceVelocity which uses a caller-supplied max_velocity that may have been computed over the full series (look-ahead bias).

Algorithm

For each bar i:

Estimate velocity v_i via finite difference at point i using only prices[0..i].
running_max_i = max(running_max_{i-1}, v_i)
β_i = v_i / running_max_i (or 0 when running_max = 0)

Arguments

prices — Full price series (at least 2 elements)
time_delta — Constant time step between observations (must be > 0)

Returns

Some(vector<BetaVelocity>) of length prices.size() — one β per bar
None if prices.size() < 2, time_delta ≤ 0, or any price is non-finite

Properties

Monotonically non-decreasing running_max
β at bar i identical whether or not future bars exist in the series
Online and offline methods agree when max velocity occurs at bar 0

Definition at line 137 of file beta_calculator.cpp.

◆ fromReturn()

std::optional< BetaVelocity > srfm::lorentz::BetaCalculator::fromReturn	(	double	period_return,
		double	max_return
	)

staticnoexcept

Compute β from a single-period percent return and a maximum reference.

β = |return| / max_return

Suitable for daily/intraday return data. Negative returns become positive β (speed is always non-negative; direction is separate).

Returns

Some(β) ∈ [0, BETA_MAX_SAFE)
None if max_return ≤ 0 or return is non-finite

Definition at line 49 of file beta_calculator.cpp.

◆ fromRollingWindow()

std::optional< BetaVelocity > srfm::lorentz::BetaCalculator::fromRollingWindow	(	std::span< const double >	prices,
		std::size_t	window,
		double	max_velocity,
		double	time_delta
	)

staticnoexcept

Compute β from a contiguous price window using central differencing.

Estimates dP/dt over window prices with constant time_delta between samples, then normalises by max_velocity to get β.

Uses the mean absolute velocity over the window to smooth noise.

Arguments

prices — Price time series (must have at least 2 elements)
window — Number of most-recent prices to include (≤ prices.size())
max_velocity — Reference maximum velocity (must be > 0)
time_delta — Time between successive prices (must be > 0)

Returns

Some(β) normalised mean rolling velocity
None if inputs are invalid (empty, window < 2, non-finite data)

Definition at line 108 of file beta_calculator.cpp.

◆ isNewtonian()

bool srfm::lorentz::BetaCalculator::isNewtonian ( BetaVelocity beta )

staticnoexcept

Return true if β is in the Newtonian regime (|β| < BETA_NEWTONIAN_THRESHOLD).

In the Newtonian regime γ ≈ 1 + β²/2 — relativistic corrections are negligible (less than 0.5%). Classical indicators apply directly.

Definition at line 203 of file beta_calculator.cpp.

◆ isRelativistic()

bool srfm::lorentz::BetaCalculator::isRelativistic ( BetaVelocity beta )

staticnoexcept

Return true if β is in the relativistic regime (|β| ≥ BETA_NEWTONIAN_THRESHOLD).

Relativistic corrections are significant; γ departs from 1 by more than ~0.5%. Lorentz-corrected indicators must be used.

Definition at line 207 of file beta_calculator.cpp.

◆ isValid()

bool srfm::lorentz::BetaCalculator::isValid ( BetaVelocity beta )

staticnoexcept

Return true if β is in the valid safe range (|β| < BETA_MAX_SAFE).

Definition at line 211 of file beta_calculator.cpp.

◆ kineticEnergy()

std::optional< double > srfm::lorentz::BetaCalculator::kineticEnergy	(	BetaVelocity	beta,
		double	effective_mass,
		double	c_market = `constants::SPEED_OF_INFORMATION`
	)

staticnoexcept

Relativistic kinetic energy analog: E_k = (γ − 1) · m_eff · c²_market.

The "excess energy" above the rest-frame baseline, representing the additional energy a market agent would need to sustain a velocity β.

Arguments

beta — Market velocity
effective_mass — Liquidity proxy (must be > 0)
c_market — Speed of information (default = SPEED_OF_INFORMATION)

Returns

Some(E_k) ≥ 0
None if effective_mass ≤ 0 or β is invalid

Definition at line 236 of file beta_calculator.cpp.

◆ meanAbsVelocity()

std::optional< double > srfm::lorentz::BetaCalculator::meanAbsVelocity	(	std::span< const double >	prices,
		double	time_delta
	)

staticnoexcept

Estimate price velocity dP/dt using central finite differences.

For a series p₀…pₙ₋₁ with constant step time_delta: v_i = (p_{i+1} − p_{i-1}) / (2·time_delta) for interior points v_0 = (p_1 − p_0) / time_delta for the left boundary v_n = (pₙ − pₙ₋₁) / time_delta for the right boundary

Returns the mean absolute velocity over the series.

Returns

Some(v) ≥ 0
None if prices has < 2 elements or time_delta ≤ 0

Definition at line 66 of file beta_calculator.cpp.

The documentation for this class was generated from the following files:

src/lorentz/beta_calculator.hpp
src/lorentz/beta_calculator.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BetaCalculator()

Member Function Documentation

◆ clamp()

◆ dopplerFactor()

Returns

◆ fromPriceVelocity()

Arguments

Returns

Look-Ahead Warning

◆ fromPriceVelocityOnline()

Algorithm

Arguments

Returns

Properties

◆ fromReturn()

Returns

◆ fromRollingWindow()

Arguments

Returns

◆ isNewtonian()

◆ isRelativistic()

◆ isValid()

◆ kineticEnergy()

Arguments

Returns

◆ meanAbsVelocity()

Returns