chronax.models.ets.ets

`HUGE_N`

chronax.ets_backend.HUGE_N

Sentinel replacing near-zero denominators in multiplicative ETS formulas.

`NA`

chronax.ets_backend.NA

Legacy sentinel for missing / invalid values; retained for upstream parity.

`TOL`

chronax.ets_backend.TOL

Near-zero guard for conditional branches (e.g. |φ − 1| < TOL).

`Component`

chronax.ets_backend.Component

ETS component type.

Values

Name	Value	Description
`Nothing`	0	No component present.
`Additive`	1	Additive dynamics for trend/season/error.
`Multiplicative`	2	Multiplicative dynamics for trend/season/error.

`Criterion`

chronax.ets_backend.Criterion

Optimization objective to minimize.

Values

Name	Value	Description
`Likelihood`	0	Gaussian log-likelihood proxy used by ETS implementations.
`MSE`	1	One-step mean squared error.
`AMSE`	2	Average MSE across horizons up to `n_mse` (capped at 30).
`Sigma`	3	Mean of squared residuals (variance proxy).
`MAE`	4	Mean absolute error.

`OptimResult`

chronax.ets_backend.OptimResult

Result of the Optax-based optimization.

Attribute	Type	Description
`success`	`bool`	Whether termination was successful under the convergence test.
`status`	`int`	0 for success; 2 for non-finite parameters.
`message`	`str`	Human-readable status message.
`x`	`jnp.ndarray`	Best-found parameter vector.
`fun`	`float`	Objective value at `x`.
`nit`	`int`	Number of iterations performed.
`nfev`	`int`	Number of objective evaluations performed.

`update`

chronax.ets_backend.update

One-step ETS state update.

Mirrors NumPy/statsmodels-like formulas for level l, trend b, and seasonal vector s given previous states (old_l, old_b, old_s), the current observation y, and smoothing parameters.

Parameter	Type	Default	Description
`s`	`jnp.ndarray`	-	current seasonal vector, level, trend (updated in-place conceptually)
`l`	`jnp.float64`	-	current seasonal vector, level, trend (updated in-place conceptually)
`b`	`jnp.float64`	-	current seasonal vector, level, trend (updated in-place conceptually)
`old_l`	`jnp.float64`	-	previous states used for update
`old_b`	`jnp.float64`	-	previous states used for update
`old_s`	`jnp.ndarray`	-	previous states used for update
`m`	`int`	-	Season length; `max(m, 1)` is used in callers.
`trend`	`Component`	-	Structural flags controlling additive/multiplicative behavior.
`season`	`Component`	-	Structural flags controlling additive/multiplicative behavior.
`error`	`int`	-	(undocumented)
`alpha`	`jnp.float64`	-	Smoothing parameters (beta/phi used only if trend present; gamma only if season present).
`beta`	`jnp.float64`	-	Smoothing parameters (beta/phi used only if trend present; gamma only if season present).
`gamma`	`jnp.float64`	-	Smoothing parameters (beta/phi used only if trend present; gamma only if season present).
`phi`	`jnp.float64`	-	Smoothing parameters (beta/phi used only if trend present; gamma only if season present).
`y`	`jnp.float64`	-	Current observation.

Returns: jnp.float64, jnp.float64, jnp.ndarray (updated states l_new, b_new, s_new).

`forecast`

chronax.ets_backend.forecast

Multi-step ETS forecast from a given state.

Builds h forecasts into f using additive/multiplicative trend/season conventions, with special handling when phi ≈ 1.

Parameter	Type	Default	Description
`f`	`jnp.ndarray`	-	Preallocated buffer (length ≥ h) to hold forecasts.
`l`	`jnp.float64`	-	Current level, trend, and seasonal states.
`b`	`jnp.float64`	-	Current level, trend, and seasonal states.
`s`	`jnp.ndarray`	-	Current level, trend, and seasonal states.
`m`	`int`	-	Season length.
`trend`	`Component`	-	Structural flags for trend and seasonality.
`season`	`Component`	-	Structural flags for trend and seasonality.
`phi`	`jnp.float64`	-	Trend damping parameter.
`h`	`jnp.int64`	-	Forecast horizon.

Returns: jnp.ndarray (Same buffer with indices [0..h-1] filled).

`calc_full`

chronax.ets_backend.calc_full

Convenience wrapper that performs a full rollout and returns states.

Parameter	Type	Default	Description
`x`	`jnp.ndarray`	-	Working buffers (see `_calc_roll`). `x` must contain the initial state in its leading slice; this function arranges storage for (n+1) slices.
`e`	`jnp.ndarray`	-	Working buffers (see `_calc_roll`). `x` must contain the initial state in its leading slice; this function arranges storage for (n+1) slices.
`a_mse`	`jnp.ndarray`	-	Working buffers (see `_calc_roll`). `x` must contain the initial state in its leading slice; this function arranges storage for (n+1) slices.
`n_mse`	`int`	-	Horizon cap for rolling MSE metrics (≤30).
`y`	`jnp.ndarray`	-	Observations.
`error`	`Component`	-	Model structure flags.
`trend`	`Component`	-	Model structure flags.
`season`	`Component`	-	Model structure flags.
`alpha`	`jnp.float64`	-	Smoothing parameters.
`beta`	`jnp.float64`	-	Smoothing parameters.
`gamma`	`jnp.float64`	-	Smoothing parameters.
`phi`	`jnp.float64`	-	Smoothing parameters.
`m`	`int`	-	Season length.

Returns: jnp.ndarray, jnp.ndarray, jnp.ndarray, jnp.float64 (Rolling MSEs, One-step residuals, Reshaped state snapshots of shape (n+1, n_states), Likelihood-style objective value).

`calc`

chronax.ets_backend.calc

Compute only the scalar objective (e.g., likelihood) for given parameters.

A thin wrapper over calc_full that discards intermediate arrays and returns the likelihood-style scalar used by Criterion.Likelihood.

Parameter	Type	Default	Description
`x`	`jnp.ndarray`	-	(undocumented)
`e`	`jnp.ndarray`	-	(undocumented)
`a_mse`	`jnp.ndarray`	-	(undocumented)
`n_mse`	`int`	-	(undocumented)
`y`	`jnp.ndarray`	-	(undocumented)
`error`	`Component`	-	(undocumented)
`trend`	`Component`	-	(undocumented)
`season`	`Component`	-	(undocumented)
`alpha`	`jnp.float64`	-	(undocumented)
`beta`	`jnp.float64`	-	(undocumented)
`gamma`	`jnp.float64`	-	(undocumented)
`phi`	`jnp.float64`	-	(undocumented)
`m`	`int`	-	(undocumented)

Returns: jnp.float64 (Objective value for the given parameters and data).

`optimize_bfgs_smoothing`

chronax.ets_backend.optimize_bfgs_smoothing

Two-phase optax optimiser: Adam warm-up → L-BFGS refinement.

Finds the unconstrained parameter vector that minimises the ETS objective selected by opt_crit. The search proceeds in two stages:

Adam warm-up — a short burst of momentum-based first-order steps (15–30 iterations depending on series length) that moves x0 into a reasonable basin.
L-BFGS refinement — 30 quasi-Newton steps compiled via lax.scan into a single XLA kernel for minimal dispatch overhead.

The best parameter vector seen across both phases is returned.

Parameter	Type	Default	Description
`x0`	`jnp.ndarray`	-	Initial unconstrained parameter vector.
`y`	`jnp.ndarray`	-	Observed time series (float64).
`init_state`	`jnp.ndarray`	-	Initial ETS state (level, trend, seasonal).
`error`	`Component`	-	Model structure flags.
`trend`	`Component`	-	Model structure flags.
`season`	`Component`	-	Model structure flags.
`opt_crit`	`Criterion`	-	Which loss to minimise (likelihood, MSE, AMSE, σ², MAE).
`n_mse`	`int`	-	Horizon cap for rolling MSE (≤ 30).
`m`	`int`	-	Seasonal period.
`n_obs`	`int`	-	Active observation count (may be `< len(y)` if padded).
`opt_alpha`	`bool`	-	`True` → optimise the corresponding smoothing parameter; `False` → keep it fixed at the supplied value.
`opt_beta`	`bool`	-	`True` → optimise the corresponding smoothing parameter; `False` → keep it fixed at the supplied value.
`opt_gamma`	`bool`	-	`True` → optimise the corresponding smoothing parameter; `False` → keep it fixed at the supplied value.
`opt_phi`	`bool`	-	`True` → optimise the corresponding smoothing parameter; `False` → keep it fixed at the supplied value.
`alpha`	`float`	-	Current / default values for the four smoothing parameters.
`beta`	`float`	-	Current / default values for the four smoothing parameters.
`gamma`	`float`	-	Current / default values for the four smoothing parameters.
`phi`	`float`	-	Current / default values for the four smoothing parameters.
`lower`	`jnp.ndarray`	-	Box-constraint bounds for smoothing parameters (length 4).
`upper`	`jnp.ndarray`	-	Box-constraint bounds for smoothing parameters (length 4).
`steps`	`int`	-	Total iteration budget (Adam uses a fraction of this).
`lr`	`float`	-	Base learning rate for the Adam warm-up phase.
`clip_norm`	`float`	-	(Unused — kept for caller API compatibility.)
`early_stop_patience`	`int`	`20`	(Unused — `lax.scan` runs a fixed number of iterations.)
`early_stop_min_delta`	`float`	`1e-6`	(Unused — kept for API compatibility.)
`adaptive_tol`	`bool`	`True`	(Unused — kept for API compatibility.)
`is_final_model`	`bool`	`False`	(Unused — kept for API compatibility.)
`clip_multiplicative_errors`	`bool`	`True`	Clamp multiplicative residuals to `[-2, 2]`.
`pure_sigmoid`	`bool`	`False`	Use the cleaner independent sigmoid parameterisation.
`opt_init_state`	`bool`	`False`	If `True`, the tail of `x0` holds optimisable initial states.
`n_state`	`int`	`0`	Number of initial-state parameters appended to `x0`.

Returns: OptimResult (Named tuple with fields success, status, message, x (best params), fun (best loss), nit, nfev).