Agentic Spice Circuit Dev Environment

Agentic Spice is a Docker-first Ngspice + Python-wrapped SPICE workspace for building, editing, profiling, and visualizing circuits from Python.

The project is designed so AI agents can turn SPICE circuit build, evaluate, and optimize loops into ordinary Python coding tasks: edit circuit netlists, run Ngspice simulations, parse raw results, compute figures of merit, and generate plots inside one reproducible container.

The normal development workflow is fully containerized. You do not need to install ngspice on your host machine.

What Is Included

• Python distribution: agentic-spice
• Python package: agentic_spice
• Containerized simulator: ngspice, installed in the Docker image
• Python simulation wrapper: run_netlist(...)
• Raw-result parsing, CSV export, custom analysis scripts, and plotting support
• Project-scoped examples under examples/<project>/
• Circuit knowledge markdown for RAG under docs/
• Notebook schematic visualization with Schemdraw
• Optional JupyterLab service through Docker Compose
• Docker Compose workflow for tests, examples, and notebooks

Quick Start With Docker

Build the image:

make build

Verify the simulator packaged inside the image:

make ngspice-version

Run the example simulation:

make example

Run tests:

make test

Run lint:

make lint

Open a development shell:

make shell

Start JupyterLab:

make notebook

Then open:

http://localhost:8888

The notebook service is only enabled through the Compose notebook profile, so the default container stays focused on scripts, tests, and deployable command-line workflows.

Docker-First Workflow

The Makefile is host-facing and runs project commands inside Docker by default. Host-level Python and host-level ngspice are not part of the normal workflow. If you open an interactive container shell, the same targets fall back to local container execution.

Project Commands

Docker-first commands from the host:

make build             # build the Docker image
make ngspice-version   # verify the containerized simulator
make test              # run pytest in Docker
make lint              # run ruff in Docker
make example           # run the default RC low-pass netlist
make notebook-check    # execute the notebook in Docker
make notebook          # start JupyterLab on localhost:8888
make shell             # open an interactive /bin/sh in Docker
make bash              # open bash in Docker
make root-shell        # open a root shell for package/debug work
make debug-shell       # open a shell with service ports enabled
make clean             # remove generated outputs through Docker
make down              # stop/remove the Compose network

Run any netlist dynamically:

make run-netlist NETLIST=examples/rc_lowpass/circuits/rc_lowpass.cir OUT=results/rc_lowpass

Run any example script dynamically:

make run-script SCRIPT=examples/opa4991_noninverting_amp/scripts/plot_opa4991_power_amp.py

Example Layout

Each example project owns its files:

examples/
  rc_lowpass/
    readme.md
    circuits/
      rc_lowpass.cir
  opa4991_noninverting_amp/
    readme.md
    circuits/
      opa4991_noninverting_power_amp.cir
      opa4991_noninverting_power_amp_square.cir
    scripts/
      plot_opa4991_power_amp.py

New user-added cases should follow the same structure and can be run through make run-netlist or make run-script instead of adding one-off Make targets.

OPA4991 Non-Inverting Amp Example

examples/opa4991_noninverting_amp/circuits/opa4991_noninverting_power_amp.cir simulates one OPA4991 channel as a single-supply, non-inverting power output stage with a sine input for spectrum inspection. examples/opa4991_noninverting_amp/circuits/opa4991_noninverting_power_amp_square.cir uses the same stage with a 0 to 2.5 V square-wave input for rise/fall timing. The concrete case matches the 12 V full-scale option in the reference design: RG = 10 kOhm, RF = 38 kOhm, gain G = 4.8, +15 V supply, and 600 Ohm load.

The TI files used for the model and documentation are downloaded under vendor/ti/opa4991/:

• opa4991_datasheet.pdf from https://www.ti.com/lit/ds/symlink/opa4991.pdf
• opa2991.lib from the TI OPA2991/OPAx991 PSpice model ZIP, SBOMB49B
• opa2991_ngspice.lib, a small ngspice-compatible copy of the TI model with PSpice switch-model and boolean-expression syntax adapted

The plotting driver:

make run-script SCRIPT=examples/opa4991_noninverting_amp/scripts/plot_opa4991_power_amp.py

writes the simulation and visual outputs under results/opa4991_noninverting_amp/, including the schematic, aligned input/output waveform plot, aligned input/output sine-spectrum plot, microsecond-scale square-wave rise/fall timing plot, spectrum CSV, rise/fall timing CSV, rise/fall waveform CSV, ngspice .raw, parsed .csv, .log, and summary.json files.

Circuit Knowledge Docs

docs/ is reserved for markdown files used as circuit-knowledge RAG context for LLM agents. Keep entries retrieval-friendly: focused topics, explicit headings, SPICE snippets, simulation intent, expected measurements, and common gotchas.

Python API

from pathlib import Path
from agentic_spice import run_netlist, read_ascii_raw, write_raw_csv

result = run_netlist(
    Path("examples/rc_lowpass/circuits/rc_lowpass.cir"),
    Path("results/rc_lowpass"),
)

raw = read_ascii_raw(result.raw_path)
write_raw_csv(raw, Path("results/rc_lowpass/rc_lowpass.csv"))

run_netlist creates:

• *.raw: ngspice raw output, configured as ASCII by the generated wrapper
• *.log: ngspice log output
• summary.json: return code, diagnostics, measurements, and output paths
• *.csv: parsed raw traces when the raw file can be parsed

Notebook Schematic Workflow

notebooks/01_rc_lowpass_schematic.ipynb:

• draws the RC low-pass schematic with Schemdraw
• saves results/rc_lowpass/rc_lowpass.svg
• runs the matching ngspice netlist when executed in Docker
• plots the simulated frequency response
• falls back to the analytic RC response only when intentionally run outside Docker without ngspice

Deployment Notes

The Docker image installs ngspice from Debian packages for easy rebuilds and migration. This keeps development, notebook execution, and deployable command-line simulation on the same packaged simulator. If a project later needs a specific ngspice release or compile-time option, add a separate source-build Docker target and pin the release there.