spice2wireviz/README.md

# spice2wireviz

Convert LTspice SPICE netlists to WireViz wiring diagrams.

## What it does

`spice2wireviz` reads SPICE netlist files (`.net`, `.cir`, `.sp`) and LTspice schematics (`.asc`) and generates [WireViz](https://github.com/wireviz/WireViz) YAML that documents the physical wiring: connectors, test points, and inter-module cables.

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

## Install

```bash
uv tool install spice2wireviz
# or
pip install spice2wireviz
```

For `.asc` file metadata extraction (optional):

```bash
pip install spice2wireviz[asc]
```

## Usage

### From netlist files

```bash
# Inter-module wiring (auto-detected from top-level X instances)
spice2wireviz top_level.net -o wiring.yml --render

# 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

# Inspect before converting
spice2wireviz design.net --list-subcircuits
spice2wireviz design.net --list-components
spice2wireviz design.net --dry-run
```

### From .asc schematics

LTspice `.asc` 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.
3. **Metadata only** -- Without a netlist, only component refs/values are available. Diagram generation is blocked, but `--list-components` still works.

```bash
# .asc with companion .net in the same directory -- works like .net input
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

# Inspect component metadata (no .net required)
spice2wireviz schematic.asc --list-components
```

## Filtering

Cherry-pick what appears in the diagram:

```bash
--include-prefixes J,TP     # Only these component types
--exclude-refs X3,J_DEBUG   # Hide specific references
--include-nets "SIG_*"      # Glob patterns for net names
--no-ground                 # Hide GND connections
--no-power                  # Hide VCC/VDD connections
```

## Development

```bash
uv sync --extra dev --extra asc
uv run pytest
uv run ruff check src/ tests/
```

## Repository

[git.supported.systems/warehack.ing/spice2wireviz](https://git.supported.systems/warehack.ing/spice2wireviz)