OptiRoulette-Keras (Torch Backend)

This package accompanies the paper "OptiRoulette Optimizer: A New Stochastic Meta-Optimizer for up to 5.3x Faster Convergence".

A standalone, pip-installable Keras meta-optimizer that brings OptiRoulette's training logic to Keras compile/fit flows:

• random optimizer switching
• warmup -> roulette phase handling
• optimizer pool with active/backup swapping
• compatibility-aware replacement
• learning-rate scaling rules when switching
• momentum/state transfer on swap

The default behavior is loaded from the bundled optimized.yaml profile.

Research Highlights

Based on the current paper draft, OptiRoulette is a stochastic meta-optimizer that combines:

• warmup optimizer locking
• randomized sampling from an active optimizer pool
• compatibility-aware LR scaling during optimizer transitions
• failure-aware pool replacement

Reported mean test accuracy vs a single-optimizer AdamW baseline:

Additional paper-reported highlights:

• Target-hit reliability: in the reported 10-seed suites, OptiRoulette reaches key validation targets in 10/10 runs, while the AdamW baseline reaches none of those targets within budget.
• Faster time-to-target on shared milestones (example: Caltech-256 @ 0.59, 25.7 vs 77.0 epochs), with budget-capped lower-bound speedups up to 5.3x for non-attained baseline targets.
• Paired-seed analysis is positive across datasets, except CIFAR-100-C test ROC-AUC, which is not statistically significant in the current 10-seed study.

Important: the metrics above are from the current OptiRoulette paper draft (PyTorch experiment suite), not from a full Keras multi-seed validation.

Status

OptiRoulette-Keras is currently an experimental / pre-release package. It has not yet been validated through full scientific multi-seed experiment suites.

Backend Requirement

You must use Keras with the torch backend:

export KERAS_BACKEND=torch

Set this before importing keras.

Install

pip install OptiRoulette-Keras

Examples

• CIFAR-100 Keras demo notebook
• Tiny-ImageNet Keras demo notebook
• Both notebooks use pure keras.layers model definitions.

Quick Use (compile/fit)

import os
os.environ["KERAS_BACKEND"] = "torch"

import keras
from optiroulette_keras import create_roulette_callback

model = keras.Sequential([
    keras.layers.Input(shape=(32, 32, 3)),
    keras.layers.Conv2D(32, 3, activation="relu"),
    keras.layers.GlobalAveragePooling2D(),
    keras.layers.Dense(100),
])

# If you do not pass arguments, bundled optimized.yaml defaults are used
# (optimizers, roulette, pool, LR rules, seed fallback).
# Advanced optimizers (e.g. ranger, adan) are resolved via pytorch-optimizer adapter.
controller, roulette_cb = create_roulette_callback()
# Note: this call is still required. Without it, there is no OptiRoulette switching.
# verbose levels:
# 0 -> no OptiRoulette output (default)
# 1 -> print only active optimizer
# 2 -> include all OptiRoulette metrics in fit/progbar logs

model.compile(
    optimizer=controller.active_optimizer,
    loss=keras.losses.SparseCategoricalCrossentropy(from_logits=True),
    metrics=["accuracy"],
)
model.fit(train_loader, validation_data=val_loader, epochs=10, callbacks=[roulette_cb])

Custom arguments example:

controller, roulette_cb = create_roulette_callback(
    optimizer_specs={
        "adam": {"learning_rate": 1e-3},
        "adamw": {"learning_rate": 1e-3, "weight_decay": 0.01},
        "sgd": {"learning_rate": 5e-2, "momentum": 0.9, "nesterov": True},
    },
    roulette={"warmup_epochs": 0, "warmup_optimizer": None, "warmup_config": {}},
    switch_granularity="epoch",
)

If you do not pass these arguments, defaults from bundled optimized.yaml are used.

API

from optiroulette_keras import (
    OptiRoulette,
    OptiRouletteOptimizer,
    OptiRouletteCallback,
    create_roulette_callback,
    PoolConfig,
    ensure_torch_backend,
    get_default_config,
    get_default_seed,
    get_default_optimizer_specs,
    get_default_pool_setup,
    get_default_roulette_config,
)

Package Layout

This folder is a standalone PyPI package inside the same repository:

• packages/optiroulette-keras/pyproject.toml
• packages/optiroulette-keras/src/optiroulette_keras/*
• packages/optiroulette-keras/tests/*

Build

From this folder:

python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*