Task: Document stochastic processes: knowledge hub + per-process pages

Table of Contents

This page documents a task in the IR Rates synthetic data generation story. It captures the goal, current status, acceptance, and any notes or results.

Goal

Every stochastic process implemented in ores.analytics.quant (GMM/geometric, arithmetic, OU, and the new Vasicek/CIR/Hull-White short-rate engines) has a corresponding knowledge doc, plus foundational docs for the underlying math (Wiener process, Ito's lemma) they all build on, linked from a new hub. Each doc gives a layperson-accessible description, a chart where one clarifies the process's behaviour, and a summary of the originating paper(s) plus closely related work – not just a formula dump.

Status

Field Value
State DONE
Parent story IR Rates synthetic data generation
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-07-16

Acceptance

  • A new hub doc (e.g. 'Stochastic Processes') exists under doc/knowledge/domain, linking every process-specific atomic doc; GBM, Wiener process, and Ito's lemma each have their own atomic doc even though they predate this story, since they are prerequisites the others link to; OU/Vasicek/CIR/Hull-White (once implemented) each get one; every doc includes a paper-summary section with real citations, not just a bibliography line
  • Follows the Zettelkasten approach already established for the interest_rate_curve_bundles.org and time_structures_and_tenors.org clusters (see doc/knowledge/domain/): small, self-contained, single-concept docs – not one large document covering every process – cross-linked via org-roam [[id:...]] links (hub -> atomic doc, and atomic doc -> atomic doc where one process builds on another, e.g. OU/Vasicek -> Wiener process/Ito's lemma). Each atomic doc must be independently readable and independently linkable from elsewhere in the graph, exactly like the existing curve-family/tenor docs.

Plan

(Implementation strategy. Written when work starts; key decisions are distilled into the parent story's * Decisions at close, but the plan itself stays — it is the historical record of what we did.)

Original implementation

One hub doc (stochastic_processes.org) plus one atomic doc per foundational concept and per concrete process implemented in ores.analytics.quant, following the existing term_structures_and_tenors.org=/=tenor.org cluster's style exactly: Summary / Detail / See also, with a "Further reading" subsection citing real, checkable papers rather than a bare bibliography line.

  • Grounded every SDE and formula directly in the corresponding C++ header's doc comment (ou_process.hpp, vasicek_process.hpp, cir_process.hpp, hull_white_process.hpp, gmm_process.hpp, arithmetic_gmm_process.hpp), rather than restating textbook formulas independently of what the codebase actually implements — where the header already states a discretisation or closed-form result, the doc quotes it verbatim.
  • 8 atomic docs: Wiener Process and Ito's Lemma (foundations); Geometric and Arithmetic Brownian Motion (price processes); Ornstein-Uhlenbeck, Vasicek, Hull-White, and CIR (mean-reverting short-rate family).
  • No PNG/chart images were generated — this codebase's knowledge docs express process behaviour via formulas and tables (as garch_volatility_models.org already does), not embedded charts; the acceptance criterion's "chart where applicable" is satisfied by the hub's comparison table across the four mean-reverting processes instead, which is the clearest way to show how they relate.
  • Registered the hub in doc/knowledge/knowledge.org under "Synthetic data generation (methodology)", and ran compass index --org-roam-db-sync to confirm all 9 docs are indexed and searchable.

Review round (after user read-through on the served site)

A full review pass, applied incrementally while the user read the built site:

  • Broadened the hub's opening framing so it isn't hard-coded to synthetic data generation — that is the first, not the only, expected consumer of the cluster.
  • Added a "Layperson's mental model" section to every atomic doc, always before the heavy maths: a plain-language analogy (elastic band for mean reversion, a jittery cork for the Wiener process, a random coin-flip walk, etc.), followed by a short C++ snippet grounding the analogy directly in the real implementation, wherever one exists.
  • Converted every formula from org-verbatim/ASCII (dX = kappa*...) to proper LaTeX ($…$ inline, \begin{equation}=/\begin{align}= for display), matching the rest of the knowledge base's convention (confirmed via aggregation_currency.org=/=covered_interest_parity.org).
  • Split out two new atomic docs the cluster was previously restating inline rather than treating as independently linkable single concepts: Markov Property (the "no memory" property) and Random Walk (the discrete-time process the Wiener process is the continuous limit of).
  • Added a "Brownian motion vs. Wiener process" section to Wiener Process (the phenomenon vs. its rigorous mathematical model), folding in a contrast against Random Walk and removing the now-redundant separate "Relationship to a random walk" section it duplicated.
  • Added a "what mean reversion means" explanatory paragraph to the hub's mean-reverting-processes section.
  • Fixed Vasicek Process's C++ snippet to show the constructor (wrapping theta as a length-1 theta_path), not just the one-line next() delegation, which didn't convey the actual "constant-target configuration of Hull-White" point.
  • Fixed an org-mode rendering bug in Random Walk's Further Reading: a continuation line starting with a bare page number ("294.") was parsed as a new ordered-list item, splitting the citation across two disconnected HTML blocks.
  • Added Wikipedia links throughout, and used the repo's established code_variable (Greek letter) convention — e.g. =kappa (κ)= — for code-variable-to-symbol call-outs in the layperson sections, matching synthetic_market_data_generators.org.

Notes

Test Scenarios

Manual QA scenarios (scaffolded via compass add test_scenario, run through the QA Validation Runner panel) that verify this task. Link new ones here as they're created; the scenario doc itself links back via its "Verifies task" field.

Scenario State Notes
     

PRs

PR Title
#1600 [doc] Document stochastic processes: knowledge hub + per-process pages

Review

# Comment summary File Decision Notes
1 ores.analytics.quant link uses wrong ID (points at ORE Studio hub, not the component doc) stochastic_processes.org Accepted Fixed in 86c2633b8
2 CIR snippet elides the lambda==0 guard, tied to the Feller-condition section discussed nearby cir_process.org Accepted Fixed in 86c2633b8
3 GBM/ABM snippets elide the sd==0 degenerate-mixture-component guard geometric_brownian_motion.org, arithmetic_brownian_motion.org Accepted Fixed in 86c2633b8
4 OU/Hull-White snippets elide kappa<=0, note for future maintenance re: OU's only-short-rate consumption ornstein_uhlenbeck_process.org, hull_white_process.org, stochastic_processes.org Declined kappa<=0 already discussed in adjacent prose (no reader confusion per reviewer); OU-consumption note is a future-maintenance observation, not a defect

Result

Shipped: a new doc/knowledge/domain/stochastic_processes.org hub plus 10 atomic docs — the original 8 (wiener_process.org, ito_lemma.org, geometric_brownian_motion.org, arithmetic_brownian_motion.org, ornstein_uhlenbeck_process.org, vasicek_process.org, hull_white_process.org, cir_process.org) plus two added during review (markov_property.org, random_walk.org) — cross-linked via org-roam [[id:...]] links exactly as the acceptance criteria specify, each with a real-citation "Further reading" section, a layperson mental model with a grounding C++ snippet, and LaTeX-rendered maths throughout. Registered in doc/knowledge/knowledge.org, confirmed indexed via compass search, and reviewed end-to-end by the user against a locally served build (compass site serve) with all feedback addressed.

Emacs 29.3 (Org mode 9.6.15)