Trait WalkTypeAble

Source

pub trait WalkTypeAble<X, Y>:
    WalkTypeAbleClone<X, Y>
    + Send
    + Syncwhere
    X: Copy + TryInto<Positive> + AddAssign + Display,
    Y: TryInto<Positive> + Display + Clone,{
Show 16 methods    // Provided methods
    fn generate(
        &self,
        params: &WalkParams<X, Y>,
    ) -> Result<Vec<Positive>, SimulationError> { ... }
    fn generate_with_vol(
        &self,
        params: &WalkParams<X, Y>,
    ) -> Result<WalkPath, SimulationError> { ... }
    fn brownian(
        &self,
        params: &WalkParams<X, Y>,
    ) -> Result<Vec<Positive>, SimulationError> { ... }
    fn geometric_brownian(
        &self,
        params: &WalkParams<X, Y>,
    ) -> Result<Vec<Positive>, SimulationError> { ... }
    fn log_returns(
        &self,
        params: &WalkParams<X, Y>,
    ) -> Result<Vec<Positive>, SimulationError> { ... }
    fn mean_reverting(
        &self,
        params: &WalkParams<X, Y>,
    ) -> Result<Vec<Positive>, SimulationError> { ... }
    fn jump_diffusion(
        &self,
        params: &WalkParams<X, Y>,
    ) -> Result<Vec<Positive>, SimulationError> { ... }
    fn garch(
        &self,
        params: &WalkParams<X, Y>,
    ) -> Result<Vec<Positive>, SimulationError> { ... }
    fn garch_with_vol(
        &self,
        params: &WalkParams<X, Y>,
    ) -> Result<WalkPath, SimulationError> { ... }
    fn heston(
        &self,
        params: &WalkParams<X, Y>,
    ) -> Result<Vec<Positive>, SimulationError> { ... }
    fn heston_with_vol(
        &self,
        params: &WalkParams<X, Y>,
    ) -> Result<WalkPath, SimulationError> { ... }
    fn custom(
        &self,
        params: &WalkParams<X, Y>,
    ) -> Result<Vec<Positive>, SimulationError> { ... }
    fn custom_with_vol(
        &self,
        params: &WalkParams<X, Y>,
    ) -> Result<WalkPath, SimulationError> { ... }
    fn telegraph(
        &self,
        params: &WalkParams<X, Y>,
    ) -> Result<Vec<Positive>, SimulationError> { ... }
    fn telegraph_with_vol(
        &self,
        params: &WalkParams<X, Y>,
    ) -> Result<WalkPath, SimulationError> { ... }
    fn historical(
        &self,
        params: &WalkParams<X, Y>,
    ) -> Result<Vec<Positive>, SimulationError> { ... }
}

Expand description

Trait for implementing various random walk models and stochastic processes.

This trait provides methods to generate different types of stochastic processes commonly used in financial modeling, time series analysis, and simulation studies. Each method implements a specific type of random walk based on the parameters provided.

The trait is generic over types X and Y, which represent the x-axis (typically time) and y-axis (typically price or value) components respectively.

§Type Parameters

X - The type for the x-axis values (typically time), must be Copy, convertible to Positive, implement AddAssign, and implement Display.
Y - The type for the y-axis values (typically price), must be Copy, convertible to Positive, and implement Display.

§Methods

The trait provides methods for generating the following stochastic processes:

Brownian motion (standard random walk)
Geometric Brownian motion
Log returns process with optional autocorrelation
Mean reverting (Ornstein-Uhlenbeck) process
Jump diffusion process
GARCH (Generalized Autoregressive Conditional Heteroskedasticity)
Heston stochastic volatility model
Custom stochastic process with mean-reverting volatility

§Object safety and cloning

WalkTypeAble is object-safe: you can hold it behind Box<dyn WalkTypeAble<X, Y>> (e.g., inside WalkParams). The super-trait WalkTypeAbleClone provides an object-safe clone_box hook that Box<dyn WalkTypeAble<X, Y>>: Clone delegates to. Concrete walkers must therefore implement WalkTypeAbleClone — a blanket impl covers every T: WalkTypeAble<X, Y> + Clone + 'static, so in practice it is enough to add #[derive(Clone)] to your walker struct and the object-safe clone path works automatically.

Walkers that cannot be Clone may implement WalkTypeAbleClone::clone_box by hand, but doing so is rarely necessary.

§Seeding

Every default walk method (and the public kernels garch_walk, heston_walk, custom_walk, telegraph_walk) reads WalkParams::seed: Some(seed) draws the whole path from optionstratlib_core::utils::deterministic_rng(seed), so it is reproducible bit for bit; None draws from the thread RNG. A walker that overrides a method and draws its own randomness should do the same with optionstratlib_core::model::decimal::decimal_normal_sample_with to keep seeded runs reproducible.

§Thread safety

A walker is Send + Sync: crate::simulation::simulator::Simulator::new builds its walks on the rayon pool, each walk on a clone of the shared WalkParams, so the boxed walker crosses threads (#860). Keep any interior state behind Arc, an atomic or a Mutex, not Rc or RefCell.

§Output contract

The walk generators (generator_optionchain, generator_positive, generator_optionseries) treat the FIRST element of a walker’s output as a duplicate of the initial value and skip it. A walker may return an empty vector or a single element; the generators then yield only the initial step. Returning fewer than params.size values is allowed and simply shortens the walk.

Provided Methods§

Source

fn generate( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

Dispatches to the walk method matching params.walk_type.

This is the single authoritative variant→method dispatch: generators call generate instead of matching on WalkType themselves, so adding a new walk variant only requires extending the enum and this trait — no generator changes.

§Parameters

params - Walk parameters; params.walk_type selects the process.

§Returns

Result<Vec<Positive>, SimulationError> - The generated path, per the contract of the selected walk method.

§Errors

Propagates the error of the dispatched walk method (see each method’s documentation).

Source

fn generate_with_vol( &self, params: &WalkParams<X, Y>, ) -> Result<WalkPath, SimulationError>

Like WalkTypeAble::generate, but also exposes the per-step volatility path for walk types whose volatility varies over time.

For the stochastic-volatility variants (Garch, Heston, Custom, Telegraph) the returned WalkPath::vols carries the ANNUALIZED volatility prevailing at each step, aligned index-by-index with WalkPath::prices. For every other variant vols is None — the constant volatility is available via WalkType::volatility, and Historical per-step estimates are the caller’s concern (see simulation::walk_steps).

§Note for implementors

The price-path methods (garch, heston, custom, telegraph) and their *_with_vol siblings are BOTH backed by the same built-in kernels (garch_walk, heston_walk, custom_walk, telegraph_walk) but are independent override points: overriding one never changes the other’s default. Consumers that need the vol path (the walk generators) call generate_with_vol, so a walker overriding a price-path method MUST override the matching *_with_vol method too — typically by wrapping its own dynamics, or by composing the public kernel — otherwise the generators will keep using the built-in dynamics.

§Errors

Propagates the error of the dispatched walk method.

Source

fn brownian( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

Generates a Brownian motion (standard random walk) process.

Brownian motion is a continuous-time stochastic process where changes are normally distributed with a drift term and volatility.

§Parameters

params - Walk parameters including initial value, time step, drift, and volatility.

§Returns

Result<Vec<Positive>, SimulationError> - A vector of positive values representing the generated Brownian motion path, or an error if parameters are invalid.

§Errors

Returns SimulationError::InvalidWalkType when params.walk_type is not a WalkType::Brownian variant, and propagates SimulationError::PositiveError from params.ystep_as_positive()? when the initial y value violates the Positive invariant.

Generated samples are clamped with Positive::new_decimal(x.max(Decimal::ZERO)) .unwrap_or(Positive::ZERO), so negative realisations do not surface an error - they are replaced by Positive::ZERO.

Source

fn geometric_brownian( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

Generates a Geometric Brownian motion process.

Geometric Brownian motion is a continuous-time stochastic process where the logarithm of the randomly varying quantity follows Brownian motion. It’s commonly used to model stock prices in the Black-Scholes options pricing model.

§Parameters

params - Walk parameters including initial value, time step, drift, and volatility.

§Returns

Result<Vec<Positive>, SimulationError> - A vector of positive values representing the generated Geometric Brownian motion path, or an error if parameters are invalid.

§Errors

Returns SimulationError::InvalidWalkType when params.walk_type is not a WalkType::GeometricBrownian variant, and SimulationError::PositiveError when a generated sample underflows below zero.

Source

fn log_returns( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

Generates a Log Returns process, potentially with autocorrelation.

This process models returns (percentage changes) directly, rather than absolute values, and can include autocorrelation to capture the tendency of returns to be influenced by previous returns.

§Parameters

params - Walk parameters including initial value, time step, expected return, volatility, and optional autocorrelation coefficient.

§Returns

Result<Vec<Positive>, SimulationError> - A vector of positive values representing the generated Log Returns path, or an error if parameters are invalid.

§Errors

Returns SimulationError::InvalidWalkType when params.walk_type is not a WalkType::LogReturns variant, SimulationError::InvalidAutocorrelation when the autocorrelation coefficient is outside [-1, 1], and SimulationError::PositiveError when the exponentiated sample underflows below zero.

Source

fn mean_reverting( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

Generates a Mean Reverting (Ornstein-Uhlenbeck) process.

The Ornstein-Uhlenbeck process models a value that tends to drift toward a long-term mean, with the strength of the reversion proportional to the distance from the mean. It’s commonly used for interest rates, volatility, and other mean-reverting financial variables.

§Parameters

params - Walk parameters including initial value, mean level, reversion speed, volatility, and time step.

§Returns

Result<Vec<Positive>, SimulationError> - A vector of positive values representing the generated Mean Reverting path, or an error if parameters are invalid.

§Errors

Returns SimulationError::InvalidWalkType when params.walk_type is not a WalkType::MeanReverting variant, and SimulationError::PositiveError when an intermediate sample breaches the Positive invariant.

Source

fn jump_diffusion( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

Generates a Jump Diffusion process.

Jump Diffusion combines continuous Brownian motion with discrete jumps that occur according to a Poisson process. This model is useful for capturing sudden market movements like crashes or spikes that standard Brownian motion cannot adequately model.

§Parameters

params - Walk parameters including initial value, drift, volatility, jump intensity, jump mean size, and jump volatility.

§Returns

Result<Vec<Positive>, SimulationError> - A vector of positive values representing the generated Jump Diffusion path, or an error if parameters are invalid.

§Errors

Returns SimulationError::InvalidWalkType when params.walk_type is not a WalkType::JumpDiffusion variant, and SimulationError::PositiveError when a jumped sample underflows below zero.

Source

fn garch( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

Generates a GARCH (Generalized Autoregressive Conditional Heteroskedasticity) process.

GARCH models time-varying volatility clustering, where periods of high volatility tend to be followed by high volatility, and low volatility by low volatility.

§Parameters

params - Walk parameters for the GARCH process.

§Returns

Result<Vec<Positive>, SimulationError> - A vector of positive values representing the generated GARCH path, or an error if parameters are invalid.

§Note

This implementation is currently a placeholder and returns an empty vector.

§Errors

Returns SimulationError::InvalidWalkType when params.walk_type is not a WalkType::Garch variant, SimulationError::GarchStationarity when alpha + beta ≥ 1 (the recurrence is non-stationary), and SimulationError::PositiveError when an intermediate variance breaches the Positive invariant.

Source

fn garch_with_vol( &self, params: &WalkParams<X, Y>, ) -> Result<WalkPath, SimulationError>

GARCH(1,1) walk that also exposes the simulated conditional-volatility path.

Same dynamics as WalkTypeAble::garch; vols[i] is the ANNUALIZED conditional volatility sqrt(var_t) that generated prices[i] (vols[0] is the initial volatility parameter).

§Errors

Same as WalkTypeAble::garch.

Source

fn heston( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

Generates a Heston stochastic volatility model.

The Heston model extends Geometric Brownian Motion by allowing the volatility itself to be a stochastic process, following a mean-reverting square-root process.

§Parameters

params - Walk parameters for the Heston process.

§Returns

Result<Vec<Positive>, SimulationError> - A vector of positive values representing the generated Heston model path, or an error if parameters are invalid.

§Note

This implementation is currently a placeholder and returns an empty vector. Generates a Heston stochastic volatility model.

The Heston model extends Geometric Brownian Motion by allowing the volatility itself to be a stochastic process, following a mean-reverting square-root process.

§Parameters

params - Walk parameters for the Heston process, including:
- dt: Time step
- drift: Drift coefficient for the price process
- v0: Initial variance
- kappa: Mean reversion speed for variance
- theta: Long-term variance mean level
- xi: Volatility of variance
- rho: Correlation between price and variance Brownian motions

§Returns

Result<Vec<Positive>, SimulationError> - A vector of positive values representing the generated Heston model path, or an error if parameters are invalid.

§Notes

The Heston model is described by the following SDEs: dS_t = μS_t dt + √v_t S_t dW^1_t dv_t = κ(θ - v_t) dt + ξ√v_t dW^2_t with dW^1_t dW^2_t = ρ dt

§Errors

Returns SimulationError::InvalidWalkType when params.walk_type is not a WalkType::Heston variant, SimulationError::InvalidCorrelation when rho is outside [-1, 1], and SimulationError::PositiveError when an intermediate price or variance breaches the Positive invariant.

Source

fn heston_with_vol( &self, params: &WalkParams<X, Y>, ) -> Result<WalkPath, SimulationError>

Heston walk that also exposes the simulated volatility path.

Same dynamics as WalkTypeAble::heston; vols[i] is the ANNUALIZED instantaneous volatility sqrt(v_t) prevailing after the step that produced prices[i] (vols[0] is the initial volatility parameter).

§Errors

Same as WalkTypeAble::heston.

Source

fn custom( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

Generates a custom stochastic process with mean-reverting volatility.

This implements a process where the underlying value follows Brownian motion, but with volatility that follows an Ornstein-Uhlenbeck (mean-reverting) process. This allows for modeling more complex dynamics than standard models.

§Parameters

params - Walk parameters including drift, initial volatility, volatility of volatility (vov), volatility mean reversion speed, volatility mean level, and time step.

§Returns

Result<Vec<Positive>, SimulationError> - A vector of positive values representing the generated custom process path, or an error if parameters are invalid.

§Errors

Returns SimulationError::InvalidWalkType when params.walk_type is not a WalkType::Custom variant, SimulationError::InsufficientHistoricalData when the provided calibration sample is too small for the requested process order, and SimulationError::PositiveError when a generated sample violates the Positive invariant.

Source

fn custom_with_vol( &self, params: &WalkParams<X, Y>, ) -> Result<WalkPath, SimulationError>

Custom (mean-reverting volatility) walk that also exposes the Ornstein-Uhlenbeck volatility path that drove the prices.

Same dynamics as WalkTypeAble::custom; vols[i] is the ANNUALIZED OU volatility used to generate prices[i] (vols[0] is the initial volatility parameter).

§Errors

Same as WalkTypeAble::custom.

Source

fn telegraph( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

Generates a Telegraph process (two-state regime switching model).

The Telegraph process alternates between two states (+1 and -1) with specified transition rates, affecting the volatility of the price path. This model captures regime-switching behavior in financial markets where volatility can suddenly change between high and low regimes.

§Parameters

params - Walk parameters including initial value, drift, base volatility, transition rates, and optional volatility multipliers for each state.

§Returns

Result<Vec<Positive>, SimulationError> - A vector of positive values representing the generated Telegraph process path, or an error if parameters are invalid.

§Errors

Returns SimulationError::InvalidWalkType when params.walk_type is not a WalkType::Telegraph variant, and SimulationError::PositiveError when an intermediate sample breaches the Positive invariant.

Source

fn telegraph_with_vol( &self, params: &WalkParams<X, Y>, ) -> Result<WalkPath, SimulationError>

Telegraph (two-state regime switching) walk that also exposes the regime-dependent volatility path.

Same dynamics as WalkTypeAble::telegraph; vols[i] is the ANNUALIZED regime volatility (base volatility times the active regime’s multiplier) used to generate prices[i] (vols[0] is the base volatility parameter).

§Errors

Same as WalkTypeAble::telegraph.

Source

fn historical( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

Generates a historical walk based on the given parameters.

This function processes the historical walk by extracting a specified number of elements from the provided price data (prices) based on the size defined in params.

§Parameters

self: Reference to the instance of the object.
params: A reference to WalkParams<X, Y> containing the configuration details for the walk.
- Expected to have a walk_type of WalkType::Historical with associated timeframe and price data.
- params.size determines the number of historical prices to include in the result.

§Returns

Ok(Vec<Positive>): A vector containing the first params.size elements from the given price data (prices), if there are at least params.size elements available.
Err(Box<dyn Error>): If the walk_type is not WalkType::Historical or if the provided price data does not contain enough elements to fulfill the requested size (params.size).

§Errors

Returns an error if:
- The walk_type in params is not WalkType::Historical.
- The prices do not contain at least params.size elements.

Trait Implementations§

Source §

impl<X, Y> Clone for Box<dyn WalkTypeAble<X, Y>>
where X: Copy + TryInto<Positive> + AddAssign + Display, Y: TryInto<Positive> + Display + Clone,

Source §

fn clone(&self) -> Self

Returns a duplicate of the value. Read more

1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more

Source §

impl<X, Y> Debug for Box<dyn WalkTypeAble<X, Y>>

Source §

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

WalkTypeAble

Trait WalkTypeAble Copy item path

§Type Parameters

§Methods

§Object safety and cloning

§Seeding

§Thread safety

§Output contract

Provided Methods§

fn generate( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

§Parameters

§Returns

§Errors

fn generate_with_vol( &self, params: &WalkParams<X, Y>, ) -> Result<WalkPath, SimulationError>

§Note for implementors

§Errors

fn brownian( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

§Parameters

§Returns

§Errors

fn geometric_brownian( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

§Parameters

§Returns

§Errors

fn log_returns( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

§Parameters

§Returns

§Errors

fn mean_reverting( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

§Parameters

§Returns

§Errors

fn jump_diffusion( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

§Parameters

§Returns

§Errors

fn garch( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

§Parameters

§Returns

§Note

§Errors

fn garch_with_vol( &self, params: &WalkParams<X, Y>, ) -> Result<WalkPath, SimulationError>

§Errors

fn heston( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

§Parameters

§Returns

§Note

§Parameters

§Returns

§Notes

§Errors

fn heston_with_vol( &self, params: &WalkParams<X, Y>, ) -> Result<WalkPath, SimulationError>

§Errors

fn custom( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

§Parameters

§Returns

§Errors

fn custom_with_vol( &self, params: &WalkParams<X, Y>, ) -> Result<WalkPath, SimulationError>

§Errors

fn telegraph( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

§Parameters

§Returns

§Errors

fn telegraph_with_vol( &self, params: &WalkParams<X, Y>, ) -> Result<WalkPath, SimulationError>

§Errors

fn historical( &self, params: &WalkParams<X, Y>, ) -> Result<Vec<Positive>, SimulationError>

§Parameters

§Returns

§Errors

Trait Implementations§

impl<X, Y> Clone for Box<dyn WalkTypeAble<X, Y>>where X: Copy + TryInto<Positive> + AddAssign + Display, Y: TryInto<Positive> + Display + Clone,

fn clone(&self) -> Self

fn clone_from(&mut self, source: &Self)

impl<X, Y> Debug for Box<dyn WalkTypeAble<X, Y>>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Dyn Compatibility§

Implementors§

Trait WalkTypeAble

impl<X, Y> Clone for Box<dyn WalkTypeAble<X, Y>>
where X: Copy + TryInto<Positive> + AddAssign + Display, Y: TryInto<Positive> + Display + Clone,