> ## Documentation Index
> Fetch the complete documentation index at: https://nixtlaverse.nixtla.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Stochastic Generators
> GARCH, Ornstein-Uhlenbeck, GBM, Jump Diffusion, Poisson, Cyclic, fBm, Hawkes, Stochastic Volatility, Regime Switching, Chaotic System, Bounded Process, and Lévy Process generators
### `GARCHGenerator`
Bases: [BaseGenerator](#synforecast.base.BaseGenerator)
Generate return series from a GARCH(p, q) model.
The model is `r_t = mu + eps_t` with `eps_t = sigma_t * z_t` and
conditional variance
```
sigma2_t = omega + sum_i alpha_i * eps_{t-i}^2
+ sum_j beta_j * sigma2_{t-j}
```
Stationarity requires `sum(alpha) + sum(beta) < 1`, giving an
unconditional variance of `omega / (1 - sum(alpha) - sum(beta))`.
Squared returns are positively autocorrelated (volatility clustering)
while the returns themselves are serially uncorrelated.
**Parameters:**
| Name | Type | Description | Default |
| ------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------- |
| `min_length` | [int](#int) | Minimum length of each series. | *required* |
| `max_length` | [int](#int) | Maximum length of each series. | *required* |
| `freq` | [str](#str) \| [int](#int) | Pandas offset alias (e.g. 'D', 'h', '5min', 'MS') or an integer time step. | *required* |
| `p` | [int](#int) | GARCH order (number of variance lags, default: 1). | *required* |
| `q` | [int](#int) | ARCH order (number of squared-innovation lags, default: 1). | *required* |
| `omega` | [float](#float) | Constant term in the variance equation (default: 0.1). | *required* |
| `alpha` | [list](#list)\[[float](#float)] \| None | ARCH coefficients; auto-generated when None. | *required* |
| `beta` | [list](#list)\[[float](#float)] \| None | GARCH coefficients; auto-generated when None. | *required* |
| `mu` | [float](#float) | Mean of returns (default: 0.0). | *required* |
| `initial_variance` | [float](#float) | Variance used to start the recursion (default: 1.0). A 100-step burn-in removes its influence. | *required* |
| `seed` | [int](#int) \| None | Random seed for reproducibility (default: None). | *required* |
#### `GARCHGenerator.generate_single_series`
```python theme={null}
generate_single_series(length)
```
Generate values for a single GARCH time series.
**Parameters:**
| Name | Type | Description | Default |
| -------- | ------------------------ | ------------------------------------ | ---------- |
| `length` | [int](#int) | The length of the series to generate | *required* |
**Returns:**
| Type | Description |
| -------------------------------------- | --------------------------- |
| [ndarray](#numpy.ndarray) | Array of time series values |
### `OrnsteinUhlenbeckGenerator`
Bases: [BaseGenerator](#synforecast.base.BaseGenerator)
Generate time series from an Ornstein-Uhlenbeck (mean-reverting) process.
The OU process is commonly used to model interest rates, volatility, and
other mean-reverting phenomena:
```
dX_t = theta * (mu - X_t) * dt + sigma * dW_t
```
Simulated with the Euler-Maruyama scheme
`X_t = X_{t-1} + theta * (mu - X_{t-1}) * dt + sigma * sqrt(dt) * z_t`,
where `z_t` are unit-variance draws from `innovation_distribution`.
This is an AR(1) process with coefficient `phi = 1 - theta * dt`,
stationary mean `mu`, stationary variance
`sigma^2 * dt / (1 - phi^2)` (which approaches the continuous-time
`sigma^2 / (2 * theta)` as dt -> 0), and lag-1 autocorrelation `phi`.
Stability requires `theta * dt < 2`. `dt` is the model time per
observation and is independent of `freq`.
**Parameters:**
| Name | Type | Description | Default |
| --------------- | --------------------------------------- | ------------------------------------------------------------------------------------------ | ---------- |
| `min_length` | [int](#int) | Minimum length of each series. | *required* |
| `max_length` | [int](#int) | Maximum length of each series. | *required* |
| `freq` | [str](#str) \| [int](#int) | Pandas offset alias (e.g. 'D', 'h', '5min', 'MS') or an integer for an integer time index. | *required* |
| `theta` | [float](#float) | Speed of mean reversion, must satisfy `theta * dt < 2` (default: 0.5). | *required* |
| `mu` | [float](#float) | Long-term mean (default: 0.0). | *required* |
| `sigma` | [float](#float) | Volatility (default: 1.0). | *required* |
| `initial_value` | [float](#float) | Initial value X\_0 (default: 0.0). | *required* |
| `dt` | [float](#float) | Model time step per observation (default: 1.0). | *required* |
| `seed` | [int](#int) \| None | Random seed for reproducibility (default: None). | *required* |
#### `OrnsteinUhlenbeckGenerator.generate_single_series`
```python theme={null}
generate_single_series(length)
```
Generate values for a single Ornstein-Uhlenbeck time series.
**Parameters:**
| Name | Type | Description | Default |
| -------- | ------------------------ | ------------------------------------- | ---------- |
| `length` | [int](#int) | The length of the series to generate. | *required* |
**Returns:**
| Type | Description |
| -------------------------------------- | ---------------------------- |
| [ndarray](#numpy.ndarray) | Array of time series values. |
### `GeometricBrownianMotionGenerator`
Bases: [BaseGenerator](#synforecast.base.BaseGenerator)
Generate time series from Geometric Brownian Motion.
GBM models strictly positive processes such as asset prices:
```
dS_t = mu * S_t * dt + sigma * S_t * dW_t
```
Simulated via the exact solution of the SDE,
`S_t = S_{t-1} * exp((mu - sigma^2/2) * dt + sigma * sqrt(dt) * z_t)`,
where `z_t` are unit-variance draws from `innovation_distribution`
(exact for normal innovations). `dt` is the model time per observation
and is independent of `freq`: with annualized `mu`/`sigma`, daily
observations correspond to `dt=1/252`. Note that the default
`dt=1.0` treats `mu` and `sigma` as per-step rates; long series
with a large `mu * dt` grow explosively.
**Parameters:**
| Name | Type | Description | Default |
| --------------- | --------------------------------------- | ------------------------------------------------------------------------------------------ | ---------- |
| `min_length` | [int](#int) | Minimum length of each series. | *required* |
| `max_length` | [int](#int) | Maximum length of each series. | *required* |
| `freq` | [str](#str) \| [int](#int) | Pandas offset alias (e.g. 'D', 'h', '5min', 'MS') or an integer for an integer time index. | *required* |
| `mu` | [float](#float) | Drift per unit of model time (default: 0.05). | *required* |
| `sigma` | [float](#float) | Volatility per sqrt unit of model time (default: 0.2). | *required* |
| `initial_value` | [float](#float) | Initial value S\_0, must be > 0 (default: 100.0). | *required* |
| `dt` | [float](#float) | Model time step per observation (default: 1.0). | *required* |
| `seed` | [int](#int) \| None | Random seed for reproducibility (default: None). | *required* |
#### `GeometricBrownianMotionGenerator.generate_single_series`
```python theme={null}
generate_single_series(length)
```
Generate values for a single Geometric Brownian Motion time series.
**Parameters:**
| Name | Type | Description | Default |
| -------- | ------------------------ | ------------------------------------- | ---------- |
| `length` | [int](#int) | The length of the series to generate. | *required* |
**Returns:**
| Type | Description |
| -------------------------------------- | ---------------------------- |
| [ndarray](#numpy.ndarray) | Array of time series values. |
### `JumpDiffusionGenerator`
Bases: [BaseGenerator](#synforecast.base.BaseGenerator)
Generate time series from a jump diffusion process (Merton model).
Combines Geometric Brownian Motion with discontinuous jumps from a
compound Poisson process, commonly used for asset prices with rare
events:
```
dS_t = mu * S_t * dt + sigma * S_t * dW_t + S_{t-} * dJ_t
```
Each step multiplies the price by
`exp((mu - sigma^2/2) * dt + sigma * sqrt(dt) * z_t + sum_k Y_k)` with
`N_t ~ Poisson(lambda_jump * dt)` jumps of log-size
`Y_k = jump_mean + jump_std * eps_k`. Both `z_t` and `eps_k` are
unit-variance draws from `innovation_distribution` (normal by default,
giving Merton's log-normal jumps). The drift is not compensated for
jumps, so the expected log-return per step is
`(mu - sigma^2/2) * dt + lambda_jump * dt * jump_mean`. `dt` is the
model time per observation and is independent of `freq`.
**Parameters:**
| Name | Type | Description | Default |
| --------------- | --------------------------------------- | ------------------------------------------------------------------------------------------ | ---------- |
| `min_length` | [int](#int) | Minimum length of each series. | *required* |
| `max_length` | [int](#int) | Maximum length of each series. | *required* |
| `freq` | [str](#str) \| [int](#int) | Pandas offset alias (e.g. 'D', 'h', '5min', 'MS') or an integer for an integer time index. | *required* |
| `mu` | [float](#float) | Drift per unit of model time (default: 0.05). | *required* |
| `sigma` | [float](#float) | Diffusion volatility (default: 0.2). | *required* |
| `lambda_jump` | [float](#float) | Jump intensity, expected jumps per unit of model time (default: 0.1). | *required* |
| `jump_mean` | [float](#float) | Mean jump size in log-price (default: 0.0). | *required* |
| `jump_std` | [float](#float) | Std of jump size in log-price (default: 0.1). | *required* |
| `initial_value` | [float](#float) | Initial value S\_0, must be > 0 (default: 100.0). | *required* |
| `dt` | [float](#float) | Model time step per observation (default: 1.0). | *required* |
| `seed` | [int](#int) \| None | Random seed for reproducibility (default: None). | *required* |
#### `JumpDiffusionGenerator.generate_single_series`
```python theme={null}
generate_single_series(length)
```
Generate values for a single jump diffusion time series.
**Parameters:**
| Name | Type | Description | Default |
| -------- | ------------------------ | ------------------------------------- | ---------- |
| `length` | [int](#int) | The length of the series to generate. | *required* |
**Returns:**
| Type | Description |
| -------------------------------------- | ---------------------------- |
| [ndarray](#numpy.ndarray) | Array of time series values. |
### `PoissonProcessGenerator`
Bases: [BaseGenerator](#synforecast.base.BaseGenerator)
Generate time series based on a homogeneous Poisson process.
Each observation is the event count in one time step:
y\_t \~ Poisson(lambda\_rate), i.i.d., so mean and variance both equal
lambda\_rate. With cumulative=True the running total N(t) = sum y\_s is
returned instead (the counting process itself). lambda\_rate is
expressed per time step of `freq`.
**Parameters:**
| Name | Type | Description | Default |
| ------------- | --------------------------------------- | ---------------------------------------------------- | ---------- |
| `min_length` | [int](#int) | Minimum length of each series | *required* |
| `max_length` | [int](#int) | Maximum length of each series | *required* |
| `freq` | [str](#str) \| [int](#int) | Frequency of the data (e.g. 'D', 'h', '5min') or int | *required* |
| `lambda_rate` | [float](#float) | Expected events per time step (default: 5.0) | *required* |
| `cumulative` | [bool](#bool) | Return cumulative counts (default: False) | *required* |
| `seed` | [int](#int) \| None | Random seed for reproducibility (default: None) | *required* |
#### `PoissonProcessGenerator.generate_single_series`
```python theme={null}
generate_single_series(length)
```
Generate values for a single Poisson Process time series.
**Parameters:**
| Name | Type | Description | Default |
| -------- | ------------------------ | ------------------------------------ | ---------- |
| `length` | [int](#int) | The length of the series to generate | *required* |
**Returns:**
| Type | Description |
| -------------------------------------- | ---------------------------------------------------- |
| [ndarray](#numpy.ndarray) | Array of time series values (counts per time period) |
### `CyclicGenerator`
Bases: [BaseGenerator](#synforecast.base.BaseGenerator)
Generate time series with irregular cyclic patterns.
Models business cycles and economic indicators: a linear trend plus
`num_cycles` superposed sinusoids whose periods and amplitudes are
drawn once per series (period \~ |N(period\_mean, period\_std)|,
amplitude \~ N(amplitude\_mean, amplitude\_std)), plus additive noise drawn
from the configured `innovation_distribution`.
Each sinusoid's instantaneous frequency is slowly modulated (+-20%
around 2\*pi/period, integrated as a cumulative phase), so cycle
lengths vary within a series, unlike regular seasonal patterns.
**Parameters:**
| Name | Type | Description | Default |
| ---------------------- | ---------------------------- | ---------------------------------------------------- | ---------- |
| `base_level` | [float](#float) | Base level of the series (default: 100.0). | *required* |
| `trend` | [float](#float) | Linear trend coefficient per step (default: 0.0). | *required* |
| `cycle_period_mean` | [float](#float) | Mean cycle period in steps (default: 50.0). | *required* |
| `cycle_period_std` | [float](#float) | Std of the per-series period draw (default: 10.0). | *required* |
| `cycle_amplitude_mean` | [float](#float) | Mean cycle amplitude (default: 20.0). | *required* |
| `cycle_amplitude_std` | [float](#float) | Std of the per-series amplitude draw (default: 5.0). | *required* |
| `num_cycles` | [int](#int) | Number of superposed cycle components (default: 3). | *required* |
| `noise_std` | [float](#float) | Standard deviation of additive noise (default: 1.0). | *required* |
#### `CyclicGenerator.generate_single_series`
```python theme={null}
generate_single_series(length)
```
Generate values for a single time series with irregular cycles.
**Parameters:**
| Name | Type | Description | Default |
| -------- | ------------------------ | ------------------------------------ | ---------- |
| `length` | [int](#int) | The length of the series to generate | *required* |
**Returns:**
| Type | Description |
| -------------------------------------- | --------------------------- |
| [ndarray](#numpy.ndarray) | Array of time series values |
### `FractionalBrownianMotionGenerator`
Bases: [BaseGenerator](#synforecast.base.BaseGenerator)
Generate time series using Fractional Brownian Motion (fBm).
fBm extends standard Brownian motion with a Hurst exponent H that
controls long-range dependence:
* H = 0.5: standard Brownian motion (independent increments)
* H > 0.5: persistent/trending (positively correlated increments)
* H \< 0.5: anti-persistent/mean-reverting (negatively correlated)
The increments (fractional Gaussian noise, fGn) are stationary with
autocovariance `gamma(k) = (sigma^2/2) * (|k+1|^{2H} - 2|k|^{2H} +
|k-1|^{2H})`, and the path satisfies `Var(B_H(t)) = sigma^2 * t^{2H}`.
Warning
The 'cholesky' and 'hosking' methods have O(n^2) memory (an n x n
covariance matrix); prefer the default 'fft' (Davies-Harte) method
for long series.
**Parameters:**
| Name | Type | Description | Default |
| ------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------- | ---------- |
| `hurst` | [float](#float) | Hurst exponent H in (0, 1) (default: 0.5). | *required* |
| `sigma` | [float](#float) | Volatility/scale of the increments (default: 1.0). | *required* |
| `method` | [str](#str) | Generation method: 'fft' (O(n log n), default), 'cholesky' or 'hosking' (both exact, O(n^2) memory). | *required* |
| `return_increments` | [bool](#bool) | Return fGn increments instead of the cumulative fBm path (default: False). | *required* |
| `initial_value` | [float](#float) | Starting value of the fBm path; ignored when return\_increments=True (default: 0.0). | *required* |
Example
> > > gen = FractionalBrownianMotionGenerator(
> > > ... min\_length=100,
> > > ... max\_length=200,
> > > ... freq="D",
> > > ... hurst=0.8, # H > 0.5: trending
> > > ... seed=42,
> > > ... )
> > > df = gen.generate(n\_series=10)
#### `FractionalBrownianMotionGenerator.generate_single_series`
```python theme={null}
generate_single_series(length)
```
Generate a single fBm series.
**Parameters:**
| Name | Type | Description | Default |
| -------- | ------------------------ | ------------------------------------- | ---------- |
| `length` | [int](#int) | The length of the series to generate. | *required* |
**Returns:**
| Type | Description |
| -------------------------------------- | --------------------------------------------------------------- |
| [ndarray](#numpy.ndarray) | fBm path values (or fGn increments if return\_increments=True). |
#### `FractionalBrownianMotionGenerator.get_model_info`
```python theme={null}
get_model_info()
```
Return model parameters and qualitative behavior.
#### `FractionalBrownianMotionGenerator.estimate_hurst`
```python theme={null}
estimate_hurst(series, method='rs')
```
Estimate the Hurst exponent from an increment (fGn) series.
**Parameters:**
| Name | Type | Description | Default |
| -------- | -------------------------------------- | -------------------------------------------------------- | ----------------- |
| `series` | [ndarray](#numpy.ndarray) | Time series of increments. | *required* |
| `method` | [str](#str) | 'rs' (rescaled range) or 'var' (variance of aggregates). | 'rs' |
**Returns:**
| Type | Description |
| ---------------------------- | --------------------------------------------------- |
| [float](#float) | Estimated Hurst exponent, clipped to \[0.01, 0.99]. |
### `HawkesProcessGenerator`
Bases: [BaseGenerator](#synforecast.base.BaseGenerator)
Generate time series using Hawkes (self-exciting) point processes.
Hawkes processes model events where past occurrences increase the
probability of future events. The conditional intensity at time t is:
```
lambda(t) = mu + sum_{t_i <= t} g(t - t_i)
```
with baseline intensity mu and excitation kernel g. Supported kernels:
```
- exponential: g(t) = alpha * exp(-beta * t), branching ratio
n = alpha / beta
- power_law: g(t) = alpha / (1 + beta * t)^p with p > 1, branching
ratio n = alpha / (beta * (p - 1))
```
Stability requires n \< 1; the long-run event rate is then mu / (1 - n)
events per time step, and each event spawns on average 1 / (1 - n)
events (itself included) in its cluster. Time is measured in steps of
`freq`, so mu and beta are per-step quantities.
Applications: order arrivals in high-frequency trading, earthquake
aftershock sequences, viral cascades, clustered fraud events.
**Parameters:**
| Name | Type | Description | Default |
| ---------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `min_length` | [int](#int) | Minimum length of each series | *required* |
| `max_length` | [int](#int) | Maximum length of each series | *required* |
| `freq` | [str](#str) \| [int](#int) | Frequency of the data (e.g. 'D', 'h', '5min') or int | *required* |
| `baseline_intensity` | [float](#float) | Background event rate mu per time step (default: 1.0) | *required* |
| `excitation_amplitude` | [float](#float) | Jump in intensity per event alpha (default: 0.5) | *required* |
| `decay_rate` | [float](#float) | Rate of intensity decay beta (default: 1.0) | *required* |
| `kernel` | [str](#str) | Excitation kernel, 'exponential' or 'power\_law' (default: 'exponential') | *required* |
| `power_law_exponent` | [float](#float) | Exponent p for the power-law kernel, must be > 1 (default: 1.5) | *required* |
| `output_type` | [str](#str) | 'counts' (events per bin), 'intensity' (lambda at bin midpoints), or 'events' (0/1 indicator per bin) (default: 'counts') | *required* |
| `max_events` | [int](#int) | Maximum events to simulate per series (default: 10000) | *required* |
| `seed` | [int](#int) \| None | Random seed for reproducibility (default: None) | *required* |
Example
> > > gen = HawkesProcessGenerator(
> > > ... min\_length=100,
> > > ... max\_length=200,
> > > ... freq="h",
> > > ... baseline\_intensity=0.5,
> > > ... excitation\_amplitude=0.3,
> > > ... decay\_rate=2.0,
> > > ... seed=42,
> > > ... )
> > > df = gen.generate(n\_series=10)
#### `HawkesProcessGenerator.generate_single_series`
```python theme={null}
generate_single_series(length)
```
Generate values for a single Hawkes process series.
**Parameters:**
| Name | Type | Description | Default |
| -------- | ------------------------ | ------------------------------------ | ---------- |
| `length` | [int](#int) | The length of the series to generate | *required* |
**Returns:**
| Type | Description |
| -------------------------------------- | ------------------------------------------------------- |
| [ndarray](#numpy.ndarray) | Array of values (counts, intensity, or event indicator) |
#### `HawkesProcessGenerator.simulate_with_events`
```python theme={null}
simulate_with_events(time_horizon)
```
Simulate and return both event times and intensity at those times.
**Parameters:**
| Name | Type | Description | Default |
| -------------- | ---------------------------- | ---------------------- | ---------- |
| `time_horizon` | [float](#float) | Total time to simulate | *required* |
**Returns:**
| Type | Description |
| ----------------------------------------------------------------------------------- | ------------------------------------- |
| [tuple](#tuple)\[[ndarray](#numpy.ndarray), [ndarray](#numpy.ndarray)] | (event\_times, intensity\_at\_events) |
#### `HawkesProcessGenerator.get_model_info`
```python theme={null}
get_model_info()
```
Get information about the Hawkes process model.
**Returns:**
| Type | Description |
| -------------------------- | ------------------------------------ |
| [dict](#dict) | Model parameters and characteristics |
#### `HawkesProcessGenerator.estimate_parameters`
```python theme={null}
estimate_parameters(event_times, _method='mle')
```
Estimate Hawkes process parameters from observed event times.
Heuristic moment-based estimation: the coefficient of variation of
inter-arrival times proxies the branching ratio (CV = 1 for a
Poisson process, larger under clustering), and the mean rate
identifies mu via rate = mu / (1 - n).
**Parameters:**
| Name | Type | Description | Default |
| ------------- | -------------------------------------- | -------------------------------------------------- | ------------------ |
| `event_times` | [ndarray](#numpy.ndarray) | Array of observed event times | *required* |
| `_method` | [str](#str) | Estimation method (currently only 'mle' supported) | 'mle' |
**Returns:**
| Type | Description |
| -------------------------- | -------------------- |
| [dict](#dict) | Estimated parameters |
### `StochasticVolatilityGenerator`
Bases: [BaseGenerator](#synforecast.base.BaseGenerator)
Generate time series where volatility itself follows a stochastic process.
Heston model (variance is mean-reverting square-root/CIR):
```
dS = mu * S dt + sqrt(V) * S dW1
dV = kappa * (theta - V) dt + sigma_v * sqrt(V) dW2
Corr(dW1, dW2) = rho
```
SABR model (for rates/FX):
```
dF = sigma * F^beta dW1
dsigma = alpha * sigma dW2
Corr(dW1, dW2) = rho
```
Both are simulated with Euler-Maruyama; the Heston variance uses a
truncation scheme (floored at a small positive value) so the discretized
variance stays positive even when the Feller condition
`2 * kappa * theta > sigma_v^2` is violated. Negative `rho` produces
the leverage effect (volatility rises when prices fall).
**Parameters:**
| Name | Type | Description | Default |
| -------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------- |
| `min_length` | [int](#int) | Minimum length of each series. | *required* |
| `max_length` | [int](#int) | Maximum length of each series. | *required* |
| `freq` | [str](#str) \| [int](#int) | Pandas offset alias (e.g. 'D', 'h', '5min') or an integer time step. | *required* |
| `model` | [str](#str) | 'heston' or 'sabr' (default: 'heston'). | *required* |
| `initial_price` | [float](#float) | Starting price S0 (default: 100.0). | *required* |
| `initial_vol` | [float](#float) | Starting variance V0; SABR uses sqrt(initial\_vol) as its starting volatility sigma0 (default: 0.04). | *required* |
| `drift` | [float](#float) | Price drift mu (default: 0.05). | *required* |
| `mean_vol` | [float](#float) | Long-run variance theta (Heston only, default: 0.04). | *required* |
| `vol_mean_reversion` | [float](#float) | Variance mean-reversion speed kappa (Heston only, default: 2.0). | *required* |
| `vol_of_vol` | [float](#float) | Volatility of volatility sigma\_v (Heston) or alpha (SABR) (default: 0.3). | *required* |
| `correlation` | [float](#float) | Price-volatility correlation rho in \[-1, 1] (default: -0.7). | *required* |
| `beta` | [float](#float) | CEV exponent in \[0, 1] (SABR only; 0=normal, 1=lognormal, default: 0.5). | *required* |
| `dt` | [float](#float) | Time step for discretization (default: 1/252). | *required* |
| `output_type` | [str](#str) | 'price', 'returns' (log returns), or 'volatility' (default: 'price'). | *required* |
| `seed` | [int](#int) \| None | Random seed for reproducibility (default: None). | *required* |
Example
> > > gen = StochasticVolatilityGenerator(
> > > ... min\_length=252,
> > > ... max\_length=252,
> > > ... freq="D",
> > > ... model="heston",
> > > ... initial\_price=100.0,
> > > ... correlation=-0.7, # Leverage effect
> > > ... seed=42,
> > > ... )
> > > df = gen.generate(n\_series=10)
#### `StochasticVolatilityGenerator.generate_single_series`
```python theme={null}
generate_single_series(length)
```
Generate values for a single stochastic volatility series.
**Parameters:**
| Name | Type | Description | Default |
| -------- | ------------------------ | ------------------------------------ | ---------- |
| `length` | [int](#int) | The length of the series to generate | *required* |
**Returns:**
| Type | Description |
| -------------------------------------- | ----------------------------------------------- |
| [ndarray](#numpy.ndarray) | Array of values (price, returns, or volatility) |
#### `StochasticVolatilityGenerator.generate_with_volatility`
```python theme={null}
generate_with_volatility(n_series=1, start_id=0)
```
Generate series and return both prices and volatility paths.
**Parameters:**
| Name | Type | Description | Default |
| ---------- | ------------------------ | ------------------------------------------ | -------------- |
| `n_series` | [int](#int) | Number of series to generate (default: 1) | 1 |
| `start_id` | [int](#int) | Starting ID for series naming (default: 0) | 0 |
**Returns:**
| Type | Description |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| [tuple](#tuple)\[[ndarray](#numpy.ndarray), [ndarray](#numpy.ndarray), [ndarray](#numpy.ndarray)] | (prices, volatilities, series\_ids) arrays |
#### `StochasticVolatilityGenerator.get_model_info`
```python theme={null}
get_model_info()
```
Get information about the stochastic volatility model.
**Returns:**
| Type | Description |
| -------------------------- | ------------------------------------ |
| [dict](#dict) | Model parameters and characteristics |
#### `StochasticVolatilityGenerator.implied_volatility_smile`
```python theme={null}
implied_volatility_smile(strikes, maturity=1.0)
```
Approximate implied volatility smile for given strikes.
Uses the Hagan SABR approximation formula (valid for the SABR model;
a rough approximation for Heston).
**Parameters:**
| Name | Type | Description | Default |
| ---------- | -------------------------------------- | ------------------------- | ---------------- |
| `strikes` | [ndarray](#numpy.ndarray) | Array of strike prices | *required* |
| `maturity` | [float](#float) | Time to maturity in years | 1.0 |
**Returns:**
| Type | Description |
| -------------------------------------- | ----------------------------- |
| [ndarray](#numpy.ndarray) | Array of implied volatilities |
### `RegimeSwitchingGenerator`
Bases: [BaseGenerator](#synforecast.base.BaseGenerator)
Generate time series with Markov regime-switching dynamics.
A hidden regime s\_t follows a first-order Markov chain with transition
matrix P (rows sum to 1). Conditional on the regime, values follow an
AR(1) around the regime mean:
```
y_t = mu_{s_t} + phi_{s_t} * (y_{t-1} - mu_{s_t}) + sigma_{s_t} * eps_t
```
When no initial regime is given, s\_0 is drawn from the stationary
distribution pi of P (pi = pi P), so long-run regime occupancy matches pi.
**Parameters:**
| Name | Type | Description | Default | | |
| ------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------- | ------------------ | ---------- |
| `min_length` | [int](#int) | Minimum length of each series. | *required* | | |
| `max_length` | [int](#int) | Maximum length of each series. | *required* | | |
| `freq` | [str](#str) \| [int](#int) | Pandas offset alias (e.g. 'D', 'h', '5min') or an integer time step. | *required* | | |
| `n_regimes` | [int](#int) | Number of regimes/states (default: 2). | *required* | | |
| `regime_means` | [list](#list)\[[float](#float)] \| None | Mean per regime (default: spread across levels). | *required* | | |
| `regime_variances` | [list](#list)\[[float](#float)] \| None | Variance per regime (default: linspace(0.5, 2.0)). | *required* | | |
| `regime_ar_coeffs` | [list](#list)\[[float](#float)] \| None | AR(1) coefficient per regime, each | phi | \< 1 (default: 0). | *required* |
| `transition_matrix` | [list](#list)\[[list](#list)\[[float](#float)]] \| None | Row-stochastic regime transition matrix (default: 0.95 self-transition probability). | *required* | | |
| `initial_regime` | [int](#int) \| None | Starting regime, 0-indexed (default: drawn from the stationary distribution). | *required* | | |
| `seed` | [int](#int) \| None | Random seed for reproducibility (default: None). | *required* | | |
Example
> > > gen = RegimeSwitchingGenerator(
> > > ... min\_length=100,
> > > ... max\_length=200,
> > > ... freq="D",
> > > ... n\_regimes=2,
> > > ... regime\_means=\[0.0, 5.0],
> > > ... regime\_variances=\[1.0, 4.0],
> > > ... transition\_matrix=\[\[0.95, 0.05], \[0.10, 0.90]],
> > > ... seed=42,
> > > ... )
> > > df = gen.generate(n\_series=10)
#### `RegimeSwitchingGenerator.generate_single_series`
```python theme={null}
generate_single_series(length)
```
Generate values for a single regime-switching time series.
**Parameters:**
| Name | Type | Description | Default |
| -------- | ------------------------ | ------------------------------------ | ---------- |
| `length` | [int](#int) | The length of the series to generate | *required* |
**Returns:**
| Type | Description |
| -------------------------------------- | --------------------------- |
| [ndarray](#numpy.ndarray) | Array of time series values |
#### `RegimeSwitchingGenerator.generate_with_regimes`
```python theme={null}
generate_with_regimes(n_series=1, start_id=0)
```
Generate series and return both values and regime labels.
**Parameters:**
| Name | Type | Description | Default |
| ---------- | ------------------------ | ------------------------------------------ | -------------- |
| `n_series` | [int](#int) | Number of series to generate (default: 1) | 1 |
| `start_id` | [int](#int) | Starting ID for series naming (default: 0) | 0 |
**Returns:**
| Type | Description |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| [tuple](#tuple)\[[ndarray](#numpy.ndarray), [ndarray](#numpy.ndarray), [ndarray](#numpy.ndarray)] | (values, regimes, series\_ids) arrays |
#### `RegimeSwitchingGenerator.get_model_info`
```python theme={null}
get_model_info()
```
Get information about the regime-switching model.
**Returns:**
| Type | Description |
| -------------------------- | ------------------------------------ |
| [dict](#dict) | Model parameters and characteristics |
### `ChaoticSystemGenerator`
Bases: [BaseGenerator](#synforecast.base.BaseGenerator)
Generate time series from deterministic chaotic dynamical systems.
Produces series that look stochastic but are fully deterministic given
the initial condition; randomness enters only through a seeded
perturbation of the initial condition and optional observation noise.
Systems
* lorenz: Lorenz attractor `x' = sigma(y-x), y' = x(rho-z) - y,
z' = xy - beta*z`, integrated with RK4 and sampled every
1/dt steps (one time unit per observation); the x-component is
returned.
* logistic: Logistic map `x_{n+1} = r * x_n * (1 - x_n)`
(chaotic for r \~ 3.57..4; for r=4 the invariant density is
Beta(1/2, 1/2)).
* mackey\_glass: Mackey-Glass delay differential equation
`x' = beta * x(t-tau) / (1 + x(t-tau)^n) - gamma * x`,
Euler-integrated with unit step (chaotic for tau >= 17 at the
default parameters).
**Parameters:**
| Name | Type | Description | Default |
| ---------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------- | ---------- |
| `system` | [str](#str) | 'lorenz', 'logistic' or 'mackey\_glass' (default: 'lorenz'). | *required* |
| `sigma` | [float](#float) | Lorenz sigma (default: 10.0). | *required* |
| `rho` | [float](#float) | Lorenz rho (default: 28.0). | *required* |
| `beta_param` | [float](#float) | Lorenz beta, alias 'lorenz\_beta' (default: 2.6667). | *required* |
| `dt` | [float](#float) | Lorenz RK4 integration step (default: 0.01). | *required* |
| `logistic_r` | [float](#float) | Logistic map parameter r (default: 3.9). | *required* |
| `mg_beta` | [float](#float) | Mackey-Glass beta (default: 0.2). | *required* |
| `mg_gamma` | [float](#float) | Mackey-Glass gamma (default: 0.1). | *required* |
| `mg_n` | [float](#float) | Mackey-Glass exponent n (default: 10.0). | *required* |
| `mg_tau` | [int](#int) | Mackey-Glass delay tau (default: 17). | *required* |
| `observation_noise` | [float](#float) | Std of additive Gaussian observation noise (default: 0.0). | *required* |
| `initial_perturbation` | [float](#float) | Scale of the random initial-condition perturbation; 0 makes the output seed-independent (default: 0.01). | *required* |
#### `ChaoticSystemGenerator.generate_single_series`
```python theme={null}
generate_single_series(length)
```
Generate a single chaotic time series.
**Parameters:**
| Name | Type | Description | Default |
| -------- | ------------------------ | ------------------------------------- | ---------- |
| `length` | [int](#int) | The length of the series to generate. | *required* |
**Returns:**
| Type | Description |
| -------------------------------------- | ---------------------------- |
| [ndarray](#numpy.ndarray) | Array of time series values. |
#### `ChaoticSystemGenerator.get_model_info`
```python theme={null}
get_model_info()
```
Return information about the chaotic system configuration.
### `BoundedProcessGenerator`
Bases: [BaseGenerator](#synforecast.base.BaseGenerator)
Generate time series constrained to a bounded interval.
Values are simulated on the unit interval and affinely mapped to
\[lower, upper] (default \[0, 1]). Useful for proportions, market shares,
probabilities, and other bounded quantities.
Models
* beta\_ar: Beta AR(1) via conditional mean parameterization.
mu\_t = omega + phi \* x\_\{t-1}, x\_t \~ Beta(mu\_t \* kappa,
(1 - mu\_t) \* kappa), so E\[x\_t | x\_\{t-1}] = mu\_t and the stationary
mean is omega / (1 - phi).
* logit\_normal: AR(1) on the logit scale, sigmoid-transformed back:
z\_t = phi \* z\_\{t-1} + sigma \* eps\_t, x\_t = sigmoid(z\_t).
**Parameters:**
| Name | Type | Description | Default |
| --------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------- |
| `min_length` | [int](#int) | Minimum length of each series. | *required* |
| `max_length` | [int](#int) | Maximum length of each series. | *required* |
| `freq` | [str](#str) \| [int](#int) | Pandas offset alias (e.g. 'D', 'h', '5min') or an integer time step. | *required* |
| `model` | [str](#str) | 'beta\_ar' or 'logit\_normal' (default: 'beta\_ar'). | *required* |
| `phi` | [float](#float) | AR coefficient in \[-1, 1] (default: 0.8). | *required* |
| `omega` | [float](#float) | Intercept of the beta\_ar conditional mean (default: 0.1). Must satisfy 0 \< omega + phi \* x \< 1 for x in (0, 1). | *required* |
| `kappa` | [float](#float) | Beta precision; larger = less noise (default: 20.0). | *required* |
| `sigma` | [float](#float) | Logit-scale innovation std (logit\_normal only, default: 0.3). | *required* |
| `initial_value` | [float](#float) | Starting value on the unit scale, in (0, 1) (default: 0.5). | *required* |
| `lower` | [float](#float) | Lower bound of the output interval (default: 0.0). | *required* |
| `upper` | [float](#float) | Upper bound of the output interval (default: 1.0). | *required* |
| `seed` | [int](#int) \| None | Random seed for reproducibility (default: None). | *required* |
#### `BoundedProcessGenerator.generate_single_series`
```python theme={null}
generate_single_series(length)
```
Generate a single bounded time series.
**Parameters:**
| Name | Type | Description | Default |
| -------- | ------------------------ | ------------------------------------ | ---------- |
| `length` | [int](#int) | The length of the series to generate | *required* |
**Returns:**
| Type | Description |
| -------------------------------------- | ---------------------------------------------- |
| [ndarray](#numpy.ndarray) | Array of time series values in \[lower, upper] |
#### `BoundedProcessGenerator.get_model_info`
```python theme={null}
get_model_info()
```
Return information about the bounded process configuration.
### `LevyProcessGenerator`
Bases: [BaseGenerator](#synforecast.base.BaseGenerator)
Generate time series with alpha-stable (Levy) increments.
Each observation step adds an independent increment
`scale * X + location` where `X ~ S(alpha, beta_skew; 1)` is a
standard alpha-stable random variable in the S1 parameterization
(matching `scipy.stats.levy_stable`), sampled with the
Chambers-Mallows-Stuck algorithm. For `alpha < 2` the increments have
infinite variance, producing extreme jumps far beyond Gaussian or
t-distributed innovations. There is no separate `dt`: `scale` is the
per-step scale (a step of duration `dt` in model time corresponds to
`scale ~ dt**(1/alpha)` by self-similarity).
Special cases
* `alpha=2`: Gaussian with standard deviation `scale * sqrt(2)`
* `alpha=1, beta_skew=0`: Cauchy
* `alpha=0.5, beta_skew=1`: Levy distribution
**Parameters:**
| Name | Type | Description | Default |
| --------------- | --------------------------------------- | ------------------------------------------------------------------------------------------ | ---------- |
| `min_length` | [int](#int) | Minimum length of each series. | *required* |
| `max_length` | [int](#int) | Maximum length of each series. | *required* |
| `freq` | [str](#str) \| [int](#int) | Pandas offset alias (e.g. 'D', 'h', '5min', 'MS') or an integer for an integer time index. | *required* |
| `alpha` | [float](#float) | Stability index in (0, 2] (default: 1.5). | *required* |
| `beta_skew` | [float](#float) | Skewness parameter in \[-1, 1] (default: 0.0). | *required* |
| `scale` | [float](#float) | Scale of each increment (default: 1.0). | *required* |
| `location` | [float](#float) | Location shift of each increment (default: 0.0). | *required* |
| `cumulative` | [bool](#bool) | Return the cumulative sum (Levy flight) instead of raw increments (default: True). | *required* |
| `initial_value` | [float](#float) | Starting value for cumulative mode (default: 0.0). | *required* |
| `seed` | [int](#int) \| None | Random seed for reproducibility (default: None). | *required* |
#### `LevyProcessGenerator.generate_single_series`
```python theme={null}
generate_single_series(length)
```
Generate a single Levy process time series.
**Parameters:**
| Name | Type | Description | Default |
| -------- | ------------------------ | ------------------------------------- | ---------- |
| `length` | [int](#int) | The length of the series to generate. | *required* |
**Returns:**
| Type | Description |
| -------------------------------------- | ---------------------------- |
| [ndarray](#numpy.ndarray) | Array of time series values. |
#### `LevyProcessGenerator.get_model_info`
```python theme={null}
get_model_info()
```
Return information about the Levy process configuration.