Virtuoso

Virtuoso Skill

CRITICAL: Do NOT invent SKILL code or API calls from memory. SKILL function names, signatures, and PDK device parameters are not reliably included in LLM training data — and they differ between Virtuoso versions (e.g. IC618 vs IC231). Before writing any SKILL expression, calling any SKILL function, or using any library cell:

1. Quick check (repo): search references/ and examples/ for the function name or operation — fastest, no round-trip.
2. REQUIRED — verify against the installed Cadence docs (the ground truth for this Virtuoso version):
   • SKILL function → virtuoso-bridge skill-find <name> (syntax + description), then virtuoso-bridge skill-info <name> (full documentation page)
   • Concept / topic → virtuoso-bridge doc-search "<query>" (searches all installed doc sets)
   • New host/profile → run virtuoso-bridge doc-info once per session to identify the active Virtuoso version and documentation layout before interpreting any doc results
3. Library cells: confirm existence (ddGetLibList / ddGetObj) and read the actual cell (symbol pins, CDF params) before instantiating or setting parameters — never assume pin names or parameter names.

If skill-find does not find a function, try doc-search with related terms before concluding anything. A miss in repo references is NOT evidence that a function does not exist. Never guess parameter names — verify first. Full protocol + command reference: references/local-docs.md.

Mental Model

You control a remote Cadence Virtuoso through virtuoso-bridge. Python runs locally; SKILL executes remotely in the Virtuoso CIW. SSH tunneling is automatic.

 Local (Python)                    Remote (Virtuoso)
┌──────────────────┐   SSH tunnel  ┌──────────────────┐
│ VirtuosoClient   │ ────────────► │ CIW (SKILL)      │
│                  │               │                  │
│ • schematic.*    │               │ • dbCreateInst   │
│ • layout.*       │               │ • schCreateWire  │
│ • execute_skill  │               │ • mae*           │
│ • load_il        │               │ • dbOpenCellView │
└──────────────────┘               └──────────────────┘

Three abstraction levels

Always use the highest level that works. Drop to a lower level only when needed.

Never guess function names. If the function isn't in the examples below, verify it against the installed Cadence documentation (see "Documentation protocol") before writing the call. Fabricating a wrong name wastes time debugging in CIW.

Documentation protocol (mandatory)

The SKILL language, its per-version function set, and PDK device parameters are the part of this stack most likely to be wrong from memory. Verify against the docs installed on the target Virtuoso — not from general knowledge — before:

• writing any SKILL expression that calls a function you haven't used before in this session,
• instantiating a library cell or setting CDF parameters on one,
• relying on version-dependent behavior (a function that exists in IC231 may be absent or renamed in IC618, and vice versa).

The four verification commands

All four support --json (for parsing), -p PROFILE (multi-profile setups), and --env FILE. doc-search additionally supports --doc-root (explicit local roots, no bridge needed), --rebuild-index, and --cache-dir. Python equivalents: client.doc_info(), client.find_skill(query, mode=...), client.get_skill_more_info(func), client.search_docs(query).

Standard verification flow

# 1. Once per session / per host: which Virtuoso, what docs are installed?
virtuoso-bridge doc-info

# 2. Is the function there, and what is its EXACT syntax?
virtuoso-bridge skill-find dbOpenCellViewByType
#    → dbOpenCellViewByType( { gt_lib | nil } t_cellName lt_viewName [ t_viewTypeName [ t_mode [ d_contextCellView ] ] ] ) => d_cellView / nil

# 3. Full argument descriptions, return values, examples:
virtuoso-bridge skill-info dbOpenCellViewByType

# 4. Concept-level questions (e.g. "how to create inherited net expression"):
virtuoso-bridge doc-search "net expression label"

Interpret results through the doc-info output: skdfref style tells you whether function pages are individual files (per-function, e.g. IC231) or one large chapter file with anchors (chapter, e.g. IC618) — skill-info handles both transparently, but it matters when reading doc paths by hand.

Library-cell verification

Before instantiating a cell or setting parameters on it:

1. Existence — confirm the lib/cell/view triple is real: client.execute_skill('ddGetObj("lib" "cell")') (iterate ddGetLibList() if you only know the cell name).
2. Pins/parameters — read them from the live cellview, never from memory: open the symbol view and list terms, or use schGetParams / dbGetq on an instance. CDF parameter names are PDK-specific (e.g. fingers is editable while nf is read-only on many PDKs — see "Create a schematic" below).
3. Semantics — for PDK device behavior (terminal order, multi-finger semantics, corner behavior), search the PDK/user documentation: virtuoso-bridge doc-search "<device> <parameter>".

Five domains

Before you start

Environment setup

virtuoso-bridge is a Python CLI. Use uv + virtual environment — never install into the global Python.

uv venv .venv && source .venv/bin/activate   # Windows: source .venv/Scripts/activate
uv pip install -e virtuoso-bridge-lite

All virtuoso-bridge CLI commands and Python scripts must run inside the activated venv.

Connection sequence (follow in order)

1. Check .env — the bridge looks up .env in this order: --env FILE (CLI flag) → first parent .env that looks like a Virtuoso Bridge config (any VB_*_HOST role or VB_LOCAL_PORT) → ~/.virtuoso-bridge/.env (user-level). If any of these exists, skip init. Only run virtuoso-bridge init when none exist — it creates ~/.virtuoso-bridge/.env (user-level, shared across projects). If the user already told you their SSH target, prefer virtuoso-bridge init user@host [-J user@jump] to fill the one-host model + ports in one step; otherwise plain virtuoso-bridge init writes a template. For split installations, verify VB_GUI_HOST owns CIW/X11, VB_DEPLOY_HOST receives generated files, VB_DAEMON_HOST is the tunnel endpoint, VB_SPECTRE_HOST runs standalone jobs, and VB_REMOTE_SCRATCH_ROOT is visible to every role that consumes deployed files. Unset roles fall back to VB_REMOTE_HOST.
2. virtuoso-bridge start — starts the local bridge service and SSH tunnel.
3. If status is degraded — load the exact setup line printed by start in Virtuoso CIW. As an opt-in alternative, run virtuoso-bridge list-windows --top-level --json, select one explicit CIW, then run virtuoso-bridge bootstrap --window WINDOW_ID; bootstrap refuses non-CIW windows and accepts no arbitrary SKILL.
4. virtuoso-bridge status — verify everything is healthy before proceeding.
5. virtuoso-bridge windows — list all open Virtuoso windows (num + name).
6. virtuoso-bridge eval 'EXPR' — run a one-line SKILL expression from the shell and print the full VirtuosoResult JSON.
7. virtuoso-bridge eval --stdin — run multi-line SKILL from stdin; the CLI auto-wraps multiple forms in progn(...) and returns the last form.
8. virtuoso-bridge load FILE.il — run a .il file in the live Virtuoso session; uploads the file automatically in SSH mode.
9. virtuoso-bridge screenshot [ciw|current|N] [-o DIR|FILE] — screenshot a window. Default target is CIW; default output is the user artifact screenshots directory.
10. virtuoso-bridge snapshot -o <dir> — dump the currently-focused maestro window to <dir>/<YYYYMMDD_HHMMSS>__<lib>__<cell>/ (state XMLs, SKILL probe output, per-point netlist + PSF results, .rdb). This is the default way to capture Maestro state — no Python required. Use the Python API (below) only inside a multi-step pipeline.

Then

• Check examples first: examples/01_virtuoso/ — don't reinvent from scratch.
• Run virtuoso-bridge doc-info once to pin the active Virtuoso version and doc layout (see "Documentation protocol (mandatory)").
• Open the window: client.open_window(lib, cell, view="layout") so the user sees what you're doing.

Client basics

Direct CLI SKILL execution

For quick checks and one-off SKILL files, prefer the CLI over writing a Python wrapper. It uses the same bridge connection and avoids shell/Python/SKILL triple-quoting problems.

# One-line expression -- full VirtuosoResult JSON on stdout
virtuoso-bridge eval 'getCurrentTime()'

# Multi-line SKILL -- auto-wrapped in progn when needed
virtuoso-bridge eval --stdin <<'EOF'
let((libs)
  libs = mapcar(lambda((l) l~>name) ddGetLibList())
  printf("found %d libraries\n" length(libs))
  libs)
EOF

# Whole .il file -- uploaded automatically in SSH mode
virtuoso-bridge load my_script.il

Use Python only when the SKILL call is one step in a larger scripted workflow or when you need structured high-level APIs such as schematic/layout editors.

Python client

from virtuoso_bridge import VirtuosoClient
client = VirtuosoClient.from_env()

client.execute_skill('...')                     # run SKILL expression
client.fetch(expr, fields)                       # batch ~>slot extract (see below)
client.fetch_one(expr, fields)                   # single-object ~>slot extract
client.load_il("my_script.il")                  # upload + load .il file
client.upload_file(local_path, remote_path)      # local → remote
client.download_file(remote_path, local_path)    # remote → local
client.open_window(lib, cell, view="layout")     # open GUI window
client.run_shell_command("ls /tmp/")             # run shell on remote
client.list_windows()                            # list all open windows
client.screenshot(target="ciw")                   # screenshot to the user artifact directory
client.screenshot(output="output", target="ciw")  # explicit repo-local output

Batch attribute fetch: fetch() / fetch_one()

execute_skill() is a raw-string in, raw-string out channel. For DFII objects it returns an opaque handle ("db:0x2800ccbe") that's useless by itself — to get attributes you'd have to send another SKILL call per attribute, which is both verbose and slow (~100 ms per round-trip).

fetch(expr, fields) does the right thing in one round-trip: sends mapcar(lambda((o) list(o~>f1 o~>f2 ...)) <expr>), parses the SKILL s-expression response, and returns a list of Python dicts.

# List of selected schematic objects in one call
objs = client.fetch("geGetSelSet()", ["objType", "cellName", "name"])
# [{"objType": "inst", "cellName": "nch_mac", "name": "M1"},
#  {"objType": "inst", "cellName": "pch_mac", "name": "M2"}, ...]
print(objs[0]["name"])     # → 'M1'

# All instances in the current schematic — 1 call, not N×fields
insts = client.fetch(
    "geGetEditCellView()~>instances",
    ["name", "cellName", "libName", "viewName"],
)

fetch_one(expr, fields) is the single-object variant — wraps in list(...) and returns one dict:

cv = client.fetch_one("geGetEditCellView()",
                      ["libName", "cellName", "viewName"])
# {"libName": "PLAYGROUND", "cellName": "AMP", "viewName": "schematic"}

Value decoding (both methods): strings unquoted, nil → None, t → True, nested SKILL lists → nested Python lists, bare atoms (numbers / symbols) returned as strings so the caller can coerce (int(d["fingers"])).

Why not a client["fn"]() lazy-proxy style (à la skillbridge)? Lazy proxies look nicer syntactically but trigger one round-trip per attribute access — 100 selected objects × 3 fields = 300 ssh hops (30 s). fetch does it all in one hop (200 ms). If you need the REPL-style ergonomics, use skillbridge alongside this bridge — they coexist fine on the same Virtuoso session.

CIW output vs return value

execute_skill() returns the result to Python but does not print anything in the CIW window. This is by design — the bridge is a programmatic API, not an interactive REPL.

# Return value only — CIW stays silent
r = client.execute_skill("1+2")        # Python gets 3, CIW shows nothing

# To also display in CIW, use printf explicitly
r = client.execute_skill(r'let((v) v=1+2 printf("1+2 = %d\n" v) v)')
#   Python gets 3, CIW shows "1+2 = 3"

Full example: examples/01_virtuoso/basic/00_ciw_output_vs_return.py

Printing multi-line text to CIW

Sending multiple printf in a single execute_skill() loses newlines — the CIW concatenates everything on one line. To print multi-line text, write it as a Python multiline string and send one execute_skill() per line:

text = """\
========================================
  Title goes here
========================================
  First paragraph line one.
  First paragraph line two.

  Second paragraph.
========================================"""

for line in text.splitlines():
    client.execute_skill('printf("' + line + '\\n")')

Constraints:

• ASCII only — emojis and CJK characters cause a JSON encoding error on the remote SKILL interpreter
• No unescaped SKILL special chars in the text — if the line may contain " or %, escape them (\\", %%) or use load_il() instead (see 03_load_il.py)

IMPORTANT: Always write .py files, never use python -c. python -c "..." has three layers of quoting (shell + Python + SKILL). \\n easily becomes \\\\n, causing printf to silently produce no output. Always write code to a .py file and run python script.py -- only two quoting layers (Python + SKILL), matching the examples.

Full example: examples/01_virtuoso/basic/02_ciw_print.py

References

Load on demand — each contains detailed API docs and edge-case guidance:

Examples

Always check these before writing new code.

examples/01_virtuoso/basic/

• 00_ciw_output_vs_return.py — CIW output vs Python return value (when CIW prints, when it doesn't)
• 01_execute_skill.py — run arbitrary SKILL expressions
• 02_ciw_print.py — print messages to CIW (one execute_skill per line)
• 03_load_il.py — upload and load .il files
• 04_list_library_cells.py — list libraries and cells
• 05_multiline_skill.py — multi-line SKILL with comments, loops, procedures
• 06_screenshot.py — capture layout/schematic screenshots
• 07_sanitize_on_download.py — download remote text while sanitizing unsafe path fragments
• 08_library_management.py — inspect a library, technology binding, categories, and members

examples/01_virtuoso/schematic/

• 01a_create_rc_stepwise.py — create RC schematic via operations
• 01b_create_rc_load_skill.py — create RC schematic via .il script
• 02_read_connectivity.py — read instance connections and nets
• 03_read_instance_params.py — read CDF instance parameters
• 04_test_set_instance_params_analoglib.py — update analogLib instance parameters
• 05_rename_instance.py — rename schematic instances
• 06_delete_instance.py — delete instances
• 07_delete_cell.py — delete cells from library
• 08_import_cdl_cap_array.py — import CDL netlist via spiceIn (SSH)
• 09_create_pins.py — create schematic pins
• 10_create_wire.py — draw wires between pins
• 11_read_schematic_unified.py — read instances, nets, pins, geometry, and parameters
• 12_plan_differential_pair.py — deterministically plan, create, read back, and verify a constrained differential-pair schematic

examples/01_virtuoso/layout/

• 01_create_layout.py — create layout with rects, paths, instances
• 02_add_polygon.py — add polygons
• 03_add_via.py — add vias
• 04_multilayer_routing.py — multi-layer routing
• 05_bus_routing.py — bus routing
• 06_read_layout.py — read layout shapes
• 07–10 — delete/clear operations
• 11_read_summary.py — read a compact layout summary
• 12_layer_visibility.py — inspect and change layer visibility
• 13_select_and_delete.py — select and delete matching figures
• 14_mosaic_and_nets.py — create mosaics and assign nets
• 15_export_gds.py — stream out GDS with staged inputs and fail-fast log polling

examples/01_virtuoso/symbol/

• 01_rc_create_with_symbol.py — native schematic-to-symbol generation
• 02_bus10_create_with_symbol.py — native generation with 20 pins
• 03_manual_symbol_semantics.py — manual drawing with native pin-name, instance/logical labels, selection box, and readback verification

examples/01_virtuoso/maestro/

• 01_read_focused_maestro.py — in-memory snapshot of the focused maestro (config + env + results + outputs + corners + variables)
• 02_snapshot_with_metrics.py — snapshot the focused maestro to a timestamped directory (disk artifacts)
• 03_bg_open_read_close_maestro.py — background open → read config → close (no GUI window)
• 04_gui_open_snapshot_close.py — GUI open → snapshot artifacts → close (owns lifecycle)
• 05_gui_session_lifecycle.py — GUI session lifecycle integration test (open/close edge cases)
• 06a_rc_create.py — create RC schematic + Maestro setup (cell name auto-timestamped)
• 06b_rc_simulate_and_read.py — run simulation in GUI mode, bind the exact history, export waveforms
• 07_ensure_maestro_view.py — bootstrap a missing maestro cellview (maeOpenSetup + maeSaveSetup) before open_gui_session
• 08_set_simulator_mode.py — switch between APS / Spectre X (LX/MX/AX/VX/CX) / Spectre FX via asiSetHighPerformanceOptionVal
• 09_export_sweep_subpoints.py — pull per-sweep-point waveforms via OCEAN openResults(<abs path>) (works around maeOpenResults rejecting Interactive.N/M)

examples/01_virtuoso/veriloga/

• import_veriloga.py — turn a local .va file into a Cadence Verilog-A cellview via the 5-step IC618 path: placeholder schematic → symbol → veriloga skeleton → upload .va → reparse. This example covers the file/cellview interface only — the .va contents are out of scope; sample.va is a trivial placeholder.

examples/01_virtuoso/diagnostics/

• sniff_cdslck.py — walk a library tree and report .cdslck lock-file owners. Authoritative when SKILL-side session enumeration disagrees with on-disk reality.

examples/01_virtuoso/digital_import/

Hand off Genus/Innovus P&R products into a Virtuoso library. All three scripts wrap standalone Cadence batch tools (strmin / ihdl) via SKILL system() — no GUI forms, no manual bootstrap. See that folder's README.md for prerequisites, PDK-portability notes, and full CLI reference.

• import_gds.py — routed layout via strmin
• import_verilog.py — schematic + symbol via ihdl batch (the official CLI entry point for Verilog Import)
• add_power_labels.py — drop VDD/VSS labels on a routed layout by reflectively reading std-cell pin geometry (no --ref-cell needed, auto-discovers)

Common workflows

Find which library contains a cell

ddGetObj(cellName) with a single argument returns nil — must iterate ddGetLibList():

r = client.execute_skill(f'''
let((result)
  result = nil
  foreach(lib ddGetLibList()
    when(ddGetObj(lib~>name "{CELL}")
      result = cons(lib~>name result)))
  result)
''')
# r.output e.g. '("2025_FIA")'

No need for a separate script — inline in any workflow that needs to locate a cell before operating on it.

Create a schematic

from virtuoso_bridge.virtuoso.schematic import (
    schematic_create_inst_by_master_name as inst,
    schematic_create_pin as pin,
)

with client.schematic.create(LIB, CELL) as sch:
    # 1. Place instances — sch.add() queues SKILL commands
    sch.add(inst("tsmcN28", "pch_mac", "symbol", "MP0", 0, 1.5, "R0"))
    sch.add(inst("tsmcN28", "nch_mac", "symbol", "MN0", 0, 0, "R0"))

    # 2. Label MOS terminals with stubs — NOT manual add_wire
    sch.add_net_label_to_transistor("MP0",
        drain_net="OUT", gate_net="IN", source_net="VDD", body_net="VDD")
    sch.add_net_label_to_transistor("MN0",
        drain_net="OUT", gate_net="IN", source_net="VSS", body_net="VSS")

    # 3. Add pins at circuit EDGE, not on terminals
    sch.add(pin("IN",  -1.0, 0.75, "R0", direction="input"))
    sch.add(pin("OUT", -1.0, 0.25, "R0", direction="output"))
    # schCheck + dbSave happen automatically on context exit

Key rules:

• Use add_net_label_to_transistor for MOS D/G/S/B — it auto-detects stub direction. Never manually add_wire between terminals.

• Pins go at the circuit edge, not on instance terminals. They connect via matching net names.

• Delete before recreate — if the cell already exists, add_instance accumulates on top of old instances:

  client.execute_skill(f'ddDeleteObj(ddGetObj("{LIB}" "{CELL}"))')
  

• CDF parameters — two-step process:

  Step 1: Set values with schHiReplace (Edit > Replace). Do NOT use param~>value = or dbSetq — they don't update display or derived params.

  client.execute_skill(
      'schHiReplace(?replaceAll t ?propName "cellName" ?condOp "==" '
      '?propValue "pch_mac" ?newPropName "w" ?newPropValue "500n")')
  

  Step 2: Trigger CDF callbacks with CCSinvokeCdfCallbacks to update derived parameters (finger_width, display annotations, etc.). Use ?order to run only the changed params — running all callbacks may fail on PDK-specific variables like mdlDir.

  # Must load CCSinvokeCdfCallbacks.il first (one-time)
  client.upload_file("reference/CCSinvokeCdfCallbacks.il", "/tmp/CCSinvokeCdfCallbacks.il")
  client.execute_skill('load("/tmp/CCSinvokeCdfCallbacks.il")')
  
  # Trigger only the callbacks you need
  client.execute_skill('CCSinvokeCdfCallbacks(geGetEditCellView() ?order list("fingers"))')
  

  Critical: PDK devices have nf as read-only. Use fingers instead:

  # ✅ "fingers" is editable, "nf" is not
  client.execute_skill(
      'schHiReplace(?replaceAll t ?propName "cellName" ?condOp "==" '
      '?propValue "pch_mac" ?newPropName "fingers" ?newPropValue "4")')
  
  # ❌ schHiReplace(...?newPropName "nf" ...) → SCH-1725 "not editable"
  

  Why two steps: schHiReplace changes the stored property but does NOT trigger CDF callbacks. Without callbacks, derived params (finger_width, m_ov_nf annotations) stay stale. CCSinvokeCdfCallbacks(?order ...) triggers only the specified callbacks, avoiding PDK errors from unrelated callbacks.

  Or use the Python wrapper which handles both steps:

  from virtuoso_bridge.virtuoso.schematic.params import set_instance_params
  set_instance_params(client, "MP0", w="500n", l="30n", nf="4", m="2")
  

Read a design (schematic + maestro + netlist)

Always use the Python API functions below. Do NOT hand-write SKILL for reading.

from virtuoso_bridge import VirtuosoClient, decode_skill_output
client = VirtuosoClient.from_env()
LIB, CELL = "myLib", "myCell"

# 1. Schematic — default: topology only (no positions/geometry)
data = client.schematic.read(LIB, CELL, include_positions=False)
# data = {
#     "instances": [{"name", "lib", "cell", "numInst", "view",
#                    "params": {...}, "terms": {...}}, ...],
#     "nets": {"VN1": {"connections": ["M0.D", ...], "numBits": 1,
#                       "sigType": "signal", "isGlobal": false}, ...},
#     "pins": {"VINP": {"direction": "input", "numBits": 1}, ...},
#     "notes": [{"text": "...", ...}, ...]
# }

# With positions (only when you need xy/bBox, e.g. for layout-aware editing):
data_with_pos = client.schematic.read(LIB, CELL, include_positions=True)

# No CDF param filtering (return all 200+ PDK params):
raw = client.schematic.read(LIB, CELL, include_positions=False, param_filters=None)

# 2. Maestro — snapshot the focused window
#
# PREFER THE CLI for one-shot captures.  The CLI handles venv + client
# construction, and on-disk output is everything you need for
# analysis (state XMLs, SKILL probe text, per-point psf/* results,
# .rdb, netlist/).  Python for this case is pure boilerplate.
#
#   $ virtuoso-bridge snapshot -o output/
#
# Use the Python API only when snapshot is one step in a larger
# same-connection pipeline (e.g. client.maestro.open_session →
# client.maestro.snapshot → client.maestro.run_simulation →
# client.maestro.close_session, or a loop over many cells):
d = client.maestro.snapshot()                             # SKILL-only, ~150ms, 1 round-trip
# d["raw_sections"] = [(probe_skill_text, raw_output), ...]
#   Each label IS the actual SKILL string we ran (e.g.
#   'maeGetAnalysis("test" "ac" ?session "fnxSession18")');
#   value is the verbatim SKILL alist — no Python parsing.
# d also has session / lib / cell / view / mode / unsaved.

# Full disk dump (raw + YAML-filtered XMLs + 16 SKILL probes + per-point
# inputs + spectre results + .rdb):
d = client.maestro.snapshot(output_root="output/")      # → d["output_dir"]

# IMPORTANT: snapshot() always uses the CURRENTLY FOCUSED maestro window.
# Click the desired ADE Assembler first, or use client.maestro.open_session() to bring it up.

# Rule of thumb: one-shot inspection → CLI; multi-step pipeline → Python.

# 3. Netlist — generate from maestro session, download via SSH
session = client.maestro.open_session(LIB, CELL)
test = decode_skill_output(
    client.execute_skill(f'car(maeGetSetup(?session "{session}"))').output)
client.execute_skill(
    f'maeCreateNetlistForCorner("{test}" "Nominal" "/tmp/nl_{CELL}" ?session "{session}")')
client.download_file(f"/tmp/nl_{CELL}/netlist/input.scs", "output/netlist.scs")
client.maestro.close_session(session)

Run a simulation

Follow this sequence exactly. Do not skip steps.

session = "fnxSession33"  # from find_open_session() or maeGetSessions()

# 1. Set variables
client.execute_skill(f'maeSetVar("CL" "1p" ?session "{session}")')

# 2. Save before running — REQUIRED, skipping causes stale state
client.execute_skill(
    f'maeSaveSetup(?lib "{LIB}" ?cell "{CELL}" ?view "maestro" ?session "{session}")')

# 3. Start + wait without blocking the SKILL channel. The timeout is one
#    end-to-end budget for Maestro to accept the run and for completion polling.
history, status = client.maestro.run_and_wait(session=session, timeout=300)
history = history.strip('"')

# 4. Read every point/output from the exact history returned above.
results = client.maestro.read_results(
    session, lib=LIB, cell=CELL, history=history,
)

# 5. If run_and_wait times out while a modal is visible, recover outside the
#    blocked SKILL channel, then diagnose before deciding whether to rerun:
#    $ virtuoso-bridge dismiss-dialog
#    $ virtuoso-bridge list-windows --top-level --json
#    $ virtuoso-bridge dismiss-window WINDOW_ID --action enter

Output read/export guardrails (collision-safe)

Apply these rules whenever you read or export any maestro output (scalar or waveform):

1. History binding is mandatory

   • Always use the exact history returned by maeRunSimulation().
   • Pass that history explicitly to result readers/exporters (for example, read_results(..., history=history) and export_waveform(..., history=history)).
   • Do not rely on "latest" history inference when reproducibility matters.

2. Remote filename must be unique per export

   • Never use a fixed /tmp/vb_wave_xxx.txt path.
   • Use unique naming such as /tmp/vb_wave_<history>_<timestamp>_<nonce>.txt.
   • This avoids collisions with stale files from previous runs or other users.

3. Bind results directory to the same history before ocnPrint

   • After maeOpenResults(?history ...), verify the resolved resultsDir contains /<history>/.
   • If mismatch is detected, stop and raise an error instead of exporting the wrong waveform.

In optimization loops: add maeSaveSetup and dialog-recovery in every iteration. GUI dialogs ("Specify history name", "No analyses enabled") block the entire SKILL channel — all subsequent execute_skill calls will timeout until the dialog is dismissed.

Debug with screenshots: if simulation appears stuck or results are unexpected, use the X11/CLI path so capture does not depend on a responsive SKILL channel:

virtuoso-bridge list-windows --top-level --json
virtuoso-bridge screenshot maestro -o output/debug_maestro.png

This reveals dialog boxes, error messages, or unexpected variable values that are invisible through the SKILL channel alone.

Root Cause: Why maeGetOutputValue returns nil for computed expressions

Symptom: maeGetOutputValue("bandwidth(...)" testName) returns nil, but maeGetOutputValue("Noise_rms_out" testName) returns a value.

Root Cause: The PSF directory contains no actual waveform data files. Check with:

# SSH to remote and check PSF directory
ssh user@compute-host "ls /path/to/results/Interactive.N/psf/<test>/psf/"
# Expected: .raw, simdata, spectre.log files
# Actual: only spectre.out, variables_file (NO waveform data!)

Why this happens:

• Maestro saves only pre-computed scalar outputs (like Noise_rms_out) to the RDB
• Raw waveforms (VOUT, VSIN signals) are NOT saved to PSF unless "save=all" is enabled
• Computed expressions (bandwidth, dB20, value) need the waveform data to calculate — returns nil

Check the RDB directly:

ssh user@compute-host "sqlite3 /path/to/Interactive.N.rdb 'SELECT * FROM resultValue'"
# Returns rows like:
# 1|7|0.000469         -> Noise_rms_out scalar (saved)
# 1|8|wave             -> VF(/VOUT)/VF(/VSIN) is a waveform reference, not saved!

Solution: Enable "save all" option before running simulation:

client.execute_skill(f'maeSetEnvOption("{test}" ?option "save" ?value "all")')
client.execute_skill('maeSaveSetup()')

Reliable Result Reading: Parse the Log File

When Maestro OCEAN functions fail (due to missing PSF waveform data), parse the .log file:

def read_maestro_results_from_log(client, LIB, CELL, history):
    """Read simulation results from the log file - most reliable method."""

    # Resolve the OA library path via SKILL — works on any setup,
    # no hardcoded ``/home/USER/...`` assumption.
    r = client.execute_skill(f'ddGetObj("{LIB}")~>readPath')
    lib_path = (r.output or "").strip().strip('"')
    log_path = f"{lib_path}/{CELL}/maestro/results/maestro/{history}.log"
    client.download_file(log_path, "/tmp/sim.log")
    
    # Parse tab-separated format: "expression\t\tvalue"
    results = {}
    with open("/tmp/sim.log") as f:
        for line in f:
            if "\t\t" in line:
                parts = line.rstrip().split("\t\t")
                if len(parts) >= 2:
                    name = parts[0].strip()
                    value = parts[1].strip()
                    # Skip header lines
                    if name and value and "corner" not in name.lower():
                        results[name] = value
    return results

# Full workflow:
from virtuoso_bridge import VirtuosoClient
client = VirtuosoClient.from_env()
LIB, CELL = "PLAYGROUND_AMP", "TB_AMP_5T_D2S_DC_AC"

session = client.maestro.open_gui_session(LIB, CELL)  # GUI mode required for results
history, _ = client.maestro.run_and_wait(session=session, timeout=300)
h = history.strip('"')

results = read_maestro_results_from_log(client, LIB, CELL, h)
print(results)
# {'bandwidth(...)': '1.64M', 'dB20(...)': '10.93', ...}

client.maestro.close_gui_session(session, save=False)

Log format in the file:

bandwidth(abs((VF("/VOUT") / VF("/VSIN"))) 3 "low")		1.64M
dB20(value(abs((VF("/VOUT") / VF("/VSIN"))) 10000))		10.93
value(abs((VF("/VOUT") / VF("/VSIN"))) 10000)		3.519
Noise_rms_out						469u

SKILL channel timeout — diagnosis and recovery

When execute_skill() times out, possible causes:

Dialog recovery (bypasses SKILL, uses X11 directly):

# Find and dismiss all blocking Virtuoso dialogs
virtuoso-bridge dismiss-dialog

# Inspect X11 windows and dismiss one explicitly
virtuoso-bridge list-windows --top-level --json
virtuoso-bridge dismiss-window 0x4203583 --action enter

# From Python
client.dismiss_dialog()

Uses xwininfo to find virtuoso-owned dialog windows and XTestFakeKeyEvent to send the requested key action. Works even when the SKILL channel is completely stuck.

Prevention: Always dbSave(cv) before hiCloseWindow(win). Never use ?waitUntilDone t in simulation calls. Add dialog-recovery in simulation loops (see "Run a simulation" section).

Related skills

• spectre — standalone netlist-driven Spectre simulation (no Virtuoso GUI). Use when the user has a .scs netlist and wants to run it directly.