darm-vol 0.1.0__tar.gz

darm_vol-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,62 @@
+name: Controlled PyPI publishing
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      destination:
+        description: 'Manual preview channel only'
+        required: true
+        type: choice
+        options: [testpypi]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: |
+          test -f LICENSE || (echo 'Licence required before public release' && exit 1)
+          python -m pip install -e '.[dev]'
+          python -m pytest -q
+          python -m ruff check src tests examples
+          python -m build
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-packages
+          path: dist/
+  testpypi:
+    if: github.event_name == 'workflow_dispatch' && inputs.destination == 'testpypi'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-packages
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+  pypi:
+    if: github.event_name == 'release' && github.event.action == 'published' && startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-packages
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

darm_vol-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,32 @@
+name: Test and build
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -e '.[dev]'
+      - run: python -m pytest -q
+      - run: python -m ruff check src tests examples
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - name: Wheel smoke test in clean environment
+        run: |
+          python -m venv /tmp/darm-wheel-smoke
+          /tmp/darm-wheel-smoke/bin/python -m pip install dist/*.whl
+          (cd /tmp && /tmp/darm-wheel-smoke/bin/python -c 'from darm_vol import DARM; print(DARM(lags=5))')

darm_vol-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 — pre-release candidate
+
+- Finite-K normalized exponential, power and hyperbolic ARCH kernels.
+- Symmetric and asymmetric news impact, Gaussian and unit-variance Student-t.
+- Bounded multi-start conditional MLE, exact finite-memory forecasts, simulation.
+- Diagnostics and optional Matplotlib visualisation.
+
+Publication date is not assigned: this version has **not** been released on PyPI.

darm_vol-0.1.0/CITATION.cff

@@ -0,0 +1,8 @@
+cff-version: 1.2.0
+message: "Please cite the software and its underlying research preprint."
+title: "darm-vol: Decaying AutoRegressive Memory for Conditional Volatility"
+type: software
+authors:
+  - family-names: Connell
+    given-names: Callum
+version: 0.1.0

darm_vol-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Please open a GitHub issue to discuss substantial numerical or public API changes.
+Submit tests verifying mathematical identities independently from the implementation.
+Do not alter kernel definitions or sample conditioning silently. Document version,
+seed, data construction and optimization tolerances of all numeric comparisons.
+
+Locally:
+
+```bash
+python -m pip install -e '.[dev]'
+python -m pytest -q
+ruff check src tests examples
+python -m build
+python -m twine check dist/*
+```
+
+**Licence selection is pending.** Obtain author approval before accepting
+third-party contributions or publicly redistributing the source.

darm_vol-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Callum Connell
+
+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.

darm_vol-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+include CITATION.cff
+include RELEASE_BLOCKERS.md
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include tests *.py
+recursive-include .github *.yml
+include VALIDATION_REPORT.md
+recursive-include benchmarks *.py

darm_vol-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: darm-vol
+Version: 0.1.0
+Summary: Decaying AutoRegressive Memory models for finite-memory conditional volatility
+Author: Callum Connell
+License-Expression: MIT
+Keywords: volatility,ARCH,conditional variance,financial econometrics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == "pandas"
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.6; extra == "plot"
+Provides-Extra: performance
+Requires-Dist: numba>=0.58; extra == "performance"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Requires-Dist: pandas>=1.5; extra == "dev"
+Requires-Dist: matplotlib>=3.6; extra == "dev"
+Dynamic: license-file
+
+# darm-vol
+
+**Decaying AutoRegressive Memory (DARM) conditional-volatility models**  
+Author: **Callum Connell** · Version: **0.1.0 pre-release candidate**
+
+A Python library for the finite-lag, normalized-kernel ARCH specifications developed in
+*Decaying Autoregressive Memory Models for Conditional Volatility: Mathematical Foundations,
+Finite-Sample Identification and Out-of-Sample Evidence* (preprint v1.0, 19 October 2026).
+
+> **Not published.** `pip install darm-vol` will only work after a PyPI release.
+> Source installation works now. The package has no selected software licence;
+> author approval is required **before** any public distribution.
+
+## Model
+
+For zero conditional-mean innovations `epsilon_t = sqrt(h_t) z_t`, where independent,
+standardized, symmetric `z_t` have mean zero and variance one, symmetric DARM is
+
+```text
+h_t = omega + rho * sum_{k=1}^K w_k(theta) * epsilon_(t-k)^2
+```
+
+with `omega > 0`, `0 <= rho < 1`, `w_k >= 0`, `sum w_k = 1`.
+For asymmetric DARM, replace each squared innovation with
+
+```text
+u_t = epsilon_t^2 * [1 - kappa + 2*kappa*1{epsilon_t<0}]
+```
+
+where `0 <= kappa < 1`. Here `u_t` denotes the transformed shock; **`nu` in
+parameter dictionaries denotes Student-t degrees of freedom, not `u_t`**.
+
+Finite-lag kernels use `k=1..K`:
+
+| Kernel | Unnormalized weight | Parameters |
+|---|---|---|
+| Exponential | `beta^(k-1)` | `0 < beta < 1` |
+| Power | `(k-1+delta)^(-alpha)` | `alpha, delta > 0` |
+| Hyperbolic | `(1+s*k)^(-p)` | `s, p > 0` |
+
+Every family is normalized over exactly **K** lags. Hyperbolic coincides with
+a subset of shifted power weights (`alpha=p`, `delta=1+1/s`) rather than an
+independent stochastic-process class. The infinite-lag counterpart is a
+**different specification**; finite exponential DARM is not exactly GARCH(1,1).
+The infinite power kernel has a finite normalizing constant only when `alpha>1`.
+
+DARM is a low-dimensional parametrization of ARCH(K), not a new stochastic
+process outside ARCH theory. A finite-K DARM can show persistent squared returns
+but is **not** strictly long-memory in the covariance non-summability sense under
+the manuscript's finite-moment conditions.
+
+## Installation
+
+In a checked-out source directory:
+
+```bash
+python -m pip install .
+python -m pip install -e '.[dev]'
+```
+
+Python >=3.10; runtime: NumPy and SciPy. pandas Series are accepted as inputs
+without requiring pandas at runtime. Plotting and optional acceleration:
+
+```bash
+python -m pip install '.[plot]'
+python -m pip install '.[performance]'
+```
+
+## Quick start — fit, forecast, simulate
+
+```python
+import numpy as np
+from darm_vol import DARM
+
+model = DARM(kernel="power", distribution="student-t", lags=30,
+             asymmetric=True)
+true = {"omega": 0.00002, "rho": 0.70, "alpha": 1.8,
+        "delta": 5.0, "kappa": 0.4, "nu": 8.0}
+
+sample = model.simulate(true, nobs=1200, burn=1000, random_state=42)
+fit = model.fit(sample.returns, n_starts=2, random_state=42)
+print(fit.summary())
+print(fit.params, fit.loglikelihood, fit.aic, fit.bic)
+
+fc = fit.forecast(horizon=5)
+print(fc.daily_variance, fc.daily_volatility)
+print(fc.integrated_variance)
+
+new_data = fit.simulate(nobs=1000, burn=1000, random_state=99)
+print(new_data.returns.shape, new_data.conditional_volatility.shape)
+
+# Optional: pip install '.[plot]'
+# fig, ax = fit.plot_volatility()
+```
+
+For live equity data see [`examples/fit_equity_returns.py`](examples/fit_equity_returns.py).
+**Inputs are always in their original units**: e.g., a 1% decimal log return
+is `0.01`, not `1.0`. No automatic scaling or demeaning occurs.
+
+The **first K observations initialize the observed lag state** and are excluded
+from the fitted conditional likelihood. Conditional variance arrays have `NaN`
+in the first K positions. Therefore AIC/BIC use `T-K` observations and the
+estimated number of free parameters. `omega` is internally reparameterized
+by a sample-variance scale during optimization, then returned in the original
+input units.
+
+## Forecasting
+
+For future times, unknown transformed shocks are replaced by their conditional
+expectations. Both Gaussian and standardized Student-t innovations are
+symmetric, giving `E[A_t]=1` with the stated asymmetric transformation.
+`forecast(horizon=H).daily_variance` computes `E_T[h_(T+j)]` for `j=1,...,H`.
+`integrated_variance` sums them. `daily_volatility` is `sqrt(E_T[h])`, **not**
+`E_T[sqrt(h)]`.
+
+With zero-mean martingale-difference returns, the sum of future conditional
+variances also equals the conditional variance of their cumulative sum;
+that equivalence should not be applied if separate serially dependent mean
+dynamics are introduced. No interval coverage claim is implied.
+
+## Simulation and diagnostics
+
+Simulation uses independent standardized Gaussian or Student-t shocks and
+exact finite-K transformed-shock recursion with K presample transformed shocks
+fixed at `omega/(1-rho)` (valid due to the symmetric innovation laws). A burn-in
+period reduces the effect of initialization. For infinite fourth-moment
+Student-t laws with `2<nu<=4`, squared-return variance diagnostics do not
+have the usual finite-moment theoretical justification.
+
+`fit.diagnostics(lags=10)` returns residual mean, variance, excess kurtosis,
+and Ljung-Box tests on residuals and residual squares (raw asymptotic p-values;
+no automatic degrees-of-freedom correction for fitted parameters).
+`fit.plot_volatility()`, `fit.plot_residuals()`, `fit.plot_kernel()`,
+`fit.plot_forecast(10)` return Matplotlib `(Figure, Axes)` objects.
+
+## Scientific limitations
+
+- **Identification:** high kernel-shape uncertainty, flat likelihood ridges,
+  and boundary estimates can arise even when point forecasts are accurate.
+  No default Wald standard errors are provided; use careful profile inference.
+- **Conditional MLE:** the first K returns are treated as conditioning
+  observations, rather than integrating out a stationary presample.
+- **Finite K:** neither finite geometric kernel GARCH equivalence nor genuine
+  covariance non-summable long memory is claimed.
+- **Forecast calibration:** prediction intervals for future squared returns
+  are not interchangeable with intervals for latent integrated variance.
+- **Performance:** source supplied for this build includes the papers, but
+  **not original research implementation or raw experiment inputs**. Our
+  independent numerical unit tests do *not* establish full paper replication.
+- **Inference:** fitted Student-t nu can be weakly identified; numerical boxes
+  are implementation limits, not the unrestricted theoretical parameter domain.
+- **Empirical superiority:** the paper's primary 10-day comparison against
+  GJR-GARCH is inconclusive (HAC p=0.146291); no universal model superiority
+  or economic trading benefit is claimed.
+
+## Research, attribution and citation
+
+Callum Connell (2026), *Decaying Autoregressive Memory Models for Conditional
+Volatility: Mathematical Foundations, Finite-Sample Identification and
+Out-of-Sample Evidence*, preprint v1.0, 19 October 2026. See
+[`research/`](research/) for the documents used to implement this package,
+including the technical supplement and mathematical correction report.
+See [`CITATION.cff`](CITATION.cff) for software citation metadata.
+No DOI or public external paper URL has been supplied, so none is fabricated.
+
+## Development status
+
+This repository is a **0.1.0 pre-release source candidate**, not a published
+PyPI release or independent replication of Experiments 13–18. See
+[`docs/limitations.md`](docs/limitations.md) and
+[`docs/publishing.md`](docs/publishing.md) before releasing.
+
+Contributions: see [`CONTRIBUTING.md`](CONTRIBUTING.md).

darm_vol-0.1.0/README.md

@@ -0,0 +1,173 @@
+# darm-vol
+
+**Decaying AutoRegressive Memory (DARM) conditional-volatility models**  
+Author: **Callum Connell** · Version: **0.1.0 pre-release candidate**
+
+A Python library for the finite-lag, normalized-kernel ARCH specifications developed in
+*Decaying Autoregressive Memory Models for Conditional Volatility: Mathematical Foundations,
+Finite-Sample Identification and Out-of-Sample Evidence* (preprint v1.0, 19 October 2026).
+
+> **Not published.** `pip install darm-vol` will only work after a PyPI release.
+> Source installation works now. The package has no selected software licence;
+> author approval is required **before** any public distribution.
+
+## Model
+
+For zero conditional-mean innovations `epsilon_t = sqrt(h_t) z_t`, where independent,
+standardized, symmetric `z_t` have mean zero and variance one, symmetric DARM is
+
+```text
+h_t = omega + rho * sum_{k=1}^K w_k(theta) * epsilon_(t-k)^2
+```
+
+with `omega > 0`, `0 <= rho < 1`, `w_k >= 0`, `sum w_k = 1`.
+For asymmetric DARM, replace each squared innovation with
+
+```text
+u_t = epsilon_t^2 * [1 - kappa + 2*kappa*1{epsilon_t<0}]
+```
+
+where `0 <= kappa < 1`. Here `u_t` denotes the transformed shock; **`nu` in
+parameter dictionaries denotes Student-t degrees of freedom, not `u_t`**.
+
+Finite-lag kernels use `k=1..K`:
+
+| Kernel | Unnormalized weight | Parameters |
+|---|---|---|
+| Exponential | `beta^(k-1)` | `0 < beta < 1` |
+| Power | `(k-1+delta)^(-alpha)` | `alpha, delta > 0` |
+| Hyperbolic | `(1+s*k)^(-p)` | `s, p > 0` |
+
+Every family is normalized over exactly **K** lags. Hyperbolic coincides with
+a subset of shifted power weights (`alpha=p`, `delta=1+1/s`) rather than an
+independent stochastic-process class. The infinite-lag counterpart is a
+**different specification**; finite exponential DARM is not exactly GARCH(1,1).
+The infinite power kernel has a finite normalizing constant only when `alpha>1`.
+
+DARM is a low-dimensional parametrization of ARCH(K), not a new stochastic
+process outside ARCH theory. A finite-K DARM can show persistent squared returns
+but is **not** strictly long-memory in the covariance non-summability sense under
+the manuscript's finite-moment conditions.
+
+## Installation
+
+In a checked-out source directory:
+
+```bash
+python -m pip install .
+python -m pip install -e '.[dev]'
+```
+
+Python >=3.10; runtime: NumPy and SciPy. pandas Series are accepted as inputs
+without requiring pandas at runtime. Plotting and optional acceleration:
+
+```bash
+python -m pip install '.[plot]'
+python -m pip install '.[performance]'
+```
+
+## Quick start — fit, forecast, simulate
+
+```python
+import numpy as np
+from darm_vol import DARM
+
+model = DARM(kernel="power", distribution="student-t", lags=30,
+             asymmetric=True)
+true = {"omega": 0.00002, "rho": 0.70, "alpha": 1.8,
+        "delta": 5.0, "kappa": 0.4, "nu": 8.0}
+
+sample = model.simulate(true, nobs=1200, burn=1000, random_state=42)
+fit = model.fit(sample.returns, n_starts=2, random_state=42)
+print(fit.summary())
+print(fit.params, fit.loglikelihood, fit.aic, fit.bic)
+
+fc = fit.forecast(horizon=5)
+print(fc.daily_variance, fc.daily_volatility)
+print(fc.integrated_variance)
+
+new_data = fit.simulate(nobs=1000, burn=1000, random_state=99)
+print(new_data.returns.shape, new_data.conditional_volatility.shape)
+
+# Optional: pip install '.[plot]'
+# fig, ax = fit.plot_volatility()
+```
+
+For live equity data see [`examples/fit_equity_returns.py`](examples/fit_equity_returns.py).
+**Inputs are always in their original units**: e.g., a 1% decimal log return
+is `0.01`, not `1.0`. No automatic scaling or demeaning occurs.
+
+The **first K observations initialize the observed lag state** and are excluded
+from the fitted conditional likelihood. Conditional variance arrays have `NaN`
+in the first K positions. Therefore AIC/BIC use `T-K` observations and the
+estimated number of free parameters. `omega` is internally reparameterized
+by a sample-variance scale during optimization, then returned in the original
+input units.
+
+## Forecasting
+
+For future times, unknown transformed shocks are replaced by their conditional
+expectations. Both Gaussian and standardized Student-t innovations are
+symmetric, giving `E[A_t]=1` with the stated asymmetric transformation.
+`forecast(horizon=H).daily_variance` computes `E_T[h_(T+j)]` for `j=1,...,H`.
+`integrated_variance` sums them. `daily_volatility` is `sqrt(E_T[h])`, **not**
+`E_T[sqrt(h)]`.
+
+With zero-mean martingale-difference returns, the sum of future conditional
+variances also equals the conditional variance of their cumulative sum;
+that equivalence should not be applied if separate serially dependent mean
+dynamics are introduced. No interval coverage claim is implied.
+
+## Simulation and diagnostics
+
+Simulation uses independent standardized Gaussian or Student-t shocks and
+exact finite-K transformed-shock recursion with K presample transformed shocks
+fixed at `omega/(1-rho)` (valid due to the symmetric innovation laws). A burn-in
+period reduces the effect of initialization. For infinite fourth-moment
+Student-t laws with `2<nu<=4`, squared-return variance diagnostics do not
+have the usual finite-moment theoretical justification.
+
+`fit.diagnostics(lags=10)` returns residual mean, variance, excess kurtosis,
+and Ljung-Box tests on residuals and residual squares (raw asymptotic p-values;
+no automatic degrees-of-freedom correction for fitted parameters).
+`fit.plot_volatility()`, `fit.plot_residuals()`, `fit.plot_kernel()`,
+`fit.plot_forecast(10)` return Matplotlib `(Figure, Axes)` objects.
+
+## Scientific limitations
+
+- **Identification:** high kernel-shape uncertainty, flat likelihood ridges,
+  and boundary estimates can arise even when point forecasts are accurate.
+  No default Wald standard errors are provided; use careful profile inference.
+- **Conditional MLE:** the first K returns are treated as conditioning
+  observations, rather than integrating out a stationary presample.
+- **Finite K:** neither finite geometric kernel GARCH equivalence nor genuine
+  covariance non-summable long memory is claimed.
+- **Forecast calibration:** prediction intervals for future squared returns
+  are not interchangeable with intervals for latent integrated variance.
+- **Performance:** source supplied for this build includes the papers, but
+  **not original research implementation or raw experiment inputs**. Our
+  independent numerical unit tests do *not* establish full paper replication.
+- **Inference:** fitted Student-t nu can be weakly identified; numerical boxes
+  are implementation limits, not the unrestricted theoretical parameter domain.
+- **Empirical superiority:** the paper's primary 10-day comparison against
+  GJR-GARCH is inconclusive (HAC p=0.146291); no universal model superiority
+  or economic trading benefit is claimed.
+
+## Research, attribution and citation
+
+Callum Connell (2026), *Decaying Autoregressive Memory Models for Conditional
+Volatility: Mathematical Foundations, Finite-Sample Identification and
+Out-of-Sample Evidence*, preprint v1.0, 19 October 2026. See
+[`research/`](research/) for the documents used to implement this package,
+including the technical supplement and mathematical correction report.
+See [`CITATION.cff`](CITATION.cff) for software citation metadata.
+No DOI or public external paper URL has been supplied, so none is fabricated.
+
+## Development status
+
+This repository is a **0.1.0 pre-release source candidate**, not a published
+PyPI release or independent replication of Experiments 13–18. See
+[`docs/limitations.md`](docs/limitations.md) and
+[`docs/publishing.md`](docs/publishing.md) before releasing.
+
+Contributions: see [`CONTRIBUTING.md`](CONTRIBUTING.md).

darm_vol-0.1.0/RELEASE_BLOCKERS.md

@@ -0,0 +1,12 @@
+# Software licence decision required before publication
+
+The author has not yet selected a software licence. No licence grant is
+implied. Do **not** publish or redistribute the package publicly on PyPI
+until Callum Connell has approved the licence and provided its full text in
+a `LICENSE` file.
+
+The most common permissive options are MIT, BSD-3-Clause and Apache-2.0,
+but no option has been selected automatically. Confirm rights in any
+incorporated third-party materials before choosing.
+
+The release workflow intentionally fails while `LICENSE` is absent.

darm_vol-0.1.0/VALIDATION_REPORT.md

@@ -0,0 +1,71 @@
+# DARM v0.1.0 candidate — build & validation report
+
+Date: 28 October 2026. Package has **not** been uploaded to PyPI or
+published on GitHub. Software licence remains undecided and is a **release
+blocker** requiring explicit author approval.
+
+## Source inspection and mathematical design
+
+- Supplied: preprint v1.0, technical supplement v1.0, mathematical
+  correction report v1.0, package implementation requirements.
+- Not supplied: original research Python sources, Monte Carlo notebook
+  implementation archive, numerical model-fit regression fixtures,
+  original equity market data, exact run environment.
+- Implemented kernel equations 10–12 from preprint, finite K normalization.
+- Implemented finite-K symmetric/asymmetric transformed-shock recursion
+  and Gaussian / unit-variance Student-t conditional log-likelihood.
+- Adopted the supplement's conditional likelihood convention: first K
+  observed returns initialize the state; effective n=T-K.
+- Multi-step forecasts use future conditional expected transformed shocks,
+  not unavailable realized future returns, under symmetric innovation laws.
+- Source code is newly implemented from papers; no claim that it recreates
+  original research Python code line-for-line.
+
+## Checks executed (current candidate)
+
+| Check | Command | Result |
+| --- | --- | --- |
+| Unit and Monte Carlo tests | `PYTHONPATH=src python -m pytest -q` | 26 passed |
+| Bytecode syntax check | `python -m compileall -q src tests examples` | Passed |
+| Wheel build | `python -m pip wheel --no-build-isolation --no-deps . -w dist` | Passed |
+| Source distribution | `python -c 'import setuptools; setuptools.setup()' sdist --dist-dir dist` | Passed |
+| Built-wheel smoke test | Install wheel with `pip --no-index --no-deps` into new venv; inject existing environment's NumPy/SciPy paths; import + ML fit + 5-day forecast from `/tmp` | Passed (dependencies NOT isolated) |
+| Time benchmark | `PYTHONPATH=src python benchmarks/benchmark_filter.py` | Success; approximately 0.014 seconds for T=10,000 K=252 (best of 3) |
+| `python -m build` | Attempted tool availability | Not run: `build` not installed and network unavailable |
+| `twine check dist/*` | Attempted tool availability | Not run: `twine` not installed and network unavailable |
+| `ruff check` | Attempted tool availability | Not run: `ruff` not installed and network unavailable |
+| Base `pip check` | `python -m pip check` | Failed due unrelated existing moviepy/pillow version mismatch |
+| Research code numerical parity | Compare original likelihood/forecasts | Not possible: original implementation absent |
+| Multi-Python matrix | GitHub Actions configured for Python 3.10–3.13 | Not executed locally; Python 3.13 tested |
+| PyPI TestPyPI publishing | Manual upload | NOT attempted; approval and licence required |
+
+### Representative filter benchmarks
+
+Environment: current Python 3.13 session, NumPy/SciPy, single-threaded
+Python loop around NumPy dot operations. The figures are local wall times;
+not a comparison against original DARM research software or GARCH models.
+
+| T | K | best of 3 |
+| ---: | ---: | ---: |
+| 1,000 | 30 | 0.0013 s |
+| 5,000 | 30 | 0.0062 s |
+| 10,000 | 30 | 0.0129 s |
+| 1,000 | 252 | 0.0011 s |
+| 5,000 | 252 | 0.0070 s |
+| 10,000 | 252 | 0.0138 s |
+| 5,000 | 1,000 | 0.0075 s |
+| 10,000 | 1,000 | 0.0162 s |
+
+## Release blockers
+
+1. Ask Callum Connell to choose and approve a software licence.
+2. Have the author review public project metadata / legal data rights.
+3. Run Ruff, `python -m build`, `twine check`, clean dependency-isolated
+   wheel install, and CI matrix in an online development environment.
+4. Acquire old research implementation and numeric fixtures for
+   independent regression comparisons and original research parity checks.
+5. Register GitHub Trusted Publishers with matching protected environments.
+6. Authorize a deliberate TestPyPI dispatch and subsequent GitHub Release.
+7. Confirm at publication time that the `darm-vol` distribution is available.
+
+See `docs/publishing.md` for step-by-step instructions.

darm_vol-0.1.0/benchmarks/benchmark_filter.py

@@ -0,0 +1,30 @@
+"""Repeatable wall-clock microbenchmark of the finite-K variance recursion.
+
+No claims are made about the original research implementations.
+Run: python benchmarks/benchmark_filter.py
+"""
+from __future__ import annotations
+
+import time
+import numpy as np
+from darm_vol import DARM
+
+
+def benchmark(n: int, k: int, repeats: int = 3) -> float:
+    rng = np.random.default_rng(20261028)
+    returns = rng.normal(0, .01, n)
+    p = {"omega": .00001, "rho": .8, "alpha": 2., "delta": 5.}
+    model = DARM(kernel="power", distribution="normal", lags=k)
+    times = []
+    for _ in range(repeats):
+        start = time.perf_counter()
+        model.conditional_variance(returns, p)
+        times.append(time.perf_counter()-start)
+    return min(times)
+
+
+if __name__ == "__main__":
+    for k in (30, 252, 1000):
+        for n in (1000, 5000, 10000):
+            if n > k:
+                print(f"T={n:5d} K={k:4d}: {benchmark(n,k):.6f} sec (best of three)")