docs: replace ASCII diagrams with Mermaid visuals + brand CSS
- Add sphinxcontrib-mermaid>=0.9.2 to requirements.txt - Add custom.css with orange brand theme (admonitions, tables, mermaid containers) - Replace Complete Algorithm ASCII pseudocode with Mermaid flowchart (differential_evolution.md) - Add Mermaid stateDiagram-v2 for Bull/Normal/Bear regime transitions (hmm.md) - Replace Rust module file tree with Mermaid graph TD (point_processes.md) - Configure mermaid_version=10.9.0 and dark+orange themeVariables in conf.py
This commit is contained in:
ThotDjehuty
@@ -4,3 +4,4 @@ furo==2023.9.10
|
||||
myst-parser==2.0.0
|
||||
sphinx-autodoc-typehints==1.24.0
|
||||
charset-normalizer>=3.4.0
|
||||
sphinxcontrib-mermaid>=0.9.2
|
||||
|
||||
@@ -0,0 +1,138 @@
|
||||
/* ─── Optimiz-rs Documentation Custom Styles ──────────────────────────────── */
|
||||
/* Brand: orange (#f97316) on furo dark theme */
|
||||
|
||||
:root {
|
||||
--brand-orange: #f97316;
|
||||
--brand-orange-light: #fb923c;
|
||||
--brand-orange-dim: rgba(249, 115, 22, 0.15);
|
||||
--brand-orange-border: rgba(249, 115, 22, 0.35);
|
||||
}
|
||||
|
||||
/* ── Mermaid diagram container ─────────────────────────────────────────────── */
|
||||
.mermaid {
|
||||
background: transparent !important;
|
||||
padding: 1.5rem 0;
|
||||
text-align: center;
|
||||
overflow-x: auto;
|
||||
}
|
||||
|
||||
.mermaid svg {
|
||||
max-width: 100%;
|
||||
border-radius: 12px;
|
||||
filter: drop-shadow(0 4px 16px rgba(249, 115, 22, 0.12));
|
||||
}
|
||||
|
||||
/* ── Better admonitions ─────────────────────────────────────────────────────── */
|
||||
.admonition {
|
||||
border-radius: 10px !important;
|
||||
border-left-width: 4px !important;
|
||||
margin: 1.5rem 0 !important;
|
||||
}
|
||||
|
||||
.admonition.note {
|
||||
border-left-color: var(--brand-orange) !important;
|
||||
background: var(--brand-orange-dim) !important;
|
||||
}
|
||||
|
||||
.admonition.tip {
|
||||
border-left-color: #22c55e !important;
|
||||
background: rgba(34, 197, 94, 0.1) !important;
|
||||
}
|
||||
|
||||
.admonition.warning {
|
||||
border-left-color: #f59e0b !important;
|
||||
background: rgba(245, 158, 11, 0.1) !important;
|
||||
}
|
||||
|
||||
.admonition.important {
|
||||
border-left-color: #ef4444 !important;
|
||||
background: rgba(239, 68, 68, 0.1) !important;
|
||||
}
|
||||
|
||||
/* ── Section headers ────────────────────────────────────────────────────────── */
|
||||
h1, h2, h3 {
|
||||
scroll-margin-top: 4rem;
|
||||
}
|
||||
|
||||
h2 {
|
||||
border-bottom: 2px solid var(--brand-orange-border);
|
||||
padding-bottom: 0.4rem;
|
||||
}
|
||||
|
||||
/* ── Code blocks ────────────────────────────────────────────────────────────── */
|
||||
.highlight {
|
||||
border-radius: 8px !important;
|
||||
border: 1px solid rgba(255, 255, 255, 0.08) !important;
|
||||
}
|
||||
|
||||
/* Inline code */
|
||||
code.literal {
|
||||
background: rgba(249, 115, 22, 0.08) !important;
|
||||
border: 1px solid var(--brand-orange-border) !important;
|
||||
padding: 0.1em 0.4em !important;
|
||||
border-radius: 4px !important;
|
||||
color: var(--brand-orange-light) !important;
|
||||
font-size: 0.88em !important;
|
||||
}
|
||||
|
||||
/* ── Tables ─────────────────────────────────────────────────────────────────── */
|
||||
table.docutils {
|
||||
border-collapse: collapse;
|
||||
width: 100%;
|
||||
margin: 1.2rem 0;
|
||||
border-radius: 8px;
|
||||
overflow: hidden;
|
||||
font-size: 0.9rem;
|
||||
}
|
||||
|
||||
table.docutils th {
|
||||
background: var(--brand-orange-dim) !important;
|
||||
color: var(--brand-orange-light) !important;
|
||||
font-weight: 700;
|
||||
padding: 0.6rem 0.9rem;
|
||||
border-bottom: 2px solid var(--brand-orange-border);
|
||||
}
|
||||
|
||||
table.docutils td {
|
||||
padding: 0.5rem 0.9rem;
|
||||
border-bottom: 1px solid rgba(255, 255, 255, 0.06);
|
||||
}
|
||||
|
||||
table.docutils tr:hover td {
|
||||
background: rgba(249, 115, 22, 0.04);
|
||||
}
|
||||
|
||||
/* ── Performance metric boxes (for benchmarks) ──────────────────────────────── */
|
||||
.perf-box {
|
||||
background: linear-gradient(135deg, rgba(249,115,22,0.12) 0%, rgba(249,115,22,0.04) 100%);
|
||||
border: 1px solid var(--brand-orange-border);
|
||||
border-radius: 10px;
|
||||
padding: 1rem 1.5rem;
|
||||
margin: 1rem 0;
|
||||
display: inline-block;
|
||||
min-width: 140px;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
.perf-box .val {
|
||||
font-size: 1.8rem;
|
||||
font-weight: 800;
|
||||
color: var(--brand-orange);
|
||||
}
|
||||
|
||||
.perf-box .lbl {
|
||||
font-size: 0.75rem;
|
||||
color: #94a3b8;
|
||||
margin-top: 0.2rem;
|
||||
}
|
||||
|
||||
/* ── Navigation sidebar ─────────────────────────────────────────────────────── */
|
||||
.sidebar-tree .current > .reference {
|
||||
color: var(--brand-orange) !important;
|
||||
}
|
||||
|
||||
/* ── Mobile ─────────────────────────────────────────────────────────────────── */
|
||||
@media (max-width: 768px) {
|
||||
.mermaid svg { width: 100% !important; }
|
||||
table.docutils { font-size: 0.78rem; }
|
||||
}
|
||||
@@ -169,46 +169,18 @@ $$
|
||||
|
||||
## Complete Algorithm
|
||||
|
||||
```
|
||||
Algorithm: Differential Evolution
|
||||
─────────────────────────────────
|
||||
Input: objective f, bounds [l, u], pop_size N_P, F, CR, max_iter
|
||||
|
||||
1. Initialize population:
|
||||
For i = 1 to N_P:
|
||||
x_{i,0} = l + rand(0,1) · (u - l) # uniform in bounds
|
||||
|
||||
2. Evaluate fitness:
|
||||
f_i = f(x_{i,0}) for all i
|
||||
|
||||
3. While g < max_iter and not converged:
|
||||
|
||||
a. For i = 1 to N_P:
|
||||
|
||||
i. Mutation:
|
||||
Select r_1, r_2, r_3 distinct and ≠ i
|
||||
v_{i,g+1} = x_{r_1,g} + F · (x_{r_2,g} - x_{r_3,g})
|
||||
|
||||
ii. Crossover:
|
||||
j_rand = randint(1, D)
|
||||
For j = 1 to D:
|
||||
if rand(0,1) ≤ CR or j = j_rand:
|
||||
u_{i,j,g+1} = v_{i,j,g+1}
|
||||
else:
|
||||
u_{i,j,g+1} = x_{i,j,g}
|
||||
|
||||
iii. Boundary handling:
|
||||
Clip u_{i,g+1} to [l, u]
|
||||
|
||||
iv. Selection:
|
||||
if f(u_{i,g+1}) ≤ f(x_{i,g}):
|
||||
x_{i,g+1} = u_{i,g+1}
|
||||
else:
|
||||
x_{i,g+1} = x_{i,g}
|
||||
|
||||
b. g = g + 1
|
||||
|
||||
4. Return x_best and f(x_best)
|
||||
```{mermaid}
|
||||
flowchart TD
|
||||
A["🎲 Initialize Population\nx_i = l + rand · (u − l)"] --> B["📊 Evaluate Fitness\nf_i = f(x_i) for all i"]
|
||||
B --> C{{"g < max_iter?"}}
|
||||
C -->|Yes| D["Mutation\nv = x_r1 + F · (x_r2 − x_r3)"]
|
||||
D --> E["Crossover\nu_j = v_j if rand ≤ CR or j = j_rand\nelse u_j = x_j"]
|
||||
E --> F["Clip to bounds [l, u]"]
|
||||
F --> G{{"f(trial) ≤ f(target)?"}}
|
||||
G -->|"Yes — better"| H["✅ Accept trial\nx_i ← u_i"]
|
||||
G -->|"No — worse"| I["Keep current\nx_i unchanged"]
|
||||
H & I --> C
|
||||
C -->|No| J["🏆 Return x_best, f(x_best)"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -458,6 +458,24 @@ For complete examples with regime detection on real market data, see the [HMM Tu
|
||||
|
||||
### Transition Diagram
|
||||
|
||||
```{mermaid}
|
||||
stateDiagram-v2
|
||||
direction LR
|
||||
[*] --> Normal
|
||||
Bull : 📈 Bull Market
|
||||
Normal : 📊 Normal Regime
|
||||
Bear : 📉 Bear Market
|
||||
Bull --> Bull : a₁₁ (self)
|
||||
Bull --> Normal : a₁₂
|
||||
Normal --> Bull : a₂₁
|
||||
Normal --> Normal : a₂₂ (self)
|
||||
Normal --> Bear : a₂₃
|
||||
Bear --> Normal : a₃₂
|
||||
Bear --> Bear : a₃₃ (self)
|
||||
```
|
||||
|
||||
**Code example** — build and visualize the transition graph programmatically:
|
||||
|
||||
```python
|
||||
import networkx as nx
|
||||
|
||||
|
||||
@@ -406,25 +406,32 @@ plt.show()
|
||||
|
||||
## Module Architecture
|
||||
|
||||
```
|
||||
optimizr/point_processes/
|
||||
├── mod.rs # Module root, public API re-exports
|
||||
├── kernels.rs # ExcitationKernel trait + implementations
|
||||
│ ├── ExponentialKernel (φ = αe^{-βt})
|
||||
│ ├── PowerLawKernel (φ = K₀(1+t)^{-1-α₀})
|
||||
│ └── CompletelyMonotoneKernel (Mittag-Leffler)
|
||||
├── hawkes.rs # Hawkes process simulation & fitting
|
||||
│ ├── HawkesProcess<K> (univariate, Ogata thinning)
|
||||
│ └── BivariateHawkes<K> (buy/sell reaction flow)
|
||||
├── mittag_leffler.rs # Special functions
|
||||
│ ├── mittag_leffler() (E_{α,β}(z))
|
||||
│ ├── f_alpha_lambda() (Theorem 3.1 scaling fn)
|
||||
│ ├── gamma() (Lanczos Γ function)
|
||||
│ └── incomplete_gamma*() (upper/lower)
|
||||
├── mixed_fbm.rs # Fractional Brownian motion
|
||||
│ ├── FractionalBM (Cholesky & Hosking simulation)
|
||||
│ └── MixedFractionalBM (a·B + b·B^H)
|
||||
└── python_bindings.rs # PyO3 bindings for all functions
|
||||
```{mermaid}
|
||||
graph TD
|
||||
MOD["📦 mod.rs\nPublic API re-exports"]
|
||||
K["🔧 kernels.rs\nExcitationKernel trait"]
|
||||
H["⚡ hawkes.rs\nSimulation & fitting"]
|
||||
ML["🔢 mittag_leffler.rs\nSpecial functions"]
|
||||
FBM["〰️ mixed_fbm.rs\nFractional Brownian motion"]
|
||||
PY["🐍 python_bindings.rs\nPyO3 bindings"]
|
||||
|
||||
MOD --> K
|
||||
MOD --> H
|
||||
MOD --> ML
|
||||
MOD --> FBM
|
||||
MOD --> PY
|
||||
|
||||
K --> EK["ExponentialKernel\nφ = α·e^−βt"]
|
||||
K --> PLK["PowerLawKernel\nφ = K₀(1+t)^−1−α"]
|
||||
K --> CMK["CompletelyMonotoneKernel\nMittag-Leffler"]
|
||||
|
||||
H --> HP["HawkesProcess K\nunivariate · Ogata thinning"]
|
||||
H --> BH["BivariateHawkes K\nbuy/sell reaction flow"]
|
||||
|
||||
ML --> mf["mittag_leffler · f_alpha_lambda\ngamma · incomplete_gamma"]
|
||||
|
||||
FBM --> fbm1["FractionalBM\nCholesky & Hosking"]
|
||||
FBM --> fbm2["MixedFractionalBM\na·B + b·B^H"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -20,6 +20,7 @@ extensions = [
|
||||
'sphinx.ext.intersphinx',
|
||||
'sphinx.ext.mathjax',
|
||||
'myst_parser',
|
||||
'sphinxcontrib.mermaid',
|
||||
]
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
@@ -76,3 +77,10 @@ myst_enable_extensions = [
|
||||
"deflist",
|
||||
"dollarmath",
|
||||
]
|
||||
|
||||
# Custom CSS
|
||||
html_css_files = ["custom.css"]
|
||||
|
||||
# Mermaid configuration
|
||||
mermaid_version = "10.9.0"
|
||||
mermaid_init_js = "mermaid.initialize({startOnLoad:true, theme:'dark', themeVariables:{primaryColor:'#f97316',primaryTextColor:'#fff',primaryBorderColor:'#ea6a0a',lineColor:'#fb923c',secondaryColor:'#1e293b',tertiaryColor:'#0f172a'}});"
|
||||
|
||||
Reference in New Issue
Block a user