Skip to content

cli.md

Latest commit

 

History

History
103 lines (75 loc) · 3.42 KB

cli.md

File metadata and controls

103 lines (75 loc) · 3.42 KB
Raw

Command-Line Interface

Installing the package (pip install -e .) provides the circuitropy command. It replaces the old root scripts run_tests.py (now circuitropy batch) and generate_overviews.py (now circuitropy analyze <file> -o <file>.json).

Inputs may be Verilog netlists (.v/.sv) or Circuitropy JSON circuit documents (.json, any known schema version).

analyze

Metrics (and entropy, by default) of one netlist:

circuitropy analyze circuit.v
circuitropy analyze circuit.v --json            # machine-readable output
circuitropy analyze circuit.v --no-entropy      # skip the simulation
circuitropy analyze circuit.v -o circuit.json   # also export the circuit

compare

Side-by-side metrics of two netlists, with percentage deltas:

circuitropy compare original.v optimized.v
circuitropy compare original.v optimized.json --no-entropy

optimize

Apply an optimization and print the trajectory (one row per step):

# Built-in methods (Rust eo_do_rs backend when available)
circuitropy optimize circuit.v --method eo -o optimized.json
circuitropy optimize circuit.v --method do --entropy

# ABC backend: measure after each script step
circuitropy optimize circuit.aig --backend abc --script "balance; rewrite; balance" --entropy

# Reproducible pipeline configuration (JSON, or YAML with pyyaml installed)
circuitropy optimize circuit.v --pipeline pipeline.json -o out.json

Example trajectory output:

step                            nodes   depth      entropy   time_s
-------------------------------------------------------------------
original                          525      28     281.4012    0.000
balance                           441      23     279.2201    0.014
rewrite                           390      22     254.8703    0.012
energy_oriented                   390      35     201.1600    0.021

Entropy is off by default for optimize (each measurement launches the Rust simulator); enable it with --entropy.

!!! note "Exporting to Verilog re-expands multi-output nodes" EO/DO produce nodes with multiple fanout functions. Writing them to .v expands each function into separate assign statements, so re-importing the Verilog yields different node/depth counts. Use .json output to preserve the optimized structure exactly.

batch

Sweep a directory of netlists (recursive) into a CSV report — the successor of run_tests.py, with the same columns and flags:

circuitropy batch benchmarks/ -o results.csv
circuitropy batch benchmarks/ --energy-oriented --images-dir imgs/
circuitropy batch benchmarks/ --original-only --chunks 4 --parallel-chunks 2

visualize

Render the DAG or the entropy-by-level profile:

circuitropy visualize circuit.v                       # DAG → circuit_dag.png
circuitropy visualize circuit.v --metric energy       # ΔH by level
circuitropy visualize circuit.v --orientation vertical --level-window 4 10

Requires the viz extra (pip install -e ".[viz]").

doctor

Diagnose the installation:

circuitropy doctor

Checks: Python version and platform, CPU SIMD capabilities, temp-directory permissions, the eo_do_rs and circuit_sim Rust binaries, the selected EO/DO backend, optional tools (ABC, Yosys, aigverse, matplotlib), and a minimal end-to-end circuit run (parse → validate → entropy). Exits non-zero when a required component is broken, which makes it useful in CI and bug reports.