CLI Usage¶
The circuitgenome command has one subcommand per module, mirroring the
Overview: synthesize (SYN), recognize (SR / FBR),
size (SZ), design (DES), and visualize (VIS). Each section below
opens with a quick command you can copy-paste, followed by the full options.
Tip
If circuitgenome is not found, run it as
python3 -m circuitgenome.cli <command> ... or see
Installation for the PATH fix.
Topology Synthesizer (SYN)¶
circuitgenome synthesize generates op-amp circuits from modular building
blocks and writes them as SPICE netlists.
# Quick: generate every valid 2-stage single-ended op-amp into ./circuits/
circuitgenome synthesize --stages 2 --output-type single_ended --output-dir ./circuits/
# Count first, without writing any files
circuitgenome synthesize --stages 2 --dry-run
Listing available resources¶
# Show all topology templates
circuitgenome synthesize --list-topologies
one_stage_opamp (stages=1, output=single_ended)
two_stage_opamp_single_ended (stages=2, output=single_ended)
two_stage_opamp_fully_differential (stages=2, output=fully_differential)
three_stage_opamp_nmc_single_ended (stages=3, output=single_ended, compensation=nested_miller)
three_stage_opamp_rnmc_single_ended (stages=3, output=single_ended, compensation=reversed_nested_miller)
three_stage_opamp_nmc_fully_differential (stages=3, output=fully_differential, compensation=nested_miller)
three_stage_opamp_rnmc_fully_differential (stages=3, output=fully_differential, compensation=reversed_nested_miller)
# Show all module variants, grouped by category
circuitgenome synthesize --list-modules
[input_pair]
differential_pair_pmos — PMOS Differential Pair
differential_pair_nmos — NMOS Differential Pair
...
Generating circuits¶
# 1-stage, flat SPICE (default format), written to ./circuits/
circuitgenome synthesize --stages 1 --output-dir ./circuits/
# 2-stage single-ended, both flat and hierarchical SPICE
circuitgenome synthesize \
--stages 2 \
--output-type single_ended \
--format both \
--output-dir ./circuits/
# Fully differential topology only
circuitgenome synthesize \
--topology two_stage_opamp_fully_differential \
--format hierarchical \
--output-dir ./circuits/
# 3-stage, Reversed Nested Miller Compensation, single-ended
circuitgenome synthesize \
--topology three_stage_opamp_rnmc_single_ended \
--output-dir ./circuits/
# Design-space exploration — also emit bias-infeasible (but functionally
# correct) wirings, e.g. the stacked-diode cascode tails
circuitgenome synthesize --stages 2 --include-infeasible --dry-run
Sample output (--stages 2 --dry-run):
Topology: two_stage_opamp_single_ended
Generated 180 circuits
Topology: two_stage_opamp_fully_differential
Generated 648 circuits
Topology: two_stage_opamp_buffered_single_ended
Generated 360 circuits
Topology: two_stage_opamp_buffered_fully_differential
Generated 2592 circuits
Total: 3780 circuits (dry run — no files written)
Output filenames follow the pattern circuit_NNNN_flat.ckt /
circuit_NNNN_hier.ckt, numbered sequentially within each topology.
Options¶
Flag |
Description |
Default |
|---|---|---|
|
Filter to topologies with this many stages |
all |
|
|
all |
|
Use one specific topology by name |
all |
|
SPICE output format |
|
|
Directory for output files (created if absent) |
|
|
Count circuits without writing files |
off |
|
Also enumerate |
off |
|
Print topology names and exit |
— |
|
Print module variants and exit |
— |
Subcircuit & Functional Block Recognizer (SR / FBR)¶
Given a flat SPICE netlist (e.g. generated by circuitgenome synthesize),
circuitgenome recognize identifies the functional building blocks and,
optionally, maps them to a topology’s named slots.
# Quick: recognize a netlist, grouping structures by circuit block
circuitgenome recognize path/to/circuit.ckt
# Topology mode — also assign structures to named topology slots
circuitgenome recognize path/to/circuit.ckt \
--topology two_stage_opamp_single_ended
Sample output (topology-free, two-stage circuit):
Netlist: circuit_0001_flat.ckt
Recognized structures (6):
[input_pair] differential_pair_pmos (devices: m1_input_pair, m2_input_pair)
[load] active_load_nmos (devices: m1_load, m2_load)
[tail_current] current_mirror_tail_pmos (devices: m1_tail_current, m2_tail_current)
[bias_generation] diode_connected_mosfet_bias (devices: mn1_bias_gen)
[second_stage] common_source (devices: mn_second_stage, mp_second_stage)
[compensation] miller_cap (devices: c1_comp)
Unrecognized devices: none
Functional block groups (topology-free):
[gain_stage_1]
input_pair differential_pair_pmos (devices: m1_input_pair, m2_input_pair)
load active_load_nmos (devices: m1_load, m2_load)
tail_current current_mirror_tail_pmos (devices: m1_tail_current, m2_tail_current)
[gain_stage_2]
second_stage common_source (devices: mn_second_stage, mp_second_stage)
[bias]
bias_generation diode_connected_mosfet_bias (devices: mn1_bias_gen)
[compensation]
compensation miller_cap (devices: c1_comp)
For a three-stage circuit the split pass automatically promotes the final gain stage:
Functional block groups (topology-free):
[gain_stage_1]
input_pair differential_pair_pmos (devices: m1_input_pair, m2_input_pair)
load resistor_load_gnd (devices: r1_load, r2_load)
tail_current current_mirror_tail_pmos (devices: m1_tail_current, m2_tail_current)
[gain_stage_2]
second_stage common_source (devices: mn1_second_stage, mp1_second_stage)
[gain_stage_3]
second_stage common_source (devices: mn1_third_stage, mp1_third_stage)
[bias]
bias_generation diode_connected_mosfet_bias (devices: mn1_bias_gen)
[compensation]
compensation miller_cap (devices: c1_comp1)
Sample output (topology mode):
... (same recognized structures as above) ...
Slot assignments (topology: two_stage_opamp_single_ended):
input_pair differential_pair_pmos (devices: m1_input_pair, m2_input_pair)
load active_load_nmos (devices: m1_load, m2_load)
tail_current current_mirror_tail_pmos (devices: m1_tail_current, m2_tail_current)
bias_gen diode_connected_mosfet_bias (devices: mn1_bias_gen)
second_stage common_source (devices: mn_second_stage, mp_second_stage)
compensation miller_cap (devices: c1_comp)
Options¶
Argument / Flag |
Description |
Default |
|---|---|---|
|
Path to the flat SPICE netlist file |
(required) |
|
Topology name for named-slot FBR assignment; omit for topology-free grouped output |
(topology-free) |
Sizer (SZ)¶
circuitgenome size sizes the transistors in a flat SPICE netlist to meet a
set of DC performance specifications. It needs the topology name (for FBR slot
assignment) and a YAML spec file.
# Quick: size a 2-stage single-ended netlist against a generic-tech spec
circuitgenome size \
circuits/two_stage_opamp_single_ended/circuit_0001_flat.ckt \
--topology two_stage_opamp_single_ended \
--spec examples/two_stage_se_specs/spec_generic.yaml
Sample output (generic tech — Level-1 analytical path):
Netlist: circuit_0001_flat.ckt | Topology: two_stage_opamp_single_ended
Tech: generic_parameterized
Solver: OPTIMAL
⚠ second-stage gm requirement exceeds the weak-inversion ceiling — increase second_stage_current_ratio/ibias or relax gain.
Transistor sizing:
m1_input_pair W=9.000µm L=1.000µm IDS=5.00µA VGS=-0.611V VDS_sat=0.111V
...
mp1_second_stage W=5.000µm L=1.000µm IDS=25.00µA VGS=-0.833V VDS_sat=0.333V
Cc = 2.9pF
r1_load R=130.00kΩ
Feasibility: MARGINAL — biases, but does not meet spec (see ⚠ above)
Performance metrics:
Open-loop gain 63.94 dB [spec ≥ 80.00 dB] margin -16.06 dB ✗
GBW 2.51 MHz [spec ≥ 2.50 MHz] margin +0.01 MHz ✓
Phase margin 63.25 ° [spec ≥ 60.00 °] margin +3.25 ° ✓
Slew rate 3.50 V/µs [spec ≥ 3.50 V/µs] margin +0.00 V/µs ✓
Quiescent power 0.43 mW [spec ≤ 1.00 mW] margin +0.57 mW ✓
CMRR 39.08 dB
PSRR+ 53.98 dB
The verdict line is FEASIBLE, MARGINAL (biases but misses a spec — failing
rows are marked ✗, as the gain row is here), or INFEASIBLE (bias point
cannot be established — the metrics table is suppressed). For the generic tech
the metrics are the Level-1 analytical estimates.
Options¶
Argument / Flag |
Description |
Default |
|---|---|---|
|
Path to the flat SPICE netlist file |
(required) |
|
Topology name (used for FBR slot assignment) |
(required) |
|
Path to the YAML performance specification file |
(required) |
|
Built-in config name or path to a technology YAML |
|
|
Cross-check the sized circuit in ngspice (analytical vs SPICE). Redundant for PTM, whose metrics are already ngspice-measured. |
off |
|
CP-SAT solver time limit, seconds (Level-1 path only) |
|
--tech accepts either a path to a technology YAML or the short name of a
built-in config: generic (default); ptm45 (ASU Predictive Technology
Model 45 nm planar-bulk node); or gf180mcu (GlobalFoundries GF180MCU 180 nm
open PDK, 3.3 V core). See Technology configurations on the
Sizer (SZ) module page for details and how to add a node
with tools/extract_tech.py.
circuitgenome size circuit_0001_flat.ckt \
--topology two_stage_opamp_single_ended \
--spec spec.yaml --tech ptm45
PTM / foundry PDK technologies (gm/Id path)¶
For a PTM node or a foundry PDK the sizer uses the gm/Id pipeline (not the Level-1
CP-SAT solver), and the performance section reports metrics measured in ngspice
(BSIM4) rather than the analytical estimates — so ngspice must be on PATH (the
command errors otherwise). Only gain, GBW, phase margin, slew rate, and power are
measured; CMRR, PSRR, and output swing have no ngspice test-bench yet and are
omitted. A metric ngspice cannot extract is shown as n/a.
Solver: GMID
... (transistor sizing) ...
Feasibility: MARGINAL — biases, but does not meet spec
Performance metrics (ngspice / BSIM4):
Open-loop gain 48.63 dB [spec ≥ 60.00 dB] margin -11.37 dB ✗
GBW 0.77 MHz [spec ≥ 2.50 MHz] margin -1.73 MHz ✗
Phase margin 84.46 ° [spec ≥ 60.00 °] margin +24.46 ° ✓
Slew rate n/a [ngspice could not extract this metric]
Quiescent power 0.05 mW [spec ≤ 0.50 mW] margin +0.45 mW ✓
ⓘ CMRR, PSRR, and output swing are not measured by the current ngspice rig and are omitted.
A PTM/SPICE-model node without a characterized gm/Id LUT is rejected with
UnsupportedTechError (the Level-1 square-law numbers are not valid there).
Foundry PDKs and process corners. --tech gf180mcu selects the GF180MCU
open PDK: its devices are PDK subcircuits (nmos_3p3/pmos_3p3) and a
process corner is selected with .lib "<file>" <corner>. Sizing is done at the
nominal (typical) corner; after the typical-corner metrics the CLI re-measures
the sized design across {typical, ss, ff, sf, fs} and prints a
corner-verification table (sizing itself stays at typical):
Feasibility: MARGINAL — biases, but does not meet spec
Performance metrics (ngspice / BSIM4):
Open-loop gain 82.31 dB [spec ≥ 45.00 dB] margin +37.31 dB ✓
GBW 0.64 MHz [spec ≥ 0.80 MHz] margin -0.16 MHz ✗
...
Corner verification (re-measured; sized at typical):
metric typical ss ff sf fs
Gain (dB) 82.31 82.11 82.42 82.61 81.90
GBW (MHz) 0.64 0.61 0.67 0.65 0.63
PM (deg) 79.05 78.91 79.17 78.49 79.58
Power (mW) 0.38 0.38 0.39 0.38 0.39
Designer (DES)¶
circuitgenome design runs the full flow — synthesize → size → SPICE-verify →
export — against a target spec, keeping only the designs whose ngspice-measured
metrics meet it. It needs a technology with a gm/Id LUT (default gf180mcu),
so ngspice must be on PATH.
# Quick: design 2-stage single-ended op-amps for a GF180MCU spec,
# evaluating up to 100 candidates across 4 worker processes
circuitgenome design \
--topology two_stage_opamp_single_ended \
--spec examples/two_stage_se_specs/spec_gf180.yaml \
--output-dir designs/ --limit 100 --workers 4
# Design every topology template
circuitgenome design --all \
--spec examples/gf180_difficulty_specs/spec_01_easy.yaml \
--output-dir designs/
The surviving sized netlists and a report.json (per-template statistics and
the best design points) are written to the output directory.
Options¶
Flag |
Description |
Default |
|---|---|---|
|
Design one template by name, or every template — exactly one is required |
(required) |
|
Path to the YAML performance specification file |
(required) |
|
Directory for the sized netlists and |
(required) |
|
Technology config or built-in name (must carry a gm/Id LUT) |
|
|
Evaluate at most N circuits per template |
exhaustive |
|
Parallel worker processes |
|
|
Also evaluate |
off |
Visualizer (VIS)¶
circuitgenome visualize launches a Streamlit web UI for browsing topologies
and module variants.
pip install circuitgenome[viz] # one-time: the visualizer needs the viz extra
circuitgenome visualize
See Visualizer in the Overview for a screenshot and description.