srfm-core 0.1.0__tar.gz

srfm_core-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+/target
+Cargo.lock.bak
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+dist/
+build/
+.venv/
+*.pyd
+*.so

srfm_core-0.1.0/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/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.

srfm_core-0.1.0/PKG-INFO

@@ -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/PYPI.md

@@ -0,0 +1,33 @@
+# 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/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "srfm-core"
+version = "0.1.0"
+description = "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."
+readme = "PYPI.md"
+license = "MIT"
+license-files = ["LICENSE", "NOTICE"]
+authors = [{ name = "Matthew Busel" }]
+requires-python = ">=3.10"
+dependencies = ["numpy>=1.22", "pandas>=1.4"]
+keywords = ["trading", "technical-analysis", "indicators", "quant", "finance", "vectorbt", "freqtrade", "srfm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+vbt = ["vectorbt>=0.25"]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/Mattbusel/srfm-core"
+Source = "https://github.com/Mattbusel/srfm-core"
+Documentation = "https://github.com/Mattbusel/srfm-core/tree/main/docs"
+Changelog = "https://github.com/Mattbusel/srfm-core/blob/main/CHANGELOG.md"
+Issues = "https://github.com/Mattbusel/srfm-core/issues"
+"Upstream (srfm-lab)" = "https://github.com/Mattbusel/srfm-lab"
+
+[tool.hatch.build.targets.wheel]
+packages = ["srfm_core"]
+
+[tool.hatch.build.targets.sdist]
+include = ["srfm_core", "tests", "PYPI.md", "LICENSE", "NOTICE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

srfm_core-0.1.0/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-0.1.0/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-0.1.0/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