Volatility Propagation and Structural Hysteresis in Equity Networks (VPSH)

Reproducible research code for the working paper:

Volatility Recovers Before Network Structure: Structural Hysteresis in Global Equity Propagation Networks
Abdelmalik Berrada — Independent Quantitative Researcher — 17 August 2026.

The central empirical distinction is between recovery of scalar market-volatility stress and recovery of the cross-sectional propagation geometry.

Paper scope

The public replication path is intentionally focused on the paper's H1–H4 questions:

Research question	Quantity
Is propagation geometry low-dimensional?	effective/stable rank of the frozen calm geometry
Is propagation horizon-dependent?	multi-horizon loadings and factorization diagnostics
Do shocks deform propagation geometry?	D_B(shock) - D_B(pre)
Does structural displacement persist after stress normalization?	matched loading/recovery gap
Does structure recover more slowly than volatility?	right-censoring-aware tau_B > tau_V
When does a positive hysteresis-loop area follow?	formal matched-stress proposition for H_B = ∮ D_B dS

H5/H6/H7/H7-R are not evidence used by the paper. Final research utilities for those follow-up projects are retained under research/ so that the development history is not mixed into the paper replication path.

Repository layout

.
├── config/research.yaml          # paper analysis configuration
├── data/                         # manifest + frozen-universe hash (raw data not committed)
├── paper/                        # SSRN working paper, PDF + DOCX
├── scripts/
│   ├── verify_universe.py
│   ├── reproduce_paper.py
│   ├── summarize_results.py
│   └── capture_environment.py
├── src/vpsh/                     # canonical package source
├── tests/                        # CPU-safe deterministic tests/self-tests
├── research/                     # follow-up H6/H7/H7-R code; outside paper evidence
└── .github/workflows/ci.yml

1. Install

CPU-only, portable path

Linux/macOS:

python -m venv .venv
source .venv/bin/activate
export VPSH_NATIVE_CUDA=0
python -m pip install -U pip setuptools wheel
python -m pip install -e ".[dev]"
vpsh backend
vpsh selftest --no-progress
pytest -q

Windows PowerShell:

$env:VPSH_NATIVE_CUDA="0"
powershell -ExecutionPolicy Bypass -File .\scripts\install_windows.ps1

CUDA path

The build uses setuptools + pybind11 and invokes nvcc directly; CMake is not required.

$env:VPSH_NATIVE_CUDA="1"
$env:VPSH_CUDA_ARCHS="86"   # example: RTX 30-series/Ampere
python -m pip install -e ".[dev]" -v
vpsh backend
vpsh selftest --no-progress

If an older CUDA Toolkit rejects a newer MSVC host compiler, VPSH_ALLOW_UNSUPPORTED_COMPILER=1 enables NVIDIA's explicit override. Use it only when you have deliberately accepted that toolchain combination.

2. Restore and verify the frozen paper universe

The source archive used to create this clean repository did not contain data/universe.csv; therefore the repository does not pretend that the numerical paper results can be regenerated until that exact artifact is restored.

Expected publication-universe fingerprint:

SHA-256  f46c342bc075d89c4e0b53f617947276f5f917581062853a4a13e52fca20e5c5
Rows     1,328
US       503
EUROPE   600
JAPAN    225

After copying the frozen file to data/universe.csv:

python scripts/verify_universe.py

A mismatch exits non-zero.

3. Reproduce the paper runs

python scripts/reproduce_paper.py

Equivalent individual commands:

vpsh run --config config/research.yaml --universe data/universe.csv --market US     --out runs/paper/us
vpsh run --config config/research.yaml --universe data/universe.csv --market EUROPE --out runs/paper/europe
vpsh run --config config/research.yaml --universe data/universe.csv --market JAPAN  --out runs/paper/japan
python scripts/summarize_results.py --root runs/paper

Each market run writes a persistent run.log, backend.json, a study manifest, selected assets, operator diagnostics, event paths, H1–H4 result JSON files, figures, and summary.json.

4. Reproducibility levels

Software reproducibility. pytest and vpsh selftest are deterministic and require no Yahoo download.

Analysis reproducibility. Requires the frozen universe.csv with the exact hash above.

Data reproducibility. Yahoo Finance is a live external source. Historical data, metadata, repairs, or symbol availability may change after the paper date. For archival/bitwise replication, preserve each run's generated cache/ directory outside Git (for example in Zenodo/OSF release assets) and record its hashes.

The code never silently claims that a live redownload is byte-identical to the original research snapshot.

5. Methodological safeguards implemented in code

• causal rolling market-volatility residualization;
• causal standardization using information through t-1;
• dense ridge operators with no imposed low rank;
• frozen calibration-period ridge tuning;
• cross-sectional propagation geometry with diagonal removed;
• non-overlapping event-relative blocks for H3/H4;
• matched-stress loading/recovery hysteresis;
• right-censoring-aware structural recovery rather than inventing tau_B = 505;
• SHA-256 manifests for configs, universes, caches and environment provenance;
• CPU fallback plus optional CUDA/OpenMP acceleration.

6. Important limitation

The paper candidate universe is a current-listed snapshot, not a point-in-time 2014 constituent panel. Calibration ends on 31 December 2014 and study inference begins in 2015, so current membership can induce survivorship/current-listing bias. This limitation should remain explicit in any public description of the results.

7. Paper

• paper/working-paper.pdf
• paper/working-paper.docx

8. Citation

See CITATION.cff.

9. License

The source archive supplied for this cleanup did not contain a software license. No open-source license has therefore been invented or assigned here. Choose an explicit license before public release if you want third parties to have reuse rights.