Skip to main content

pages-build-deployment lx-build-and-pytest win-build-and-pytest macos-build-and-pytest

OMADS logo

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-constrained suite 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.

Runtime distributions on COCO bbob-constrained in 2D: OMADS against COBYLA, AL1-CMA-ES, fmincon and random search

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: 2n orthogonal directions (ORTHO_2N) or n+1 directions (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 ACTIVE sampling 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_cache and check_cache set to True; the mads and search solvers need the cache. The internal evaluator 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 of OMADS and NSGA-II on the 100 problems of Custódio et al.

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

Pareto fronts of OMADS on six constrained bi-objective test problems

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

BM_res_UnconstrainedMOO

Benchmarking

  • pytest tests runs 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.py runs OMADS on the COCO bbob-constrained suite.
  • benchmarks/dms/run_dms_benchmark.py and postprocess_dms.py compare OMADS with NSGA-II on the 100 multi-objective problems of Custódio et al. (DMulti-MADS protocol); check_problems.py checks the problem definitions against the original MATLAB files.
  • benchmarks/cmo/plot_constrained_mo.py draws 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.

© 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)

Table of built distributions (wheels) for OMADS 2612.1
File Interpreter ABI Platform Actions
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.

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