# pyspice-org/pyspice architecture

> Architecture diagram of the GitHub repository pyspice-org/pyspice, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pyspice-org/pyspice
- Repository: https://github.com/pyspice-org/pyspice

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "User Layer"
    U1["User Scripts / Notebooks"]:::cli
    U2["CLI Tools"]:::cli
  end

  subgraph "PySpice Core"
    subgraph "Config"
      ConfInstall["ConfigInstall"]:::internal
      LoggingYml["logging.yml"]:::internal
    end
    subgraph "DeviceLibrary"
      DeviceLib["DeviceLibrary"]:::internal
    end
    subgraph "Logging"
      CentralLog["Logging"]:::internal
    end
    subgraph "Math & Unit"
      Calculus["Calculus"]:::internal
      Unit["Unit"]:::internal
      SiUnits["SiUnits"]:::internal
    end
    subgraph "Physics"
      PhysConst["PhysicalConstants"]:::internal
      MatProps["MaterialProperties"]:::internal
      Resistor["Resistor"]:::internal
      SemiCond["SemiConductor"]:::internal
    end
    subgraph "Plot & Probe"
      Bode["BodeDiagram"]:::internal
      Plot["Plot"]:::internal
      WaveForm["WaveForm"]:::internal
    end
    subgraph "Spice Core"
      BE["BasicElement"]:::internal
      HE["HighLevelElement"]:::internal
      EP["ElementParameter"]:::internal
      Netlist["Netlist"]:::internal
      Ast["Ast"]:::internal
      ParserExpr["Parser"]:::internal
      ParserGen["Parser"]:::internal
      ParserJmgc["Parser_jmgc"]:::internal
      SimulationAbs["Simulation"]:::internal
      LibReg["Library"]:::internal
      RawFileGen["RawFile"]:::internal
    end
    subgraph "Scripts"
      Cir2pyScript["cir2py.py"]:::cli
      PostInstall["pyspice_post_installation.py"]:::cli
      BinCir2py["bin/cir2py"]:::cli
      BinPostInstall["bin/pyspice-post-installation"]:::cli
    end
    subgraph "Tools"
      FileTool["File"]:::internal
      PathTool["Path"]:::internal
      StringTool["StringTools"]:::internal
      EnumFactory["EnumFactory"]:::internal
    end
  end

  subgraph "Simulator Adapters"
    subgraph "NgSpiceShared"
      NgShared["Shared"]:::internal
      NgServer["Server"]:::internal
      NgSim["Simulation"]:::internal
      NgSimType["SimulationType"]:::internal
      NgRaw["RawFile"]:::internal
      ApiH["api.h"]:::internal
    end
    subgraph "Xyce"
      XyServer["Server"]:::internal
      XySim["Simulation"]:::internal
      XyRaw["RawFile"]:::internal
    end
  end

  subgraph "External Simulators"
    NgspiceExe["Ngspice"]:::externalEngine
    XyceExe["Xyce"]:::externalEngine
  end

  subgraph "External Libraries"
    CFFI["CFFI"]:::thirdparty
    NumPy["NumPy"]:::thirdparty
    MatPlot["Matplotlib"]:::thirdparty
    Pint["Pint"]:::thirdparty
    KiCad["KiCad"]:::thirdparty
  end

  subgraph "Data Wrapping & Plotting"
    ProbeWave["Waveform Parser"]:::internal
    NumArr["NumPy Arrays"]:::thirdparty
    PlotLayer["Plot Layer"]:::internal
  end

  U1 --> BE
  U2 --> Cir2pyScript
  U2 --> PostInstall

  HE --> BE
  EP --> HE
  BE --> Netlist
  Netlist --> ParserGen
  ParserGen --> Ast
  ParserGen --> ParserExpr
  ParserGen --> ParserJmgc
  ParserExpr --> Ast

  SimulationAbs --> NgShared
  SimulationAbs --> XyServer

  NgShared --> NgServer
  NgServer --> NgspiceExe
  NgShared --> CFFI

  XyServer --> XyceExe

  NgspiceExe --> NgRaw
  XyceExe --> XyRaw

  NgRaw --> ProbeWave
  XyRaw --> ProbeWave

  ProbeWave --> Unit
  Unit --> NumArr
  NumArr --> PlotLayer
  PlotLayer --> MatPlot

  DeviceLib --> LibReg

  ConfInstall --> CentralLog
  LoggingYml --> CentralLog

  Calculus --> Unit
  SiUnits --> Unit

  PhysConst --> DeviceLib
  MatProps --> DeviceLib
  Resistor --> PhysConst
  SemiCond --> PhysConst

  FileTool --> ParserGen
  PathTool --> ParserGen
  StringTool --> ParserGen
  EnumFactory --> ParserGen

  click ConfInstall "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Config/ConfigInstall.py"
  click LoggingYml "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Config/logging.yml"
  click DeviceLib "https://github.com/pyspice-org/pyspice/blob/master/PySpice/DeviceLibrary/__init__.py"
  click CentralLog "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Logging/Logging.py"
  click Calculus "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Math/Calculus.py"
  click Unit "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Unit/Unit.py"
  click SiUnits "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Unit/SiUnits.py"
  click PhysConst "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Physics/PhysicalConstants.py"
  click MatProps "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Physics/MaterialProperties.py"
  click Resistor "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Physics/Resistor.py"
  click SemiCond "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Physics/SemiConductor.py"
  click Bode "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Plot/BodeDiagram.py"
  click Plot "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Probe/Plot.py"
  click WaveForm "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Probe/WaveForm.py"
  click BE "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Spice/BasicElement.py"
  click HE "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Spice/HighLevelElement.py"
  click EP "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Spice/ElementParameter.py"
  click Netlist "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Spice/Netlist.py"
  click Ast "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Spice/Expression/Ast.py"
  click ParserExpr "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Spice/Expression/Parser.py"
  click ParserGen "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Spice/Parser.py"
  click ParserJmgc "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Spice/Parser_jmgc.py"
  click SimulationAbs "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Spice/Simulation.py"
  click NgShared "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Spice/NgSpice/Shared.py"
  click NgServer "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Spice/NgSpice/Server.py"
  click NgSim "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Spice/NgSpice/Simulation.py"
  click NgSimType "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Spice/NgSpice/SimulationType.py"
  click NgRaw "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Spice/NgSpice/RawFile.py"
  click ApiH "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Spice/NgSpice/api.h"
  click XyServer "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Spice/Xyce/Server.py"
  click XySim "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Spice/Xyce/Simulation.py"
  click XyRaw "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Spice/Xyce/RawFile.py"
  click RawFileGen "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Spice/RawFile.py"
  click LibReg "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Spice/Library.py"
  click Cir2pyScript "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Scripts/cir2py.py"
  click PostInstall "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Scripts/pyspice_post_installation.py"
  click BinCir2py "https://github.com/pyspice-org/pyspice/tree/master/bin/cir2py"
  click BinPostInstall "https://github.com/pyspice-org/pyspice/tree/master/bin/pyspice-post-installation"
  click FileTool "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Tools/File.py"
  click PathTool "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Tools/Path.py"
  click StringTool "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Tools/StringTools.py"
  click EnumFactory "https://github.com/pyspice-org/pyspice/blob/master/PySpice/Tools/EnumFactory.py"

  classDef internal fill:#ADD8E6
  classDef externalEngine fill:#90EE90
  classDef thirdparty fill:#FFFF99
  classDef cli fill:#D3D3D3
```
