mace-eda-bo 0.1.1

Cold-start MACE Bayesian optimization for mixed-variable EDA design spaces.

MACE EDA BO

Cold-start Bayesian optimization for mixed-variable EDA design spaces.

This first version keeps the HEBO-style MACE acquisition idea (LCB, EI, and PI) but changes the surrounding loop for discrete EDA-style spaces:

• mixed variables: continuous, integer, categorical, boolean
• optional legalize(config) hook for repairing invalid designs
• optional canonicalize(config) hook for de-duplicating equivalent designs
• tree-ensemble surrogate with uncertainty from estimator disagreement
• candidate-pool MACE selection instead of raw-space acquisition gradients
• ask/tell API suitable for expensive external EDA evaluators

Install

For regular use, install the released package from PyPI:

python -m pip install mace-eda-bo

For local development, clone the repository and install it in editable mode:

cd mace-eda-bo
python -m pip install -e .[dev]

Minimal Example

from mace_eda_bo import MACEBO, DesignSpace

space = DesignSpace([
    {"name": "x", "type": "num", "lb": -5.0, "ub": 5.0},
    {"name": "n", "type": "int", "lb": 1, "ub": 8},
    {"name": "kind", "type": "cat", "categories": ["a", "b", "c"]},
    {"name": "flag", "type": "bool"},
])

opt = MACEBO(space, init_samples=8, seed=0, maximize=False)

for _ in range(40):
    cfg = opt.ask()
    y = (cfg["x"] - 1.5) ** 2 + (cfg["n"] - 3) ** 2
    opt.tell(cfg, y)

print(opt.best_config, opt.best_y)

For EDA flows, pass shell-backed evaluators outside the optimizer and call tell() with the measured metric.

Available surrogate plugins:

MACEBO(space, surrogate="extra_trees")
MACEBO(space, surrogate="random_forest")
MACEBO(space, surrogate="gaussian_process")
MACEBO(space, surrogate="tpe")

Trace and Resume

opt = MACEBO(space, initial_sampler="sobol", seed=0)
cfg = opt.ask()

try:
    y = run_expensive_flow(cfg)
    opt.tell(cfg, y)
except RuntimeError as exc:
    opt.tell_failed(cfg, reason=str(exc))

opt.save_trace("trace.csv")

restored = MACEBO.from_trace("trace.csv", space, initial_sampler="sobol", seed=0)

Examples

python examples/chiplet_like.py
python examples/chiplet_benchmark.py
python examples/shell_evaluator_demo.py
python examples/flow_adapter_demo.py
python examples/multi_objective_archive.py
python examples/parego_demo.py
python examples/repeatability_check.py
python examples/analyze_pareto.py
mace-eda-bo chiplet-like --budget 50
mace-eda-bo benchmark-chiplet-like --budget 40 --seeds 0 1 2
mace-eda-bo benchmark --config configs/chiplet_like.json
mace-eda-bo benchmark --config configs/parego_chiplet_like.json

The chiplet-like example demonstrates legalize, canonicalize, equivalent-design de-duplication, and a throughput-like maximization loop. The benchmark example compares random search with several MACEBO surrogate plugins across multiple seeds and writes trace.csv, summary.csv, convergence.csv, and convergence_mean.csv. The shell evaluator demo shows the same interface you would use for OpenROAD/Yosys-style command-line flows: write config.json, run an external command, parse metrics.json, and keep per-run artifacts. The flow adapter demo also renders a per-run flow.tcl template before launching the external command. The multi-objective archive example tracks Pareto-optimal designs from raw EDA metrics without collapsing them into a weighted score. The ParEGO demo uses the existing single-objective MACEBO loop to explore a multi-objective Pareto front with changing scalarizations. The repeatability check example estimates metric noise from repeated evaluations and recommends absolute epsilon values for Pareto pruning. The Pareto analyzer reads pareto_front.csv, writes pareto_summary.csv with count, coverage, and 2D hypervolume metrics, and plots common metric trade-offs when matplotlib is available. The parego_chiplet_like config compares random search, scalar MACEBO, and ParEGO on a toy multi-objective chiplet-like benchmark. ParEGO supports weight_sampler="random" and weight_sampler="sobol"; Sobol weights give a more even coverage of objective preferences. ParEGO also supports normalization="online" and normalization="fixed"; fixed normalization uses user-provided objective_bounds to keep scalarization scales stable across the run.

Config-Driven Benchmarks

Benchmark configs are JSON by default:

{
  "problem": "chiplet_like",
  "budget": 40,
  "seeds": [0, 1, 2],
  "output_dir": "examples/output/chiplet_benchmark_config",
  "optimizers": [
    {"name": "random", "type": "random"},
    {
      "name": "macebo_extra_trees",
      "type": "macebo",
      "init_samples": 10,
      "candidate_pool_size": 512,
      "local_fraction": 0.6,
      "initial_sampler": "sobol",
      "surrogate": "extra_trees"
    }
  ]
}

Run:

mace-eda-bo benchmark --config configs/chiplet_like.json

When a benchmark is configured with multi-objective metrics, it also writes pareto_front.csv with non-dominated designs per optimizer and seed.

{
  "objectives": [
    {"name": "frequency_mhz", "direction": "max"},
    {"name": "timing_slack_ns", "direction": "max"},
    {"name": "area_um2", "direction": "min"},
    {"name": "power_mw", "direction": "min"}
  ]
}

Near-duplicate Pareto points can be pruned explicitly with absolute or relative tolerances. By default, no pruning is applied.

{
  "pareto_abs_eps": {
    "frequency_mhz": 5.0,
    "timing_slack_ns": 0.005,
    "area_um2": 1000.0,
    "power_mw": 1.0
  },
  "pareto_rel_eps": {
    "area_um2": 0.01,
    "power_mw": 0.01
  }
}

Absolute epsilon values can be estimated from repeated evaluations of the same design:

from mace_eda_bo import recommend_abs_epsilons

pareto_abs_eps = recommend_abs_epsilons(repeated_metrics, multiplier=3.0)

Evaluators

See docs/eda_flow_contract.md for the expected input/output contract for real Yosys/OpenROAD-style flows.

For real EDA flows, return an EvaluationResult instead of a bare float when you want traces to keep metrics, runtime, artifacts, or failure reasons:

from mace_eda_bo import EvaluationResult

def evaluate(config):
    try:
        metrics = run_openroad_flow(config)
    except RuntimeError as exc:
        return EvaluationResult.failed(str(exc), artifacts_dir="runs/design_001")

    score = metrics["frequency_mhz"] - 0.01 * metrics["area_um2"]
    return EvaluationResult.ok(
        score,
        metrics=metrics,
        artifacts_dir="runs/design_001",
        runtime_sec=metrics.get("runtime_sec"),
    )

Benchmark traces include metrics_json, artifacts_dir, and runtime_sec columns.

For command-line EDA tools, use ShellEvaluator:

from mace_eda_bo import ShellEvaluator

evaluator = ShellEvaluator(
    ["python", "flow.py", "--config", "{config_json}", "--out", "{run_dir}"],
    root_dir="runs/openroad",
    metrics_file="metrics.json",
    score_key="score",
    timeout_sec=3600,
)

result = evaluator.evaluate({"clock_period": 2.0, "utilization": 0.65})

Each run directory contains config.json, stdout.txt, stderr.txt, and the metrics file produced by the external command.

For template-driven Yosys/OpenROAD-style flows, use EDAFlowEvaluator:

from mace_eda_bo import EDAFlowEvaluator

evaluator = EDAFlowEvaluator(
    ["openroad", "flow.tcl"],
    root_dir="runs/openroad",
    template_texts={
        "flow.tcl": """
set clock_period_ns ${clock_period_ns}
set core_utilization ${core_utilization}
# write metrics to ${metrics_json}
"""
    },
    metrics_file="metrics.json",
    score_key="score",
    timeout_sec=3600,
)

Templates use ${name} placeholders. Available names include the config keys plus ${run_dir}, ${config_json}, and ${metrics_json}.