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.orgalready 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.orgunder "Synthetic data generation (methodology)", and rancompass index --org-roam-db-syncto 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 viaaggregation_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) andRandom 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 againstRandom Walkand 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 (wrappingthetaas a length-1theta_path), not just the one-linenext()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, matchingsynthetic_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.