1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
// Per rules/global_rules.md §Error Handling, unchecked `[]` / slicing is
// banned in production code.
// Unit tests routinely index into `Vec`s they just pushed into, so the lint
// is silenced in `#[cfg(test)]` only.
// Per rules/global_rules.md §Arithmetic, an operator that overflows, divides
// by zero or breaks the `Positive` invariant aborts the caller, so every
// operation on `Decimal`, `Positive` and the integers goes through its
// checked form (#788, #808). `clippy.toml` exempts the unary minus on
// `Decimal`, which cannot overflow. Casts that truncate, wrap or drop the
// sign are denied for the same reason. Unit tests are exempt, as above.
// An error or a default built eagerly in `ok_or` / `unwrap_or` is paid on
// the success path too (#857), so it is built in a closure.
//! # optionstratlib-simulation
//!
//! The simulation engine of OptionStratLib: random walks, stochastic
//! processes, simulators, exit policies and the generic evaluation and
//! statistics of simulated paths. It depends on `optionstratlib-core` and
//! `optionstratlib-pricing`, and on no option chain, strategy, backtesting,
//! plotting, I/O or terminal-presentation code.
//!
//! - [`simulation`]: the stochastic processes ([`simulation::WalkType`]:
//! Brownian, geometric Brownian, log-returns, mean-reverting, jump
//! diffusion, GARCH, Heston, telegraph, custom and historical) and their
//! default kernels ([`simulation::WalkTypeAble`]); walk parameters and
//! steps ([`simulation::WalkParams`], [`simulation::steps::Step`],
//! [`simulation::steps::Xstep`], [`simulation::steps::Ystep`]); the walk
//! driver shared by every generator ([`simulation::walk_steps`],
//! [`simulation::walk_steps_par`], [`simulation::generator_positive`]);
//! [`simulation::randomwalk::RandomWalk`] and
//! [`simulation::simulator::Simulator`]; the Ornstein-Uhlenbeck process
//! ([`simulation::generate_ou_process`]); exit policies
//! ([`simulation::ExitPolicy`], [`simulation::check_exit_policy`]); and the
//! generic path evaluation ([`simulation::PathEvaluator`],
//! [`simulation::PathOutcome`], [`simulation::PathStatistics`],
//! [`simulation::evaluate_paths`]).
//! - [`error`]: [`error::SimulationError`] and [`error::SimulationResult`].
//!
//! Prices along a path are `Positive`, drifts and statistics `Decimal`;
//! `f64` stays inside the kernels, and a non-finite value at an
//! `f64` → `Decimal` boundary is reported as
//! [`error::SimulationError::NonFinite`].
//!
//! The evaluation of a strategy over simulated paths, its statistics report
//! and the charts of a walk stay with the backtesting and visualization
//! layers, which the `optionstratlib` facade provides; the chain and series
//! generators built on these walks are in `optionstratlib-market`, behind
//! its `synthetic` feature.
//!
//! ## Imports
//!
//! There is no prelude, as in the other component crates (ADR-0001 D7): the
//! [`simulation`] module root re-exports the capability, and the
//! `optionstratlib` facade prelude serves broad imports.
//!
//! ## Place in the workspace
//!
//! - **Depends on** `optionstratlib-core` and `optionstratlib-pricing`.
//! - **Must not depend on** `optionstratlib-market`, `-analytics`, `-strategies`,
//! `-backtest` and `-visualization`; `make check-graph` enforces the layering
//! (ADR-0001 D9).
//! - **In the facade:** `optionstratlib::simulation` and `SimulationError` /
//! `SimulationResult` in `optionstratlib::error`, under the facade feature
//! `simulation`. The facade paths are the same types as the paths here; the
//! [ownership
//! map](https://github.com/joaquinbejar/OptionStratLib/blob/main/docs/ownership.md)
//! lists every one with its feature.
//!
//! Moving from 0.21? The [0.22 architecture and adoption
//! guide](https://github.com/joaquinbejar/OptionStratLib/blob/main/docs/migration-0.22.md)
//! maps each redesign to its replacement workflow; 0.22 keeps no
//! compatibility with 0.21.
//!
//! ## Minimal example
//!
//! ```rust
//! use optionstratlib_core::pos_or_panic;
//! use optionstratlib_simulation::simulation::generate_ou_process;
//!
//! // An Ornstein-Uhlenbeck path of 50 steps mean-reverting to 100.
//! let path = generate_ou_process(
//! pos_or_panic!(100.0),
//! pos_or_panic!(100.0),
//! pos_or_panic!(0.5),
//! pos_or_panic!(0.2),
//! pos_or_panic!(0.01),
//! 50,
//! )?;
//! assert_eq!(path.len(), 50);
//! # Ok::<(), optionstratlib_simulation::error::SimulationError>(())
//! ```
//!
//! ## Runnable example
//!
//! A runnable program that depends on this crate directly, with the smallest
//! dependency set and no facade, is [`osl-example-direct-simulation`](https://github.com/joaquinbejar/OptionStratLib/tree/main/examples/direct/simulation); `make tree-example-direct-simulation`
//! asserts its resolved graph.
//!
//! ## Features
//!
//! - `schema` (off by default): derives `utoipa::ToSchema` on the simulation
//! types and enables `schema` in core and pricing.
/// Random walks, stochastic processes, simulators, exit policies and the
/// generic evaluation of simulated paths.
/// Errors raised by the simulation layer.
/// Version of the `optionstratlib-simulation` crate.
pub const VERSION: &str = env!;
/// Compiles the Rust examples of this crate's `README.md` as doctests, so the
/// README cannot drift from the API (#554). Exists only under `cfg(doctest)`.
;