AgenticMap

AgenticMap is an Agent-driven, GPU-compute-friendly EDA system that automatically discovers and validates circuit-specific technology-mapping algorithms for each circuit. The entire codebase was built from scratch by Agents and continues to evolve under the guidance of research literature, algorithmic context, and engineering constraints. Agents propose approaches, implement code, organize experiments, analyze results, and distill what they learn into traceable, reusable evolutionary memory in plans/, thoughts/, skills/, and summaries/. Through the closed loop of “Agent-generated algorithms → AgenticMap optimization search → ABC scoring and CEC signoff → feedback-driven iteration,” the system continually discovers specialized optimization paths for different circuits.

This repository keeps ABC as the mature cut-enumeration and baseline mapping engine, then adds a standalone PyTorch core that consumes already-enumerated cuts and optimizes soft cut-selection probabilities.

The Python import namespace and command-line entry points use agenticmap. AgenticMap cut dumps use the *.agenticmap.json artifact suffix and the agenticmap.enumerated_cuts.v1 schema.

What It Does

• Loads an enumerated-cut mapping problem from JSON.
• Dumps retained ABC If_Cut_t priority cuts with if -O <json>.
• Learns one logit per candidate cut.
• Computes differentiable soft delay, use probability, expected mapped area, and optional power and placement proxy costs.
• Supports library-specific LUT areas and per-pin delays.
• Optimizes a weighted objective with temperature annealing plus optional Gumbel-Softmax or straight-through hardening.
• Calibrates objective weights against ABC if metrics embedded in cut dumps.
• Projects the learned probabilities back to a discrete selected-cut mapping.
• Writes mapped BLIFs and uses ABC read; print_stats; cec for final legalization, scoring, and equivalence signoff.

Repository Notes

• High-level planning lives in split markdown files under plans/; PLAN.md is an index.
• Detailed implementation notes, experiment notes, and intermediate reasoning live in thoughts/.
• Final or aggregate experimental result summaries should be saved under summaries/.
• When a run emits a markdown summary under results/ or another artifact directory, copy it into summaries/ with an experiment-prefixed filename and include a reference path back to the original result summary or artifact directory inside the copied markdown.
• Plans, thoughts, and summaries for experiments should always include the general baseline ABC command template used for comparison, including the input-file pattern or circuit set, mapping, cleanup/scoring, and CEC/signoff commands when applicable. Avoid repeating the same ABC command once per benchmark; list per-circuit commands only when a circuit uses a genuinely different ABC flow.
• During mapper evolution, keep the ABC comparison flow fixed. Do not add new ABC operators, cleanup passes, libraries, cut settings, or mapper configs while comparing an evolved mapper against its baseline unless that is explicitly the experiment being run. Use the same baseline commands before and after mapping so area or delay changes come from the mapper implementation, not from a changed ABC script.
• Helper scripts for evolved mapper runs should preserve the recorded baseline command shape for dump generation, scoring, and CEC signoff. Deliberate ABC flow changes must be documented as separate experiments in plans/, thoughts/, and summaries/.
• Result summary artifacts should include the experiment name as the filename prefix. Prefer <experiment>_summary.csv, <experiment>_summary.md, and <experiment>_summary.json over bare summary.csv, summary.md, or summary.json.
• Validated reusable mapper skills live in split markdown files under skills/; skills.md is an index.

Environment

Use the abc conda env; it has torch installed.

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src conda run -n abc python -m unittest discover -s tests

On this machine torch is available in that env, but no CUDA or MPS backend is currently visible, so verification runs on CPU.

GPU / Apple MPS

The mapper uses OptimizationConfig(device="auto") by default. auto chooses CUDA first, then Apple MPS, then CPU. Pass --device to pin a backend:

# NVIDIA GPU
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src conda run -n abc python -m agenticmap.cli /private/tmp/i10.agenticmap.json --steps 200 --device cuda

# Apple Silicon GPU through Metal Performance Shaders
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src conda run -n abc python -m agenticmap.cli /private/tmp/i10.agenticmap.json --steps 200 --device mps

# Force CPU, useful for debugging or reproducibility checks
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src conda run -n abc python -m agenticmap.cli /private/tmp/i10.agenticmap.json --steps 200 --device cpu

Use --device auto explicitly when you want portable scripts that accelerate when a supported backend is visible:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src conda run -n abc python -m agenticmap.reward --set fast --abc-bin third_party/abc/abc --steps 80 --device auto

The same flag is accepted by agenticmap.cli, agenticmap.benchmark, agenticmap.reward, agenticmap.torch_mapper_v2_constrained, and agenticmap.torch_mapper_v3_constrained.

To check what PyTorch can see in the active env:

PYTHONDONTWRITEBYTECODE=1 conda run -n abc python -c "import torch; print('cuda', torch.cuda.is_available()); print('mps', hasattr(torch.backends, 'mps') and torch.backends.mps.is_available())"

If --device cuda or --device mps is requested but unavailable, the mapper raises a clear error instead of silently falling back to CPU.

ABC Cut Dumps

Build ABC after changing the C integration:

make -C third_party/abc ABC_USE_NO_READLINE=1 -j4

Minimal Linux servers often do not have the readline development headers installed. ABC_USE_NO_READLINE=1 disables ABC's interactive readline support and avoids fatal error: readline/readline.h: No such file or directory.

ABC Submodule Patch

ABC is kept as the third_party/abc submodule. To save local ABC source edits without committing the submodule pointer, write them to a patch file under src/:

scripts/abc_patch.sh save

The default output is src/abc_local_changes.patch. The script includes both tracked edits and new untracked files inside third_party/abc, but it does not stage or commit the submodule.

To verify or reproduce the ABC changes later:

scripts/abc_patch.sh check
scripts/abc_patch.sh apply
make -C third_party/abc ABC_USE_NO_READLINE=1 -j4

Use a custom patch path when needed:

scripts/abc_patch.sh save src/my_abc_experiment.patch
scripts/abc_patch.sh apply src/my_abc_experiment.patch

Then emit a differentiable-mapper JSON dump from ABC's if command:

third_party/abc/abc -c "read third_party/abc/i10.aig; strash; if -K 6 -C 8 -O /private/tmp/i10.agenticmap.json; quit"

The dump uses schema agenticmap.enumerated_cuts.v1 and includes:

• topological nodes, primary inputs, and primary-output drivers;
• retained non-trivial cuts with leaves, area, base delay, and pin delays;
• selected-cut and ABC flow/timing metadata;
• an embedded LUT library table when ABC has one available;
• abc_metrics for delay, area, edge count, and power. Edge is reported as an ABC diagnostic, not used as an optimization objective or reward penalty.

Validate a dump from Python:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src conda run -n abc python -c "from agenticmap.abc_dump import load_abc_cut_dump; p = load_abc_cut_dump('/private/tmp/i10.agenticmap.json'); print(p.num_nodes, len(p.all_cuts), p.metadata.get('abc_metrics'))"

Tiny Example

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src conda run -n abc python -m agenticmap.cli examples/tiny_mapping.json --steps 200

The command prints a JSON summary containing the final relaxed metrics and the projected hard mapping.

Optimize An ABC Dump

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src conda run -n abc python -m agenticmap.cli /private/tmp/i10.agenticmap.json --steps 200 --hardening gumbel_st --area-weight 0.03

For weight sweeps, load abc_metrics from the dump and pass candidate ObjectiveWeights values into agenticmap.calibration.calibrate_objective_weights.

Reward Suites

Use third_party/abc/i10.aig for quick debugging:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src conda run -n abc python -m agenticmap.reward --set quick --abc-bin third_party/abc/abc --steps 20

Use the requested small EPFL circuits for fast reward computation:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src conda run -n abc python -m agenticmap.reward --set fast --abc-bin third_party/abc/abc --steps 80

Use every .aig under input_circuits/epfl_benchmarks/arithmetic/ and input_circuits/epfl_benchmarks/random_control/ for final reward computation:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src conda run -n abc python -m agenticmap.reward --set final --abc-bin third_party/abc/abc --steps 80

Reward is computed from ABC-final delay and area only:

reward = (abc_delay - neural_delay) / abc_delay
       + area_weight * (abc_area - neural_area) / abc_area

Edge is still printed in ABC stats for visibility, but it is not an objective, tie-breaker, calibration term, or reward penalty.

ABC Baseline Comparison

Run ABC's default if mapper and neural mapping under the same -K/-C config:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src conda run -n abc python -m agenticmap.benchmark third_party/abc/i10.aig --abc-bin third_party/abc/abc --dump /private/tmp/i10.agenticmap.json --abc-blif /private/tmp/i10.abc_if.blif --neural-blif /private/tmp/i10.neural.blif --lut-size 6 --cuts 8 --steps 80

When evolving mapper versions, keep this comparison flow unchanged before and after mapping: same input circuit set, same -K/-C values, same ABC operators, same cleanup/scoring command, and same CEC/signoff command. Do not add passes such as additional resynthesis or remapping to only one side of the comparison.

The benchmark writes ABC's mapped BLIF and the projected neural BLIF, then scores both through ABC:

read <mapped.blif>; print_stats; cec <source.aig>; quit

By default the Python wrapper invokes cec -n because generated BLIFs preserve primary-input/output order rather than original AIG signal names. Use --cec-match-by-name when the mapped BLIF has source-compatible names and plain ABC cec should be used.

On third_party/abc/i10.aig with -K 6 -C 8, final ABC signoff currently reports:

• ABC baseline BLIF: equivalent, levels 11, nodes 612, edges 2679.
• Neural BLIF: equivalent, levels 12, nodes 749, edges 2932.
• Retained-cut minimum delay: 11.0.

Because the retained cut set cannot realize delay below 11.0, this benchmark cannot beat ABC's delay without changing cut enumeration or constraints. The Python projected mapping can still report delay 11.0 and area 599.0, but the ABC-legalized BLIF score is the final source of truth and currently shows the neural materialization is worse. That is now visible in the workflow rather than hidden behind Python-only counters.