Skip to main content

OmniOpt2

OmniOpt2 is a highly parallel hyperparameter optimizer for Linux, SLURM clusters, and local workstations. It explores a parameter search space, runs your program with the proposed parameters, reads a result from its output, and uses Ax/BoTorch, Optuna, or other generators to decide what to try next.

OmniOpt2 is program-agnostic: your program can be Python, C, R, a shell script, a simulation, or anything else that runs on Linux. It only needs to

  1. accept parameters on the command line, and
  2. print a result line such as RESULT: 0.123.

Contents

Highlights

  • GUI and CLI: build a complete omniopt command in the browser or use the CLI directly.
  • SLURM and local execution: workers run as SLURM jobs when sbatch is available, otherwise locally through submitit's local executor.
  • HPC-ready environment handling: automatic Lmod/Load-Modules detection, optional per-evaluation --modules and --venv, and automatic re-exec/bootstrap with the right Python.
  • Many generators: BoTorch GP (BOTORCH_MODULAR), SAASBO, mixed-variable BO, Sobol, factorial/grid search, random search, random forest, external generators, TPE, and Optuna samplers including multi-objective ones.
  • Multi-objective optimization: multiple --result_names, Pareto fronts, optional OCC (optimization with combined criteria), and constraints.
  • Formula mode: optimize a mathematical expression directly with --formula (LaTeX or Python-style infix) instead of a run script.
  • Robust runs: checkpoints, continuation, state files, orchestrator hooks, automatic exclusion of defective GPU nodes, and actionable diagnostics for failed evaluations.
  • Results and sharing: CSV results, interactive plots, terminal graphics, OmniOpt2-Share, and optional live sharing.

Installation

OmniOpt2 is self-installing. The first run creates a virtual environment under ~/.omniax_venvs/<python-version>/<architecture> and installs its dependencies there. Later runs reuse it. Use --root_venv_dir=/path to choose a different base directory.

Run directly from the repository

git clone https://github.com/NormanTUD/OmniOpt.git
cd OmniOpt
./omniopt --help
./omniopt --install    # bootstrap dependencies and exit

Install with pip

The PyPI version is the released version:

pip3 install omniopt2
omniopt --help

The bleeding-edge version from Git:

pip3 install "git+https://github.com/NormanTUD/OmniOpt.git"

Docker

./omniopt_docker
./omniopt_docker omniopt --tests

The current directory is mounted inside the container. In the GUI, the run mode can be switched to Docker. Docker is intended for local use and is not supported on the HPC systems.

Requirements

  • Linux
  • python3
  • Optional: SLURM (sbatch, squeue, ...)
  • Optional: an Lmod/Environment Modules installation (ml, module)
  • Optional: Docker
  • System packages listed in apt-dependencies.txt

Quick Start

GUI

Open the OmniOpt2 GUI, fill in the experiment, copy the generated command, and run it on the login node or locally. The GUI also documents every option and can produce a reproducible configuration.

CLI

./omniopt \
    --experiment_name=example \
    --mem_gb=1 \
    --time=60 \
    --worker_timeout=60 \
    --max_eval=100 \
    --num_parallel_jobs=4 \
    --num_random_steps=10 \
    --gpus=0 \
    --model=BOTORCH_MODULAR \
    --result_names RESULT=min \
    --parameter x range 0 10 float \
    --run_program="$(printf '%s' 'bash ./run.sh --x=%(x)' | base64 -w0)" \
    --follow \
    --force_local_execution

Remove --force_local_execution and add --partition=<name> to run on SLURM. --run_program is Base64-encoded so spaces, quotes, and newlines survive shell parsing. The GUI generates this automatically.

A minimal run.sh:

#!/bin/bash
# $@ contains --x=<value>
python3 train.py "$@"

The program must print a result that OmniOpt2 can parse:

RESULT: 0.12345

Use --result_names LOSS=min ACCURACY=max for multiple objectives and --occ for optimization with combined criteria. Without an explicit min/max, minimizing is assumed. See the run.sh tutorial and the results.csv documentation.

Parameters and search space

--parameter learning_rate range 0.0001 0.5 float
--parameter epochs choice 1,10,20,50,100
--parameter layers fixed 10
--parameter dropout range 0 0.8 float true

Range parameters support explicit log scaling. Fixed parameters are passed to the program but do not consume search dimensions. Use --experiment_constraints for linear constraints such as a + b <= 10. See the constraints tutorial.

Models

The current model list is available with ./omniopt --help and includes:

  • BOTORCH_MODULAR (default BoTorch GP)
  • SAASBO, BO_MIXED
  • SOBOL, FACTORIAL, UNIFORM, PSEUDORANDOM
  • RANDOMFOREST
  • TPE
  • EXTERNAL_GENERATOR
  • OPTUNA_TPE, OPTUNA_CMAES, OPTUNA_GP, OPTUNA_RANDOM, OPTUNA_GRID, OPTUNA_QMC, OPTUNA_BruteForce, OPTUNA_NSGAII, OPTUNA_NSGAIII, OPTUNA_MOTPE

See the surrogate models tutorial for guidance on choosing a model. Custom Ax generation strategies can be passed with --generation_strategy (see the custom generation strategy tutorial), and external optimizers can be connected with --model=EXTERNAL_GENERATOR and --external_generator=<program>.

Formula mode

Instead of a run program, you can optimize an equation:

./omniopt \
    --experiment_name=formula_example \
    --formula 'x**2 + y**2' \
    --formula_mode=infix \
    --parameter x range -10 10 float \
    --parameter y range -10 10 float \
    --max_eval=50 --num_random_steps=10 --mem_gb=1 --time=30 \
    --result_names RESULT=min --force_local_execution

LaTeX and Python-style infix are supported. See the formula tutorial.

HPC, SLURM, Lmod, and Virtual Environments

When sbatch is available, OmniOpt2 submits the main process as a SLURM job unless --force_local_execution is set. Workers are scheduled through submitit. Common SLURM options include:

--partition=alpha --account=<account> --reservation=<name> \
--gpus=1 --cpus_per_task=4 --nodes_per_job=1 \
--time=120 --worker_timeout=30 --num_parallel_jobs=20 \
--dependency=afterok:<jobid> --follow --auto_exclude_defective_hosts

--dependency=omniopt_singleton serializes OmniOpt2 jobs with the same name. --wait_until_ended waits for the submitted main job and prints its log.

Lmod modules per evaluation

Use --modules to load Lmod modules in every evaluation. This replaces a run.sh that only does module load ...; python3 ....

--modules='ml release/24.10 GCCcore/13.3.0 Python/3.12.3'

All of these are accepted and mean the same thing:

release/24.10 GCCcore/13.3.0 Python/3.12.3
module release/24.10 GCCcore/13.3.0 Python/3.12.3
ml release/24.10 GCCcore/13.3.0 Python/3.12.3
module load release/24.10 GCCcore/13.3.0 Python/3.12.3

Multiple lines are allowed. On systems without Lmod, OmniOpt2 prints a warning and continues without loading the modules. Modules are checked before the main SLURM job is submitted, so a typo is reported immediately on the login node. A failing module load is reported as a red, actionable error and OmniOpt2 exits with code 35. See the TU Dresden module documentation for release and toolchain examples.

Virtualenv per evaluation

Use --venv to activate a virtualenv inside every evaluation:

--venv=/path/to/venv

The order is always:

modules -> virtualenv -> run program

Use --workdir=/path if relative paths in your run program should resolve from a specific directory instead of the one where OmniOpt2 was started. Use --run_program_once for setup steps that should run once before the search.

--venv may point to the virtualenv directory or directly to its bin/activate script. The main OmniOpt2 process is not affected. A missing or broken virtualenv is reported inside the evaluation with exit code 36 and an actionable message.

Both --modules and --venv are stored in the run's state files and restored when continuing a run. See the virtualenv tutorial.

Automatic Lmod handling

OmniOpt2 also detects Lmod automatically to build its own virtual environment with the cluster's Python/toolchain. Set LOAD_MODULES=0 to disable the automatic cluster toolchain snippet. Set OMNIOPT_INSTALL_DEBUG=1 for a detailed installer trace (detected Lmod commands, Python candidates, venv rebuilds, pip attempts).

Optuna

omniopt_optuna exposes Optuna samplers through OmniOpt2:

# Single-objective TPE
omniopt_optuna run --max-eval=20 --parameter 'x range -10 10 int' \
    --run-program 'echo "RESULT: %(x)"'

# Multi-objective NSGA-II
omniopt_optuna run --model=OPTUNA_NSGAII --max-eval=30 \
    --result-names RESULT1=min RESULT2=max \
    --parameter 'x range 0 5 float' \
    --run-program 'echo "RESULT1: %(x)"; echo "RESULT2: %(x)"'

Persistent studies and remote control:

omniopt_optuna study create --workdir runs/my_study --sampler=tpe
omniopt_optuna study add --workdir runs/my_study --params-file p.json \
    --values '{"RESULT": 3.5}'
omniopt_optuna study suggest --workdir runs/my_study --parameters-file spec.json

See the Optuna tutorial.

Configuration Files and Continuation

OmniOpt2 is CLI-first, but it can also read YAML, JSON, or TOML:

./omniopt --config_yaml config.yaml
./omniopt --config_json config.json
./omniopt --config_toml config.toml

Use --dump_config to write the effective configuration.

Continue a previous run with:

./omniopt --continue runs/my_experiment/0

State files and run.sh are written into the run directory. See the continue tutorial and the folder structure.

For custom recovery behavior, --orchestrator_file can react to errors in the worker output (restart, exclude a node, etc.). See the orchestrator tutorial.

Results, Plots, Evaluation, and Sharing

Each run stores its results and state under runs/<experiment>/<number>/ by default (use --run_dir to change the base directory). The main result file is results.csv.

# Plot a finished run
omniopt_plot --run_dir runs/example/0
omniopt_plot --run_dir runs/example/0 --plot_type=scatter
omniopt_plot --run_dir runs/example/0 --plot_type=scatter_hex --min 0 --max 100

# Interactive terminal evaluation
omniopt_evaluate --projectdir=runs

# Upload a run (link valid for 30 days)
omniopt_share runs/example/0

Plot types include cpu_ram_usage, general, gpu_usage, kde, scatter, scatter_generation_method, scatter_hex, time_and_exit_code, trial_index_result, and worker.

Use --live_share to upload results while the run is active. Both live sharing and --send_anonymized_usage_stats are opt-in. See the OmniOpt2-Share tutorial.

Updates are incremental: omniopt_share --update only zips and uploads files that changed since the last successful share. Large state_files/ snapshots such as pd.json and checkpoint.json are skipped by default because the GUI does not need them; use --include_state_files to send them anyway. Use --force only when you really want to re-send everything.

Only single-run logs from failed or interrupted evaluations are shared by default. Use --send_all_single_runs to include successful logs too, or --dont_send_singleruns / --no_single_run_logs to skip them entirely. If even the failed logs exceed 50 MiB, a stable random subset is selected so the upload stays under the cap; --send_all_failed_logs disables that sampling. If a share is larger than 50 MiB, omniopt_share prints a size breakdown by category and the largest files so it is clear what is taking up the space. The share GUI also shows which jobs had their logs omitted and prints the exact omniopt_share command(s) needed to include them later.

Exit Codes and Diagnostics

OmniOpt2 uses distinct exit codes so scripts can react precisely. The complete list is in the exit codes tutorial. Recent additions include:

  • 4: bootstrap/import failure while loading base modules
  • 35: the Lmod modules requested with --modules could not be loaded
  • 36: the virtualenv requested with --venv could not be activated
  • 87: search space exhausted
  • 89: all jobs failed
  • 248: the external generator failed repeatedly (its input folder is kept)

Failed evaluations include a red summary panel with actionable hints for common problems: missing results, Python traceback output, missing files, wrong working directory, missing Python packages, and malformed result values. For a quick sanity check without a full optimization run, use:

./omniopt --dryrun ...

Use --verbose, --debug, or --prettyprint for more diagnostics. See the debugging tutorial and the dry-run tutorial.

Tests and Development

The test suite lives in .tests:

./omniopt --tests                   # quick built-in self-test
python3 .tests/main                 # run everything
python3 .tests/main --quick         # quick subset
python3 .tests/main --list          # list matching tests
python3 .tests/main --only=suite:basic
python3 .tests/main --no_plots --no_linter
python3 .tests/smoke_tests          # pre-commit smoke tests
python3 .tests/test_lmod_modules_and_venv  # real Lmod/venv integration checks

The Lmod/venv test runs the real ./omniopt binary for the no-Lmod, fake-Lmod, failing-module, and real-Lmod scenarios and prints the full command and output. The smoke tests also cover the GUI JavaScript, PHP, Python unit tests, linting, typing, and the installer.

Repository entry points:

Path Purpose
omniopt Main optimizer and bootstrap
omniopt_plot Plot results
omniopt_evaluate Interactive result browser
omniopt_share Upload/share results
omniopt_optuna Optuna runner and study control
omniopt_docker Docker build/run helper
.ax.py Ax/BoTorch backend abstraction
.executor_backend.py submitit/SLURM/local execution backend
.gui/ PHP/JavaScript GUI and documentation
.tests/ Test framework and test suite

Shell Completion

Completion definitions for bash and zsh are in .shells:

bash .shells/install

See .shells/README.md for details.

License and Contact

OmniOpt2 is licensed under the GNU General Public License v3. See LICENSE.

Old OmniOpt

The old HyperOpt-based OmniOpt version is no longer supported. It remains available at https://github.com/NormanTUD/LegacyOmniOpt.

Metadata

Release files for omniopt2 10100

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for omniopt2 10100
File Size Uploaded Provenance Actions
omniopt2-10100.tar.gz 323.4 kB Without provenance Details for omniopt2-10100.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for omniopt2 10100
File Interpreter ABI Platform Actions
omniopt2-10100-py3-none-any.whl Python 3 none any Details for omniopt2-10100-py3-none-any.whl

Total release size: 1.0 MB

Release files / omniopt2-10100.tar.gz

Download URL omniopt2-10100.tar.gz
Size 323.4 kB
Tags Source
SHA-256 checksum
How to use checksums
58f55be60ce93cbd3c7b0afd980c01949e813e3aec2462a680ab7fb33d215ace
BLAKE2b-256 checksum
How to use checksums
12b928855f30e00acdc0f04adf7d3539503aefa5959e9d0500fff53e600fe34f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.25

Release files / omniopt2-10100-py3-none-any.whl

Download URL omniopt2-10100-py3-none-any.whl
Size 694.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
39654a3d0e09c5496f41b03aa4d50623e208883272453d93754f83833648c22f
BLAKE2b-256 checksum
How to use checksums
793b15977df74de4d2ca48f98369a9af123cbe9ce212ad03a0b8b459d659b5d5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.25

Security for omniopt2 10100

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

10100 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page