srfm-core 0.1.0__py3-none-any.whl

srfm_core/__init__.py

@@ -0,0 +1,46 @@
+"""srfm-core: the SRFM bar transforms from srfm-lab.
+
+Beta (Minkowski TIMELIKE/SPACELIKE), black-hole mass, the rolling geodesic
+and the Hawking z proxy, as streaming classes and as numpy/pandas batch
+functions. The same math ships as the Rust crate ``srfm-core``; both are
+checked against one set of golden vectors generated from srfm-lab's
+``lib/srfm_core.py``.
+
+These are feature transforms. They are not a trading edge on their own.
+"""
+
+from .frames import add_srfm_columns, beta, bh_mass, geodesic, hawking_z, wilder_atr
+from .kernels import BH_DEFAULTS
+from .streaming import (
+    SPACELIKE,
+    TIMELIKE,
+    UNKNOWN,
+    BlackHoleDetector,
+    GeodesicAnalyzer,
+    GravitationalLens,
+    HawkingMonitor,
+    MinkowskiClassifier,
+    WilderATR,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "beta",
+    "bh_mass",
+    "geodesic",
+    "hawking_z",
+    "wilder_atr",
+    "add_srfm_columns",
+    "BH_DEFAULTS",
+    "MinkowskiClassifier",
+    "BlackHoleDetector",
+    "GeodesicAnalyzer",
+    "GravitationalLens",
+    "HawkingMonitor",
+    "WilderATR",
+    "TIMELIKE",
+    "SPACELIKE",
+    "UNKNOWN",
+    "__version__",
+]

srfm_core/frames.py

@@ -0,0 +1,111 @@
+"""pandas front end over :mod:`srfm_core.kernels`.
+
+Each function accepts a list, ndarray or pandas Series. A Series keeps its
+index; anything else gets a RangeIndex.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+
+from . import kernels as _k
+
+__all__ = ["beta", "bh_mass", "geodesic", "hawking_z", "wilder_atr", "add_srfm_columns"]
+
+
+def _index(x) -> Optional[pd.Index]:
+    return x.index if isinstance(x, (pd.Series, pd.DataFrame)) else None
+
+
+def beta(close, cf: float = 0.001) -> pd.Series:
+    """Per-bar beta (``|dC| / C_prev / cf``). ``< 1`` is TIMELIKE."""
+    return pd.Series(_k.beta(close, cf), index=_index(close), name="beta")
+
+
+def bh_mass(
+    close,
+    cf: float = 0.001,
+    bh_form: float = 1.5,
+    bh_collapse: float = 1.0,
+    timelike_decay: float = 0.95,
+    spacelike_decay: float = 0.7,
+    ctl_min: int = 5,
+    **advanced,
+) -> pd.DataFrame:
+    """Black-hole mass. Returns a DataFrame with columns
+    ``bh_mass, bh_active, bh_dir, ctl``.
+
+    ``advanced`` accepts ``gain``, ``boost_step``, ``boost_cap``,
+    ``reform_window`` and ``reform_frac`` (see docs/PARAMETERS.md).
+    """
+    unknown = set(advanced) - {"gain", "boost_step", "boost_cap", "reform_window", "reform_frac"}
+    if unknown:
+        raise TypeError(f"unexpected keyword arguments: {sorted(unknown)}")
+    out = _k.bh_mass(close, cf=cf, bh_form=bh_form, bh_collapse=bh_collapse,
+                     timelike_decay=timelike_decay, spacelike_decay=spacelike_decay,
+                     ctl_min=ctl_min, **advanced)
+    return pd.DataFrame(out, index=_index(close))
+
+
+def geodesic(close, atr, window: int = 20, cf: float = 0.001) -> pd.DataFrame:
+    """Rolling geodesic. Columns ``geo_dev, geo_slope, causal_frac``."""
+    a = atr.to_numpy(dtype=float) if isinstance(atr, pd.Series) else atr
+    return pd.DataFrame(_k.geodesic(close, a, window=window, cf=cf), index=_index(close))
+
+
+def hawking_z(close, period: int = 20) -> pd.DataFrame:
+    """Bollinger z and Hawking proxy. Columns ``hawking_z, hawking_t``."""
+    return pd.DataFrame(_k.hawking_z(close, period=period), index=_index(close))
+
+
+def wilder_atr(high, low, close, period: int = 14) -> pd.Series:
+    """Wilder ATR with srfm-lab's warm-up (NaN on the first bar)."""
+    def arr(x):
+        return x.to_numpy(dtype=float) if isinstance(x, pd.Series) else x
+    return pd.Series(_k.wilder_atr(arr(high), arr(low), arr(close), period),
+                     index=_index(close), name="atr")
+
+
+def add_srfm_columns(
+    df: pd.DataFrame,
+    cf: float = 0.001,
+    window: int = 20,
+    period: int = 20,
+    atr_period: int = 14,
+    prefix: str = "srfm_",
+    close_col: str = "close",
+    **bh_params,
+) -> pd.DataFrame:
+    """Add every SRFM column to ``df`` in place and return it.
+
+    Made for a freqtrade ``populate_indicators``::
+
+        from srfm_core import add_srfm_columns
+
+        def populate_indicators(self, dataframe, metadata):
+            return add_srfm_columns(dataframe, cf=0.001)
+
+    Adds ``beta, bh_mass, bh_active, bh_dir, ctl, geo_dev, geo_slope,
+    causal_frac, hawking_z, hawking_t, atr``, each named with ``prefix``
+    (default ``srfm_``, so ``srfm_bh_mass``; pass ``prefix=""`` for bare
+    names). ATR is Wilder ATR from ``high``/``low``/``close``; on a close-only
+    frame the true range falls back to ``|dC|``.
+    ``bh_params`` go to :func:`bh_mass`.
+    """
+    close = df[close_col].to_numpy(dtype=float)
+    if "high" in df.columns and "low" in df.columns:
+        atr = _k.wilder_atr(df["high"].to_numpy(dtype=float), df["low"].to_numpy(dtype=float),
+                            close, atr_period)
+    else:
+        atr = _k.wilder_atr(close, close, close, atr_period)
+    cols = {"beta": _k.beta(close, cf)}
+    cols.update(_k.bh_mass(close, cf=cf, **bh_params))
+    cols.update(_k.geodesic(close, atr, window=window, cf=cf))
+    cols.update(_k.hawking_z(close, period=period))
+    cols["atr"] = atr
+    for name, values in cols.items():
+        df[prefix + name] = values
+    return df

srfm_core/kernels.py

@@ -0,0 +1,256 @@
+"""NumPy-only batch kernels. No pandas import.
+
+Every function takes 1-D float arrays and returns ndarrays (or a dict of
+ndarrays). Shared conventions, identical in the Rust crate and checked by
+``golden/golden_vectors.json``:
+
+* Non-finite closes (NaN, inf) are gaps. A gap bar outputs NaN (``bh_active``
+  False, ``bh_dir`` 0, ``ctl`` 0), does not touch the state, and the next
+  finite bar is compared with the last finite close.
+* Finite closes must be > 0, otherwise ``ValueError``.
+* Warm-up outputs are NaN, never a fake 0.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Dict, Tuple
+
+import numpy as np
+
+__all__ = ["beta", "bh_mass", "geodesic", "hawking_z", "wilder_atr", "BH_DEFAULTS"]
+
+_EPS = 1e-9
+
+#: LARSA's BH constants, now parameters. See docs/PARAMETERS.md.
+BH_DEFAULTS = dict(
+    cf=0.001,
+    bh_form=1.5,
+    bh_collapse=1.0,
+    timelike_decay=0.95,
+    spacelike_decay=0.7,
+    ctl_min=5,
+    gain=100.0,
+    boost_step=0.1,
+    boost_cap=2.0,
+    reform_window=15,
+    reform_frac=0.5,
+)
+
+
+def _as_close(close) -> Tuple[np.ndarray, np.ndarray]:
+    c = np.asarray(close, dtype=float)
+    if c.ndim != 1:
+        raise ValueError("close must be 1-D")
+    finite = np.isfinite(c)
+    if np.any(c[finite] <= 0):
+        raise ValueError("close prices must be > 0 (non-finite values are treated as gaps)")
+    return c, finite
+
+
+def _check_cf(cf: float) -> None:
+    if not (cf > 0 and math.isfinite(cf)):
+        raise ValueError("cf must be a finite number > 0")
+
+
+def beta(close, cf: float = 0.001) -> np.ndarray:
+    """``|C_t - C_{t-1}| / C_{t-1} / cf`` per bar. NaN on the first finite bar and on gaps.
+
+    ``beta < 1`` is a TIMELIKE bar, ``beta >= 1`` SPACELIKE.
+    """
+    _check_cf(cf)
+    c, finite = _as_close(close)
+    out = np.full(c.shape, np.nan)
+    idx = np.flatnonzero(finite)
+    if idx.size >= 2:
+        v = c[idx]
+        out[idx[1:]] = np.abs(v[1:] - v[:-1]) / (v[:-1] + _EPS) / cf
+    return out
+
+
+def bh_mass(
+    close,
+    cf: float = 0.001,
+    bh_form: float = 1.5,
+    bh_collapse: float = 1.0,
+    timelike_decay: float = 0.95,
+    spacelike_decay: float = 0.7,
+    ctl_min: int = 5,
+    gain: float = 100.0,
+    boost_step: float = 0.1,
+    boost_cap: float = 2.0,
+    reform_window: int = 15,
+    reform_frac: float = 0.5,
+) -> Dict[str, np.ndarray]:
+    """Black-hole mass per bar.
+
+    Returns a dict with ``bh_mass`` (float), ``bh_active`` (bool), ``bh_dir``
+    (int8, +1/-1/0) and ``ctl`` (int64, consecutive TIMELIKE bars). See
+    :class:`srfm_core.BlackHoleDetector` for the recurrence.
+    """
+    _check_cf(cf)
+    c, finite = _as_close(close)
+    n = c.shape[0]
+    mass_out = np.full(n, np.nan)
+    active_out = np.zeros(n, dtype=bool)
+    dir_out = np.zeros(n, dtype=np.int8)
+    ctl_out = np.zeros(n, dtype=np.int64)
+
+    mass = 0.0
+    active = False
+    bdir = 0
+    ctl = 0
+    cum = 0.0
+    prev_mass = 0.0
+    reform = 0
+    prev = None
+    for i in np.flatnonzero(finite).tolist():
+        x = float(c[i])
+        if prev is not None:
+            diff = x - prev
+            timelike = abs(diff) / (prev + _EPS) / cf < 1.0
+            br = diff / (prev + _EPS)
+            if timelike:
+                ctl += 1
+                cum += br
+                sb = min(boost_cap, 1.0 + ctl * boost_step)
+                mass = mass * timelike_decay + abs(br) * gain * sb
+            else:
+                ctl = 0
+                mass *= spacelike_decay
+            if cum > 0:
+                bdir = 1
+            elif cum < 0:
+                bdir = -1
+            was = active
+            if not was:
+                if 0 < reform < reform_window:
+                    mass += prev_mass * reform_frac
+                    prev_mass = 0.0
+                active = mass > bh_form and ctl >= ctl_min
+            else:
+                active = mass > bh_collapse and ctl >= ctl_min
+            if active and not was:
+                reform = 0
+            elif was and not active:
+                prev_mass = mass
+                reform = 1
+            if not active:
+                if reform > 0:
+                    reform += 1
+                if ctl == 0:
+                    cum = 0.0
+        mass_out[i] = mass
+        active_out[i] = active
+        dir_out[i] = bdir
+        ctl_out[i] = ctl
+        prev = x
+    return {"bh_mass": mass_out, "bh_active": active_out, "bh_dir": dir_out, "ctl": ctl_out}
+
+
+def geodesic(close, atr, window: int = 20, cf: float = 0.001) -> Dict[str, np.ndarray]:
+    """Rolling log-linear "geodesic" over ``window`` finite closes.
+
+    Returns ``geo_dev`` = tanh((C - fitted C) / atr), ``geo_slope`` =
+    100 * slope of log price per bar, and ``causal_frac`` = share of lags
+    1..window-1 with a TIMELIKE interval. NaN until ``window`` finite closes.
+    ``atr`` is aligned with ``close``; NaN ATR gives NaN ``geo_dev`` only.
+    """
+    if window < 2:
+        raise ValueError("window must be >= 2")
+    _check_cf(cf)
+    c, finite = _as_close(close)
+    a = np.asarray(atr, dtype=float)
+    if a.shape != c.shape:
+        raise ValueError("atr must have the same length as close")
+    n = c.shape[0]
+    dev = np.full(n, np.nan)
+    slope_out = np.full(n, np.nan)
+    causal = np.full(n, np.nan)
+    idx = np.flatnonzero(finite)
+    m = idx.size
+    if m >= window:
+        v = c[idx]
+        w = np.lib.stride_tricks.sliding_window_view(v, window)  # oldest -> newest
+        lp = np.log(w + _EPS)
+        x = np.arange(window, dtype=float)
+        nn = float(window)
+        sx = x.sum()
+        sxx = float(np.dot(x, x))
+        slp = lp.sum(axis=1)
+        sxlp = lp @ x
+        slope = (nn * sxlp - sx * slp) / (nn * sxx - sx * sx + _EPS)
+        intercept = (slp - slope * sx) / nn
+        geo_p = np.exp(slope * (window - 1) + intercept)
+        last = w[:, -1]
+        tgt = idx[window - 1:]
+        dev[tgt] = np.tanh((last - geo_p) / (a[tgt] + _EPS))
+        slope_out[tgt] = slope * 100
+        k = np.arange(1, window, dtype=float)
+        past = w[:, :-1][:, ::-1]  # column j = lag j+1
+        dp = np.abs(last[:, None] - past) / (past + _EPS)
+        ds2 = -(cf * k) ** 2 + dp * dp
+        causal[tgt] = (ds2 < 0).sum(axis=1) / (window - 1)
+    return {"geo_dev": dev, "geo_slope": slope_out, "causal_frac": causal}
+
+
+def hawking_z(close, period: int = 20) -> Dict[str, np.ndarray]:
+    """Bollinger z-score and the LARSA Hawking-temperature proxy.
+
+    ``hawking_z = (C - mean) / std`` over the last ``period`` finite closes
+    (population std, current bar included) and
+    ``hawking_t = z * (z - z_prev)``, where ``z_prev`` is the previous defined
+    z (0 before the first). NaN in warm-up and where std == 0.
+    """
+    if period < 2:
+        raise ValueError("period must be >= 2")
+    c, finite = _as_close(close)
+    n = c.shape[0]
+    z_out = np.full(n, np.nan)
+    t_out = np.full(n, np.nan)
+    idx = np.flatnonzero(finite)
+    if idx.size >= period:
+        v = c[idx]
+        w = np.lib.stride_tricks.sliding_window_view(v, period)
+        mid = w.sum(axis=1) / period
+        std = w.std(axis=1)
+        last = w[:, -1]
+        tgt = idx[period - 1:]
+        ok = std > 0
+        z = np.full(last.shape, np.nan)
+        z[ok] = (last[ok] - mid[ok]) / std[ok]
+        zv = z[ok]
+        pz = np.concatenate(([0.0], zv[:-1]))
+        t = np.full(last.shape, np.nan)
+        t[ok] = zv * (zv - pz)
+        z_out[tgt] = z
+        t_out[tgt] = t
+    return {"hawking_z": z_out, "hawking_t": t_out}
+
+
+def wilder_atr(high, low, close, period: int = 14) -> np.ndarray:
+    """Wilder ATR (mean of true ranges for the first ``period`` bars, then
+    Wilder smoothing). NaN on the first finite close and on gaps."""
+    if period < 1:
+        raise ValueError("period must be >= 1")
+    c, finite = _as_close(close)
+    h = np.asarray(high, dtype=float)
+    lo = np.asarray(low, dtype=float)
+    if h.shape != c.shape or lo.shape != c.shape:
+        raise ValueError("high, low and close must have the same length")
+    out = np.full(c.shape, np.nan)
+    prev = None
+    val = 0.0
+    k = 0
+    for i in np.flatnonzero(finite).tolist():
+        x = float(c[i])
+        if prev is not None:
+            tr = max(float(h[i]) - float(lo[i]), abs(float(h[i]) - prev), abs(float(lo[i]) - prev))
+            if k < period:
+                val = (val * k + tr) / (k + 1)
+            else:
+                val = (val * (period - 1) + tr) / period
+            k += 1
+            out[i] = val
+        prev = x
+    return out

srfm_core/streaming.py

@@ -0,0 +1,376 @@
+"""Streaming (bar-by-bar) SRFM classes.
+
+These are the classes from srfm-lab ``lib/srfm_core.py`` (commit 8cbfcb0) with
+two changes and no change to the math at default settings:
+
+* every LARSA constant is now a documented constructor parameter whose
+  default is the value LARSA shipped with;
+* lab-only batch wrappers (``detect``, ``analyze``, ``compute_mu``,
+  ``compute_temperature``, ``classify``) are gone; use the functions in
+  :mod:`srfm_core` instead, which do not have the one-bar lag of ``detect``.
+
+The golden vectors in ``golden/golden_vectors.json`` are produced from the
+untouched srfm-lab file and these classes are tested against them.
+"""
+
+from __future__ import annotations
+
+import math
+from collections import deque
+from typing import Deque, List, Optional, Tuple
+
+import numpy as np
+
+__all__ = [
+    "MinkowskiClassifier",
+    "BlackHoleDetector",
+    "GeodesicAnalyzer",
+    "GravitationalLens",
+    "HawkingMonitor",
+    "WilderATR",
+    "TIMELIKE",
+    "SPACELIKE",
+    "UNKNOWN",
+]
+
+TIMELIKE = "TIMELIKE"
+SPACELIKE = "SPACELIKE"
+UNKNOWN = "UNKNOWN"
+
+_EPS = 1e-9  # denominator guard used throughout LARSA; kept for bit-exactness
+
+
+class MinkowskiClassifier:
+    """Classify each bar as TIMELIKE or SPACELIKE.
+
+    ``beta = |close_t - close_{t-1}| / close_{t-1} / cf``.
+    ``beta < 1`` is TIMELIKE (an ordered move smaller than the "speed of
+    light" ``cf``), ``beta >= 1`` is SPACELIKE.
+
+    Also tracks ``tl_confirm`` (consecutive TIMELIKE bars, capped at
+    ``tl_cap``) and ``proper_time`` (sum of 1/gamma with
+    ``v = min(0.99, |dC/C| / max_vol)``).
+
+    Parameters
+    ----------
+    cf : float, default 0.001
+        Speed-of-light constant as a fraction of price per bar. A bar whose
+        absolute return is below ``cf`` is TIMELIKE. Tune per instrument and
+        bar size; LARSA used 0.001 on hourly index futures.
+    max_vol : float, default 0.01
+        Return at which proper-time velocity saturates (v capped at 0.99).
+    tl_cap : int, default 3
+        Cap on the ``tl_confirm`` counter.
+    """
+
+    def __init__(self, cf: float = 0.001, max_vol: float = 0.01, tl_cap: int = 3):
+        if cf <= 0:
+            raise ValueError("cf must be > 0")
+        self.cf = cf
+        self.max_vol = max_vol
+        self.tl_cap = tl_cap
+        self.beta: float = 0.0
+        self.bit: str = UNKNOWN
+        self.tl_confirm: int = 0
+        self.proper_time: float = 0.0
+        self._prev_close: Optional[float] = None
+
+    def update(self, close: float) -> str:
+        """Feed one close. Returns ``"TIMELIKE"``, ``"SPACELIKE"`` or ``"UNKNOWN"`` (first bar)."""
+        if self._prev_close is None or self._prev_close <= 0:
+            self._prev_close = close
+            return self.bit
+        price_diff = abs(close - self._prev_close)
+        self.beta = price_diff / (self._prev_close + _EPS) / self.cf
+        self.bit = TIMELIKE if self.beta < 1.0 else SPACELIKE
+        if self.bit == TIMELIKE:
+            self.tl_confirm = min(self.tl_confirm + 1, self.tl_cap)
+        else:
+            self.tl_confirm = 0
+        hv = price_diff / (self._prev_close + _EPS)
+        v = min(0.99, hv / self.max_vol)
+        gamma = 1.0 / math.sqrt(max(1e-9, 1.0 - v * v))
+        self.proper_time += 1.0 / gamma
+        self._prev_close = close
+        return self.bit
+
+    def reset_proper_time(self) -> None:
+        self.proper_time = 0.0
+
+    def reset(self) -> None:
+        self.__init__(self.cf, self.max_vol, self.tl_cap)
+
+    @property
+    def is_timelike(self) -> bool:
+        return self.bit == TIMELIKE
+
+
+class BlackHoleDetector:
+    """Black-hole (BH) mass: a decaying accumulator of ordered momentum.
+
+    Per bar, with ``br = (close - prev_close) / prev_close``:
+
+    * TIMELIKE: ``ctl += 1``; ``sb = min(boost_cap, 1 + ctl * boost_step)``;
+      ``mass = mass * timelike_decay + |br| * gain * sb``
+    * otherwise: ``ctl = 0``; ``mass *= spacelike_decay``
+
+    A well *forms* when ``mass > bh_form`` and ``ctl >= ctl_min``; it stays
+    active while ``mass > bh_collapse`` and ``ctl >= ctl_min``. ``bh_dir`` is
+    the sign of the return accumulated over the current TIMELIKE run.
+    Within ``reform_window`` bars of a collapse, the next formation attempt
+    adds ``reform_frac`` of the mass at collapse (once).
+
+    All defaults are the values LARSA shipped with.
+    """
+
+    def __init__(
+        self,
+        bh_form: float = 1.5,
+        bh_collapse: float = 1.0,
+        bh_decay: float = 0.95,
+        *,
+        spacelike_decay: float = 0.7,
+        ctl_min: int = 5,
+        gain: float = 100.0,
+        boost_step: float = 0.1,
+        boost_cap: float = 2.0,
+        reform_window: int = 15,
+        reform_frac: float = 0.5,
+    ):
+        self.bh_form = bh_form
+        self.bh_collapse = bh_collapse
+        self.bh_decay = bh_decay  # TIMELIKE decay; name kept from srfm-lab
+        self.spacelike_decay = spacelike_decay
+        self.ctl_min = ctl_min
+        self.gain = gain
+        self.boost_step = boost_step
+        self.boost_cap = boost_cap
+        self.reform_window = reform_window
+        self.reform_frac = reform_frac
+        self.reset()
+        self.well_events: List[dict] = []
+
+    @property
+    def timelike_decay(self) -> float:
+        return self.bh_decay
+
+    def update(self, bit: str, close: float, prev_close: float) -> bool:
+        """Feed one bar (its classification and the two closes). Returns ``bh_active``."""
+        br = (close - prev_close) / (prev_close + _EPS)
+        if bit == TIMELIKE:
+            self.ctl += 1
+            self.cum_disp += br
+            sb = min(self.boost_cap, 1.0 + self.ctl * self.boost_step)
+            self.bh_mass = self.bh_mass * self.bh_decay + abs(br) * self.gain * sb
+        else:
+            self.ctl = 0
+            self.bh_mass *= self.spacelike_decay
+
+        if self.cum_disp > 0:
+            self.bh_dir = 1
+        elif self.cum_disp < 0:
+            self.bh_dir = -1
+
+        prev_active = self.bh_active
+        if not prev_active:
+            if 0 < self.reform_bars < self.reform_window:
+                self.bh_mass += self.prev_bh_mass * self.reform_frac
+                self.prev_bh_mass = 0.0
+            self.bh_active = self.bh_mass > self.bh_form and self.ctl >= self.ctl_min
+        else:
+            self.bh_active = self.bh_mass > self.bh_collapse and self.ctl >= self.ctl_min
+
+        if self.bh_active and not prev_active:
+            self.reform_bars = 0
+            self.well_events.append(
+                {"event": "formed", "mass": self.bh_mass, "dir": self.bh_dir, "ctl": self.ctl})
+        elif not self.bh_active and prev_active:
+            self.prev_bh_mass = self.bh_mass
+            self.reform_bars = 1
+            self.well_events.append({"event": "collapsed", "mass": self.bh_mass})
+
+        if not self.bh_active:
+            if self.reform_bars > 0:
+                self.reform_bars += 1
+            if self.ctl == 0:
+                self.cum_disp = 0.0
+        return self.bh_active
+
+    def reset(self) -> None:
+        self.bh_mass = 0.0
+        self.bh_active = False
+        self.bh_dir = 0
+        self.ctl = 0
+        self.cum_disp = 0.0
+        self.prev_bh_mass = 0.0
+        self.reform_bars = 0
+        self.well_events = []
+
+
+class GeodesicAnalyzer:
+    """Rolling log-linear regression ("geodesic") and Minkowski causal fraction.
+
+    Over the last ``window`` closes:
+
+    * ``geo_slope = 100 * slope`` of ``log(close)`` on bar index;
+    * ``geo_dev = tanh((close - fitted_close) / atr)``;
+    * ``causal_frac`` = share of lags ``k = 1..window-1`` whose interval
+      ``ds2 = -(cf*k)^2 + (|C_t - C_{t-k}| / C_{t-k})^2`` is negative.
+
+    ``update`` returns ``(geo_dev, geo_slope, causal_frac, rapidity)`` and
+    ``(0, 0, 1, 0)`` during warm-up, exactly as in srfm-lab. ``rapidity`` is
+    the LARSA production formula, which is identically 0 (its denominator
+    guard never passes); it is kept only for drop-in compatibility.
+    """
+
+    def __init__(self, cf: float = 0.001, window: int = 20):
+        if window < 2:
+            raise ValueError("window must be >= 2")
+        self.cf = cf
+        self.window = window
+        self._closes: Deque[float] = deque(maxlen=window)
+
+    def update(self, close: float, atr: float) -> Tuple[float, float, float, float]:
+        self._closes.appendleft(close)
+        if len(self._closes) < self.window:
+            return 0.0, 0.0, 1.0, 0.0
+        prices = list(reversed(list(self._closes)))
+        lp = np.log(np.array(prices) + _EPS)
+        x = np.arange(self.window, dtype=float)
+        n = float(self.window)
+        sx = x.sum()
+        slp = lp.sum()
+        sxx = np.dot(x, x)
+        sxlp = np.dot(x, lp)
+        slope = (n * sxlp - sx * slp) / (n * sxx - sx * sx + _EPS)
+        intercept = (slp - slope * sx) / n
+        geo_p = float(np.exp(slope * (self.window - 1) + intercept))
+        geo_dev = float(np.tanh((close - geo_p) / (atr + _EPS)))
+        geo_slope = float(slope * 100)
+
+        closes_list = list(self._closes)
+        cc = 0
+        for k in range(1, self.window):
+            pp = closes_list[k]
+            dp = abs(close - pp) / (pp + _EPS)
+            if -(self.cf * k) ** 2 + dp * dp < 0:
+                cc += 1
+        causal_frac = cc / (self.window - 1)
+
+        e = (close - closes_list[self.window - 1]) / (closes_list[self.window - 1] + _EPS)
+        denom = e - e + _EPS
+        num = e + e
+        if abs(denom) > _EPS and num / denom > 0:
+            rapidity = float(np.tanh(0.5 * np.log(num / denom + _EPS)))
+        else:
+            rapidity = 0.0
+        return geo_dev, geo_slope, causal_frac, rapidity
+
+    @property
+    def ready(self) -> bool:
+        return len(self._closes) >= self.window
+
+    def reset(self) -> None:
+        self._closes.clear()
+
+
+class GravitationalLens:
+    """Lensing amplification ``mu`` from the distance to the TIMELIKE-bar VWAP.
+
+    ``M = ctl + (1 if TIMELIKE)``, ``R_E = sqrt(M)``,
+    ``r = |close - VWAP_TL| / atr``, ``mu = 1 + R_E / (r + R_E)``;
+    ``mu = max(0.3, M / 3)`` when ``M < 2``.
+    """
+
+    def __init__(self):
+        self._closes_tl: List[float] = []
+        self._vols_tl: List[float] = []
+        self.mu: float = 1.0
+
+    def update(self, close: float, volume: float, bit: str, ctl: int, atr: float) -> float:
+        if bit == TIMELIKE:
+            self._closes_tl.append(close)
+            self._vols_tl.append(volume)
+        else:
+            self._closes_tl = []
+            self._vols_tl = []
+        m = float(ctl + (1 if bit == TIMELIKE else 0))
+        r_e = math.sqrt(m + _EPS)
+        if m < 2.0:
+            self.mu = max(0.3, m / 3.0)
+        elif self._closes_tl:
+            sv = sum(self._vols_tl)
+            if sv > 0:
+                vwap = sum(p * v for p, v in zip(self._closes_tl, self._vols_tl)) / sv
+            else:
+                vwap = sum(self._closes_tl) / len(self._closes_tl)
+            r = abs(close - vwap) / (atr + _EPS)
+            self.mu = float(1.0 + r_e / (r + r_e))
+        else:
+            self.mu = 1.0
+        return self.mu
+
+
+class HawkingMonitor:
+    """Hawking-temperature proxy: ``ht = z * (z - z_prev)`` on a Bollinger z-score.
+
+    ``z = (close - bb_middle) / std``. LARSA treated ``ht > hot`` (1.8) as a
+    hot well (avoid long entry) and ``ht < inverted`` (-1.5) as a boost.
+    """
+
+    def __init__(self, hot: float = 1.8, inverted: float = -1.5):
+        self.hot = hot
+        self.inverted = inverted
+        self.ht: float = 0.0
+        self.z: float = 0.0
+        self._pz: float = 0.0
+
+    def update(self, close: float, bb_middle: float, std: float) -> float:
+        if std <= 0:
+            return self.ht
+        z = (close - bb_middle) / std
+        self.ht = z * (z - self._pz)
+        self._pz = z
+        self.z = z
+        return self.ht
+
+    @property
+    def is_hot(self) -> bool:
+        return self.ht > self.hot
+
+    @property
+    def is_inverted(self) -> bool:
+        return self.ht < self.inverted
+
+    def reset(self) -> None:
+        self.ht = 0.0
+        self.z = 0.0
+        self._pz = 0.0
+
+
+class WilderATR:
+    """Wilder ATR as used by srfm-lab: simple mean of true ranges for the first
+    ``period`` bars, Wilder smoothing after. The first bar has no true range
+    and returns ``nan`` (srfm-lab returned 0.0)."""
+
+    def __init__(self, period: int = 14):
+        self.period = period
+        self.reset()
+
+    def update(self, high: float, low: float, close: float) -> float:
+        if self._prev_c is None:
+            self._prev_c = close
+            return float("nan")
+        tr = max(high - low, abs(high - self._prev_c), abs(low - self._prev_c))
+        if self._n < self.period:
+            self.val = (self.val * self._n + tr) / (self._n + 1)
+        else:
+            self.val = (self.val * (self.period - 1) + tr) / self.period
+        self._n += 1
+        self._prev_c = close
+        return self.val
+
+    def reset(self) -> None:
+        self._prev_c: Optional[float] = None
+        self.val = 0.0
+        self._n = 0

srfm_core/vbt.py

@@ -0,0 +1,95 @@
+"""vectorbt indicators (optional extra: ``pip install "srfm-core[vbt]"``).
+
+vectorbt is imported the first time an indicator is used, not when
+``srfm_core`` is imported::
+
+    import vectorbt as vbt
+    from srfm_core.vbt import BHMass
+
+    close = vbt.YFData.download("BTC-USD").get("Close")
+    bh = BHMass.run(close, cf=[0.001, 0.002])      # parameter grid works
+    entries = bh.active & ~bh.active.shift(1, fill_value=False)
+    pf = vbt.Portfolio.from_signals(close, entries, ~bh.active)
+
+Indicators: ``BHMass`` (outputs mass, active, dir, ctl), ``SRFMBeta``
+(beta) and ``HawkingZ`` (z, t). Each column of a 2-D input is run
+independently; NaN padding between columns is treated as gaps.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from . import kernels as _k
+
+__all__ = ["BHMass", "SRFMBeta", "HawkingZ"]
+
+_cache: dict = {}
+
+
+def _per_column(fn, close2d, keys, dtypes):
+    close2d = np.asarray(close2d, dtype=float)
+    if close2d.ndim == 1:
+        close2d = close2d[:, None]
+    outs = [np.empty(close2d.shape, dtype=d) for d in dtypes]
+    for j in range(close2d.shape[1]):
+        res = fn(close2d[:, j])
+        for o, k in zip(outs, keys):
+            o[:, j] = res[k]
+    return tuple(outs) if len(outs) > 1 else outs[0]
+
+
+def _bh_apply(close, cf, bh_form, bh_collapse, timelike_decay, spacelike_decay, ctl_min):
+    return _per_column(
+        lambda c: _k.bh_mass(c, cf=cf, bh_form=bh_form, bh_collapse=bh_collapse,
+                             timelike_decay=timelike_decay, spacelike_decay=spacelike_decay,
+                             ctl_min=int(ctl_min)),
+        close, ("bh_mass", "bh_active", "bh_dir", "ctl"),
+        (float, bool, np.int8, np.int64))
+
+
+def _beta_apply(close, cf):
+    return _per_column(lambda c: {"beta": _k.beta(c, cf)}, close, ("beta",), (float,))
+
+
+def _hz_apply(close, period):
+    return _per_column(lambda c: _k.hawking_z(c, int(period)), close,
+                       ("hawking_z", "hawking_t"), (float, float))
+
+
+def _build(name: str):
+    try:
+        import vectorbt as vbt
+    except ImportError as exc:  # pragma: no cover - exercised only without vectorbt
+        raise ImportError(
+            "srfm_core.vbt needs vectorbt: pip install \"srfm-core[vbt]\"") from exc
+    if name == "BHMass":
+        d = _k.BH_DEFAULTS
+        return vbt.IndicatorFactory(
+            class_name="BHMass", short_name="bh", input_names=["close"],
+            param_names=["cf", "bh_form", "bh_collapse", "timelike_decay",
+                         "spacelike_decay", "ctl_min"],
+            output_names=["mass", "active", "dir", "ctl"],
+        ).from_apply_func(
+            _bh_apply, cf=d["cf"], bh_form=d["bh_form"], bh_collapse=d["bh_collapse"],
+            timelike_decay=d["timelike_decay"], spacelike_decay=d["spacelike_decay"],
+            ctl_min=d["ctl_min"])
+    if name == "SRFMBeta":
+        return vbt.IndicatorFactory(
+            class_name="SRFMBeta", short_name="srfm_beta", input_names=["close"],
+            param_names=["cf"], output_names=["beta"],
+        ).from_apply_func(_beta_apply, cf=0.001)
+    if name == "HawkingZ":
+        return vbt.IndicatorFactory(
+            class_name="HawkingZ", short_name="hawking", input_names=["close"],
+            param_names=["period"], output_names=["z", "t"],
+        ).from_apply_func(_hz_apply, period=20)
+    raise AttributeError(name)
+
+
+def __getattr__(name: str):
+    if name in __all__:
+        if name not in _cache:
+            _cache[name] = _build(name)
+        return _cache[name]
+    raise AttributeError(f"module 'srfm_core.vbt' has no attribute {name!r}")

srfm_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: srfm-core
+Version: 0.1.0
+Summary: SRFM bar transforms (Minkowski beta, black-hole mass, geodesic, Hawking z) as numpy/pandas functions, streaming classes, a vectorbt indicator and a freqtrade helper. Carved out of srfm-lab, with golden vectors shared with the Rust crate.
+Project-URL: Homepage, https://github.com/Mattbusel/srfm-core
+Project-URL: Source, https://github.com/Mattbusel/srfm-core
+Project-URL: Documentation, https://github.com/Mattbusel/srfm-core/tree/main/docs
+Project-URL: Changelog, https://github.com/Mattbusel/srfm-core/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Mattbusel/srfm-core/issues
+Project-URL: Upstream (srfm-lab), https://github.com/Mattbusel/srfm-lab
+Author: Matthew Busel
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: finance,freqtrade,indicators,quant,srfm,technical-analysis,trading,vectorbt
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.22
+Requires-Dist: pandas>=1.4
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Provides-Extra: vbt
+Requires-Dist: vectorbt>=0.25; extra == 'vbt'
+Description-Content-Type: text/markdown
+
+# srfm-core
+
+The SRFM bar transforms from [srfm-lab](https://github.com/Mattbusel/srfm-lab), as a small package you can drop into a pandas, vectorbt or freqtrade workflow. NumPy and pandas only.
+
+| Function | What it gives you per bar |
+|---|---|
+| `beta(close, cf=0.001)` | `abs(dC) / C_prev / cf`. Below 1 is a TIMELIKE (ordered) bar, 1 or more is SPACELIKE. |
+| `bh_mass(close, cf, bh_form=1.5, bh_collapse=1.0, timelike_decay=0.95, spacelike_decay=0.7, ctl_min=5)` | DataFrame `bh_mass, bh_active, bh_dir, ctl`: a decaying accumulator of ordered momentum and whether a "well" is active. |
+| `geodesic(close, atr, window=20)` | DataFrame `geo_dev, geo_slope, causal_frac`: rolling log-linear fit and the share of lags with a TIMELIKE interval. |
+| `hawking_z(close, period=20)` | DataFrame `hawking_z, hawking_t`: Bollinger z and LARSA's `z * (z - z_prev)` proxy. |
+| `add_srfm_columns(df)` | All of the above added to an OHLCV frame as `srfm_*` columns (made for freqtrade `populate_indicators`). |
+
+```python
+import srfm_core as sc
+
+df = sc.add_srfm_columns(ohlcv)            # srfm_bh_mass, srfm_bh_active, ...
+bh = sc.bh_mass(ohlcv["close"], cf=0.002)  # tune cf to your bar size
+```
+
+vectorbt (optional, `pip install "srfm-core[vbt]"`):
+
+```python
+from srfm_core.vbt import BHMass
+bh = BHMass.run(close, cf=[0.001, 0.002])  # parameter grids work
+```
+
+Streaming classes (`MinkowskiClassifier`, `BlackHoleDetector`, `GeodesicAnalyzer`, `GravitationalLens`, `HawkingMonitor`) keep the `update()` bar-by-bar API from srfm-lab.
+
+Every LARSA constant is a documented parameter with LARSA's value as the default. The batch functions are checked against `golden/golden_vectors.json`, generated from srfm-lab's untouched `lib/srfm_core.py`; the Rust crate [`srfm-core`](https://crates.io/crates/srfm-core) is checked against the same file.
+
+These are feature transforms, not a strategy. Nothing here claims a trading edge.
+
+Docs: https://github.com/Mattbusel/srfm-core/tree/main/docs. License: MIT.

srfm_core-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+srfm_core/__init__.py,sha256=E5uaQ5krMNjxnSsdaY9pAk4G-zC4IizD6Yyg-7-rdYE,1123
+srfm_core/frames.py,sha256=ZvQIBQDFCraVXwzM7o0btYZ04xnuqNcRJoM4ekwO2Y4,4054
+srfm_core/kernels.py,sha256=Zz8FJ_ZAWCouHJdXAvcKL1ul5wWu1cEx4Z9xERUd4Ek,8465
+srfm_core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+srfm_core/streaming.py,sha256=I19J2k5Cr7Y1DqKlT5ehwU_q8nadk0BM2hV9kf2PmV0,12979
+srfm_core/vbt.py,sha256=y0nxHR7Q5yF2FrBE5Di-WVLV5AJspA1rbgkr9GDORMs,3595
+srfm_core-0.1.0.dist-info/METADATA,sha256=x38LHiLAESQ8mYB46WDQQ494d1iiw-x01Rr7gKMYOqo,3911
+srfm_core-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+srfm_core-0.1.0.dist-info/licenses/LICENSE,sha256=TpCqwl9Iq4EFUnYGbR2dGUSmF5tDy-hCISSPJasaP10,1070
+srfm_core-0.1.0.dist-info/licenses/NOTICE,sha256=MaygiZYB0xhiYYke5xCDKXepkxiuHzfzQ5qFIq-0qjM,899
+srfm_core-0.1.0.dist-info/RECORD,,

srfm_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

srfm_core-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Busel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

srfm_core-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,16 @@
+srfm-core
+Copyright (c) 2026 Matthew Busel. Licensed under the MIT License (see LICENSE).
+
+This package is carved out of srfm-lab (https://github.com/Mattbusel/srfm-lab),
+also MIT licensed, copyright (c) 2026 Matthew Busel, at commit
+8cbfcb0551d44e3ed1c20bdae9dc805d61521c62:
+
+  * lib/srfm_core.py                  -> python/srfm_core/streaming.py,
+                                         golden/reference/srfm_core_lab.py (verbatim)
+  * crates/tick-backtest/src/bh_physics.rs -> src/lib.rs (structure; math re-ported
+                                         from lib/srfm_core.py)
+  * crates/larsa-core                 -> bindings/python-rs (pyo3 layer only)
+  * tests/test_srfm_core.py, tests/test_bh_physics.py -> python/tests, tests
+
+The SRFM transforms (Minkowski beta, black-hole mass, geodesic, Hawking proxy)
+were defined in the LARSA strategy code inside srfm-lab. See docs/PROVENANCE.md.