How pyspice-org/pyspice works
Project type and purpose
• PySpice is an open‑source Python library and CLI toolset to interface Python with the Ngspice and Xyce circuit simulators.
• It provides:
• A high‑level, object‑oriented Python API to define electronic circuits
• A SPICE netlist parser (AST-based)
• CFFI-based bindings to the Ngspice shared library and to Xyce
• Data‑wrapping into NumPy arrays, unit handling, plotting with Matplotlib
• Helper scripts (cir2py, post‑install, documentation generator)
Architectural overview from file structure
• Top‑level “PySpice” package subdivided into subpackages:
• Config: installation and logging configuration
• DeviceLibrary: collections of SPICE device models
• Logging: centralized logging setup
• Math & Unit: calculus helpers and SI‑unit support (Pint or custom)
• Physics: physical constants and device‑specific properties
• Plot & Probe: wrappers for Bode, waveform plotting
• Spice: core engine – BasicElement, HighLevelElement, Netlist, Parser, RawFile, Simulation, and subpackages for NgSpice and Xyce backends
• Scripts: CLI entry points (cir2py, post‑install)
• Tools: filesystem, string, enum utilities
• Surrounding ecosystem:
• Examples, documentation (Sphinx, Pelican), unit tests
• Dev infrastructure: CI workflows, tox, setup.py
Key insights from README
• Two simulation backends (Ngspice via CFFI and Xyce via subprocess)
• Partial SPICE netlist parser for integration with KiCad
• Layered API: high‑level circuit objects → low‑level netlist → external simulator → raw output → NumPy → plot
• Extensibility points: adding new devices, new backends, new parser rules
Main components and their relationships
a. User Layer
• Python user scripts or Jupyter notebooks
• CLI scripts (cir2py, check-installation)
b. PySpice Core API
• Circuit Building: HighLevelElement → BasicElement
• Netlist Generation: Netlist.py
• Expression AST & Parser: Spice/Expression/Ast.py + Parser.py
• Simulation Manager: Simulation.py (abstract)
• Simulator Plugins:
– NgSpiceShared: CFFI binding, Server, SimulationType
– Xyce: Server, Simulation
• Output Handling:
– RawFile parsers (NgSpice/Xyce) → Probe.WaveForm → Unit wrapping → NumPy arrays
• Plotting: Plot/BodeDiagram, Probe/Plot
• DeviceLibrary lookup and library support
• Configuration & Logging
c. External Dependencies
• CFFI for shared library binding
• Ngspice shared library or executable
• Xyce executable
• NumPy, Matplotlib, Pint (optional)
• KiCad integration via netlist parser
d. Support Infrastructure
• Documentation generators (Pyterate, Sphinx)
• Example repository and data sheets
• CI/CD workflows (GitHub Actions, Travis)
Architectural patterns and design principles
• Layered architecture:
[ User ] → [ High‑level API ] → [ Netlist/Parser layer ] → [ Simulator Adapter layer ] → [ External engine ]
→ [ Raw output layer ] → [ Data‑wrapping/Plot layer ]
• Plugin/Strategy pattern for simulator backends (Ngspice vs. Xyce)
• AST + Visitor pattern for SPICE expressions
• Separation of concerns: circuit definition, parsing, simulation, data handling, plotting
• Modular design to allow adding new devices, simulators, or parser rules