From fd822e07cee74bd37eec272ca49f6bae6256080f Mon Sep 17 00:00:00 2001 From: Ryan Malloy Date: Fri, 13 Feb 2026 07:09:53 -0700 Subject: [PATCH] Expand README with output examples, BOM docs, architecture diagram Add real YAML/CSV output examples generated from test fixtures, document --bom/--bom-wiring flags, layout optimization, inspection commands, and LTspice --ltspice-exe option. --- README.md | 297 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 274 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 1e9665a..f45f2fd 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,8 @@ Two operating modes: - **Single module** -- External interface of one subcircuit (its connectors, test points, port interface) - **Inter-module** -- How multiple subcircuits/boards connect to each other +It also produces **Bill of Materials** output as CSV, and includes layout optimization to minimize cable crossings in rendered diagrams. + ## Install ```bash @@ -25,43 +27,239 @@ For `.asc` file metadata extraction (optional): pip install spice2wireviz[asc] ``` -## Usage - -### From netlist files +## Quick start ```bash # Inter-module wiring (auto-detected from top-level X instances) -spice2wireviz top_level.net -o wiring.yml --render +spice2wireviz top_level.net -o wiring.yml # Single module external interface spice2wireviz design.net -s amplifier_board -o amp.yml -# Only connectors and test points, no ground -spice2wireviz design.net --include-prefixes J,TP --no-ground +# Render to SVG/PNG/HTML (requires WireViz installed) +spice2wireviz design.net -o wiring.yml --render --format sph -# Inspect before converting -spice2wireviz design.net --list-subcircuits -spice2wireviz design.net --list-components -spice2wireviz design.net --dry-run +# Component bill of materials +spice2wireviz design.net --bom + +# Wiring bill of materials (cables, wire counts, endpoints) +spice2wireviz top_level.net --bom-wiring ``` -### From .asc schematics +## Output examples -LTspice `.asc` files are supported with tiered netlist resolution: +### Input: SPICE netlist -1. **Companion netlist** (automatic) -- If a `.net`, `.cir`, or `.sp` file exists alongside the `.asc` (same basename), it's used for full connectivity. LTspice generates these automatically when you run a simulation. -2. **LTspice generation** (opt-in) -- Pass `--generate-netlist` to invoke LTspice and produce a `.net` file. -3. **Metadata only** -- Without a netlist, only component refs/values are available. Diagram generation is blocked, but `--list-components` still works. +A multi-board system with power supply, amplifier, and I/O board: + +```spice +.subckt power_supply VCC GND +J1 AC_IN AC_GND AC_INLET +.ends power_supply + +.subckt amplifier VIN GND VOUT +J1 VIN GND INPUT_CONN +TP1 VOUT +.ends amplifier + +.subckt io_board SIG_IN SIG_OUT GND CTRL +J1 SIG_IN SIG_OUT DB9_CONN +J2 CTRL GND CTRL_CONN +.ends io_board + +* Top-level instantiation +X1 VCC GND power_supply +X2 VCC GND AUDIO_OUT amplifier +X3 AUDIO_OUT CTRL_SIG GND ENABLE io_board + +* Top-level connectors +J_CHASSIS GND EARTH chassis_gnd +TP_VCC VCC +``` + +### Output: Inter-module WireViz YAML ```bash -# .asc with companion .net in the same directory -- works like .net input -spice2wireviz schematic.asc -s amplifier_board -o amp.yml +spice2wireviz multi_board.net +``` -# No companion .net -- invoke LTspice to generate one -spice2wireviz schematic.asc --generate-netlist -o wiring.yml +```yaml +metadata: + title: 'Wiring diagram: multi_board' + source: multi_board.net + generator: spice2wireviz 2026.2.14 +connectors: + J_CHASSIS: + type: chassis_gnd + pinlabels: + - EARTH + - GND + notes: 'SPICE ref: J_CHASSIS' + TP_VCC: + type: TP + style: simple + pinlabels: + - VCC + notes: 'SPICE ref: TP_VCC' + X1: + type: power_supply + pinlabels: + - VCC + - GND + notes: 'SPICE instance: X1 (power_supply)' + X2: + type: amplifier + pinlabels: + - VIN + - GND + - VOUT + notes: 'SPICE instance: X2 (amplifier)' + X3: + type: io_board + pinlabels: + - GND + - SIG_IN + - SIG_OUT + - CTRL + notes: 'SPICE instance: X3 (io_board)' +cables: + W1: + colors: + - BK + wirelabels: + - GND + W3: + colors: + - RD + wirelabels: + - VCC + W5: + category: bundle + colors: + - BK + - RD + wirelabels: + - GND + - VCC + W8: + wirecount: 1 + wirelabels: + - AUDIO_OUT +connections: +- - TP_VCC: 1 + - W3: 1 + - X1: 1 +- - X1: [2, 1] + - W5: [1, 2] + - X2: [2, 1] +- - X2: 3 + - W8: 1 + - X3: 2 +``` -# Inspect component metadata (no .net required) -spice2wireviz schematic.asc --list-components +Every connector includes a `notes` field tracing back to the original SPICE reference or instance. Ground wires are colored black (`BK`), power wires red (`RD`). Parallel wires between the same module pair are grouped into multi-wire cables (like `W5` above). + +### Output: Single-module WireViz YAML + +```bash +spice2wireviz simple_board.net -s amplifier_board +``` + +```yaml +connectors: + amplifier_board: + type: Module Interface + pinlabels: + - VIN + - GND + - VOUT + - SIGNAL_IN + notes: 'SPICE subcircuit: .subckt amplifier_board' + J1: + type: PWR_CONN + pinlabels: + - VIN + - GND + J2: + type: SIG_CONN + pinlabels: + - VOUT + - SIGNAL_IN + TP1: + type: TP + style: simple + pinlabels: + - N001 +cables: + W_J1: + category: bundle + colors: ['', BK] + wirelabels: [VIN, GND] + W_J2: + category: bundle + wirecount: 2 + wirelabels: [VOUT, SIGNAL_IN] +connections: +- - amplifier_board: [1, 2] + - W_J1: [1, 2] + - J1: [1, 2] +- - amplifier_board: [3, 4] + - W_J2: [1, 2] + - J2: [1, 2] +``` + +Single-module mode generates a central "module header" connector representing the subcircuit's port interface, with star-topology cables radiating out to each boundary component (J*, TP*, P*). + +### Output: Component BOM + +```bash +spice2wireviz simple_board.net --bom +``` + +```csv +Reference,Prefix,Value,Pins,Subcircuit,Attributes +J1,J,PWR_CONN,2,amplifier_board, +J2,J,SIG_CONN,2,amplifier_board, +TP1,TP,,1,amplifier_board, +``` + +Component BOM lists all boundary components (connectors, test points) with their reference, value, pin count, and which subcircuit they belong to. Works even on `.asc` files without connectivity data. + +### Output: Wiring BOM + +```bash +spice2wireviz multi_board.net --bom-wiring +``` + +```csv +Cable,Wirecount,Nets,From,To +W1,1,GND,J_CHASSIS,X1 +W3,1,VCC,TP_VCC,X1 +W5,2,"GND, VCC",X1,X2 +W6,1,GND,X1,X3 +W8,1,AUDIO_OUT,X2,X3 +``` + +Wiring BOM lists every cable with wire count, net names, and connected endpoints. Useful for generating cut lists and wire pull schedules. + +## Inspection commands + +Preview what's in a netlist before generating diagrams: + +```bash +# List subcircuit definitions +$ spice2wireviz multi_board.net --list-subcircuits + amplifier: ports=[VIN, GND, VOUT], boundary_components=2 + io_board: ports=[SIG_IN, SIG_OUT, GND, CTRL], boundary_components=2 + power_supply: ports=[VCC, GND], boundary_components=1 + +# Dry run (connector/cable/connection counts) +$ spice2wireviz multi_board.net --dry-run +Mode: inter +Connectors: 5 +Cables: 5 +Connection sets: 5 +Connector names: J_CHASSIS, TP_VCC, X1, X2, X3 ``` ## Filtering @@ -69,21 +267,74 @@ spice2wireviz schematic.asc --list-components Cherry-pick what appears in the diagram: ```bash ---include-prefixes J,TP # Only these component types +--include-prefixes J,TP # Only these component types (default: J,TP,P,X) +--exclude-prefixes X # Hide subcircuit modules --exclude-refs X3,J_DEBUG # Hide specific references --include-nets "SIG_*" # Glob patterns for net names +--exclude-nets "*_DEBUG" # Exclude debug nets --no-ground # Hide GND connections --no-power # Hide VCC/VDD connections +--no-group # Don't bundle parallel wires into multi-wire cables ``` +## LTspice .asc support + +LTspice `.asc` schematic files are supported with tiered netlist resolution: + +1. **Companion netlist** (automatic) -- If a `.net`, `.cir`, or `.sp` file exists alongside the `.asc` (same basename), it's used for full connectivity. LTspice generates these automatically when you run a simulation. +2. **LTspice generation** (opt-in) -- Pass `--generate-netlist` to invoke LTspice and produce a `.net` file. Use `--ltspice-exe` to specify the LTspice binary path if it's not auto-detected. +3. **Metadata only** -- Without a netlist, only component refs/values are available. Diagram generation is blocked, but `--list-components` and `--bom` still work. + +```bash +# .asc with companion .net in the same directory +spice2wireviz schematic.asc -s amplifier_board -o amp.yml + +# No companion .net -- invoke LTspice to generate one +spice2wireviz schematic.asc --generate-netlist -o wiring.yml + +# Specify LTspice binary path (Linux/wine, macOS, Windows) +spice2wireviz schematic.asc --generate-netlist --ltspice-exe /path/to/ltspice + +# Component BOM from .asc (no .net required) +spice2wireviz schematic.asc --bom +``` + +## Layout optimization + +Both mappers apply layout optimization to minimize cable crossings in rendered diagrams: + +- **Inter-module**: Sugiyama-lite layered graph drawing -- external connectors are placed at the left edge, modules are layered by BFS distance, barycenter ordering reduces crossings, and pins are reordered to group connections to the same neighbor. +- **Single-module**: Star topology optimization -- boundary components are ordered by their connection pattern to the module header, header pins are grouped by target component, and pin sequences are parallelized. + +This is automatic and requires no configuration. + +## How it works + +``` +.net/.cir/.sp ─────┐ + ├─→ Parser ─→ ParsedNetlist ─→ Filters ─→ Mapper ─→ WireViz YAML +.asc (+ companion) ┘ │ │ + │ └─→ Wiring BOM CSV + └─→ Component BOM CSV +``` + +The parser extracts subcircuit definitions (`.subckt`), instances (`X*`), and boundary components (`J*`, `TP*`, `P*`) from SPICE netlists. Filters remove unwanted elements. The mapper converts the remaining structure into WireViz connector/cable/connection format. The emitter serializes to deterministic YAML (byte-identical output for identical input) or CSV. + ## Development ```bash uv sync --extra dev --extra asc -uv run pytest +uv run pytest # 188 tests uv run ruff check src/ tests/ ``` +LTspice integration tests require LTspice installed and are marked: + +```bash +uv run pytest -m ltspice # Run only LTspice tests +uv run pytest -m "not ltspice" # Skip LTspice tests (CI default) +``` + ## Repository [git.supported.systems/warehack.ing/spice2wireviz](https://git.supported.systems/warehack.ing/spice2wireviz)