SafeEncoder

benchmark_suite.py.SafeEncoder

JSON encoder that serializes NumPy/JAX scalar and array types.

default(self, obj: Any) -> Any

Convert unsupported numeric objects into JSON-safe values.

Parameter	Type	Default	Description
obj	Any	-	Arbitrary object encountered by JSON serialization.

Returns: Any (JSON-serializable replacement value.) Raises: TypeError (When object cannot be serialized by base encoder.)

BenchmarkLogger

benchmark_suite.py.BenchmarkLogger

In-memory benchmark record collector and CSV writer.

__init__(self, output_dir: str = 'results') -> None

Initialize logger output directory and in-memory record buffer.

Parameter	Type	Default	Description
output_dir	str	"results"	-

log(self, dataset: str, length: int, model: str, time_cold: float, time_warm: float, time_interval: Optional[float] = None, overhead_pct: Optional[float] = None, mape: Optional[float] = None, mae: Optional[float] = None, rmse: Optional[float] = None, mase: Optional[float] = None) -> None

Append one benchmark record to the in-memory log and print a summary line.

Parameter	Type	Default	Description
dataset	str	-	Name or identifier of the dataset (e.g. "Trend", "AirlinePassengers").
length	int	-	Series length (number of observations) for this run.
model	str	-	Model identifier (e.g. "Chronax_ARIMA", "StatsForecast_Naive").
time_cold	float	-	Cold-start runtime in seconds (first run including compile/load).
time_warm	float	-	Warm runtime in seconds (average of repeated runs).
time_interval	Optional[float]	None	Time in seconds for run with prediction intervals.
overhead_pct	Optional[float]	None	Percentage overhead of interval run vs point forecast.
mape	Optional[float]	None	Mean absolute percentage error.
mae	Optional[float]	None	Mean absolute error.
rmse	Optional[float]	None	Root mean squared error.
mase	Optional[float]	None	Mean absolute scaled error.

Returns: None (Mutates self.records and prints to stdout.)

save(self, filename: str = 'benchmark_results.csv') -> pd.DataFrame

Write all accumulated benchmark records to a CSV file and return a DataFrame.

Parameter	Type	Default	Description
filename	str	"benchmark_results.csv"	Name of the CSV file under output_dir; default "benchmark_results.csv".

Returns: pd.DataFrame (DataFrame built from self.records, with columns Dataset, Length, Model, Time_Cold_Sec, Time_Warm_Sec, etc.)

SFWrapper

benchmark_suite.py.SFWrapper

StatsForecast wrapper with lazy imports.

__init__(self, model_cls: Type[Any], model_params: Dict[str, Any], horizon: int, seasonality: int) -> None

Construct a StatsForecast model wrapper with lazy backend import.

Parameter	Type	Default	Description
model_cls	Type[Any]	-	The StatsForecast model class (e.g. Naive, ARIMA).
model_params	Dict[str, Any]	-	Keyword arguments for the model constructor; may be modified for name compatibility.
horizon	int	-	Forecast horizon (number of steps) for subsequent fit_predict calls.
seasonality	int	-	Seasonal period used for parameter mapping and configuration.

fit_predict(self, df: pd.DataFrame, intervals: bool = False) -> pd.DataFrame

Run StatsForecast fit and forecast and return the forecast DataFrame.

Parameter	Type	Default	Description
df	pd.DataFrame	-	Training data with columns unique_id, ds, y.
intervals	bool	False	If True, request 95% prediction intervals; on failure, fall back to point forecast. Default False.

Returns: pd.DataFrame (Forecast output from StatsForecast (point forecasts and optionally interval columns).)

ChronaxWrapper

benchmark_suite.py.ChronaxWrapper

Chronax wrapper with lazy imports.

__init__(self, model_cls: Type[Any], model_params: Dict[str, Any], horizon: int, seasonality: int) -> None

Construct a Chronax model wrapper with lazy JAX import.

Parameter	Type	Default	Description
model_cls	Type[Any]	-	The Chronax forecaster class (e.g. ARIMA, Naive).
model_params	Dict[str, Any]	-	Keyword arguments for the model constructor; may be modified and/or moved to extra_fit_params.
horizon	int	-	Forecast horizon for predict/forecast calls.
seasonality	int	-	Seasonal period used for default params (e.g. AutoETS).

fit_predict(self, y_array: Any, intervals: bool = False) -> Any

Produce point forecasts from the wrapped Chronax model and sync JAX.

Parameter	Type	Default	Description
y_array	Any	-	Training series (JAX array or array-like).
intervals	bool	False	Ignored; kept for signature compatibility with SFWrapper.fit_predict. Default False.

Returns: Any (The "mean" forecast array from the model (typically jnp.ndarray of shape (horizon,)).)

ModelRegistry

benchmark_suite.py.ModelRegistry

Central registry with lazy model loading.

get_chronax_model(name: str) -> Optional[Type[Any]]

Resolve a registered model name to its Chronax class via lazy import.

Parameter	Type	Default	Description
name	str	-	Registered model name; must be a key in _MODELS.

Returns: Optional[Type[Any]] (The Chronax model class, or None if unavailable or not found.)

get_sf_model(name: str) -> Optional[Type[Any]]

Resolve a registered model name to its StatsForecast model class.

Parameter	Type	Default	Description
name	str	-	Registered model name (key in _MODELS).

Returns: Optional[Type[Any]] (The StatsForecast model class, or None.)

get_model_entry(model_name: str) -> Dict[str, Any]

Return the full model entry (Chronax class, StatsForecast class, params) for a name.

Parameter	Type	Default	Description
model_name	str	-	Registered model name; must be a key in _MODELS.

Returns: Dict[str, Any] (Keys "chronax_cls", "sf_cls", "params". Either class may be None if that backend is unavailable.) Raises: ValueError (If model_name is not in _MODELS.)

generate_series

benchmark_suite.py.generate_series

Generate a synthetic univariate time series for benchmarking.

Parameter	Type	Default	Description
series_type	str	-	One of "Trend", "Seasonality", "Stochastic". Any other value raises ValueError.
length	int	-	Number of observations to generate.
seed	int	42	Random seed for reproducibility; default 42.

Returns: np.ndarray (1D float32 array of shape (length,) containing the synthetic series.) Raises: ValueError (If series_type is not "Trend", "Seasonality", or "Stochastic".)

prepare_inputs

benchmark_suite.py.prepare_inputs

Convert a raw numpy time series into Chronax- and StatsForecast-ready inputs.

Parameter	Type	Default	Description
y_array	np.ndarray	-	1D array of training values (any length).
return_jax	bool	True	If True, attempt to build a JAX array for Chronax; if False or JAX unavailable, first element of the return tuple is None. Default True.

Returns: Tuple[Optional[Any], pd.DataFrame] ((jax_input, sf_input). jax_input is a jnp.ndarray or None; sf_input is a DataFrame with unique_id, ds, y.)

calculate_mape

benchmark_suite.py.calculate_mape

Compute Mean Absolute Percentage Error in percentage units (0--100).

Parameter	Type	Default	Description
y_true	np.ndarray	-	Actual (ground truth) values, typically test set.
y_pred	np.ndarray	-	Predicted values; same shape as y_true.

Returns: float (MAPE in percentage units (e.g. 12.5 for 12.5%).)

calculate_mae

benchmark_suite.py.calculate_mae

Compute Mean Absolute Error as a Python float.

Parameter	Type	Default	Description
y_true	np.ndarray	-	Actual values.
y_pred	np.ndarray	-	Predicted values; same shape as y_true.

Returns: float (Mean absolute error in same units as the data.)

calculate_rmse

benchmark_suite.py.calculate_rmse

Compute Root Mean Squared Error as a Python float.

Parameter	Type	Default	Description
y_true	np.ndarray	-	Actual values.
y_pred	np.ndarray	-	Predicted values; same shape as y_true.

Returns: float (RMSE in same units as the data.)

calculate_mase

benchmark_suite.py.calculate_mase

Compute Mean Absolute Scaled Error using in-sample naive forecast.

Parameter	Type	Default	Description
y_true	np.ndarray	-	Actual values (test). Length at least 2.
y_pred	np.ndarray	-	Predicted values; same length as y_true.

Returns: float (MASE value; dimensionless.)

run_single_model

benchmark_suite.py.run_single_model

Execute a single model benchmark for one library and dataset, returning JSON.

Parameter	Type	Default	Description
model_name	str	-	Registered model name (e.g. "ARIMA", "Naive").
library	str	-	Either "chronax" or "statsforecast"; selects wrapper and input format.
dataset_path	str	-	For synthetic: "Trend", "Seasonality", or "Stochastic". For external: path to CSV file.
config	Dict[str, Any]	-	Full benchmark config with "experiment" (horizon, seasonality, n_iterations, scales) and optional "models" list for param overrides.
target_column	Optional[str]	None	If dataset_path is a CSV, optional column name for the target series; otherwise "y" or last column.
forecast_mode	bool	False	If True, return forecast artifact payload (y_train, y_test, predictions, MAPE) for plotting; if False, return standard benchmark metrics (timing, MAPE, MAE, etc.). Default False.

Returns: str (JSON-serialized result. In benchmark mode: Model, Dataset, Length, Time_Cold_Sec, Time_Warm_Sec, Time_Interval_Sec, Interval_Overhead_Pct, MAPE, MAE, RMSE, MASE. In forecast mode: Model, Dataset, Length, y_train, y_test, predictions, MAPE, forecast_mode=True. On error: {"error": ""}. )