mloopforml 1.0.0

Neural network surrogate hyperparameter optimization via a simple decorator

mloopforml

Neural network surrogate hyperparameter optimization via a simple decorator.

Install

pip install mloopforml

Quickstart

import mloopforml as mloop

@mloop.optimize(
    params={"lr": (1e-4, 1e-1), "dropout": (0.0, 0.5)},
    max_iterations=50,
    direction="minimize",   # or "maximize"
    seed=42,
)
def train(lr, dropout):
    # Replace with your actual training loop
    # Return a single float (lower is better when direction="minimize")
    loss = some_model.train(lr=lr, dropout=dropout)
    return loss

result = train()

print(result.best_params)   # {'lr': 0.0042, 'dropout': 0.12}
print(result.best_score)    # 0.237

mloopforml uses M-LOOP's neural network surrogate to propose new parameter combinations. The decorator handles the optimization loop — your function just returns a number.

Parameters

Parameter	Type	Default	Description
params	dict[str, (float, float)]	required	Hyperparameter name → (min, max) bounds
max_iterations	int	50	Total number of trials
direction	str	"minimize"	"minimize" or "maximize"
num_training_runs	int	1	Bootstrap trials before the NN surrogate activates
seed	int | None	None	Random seed for reproducible runs

Result

Calling the decorated function returns an OptimizeResult:

result.best_params   # dict[str, float] — best parameter combination found
result.best_score    # float — best objective value
result.all_params    # list[dict] — all trial params, in order
result.all_costs     # list[float] — all trial scores (nan for failed trials)

Requirements

• Python >=3.11
• numpy >=2.0
• scipy >=1.15

License

MIT