Quick Start

This page runs the MACE loop once on a 2x2 Ariane mesh with examples/mace_end_to_end.py. It assumes you finished Installation: the Python environment is active, and ~/openpiton is a patched OpenPiton checkout. Run every command from the root of the MACE repository.

Set up the LLM backend

The script uses the Vertex Gemini backend by default. Log in with Application Default Credentials and name the GCP project to use:

gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT=<your-gcp-project>

LLM Backends covers the other backends.

Run the loop

python examples/mace_end_to_end.py \
    --piton-root ~/openpiton \
    --core ariane \
    --mesh 2x2 \
    --workload barrier_atomic.c \
    --backend vertex \
    --max-iterations 3 \
    --db-path runs/mace_end_to_end.db

--mesh sets the size of every config and workload build; the objective text does not. With no --objective, the script writes one from the workload and mesh, here Verify the barrier_atomic.c gate workload passes on a 2x2 mesh. Each configuration compiles its Verilator model once, and later runs reuse it until the checkout changes.

Flags

Flag	Default	Purpose
--piton-root	required	OpenPiton checkout.
--piton-root-2	none	Second checkout; independent tasks in one DAG level run on the two checkouts in parallel.
--core	ariane	ariane, sparc, or pico.
--mesh	1x1	Target mesh as XxY, such as 2x2 or 4x4.
--workload	barrier_atomic.c	Gate workload that config and workload tasks simulate.
--objective	generated	Objective text for the planner.
--backend	vertex	LLM backend.
--model	gemini-2.5-flash on vertex	Model name; other backends use their own default.
--project	none	GCP project for vertex. It overrides GOOGLE_CLOUD_PROJECT, and vertex needs one of the two.
--max-iterations	3	Iteration cap. The USD and wall-clock caps keep their Budget defaults.
--db-path	runs/mace_end_to_end.db	Run database. The default resolves against the current directory.

Read the output

The script prints the run ID and status, one block per iteration, and the five summary metrics. A run that ends failed or budget_exceeded also prints its post-mortem. The exit code is 0 only for a passed run.

run_id=<run_id> status=passed

--- iteration 0 ---
  <task_id> (<kind>): passed=True build.success=True verdict=pass

--- summary (db=runs/mace_end_to_end.db) ---
  successful_tasks: <n>
  iterations: <n>
  failures_recovered: <n>
  execution_time_s: <seconds>
  compute_usd: <dollars>

compute_usd sums the cost of every LLM call the run made; see Results and Metrics. mace results lists past runs, and --trace shows one run’s plan, dispatch, and triage, the LLM call that diagnoses a failed task for the next plan (see Failure Analysis):

mace results --db-path runs/mace_end_to_end.db
mace results --db-path runs/mace_end_to_end.db --run-id <run_id> --trace

Other cores and meshes

For PicoRV32, run addi.S and name the CONFIG_DISABLE_BIST_CLEAR RTL define in the objective:

python examples/mace_end_to_end.py \
    --piton-root ~/openpiton \
    --core pico \
    --mesh 2x2 \
    --workload addi.S \
    --objective "Verify the addi.S gate workload passes on a 2x2 pico mesh in a single task. That task needs the CONFIG_DISABLE_BIST_CLEAR RTL define."

Before a 4x4 run, export MAKEFLAGS=-j1 to limit the memory the Verilator C++ compile uses; Troubleshooting explains why. Running the Loop covers the spec, the budget, and planner directives. examples/mace_end_to_end.py and the shell take only the native cores (--core ariane, sparc, or pico). To have MACE write the wrapper of an RV32 core with no OpenPiton adapter, use examples/generic_integrate.py instead; see Generic Tile.