OMADS
OMADS (Optimization using Mesh Adaptive Direct Search) is a Python implementation of the MADS algorithm for blackbox optimization. It solves single- and multi-objective problems, with or without constraints.
Documentation, tutorials and algorithms: ahmed-bayoumy.github.io/OMADS
Version 2610
Why OMADS
Optimize what you can only run. Your simulation, CAD pipeline or legacy code gives you a
number, not a gradient: it may be noisy, non-smooth, slow, or crash at some inputs. OMADS
optimizes it directly from pip install and a ten-line Python dictionary, with no
derivatives, no surrogate to train and no solver to compile.
- Built on a convergence theory, not a heuristic. OMADS implements Mesh Adaptive Direct Search (MADS), whose iterates converge, under standard assumptions and from any starting point, to points satisfying Clarke stationarity conditions.
- Measured against established solvers. On the 54 constrained problems of the COCO
bbob-constrainedsuite in 2D, the published benchmark configuration solves about 61% of the (function, target) pairs within 100 × n evaluations, and 97% with restarts (as simulated by COCO): ahead of fmincon (92%) and close to COBYLA and AL1-CMA-ES (100%), which were run with up to 10⁷ × n evaluations. - Multi-objective, measured against NSGA-II. On the 100 bound-constrained problems of Custódio et al., following the protocol of the DMulti-MADS article (NOMAD 4's multi-objective solver), OMADS reaches the hypervolume targets of the problems that both solve with about five times fewer evaluations than NSGA-II, and its fronts have the higher purity on about 72% of the problems (best of 10 runs).
- Constraints the way engineers have them. Relaxable constraints are steered towards feasibility with a progressive barrier; points that violate hard constraints (where the code cannot even run) are rejected; failed evaluations are discarded and the search carries on.
- One input, many problems. The same dictionary or JSON file handles constrained and unconstrained, single- and multi-objective (Pareto) problems, serial or parallel evaluation, and any Python callable, including wrappers around external programs.
- Results you can check. Every published benchmark is reproducible with a single command
(
python benchmarks/coco/reproduce_results.py,python benchmarks/dms/run_dms_benchmark.py), and a regression suite runs on Linux, Windows and macOS in continuous integration.
Fraction of (function, target) pairs solved versus evaluations per variable, over the 54
COCO bbob-constrained functions in 2D. OMADS-A is the published benchmark configuration
(OMADS-B and OMADS-Halton are two alternatives). OMADS ran with 100 × n objective
evaluations (shaded; COCO also counts constraint evaluations, hence about 200 × n on the
axis), the reference algorithms with up to 10⁷ × n. Curves are solid over the recorded runs
and dotted where COCO simulates restarts; the two columns give each solver's value at the
OMADS budget and at 10⁷ × n. Details in the
benchmarking documentation.
Features
- Three solvers with one input format: full MADS (
mads), poll only (poll) and search only (search) - Householder poll directions:
2northogonal directions (ORTHO_2N) orn+1directions (N+1) - Orthogonal mesh or anisotropic granular mesh (
GMESH) - Progressive (
PB) and extreme (EB) barriers for constraints, or a two-phase strategy (constraint_strategy="TWO_PHASE") - A cheap speculative step plus a constraint-aware quadratic model search at every iteration
- An
ACTIVEsampling search (BiTPE density-ratio sampling with Halton, LHS, simulated annealing and particle swarm fallbacks) - Multi-objective Pareto studies in the spirit of DMulti-MADS, with model searches that move towards points dominating the frame centre, extend the front from its extremes and fill its largest gaps (
mo_search), and an exact hypervolume indicator - Cache, opportunistic evaluation, parallel evaluation, CSV logs and reproducible seeds
Installation
pip install OMADS
Quick start
import numpy as np
from OMADS import mads
def rosenbrock(x):
x = np.asarray(x)
f = np.sum(100.0 * (x[1:] - x[:-1] ** 2) ** 2 + (1 - x[:-1]) ** 2)
return [f, [0]] # [objective, list of constraints c(x) <= 0]
data = {
"evaluator": {"blackbox": rosenbrock},
"param": {"name": "rosen", "baseline": [-2.0, -2.0], "lb": [-5, -5],
"ub": [10, 10], "scaling": [15, 15], "post_dir": "./post"},
"options": {"seed": 0, "budget": 1000, "tol": 1e-9, "rich_direction": True,
"store_cache": True, "check_cache": True},
"search": {"type": "sampling", "s_method": "ACTIVE", "ns": 10},
}
if __name__ == "__main__":
out, poll_step, search_step = mads.main(data)
print(out["xmin"], out["fmin"], out["nbb_evals"]) # [1.0, 1.0] [0.0] 223
poll.main(data) and search.main(data) take the same input and return (out, sampler).
Each solver also accepts the path to a JSON file holding the same dictionary.
Input at a glance
| Section | Purpose | Main keys |
|---|---|---|
evaluator |
How to evaluate a point | blackbox (callable or executable), constants, path, input, output, timeout |
param |
The problem | name, baseline, lb, ub, var_names, scaling, post_dir, constraints_type, h_max, mesh_type, nobj, is_pareto |
options |
Algorithm and run options | seed, budget, tol, psize_init, store_cache, check_cache, rich_direction, direction_type, opportunistic, parallel_mode, np, save_results, mo_search, constraint_strategy |
search |
The search step (mads, search) |
type (sampling or VNS), s_method (ACTIVE, LH, RS, HALTON, FULLFACTORIAL), ns |
The blackbox receives the design vector and returns [f, [c1, c2, ...]], with constraints
feasible when c_j(x) <= 0. Every key, with its default, is listed in the
configuration reference.
Note: keep
store_cacheandcheck_cacheset toTrue; themadsandsearchsolvers need the cache. Theinternalevaluator suites ("con","uncon") of older releases have been removed.
Multi-objective MADS
Return a list of objectives from the blackbox and set "nobj" and "is_pareto": True in
param to run a Pareto study with poll.main or mads.main. See the
multi-objective tutorial.
Benchmark against NSGA-II
Hypervolume data profiles on the 100 bound-constrained multi-objective problems of Custódio
et al. (2 to 4 objectives, 1 to 30 variables), with the protocol of the DMulti-MADS article:
20,000 evaluations per run, 10 runs of each OMADS solver, 50 of NSGA-II (pymoo, population
100). A problem is solved with tolerance ε when the hypervolume of the front reaches
(1 − ε) times that of the best front found by all runs. Run with
python benchmarks/dms/run_dms_benchmark.py and benchmarks/dms/postprocess_dms.py, which
also draws the purity and spread profiles of Custódio et al.
Constrained test functions
One run of mads.main per problem (seed 0, 5,000 evaluations, progressive barrier), with
the true Pareto fronts in black; the titles give the hypervolume ratio to the best known
front. Run with python benchmarks/cmo/plot_constrained_mo.py.
Unconstrained test functions
Benchmarking
pytest testsruns the regression suite (Rosenbrock in 2, 10 and 20 dimensions, constrained and geometric-programming problems), with a target value for each solver.benchmarks/coco/run_mads_bbob_constrained.pyruns OMADS on the COCObbob-constrainedsuite.benchmarks/dms/run_dms_benchmark.pyandpostprocess_dms.pycompare OMADS with NSGA-II on the 100 multi-objective problems of Custódio et al. (DMulti-MADS protocol);check_problems.pychecks the problem definitions against the original MATLAB files.benchmarks/cmo/plot_constrained_mo.pydraws the fronts on six constrained bi-objective problems.
See the benchmarking page.
Building the documentation
pip install -r docs_src/requirements.txt
sphinx-build -b html docs_src docs
The sources live in docs_src/; the rendered site in docs/ is served by GitHub Pages.
License & copyright
© Ahmed H. Bayoumy 2022-2026
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See the LICENSE file for the full license text.
Citation
If you use this code, please cite it as follows.
@software{OMADS_AB,
author = {Bayoumy, Ahmed H.},
title = {OMADS: Optimization using Mesh Adaptive Direct Search},
year = {2022},
publisher = {GitHub},
version = {2612.1},
doi = {https://doi.org/10.5281/zenodo.23407606},
url = {https://github.com/Ahmed-Bayoumy/OMADS}
}
https://github.com/Ahmed-Bayoumy/OMADS/assets/22842095/5dc72c34-4722-4d93-8c84-d17f5595556d
Metadata
Release files for OMADS 2612.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| omads-2612.1-py3-none-any.whl | Python 3 | none | any | Details for omads-2612.1-py3-none-any.whl |
Release files / omads-2612.1-py3-none-any.whl
| Download URL | omads-2612.1-py3-none-any.whl |
|---|---|
| Size | 161.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
79095ea625d1efcd930f4098640d7ca5a3de2fd5306479a11ff60cc4756cfa25
|
|
BLAKE2b-256 checksum How to use checksums |
4d43196d20a471caf3878e3e4c2e2e4988a2ddfde4435bb52443c06121c2107c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.23 {"installer":{"name":"uv","version":"0.11.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for OMADS 2612.1
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.