# neurois3/modelngspicer architecture

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

- Interactive diagram: https://gitdiagram.com/neurois3/modelngspicer
- Repository: https://github.com/neurois3/modelngspicer

## Overview

##### Project type and purpose
- This is a desktop GUI application (“MODELngspicer”) built in Python, using PySide6 (Qt) for the interface and ngspice as its simulation engine.

##### File structure
Top-level directories:
- src/ – all Python source modules
- demo/ – example configurations, scripts and output summaries
- docs/ – user guide and LaTeX sources

Key configuration files:
- _config.yml (likely for CI or documentation build)
- demos’ config.ini – per-example SPICE settings
- run.bat / run.vbs – convenience launchers

##### README for additional insights
- Technology stack: Python 3.x, PySide6, ngspice
- Core features: parameter tuning UI, syntax‐highlighting code editor, real-time plots, light/dark themes, file save/load.

##### Main components and their relationships
a. UI Layer (Qt/PySide6)
- code_editor_window.py, code_editor.py, code_view.py, syntax_highlighter.py
- main_window.py, simulation_panel.py, summary_viewer.py, graph.py
- exponential_spinbox.py, parameter_table.py
- ui_manager.py orchestrates widget creation & theme switching
b. Core Logic / Controller
- ngspice_con.py: wraps invocation of ngspice processes, streams input/output
- parameter_io.py: read/write .ini and user settings
- path_utils.py: resolves file paths for scripts, outputs, resources
- app_version.py: version tagging for about dialogs or change logs
c. Data / Model
- In-memory representation of circuit parameters, simulation results
- Demo examples under demo/ provide real .spice scripts and summary.html
d. Visualization
- graph.py: real-time plotting (likely QtChart or matplotlib)
- summary_viewer.py: renders summary.html (using Qt WebEngine or QTextBrowser)
e. Resources

f. External Services
- ngspice binary (launched via ngspice_con.py)
- File system for reading/writing config and result files

##### Architectural patterns & design principles
- MVC-like separation:
- View = Qt widgets (views and editors)
- Controller = ui_manager + event-handler logic in main_window & simulation_panel
- Model = parameter_io + internal data structures holding simulation parameters/results
- Single monolithic process with asynchronous process calls to ngspice
- Resource management via centralized ui_manager and path_utils

##### Final checklist for the principal software engineer
- Interactions: user → UI → controller → ngspice → parser → UI.
- Resource loading and settings persistence.
- Architectural patterns used (MVC, process wrapper).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        CodeEditorWindow["code_editor_window.py"]:::ui
        CodeEditor["code_editor.py"]:::ui
        CodeView["code_view.py"]:::ui
        SyntaxHighlighter["syntax_highlighter.py"]:::ui
        MainWindow["main_window.py"]:::ui
        SimulationPanel["simulation_panel.py"]:::ui
        SummaryViewer["summary_viewer.py"]:::ui
        Graph["graph.py"]:::ui
        ExponentialSpinbox["exponential_spinbox.py"]:::ui
        ParameterTable["parameter_table.py"]:::ui
    end

    %% Core Logic / Controller
    subgraph "Core Logic / Controller"
        direction TB
        UIManager["ui_manager.py"]:::business
        NgspiceCon["ngspice_con.py"]:::business
        ParameterIO["parameter_io.py"]:::business
        PathUtils["path_utils.py"]:::business
        AppVersion["app_version.py"]:::business
    end

    %% Data Model Layer
    subgraph "Data Model Layer"
        direction TB
        DataModel["In-memory Model (parameters/results)"]:::data
    end

    %% External Process
    subgraph "Simulation Engine (External Process)"
        direction TB
        NgspiceBinary["ngspice binary"]:::external
    end

    %% Resources
    subgraph "Resource Store"
        direction TB
        Resources["src/resources (icons, stylesheets)"]:::resources
    end

    %% Demo Files
    subgraph "Demo Files"
        direction TB
        DemoFiles["demo/ (example scripts, summaries)"]:::resources
    end

    %% Connections
    MainWindow -->|"userActions()"| UIManager
    SimulationPanel -->|"runSimulation()"| UIManager
    UIManager -->|"spawn ngspice()"| NgspiceCon
    NgspiceCon -->|"spawnProcess()"| NgspiceBinary
    NgspiceBinary -->|"outputStream()"| NgspiceCon
    NgspiceCon -->|"rawOutput()"| UIManager
    UIManager -->|"parse & store"| DataModel
    UIManager -->|"updatePlot()"| Graph
    UIManager -->|"updateSummary()"| SummaryViewer
    UIManager -->|"loadSettings()"| ParameterIO
    UIManager -->|"saveSettings()"| ParameterIO
    MainWindow -->|"loadResources()"| Resources
    UIManager -->|"resolvePaths()"| PathUtils
    MainWindow -->|"showVersion()"| AppVersion
    DataModel -->|"provideData()"| SummaryViewer

    %% Click Events
    click CodeEditorWindow "https://github.com/neurois3/modelngspicer/blob/main/src/code_editor_window.py"
    click CodeEditor "https://github.com/neurois3/modelngspicer/blob/main/src/code_editor.py"
    click CodeView "https://github.com/neurois3/modelngspicer/blob/main/src/code_view.py"
    click SyntaxHighlighter "https://github.com/neurois3/modelngspicer/blob/main/src/syntax_highlighter.py"
    click MainWindow "https://github.com/neurois3/modelngspicer/blob/main/src/main_window.py"
    click SimulationPanel "https://github.com/neurois3/modelngspicer/blob/main/src/simulation_panel.py"
    click SummaryViewer "https://github.com/neurois3/modelngspicer/blob/main/src/summary_viewer.py"
    click Graph "https://github.com/neurois3/modelngspicer/blob/main/src/graph.py"
    click ExponentialSpinbox "https://github.com/neurois3/modelngspicer/blob/main/src/exponential_spinbox.py"
    click ParameterTable "https://github.com/neurois3/modelngspicer/blob/main/src/parameter_table.py"
    click UIManager "https://github.com/neurois3/modelngspicer/blob/main/src/ui_manager.py"
    click NgspiceCon "https://github.com/neurois3/modelngspicer/blob/main/src/ngspice_con.py"
    click ParameterIO "https://github.com/neurois3/modelngspicer/blob/main/src/parameter_io.py"
    click PathUtils "https://github.com/neurois3/modelngspicer/blob/main/src/path_utils.py"
    click AppVersion "https://github.com/neurois3/modelngspicer/blob/main/src/app_version.py"
    click Resources "https://github.com/neurois3/modelngspicer/tree/main/src/resources"
    click DemoFiles "https://github.com/neurois3/modelngspicer/tree/main/demo/"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0066CC
    classDef business fill:#D0FFD8,stroke:#009900
    classDef data fill:#FFF8B8,stroke:#CCA300
    classDef external fill:#FFD8D8,stroke:#CC0000
    classDef resources fill:#F0F0F0,stroke:#888888
```
