Add ngspice shared library support with unified error handling

Implements support for running simulations using the ngspice shared library
interface alongside the existing external process (QProcess) execution mode.

Key features:
- CMake options: WITH_NGSPICE_SHARED and WITH_EXTERNAL_SIMULATORS
- NgspiceShared wrapper class for libngspice API integration
- Unified SimulatorError enum for type-safe error handling across backends
- Conditional compilation supporting three build configurations:
  1. Both modes enabled (shared library priority, external fallback)
  2. Shared library only (WebAssembly/Emscripten compatible)
  3. External process only (traditional QProcess-based)
- No breaking changes to existing API

Implementation details:
- Created qucs/extsimkernels/ngspice_shared.{h,cpp} wrapper
- Modified AbstractSpiceKernel to conditionally compile QProcess code
- Updated Ngspice class to dispatch to appropriate backend
- Added SimulatorError enum with distinct codes for each backend
- Shared library errors use negative values, process errors positive
- Updated Xyce simulator for conditional QProcess support

All three build configurations tested and working on macOS.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: robtaylor

CLAUDE.md

@@ -0,0 +1,225 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## About Qucs-S
+
+Qucs-S is a graphical circuit simulator with support for multiple SPICE simulation kernels (Ngspice, Xyce, SpiceOpus) and the native Qucsator engine. It's a Qt6-based C++ application with extensive component libraries and visualization capabilities.
+
+## Build System
+
+### Building
+All builds use CMake with out-of-source builds required:
+
+```bash
+git submodule init
+git submodule update
+mkdir builddir
+cd builddir
+cmake .. -DCMAKE_INSTALL_PREFIX=/your_install_prefix/
+make
+make install
+```
+
+### Build Options
+
+#### Simulator Backend Configuration
+- **`WITH_NGSPICE_SHARED`** (default: OFF) - Enable ngspice shared library support
+  - When enabled, simulations use ngspice as a shared library (libngspice) instead of external process
+  - Requires libngspice development package installed
+  - Example: `cmake .. -DWITH_NGSPICE_SHARED=ON`
+  - Install on macOS: `brew install libngspice`
+  - Install on Ubuntu: `sudo apt-get install libngspice0-dev`
+
+- **`WITH_EXTERNAL_SIMULATORS`** (default: ON) - Enable external simulator support (QProcess-based)
+  - Traditional mode: runs simulators (ngspice, xyce, etc.) as external processes
+  - Can be disabled if only using shared library mode
+  - Example: `cmake .. -DWITH_EXTERNAL_SIMULATORS=OFF`
+
+Both options can be enabled simultaneously. Priority order: shared library → external process.
+
+### Dependencies
+- **Required**: Qt6 (Core, Gui, Widgets, Svg, SvgWidgets, Xml, PrintSupport, Charts), CMake, flex, bison, gperf, dos2unix, C++20 compiler
+- **Runtime**: ngspice (primary simulation kernel, or libngspice if using shared library mode)
+- **Optional**: libngspice (for WITH_NGSPICE_SHARED)
+
+### Running
+```bash
+cd /your_install_prefix/bin
+./qucs-s
+```
+
+### Testing
+Limited test coverage exists:
+```bash
+cd builddir
+ctest
+```
+
+Individual test executable: `builddir/qucs/geometry/test_geometry`
+
+## Code Organization
+
+### Main Application (`qucs/`)
+- **qucs.cpp/h**: Main application window (QucsApp class)
+- **schematic.cpp/h**: Schematic editor canvas and logic
+- **main.cpp**: Application entry point
+- **mouseactions.cpp**: Mouse interaction handling for schematic editor
+
+### Component System (`qucs/components/`)
+Contains 300+ component implementations. Each component typically has:
+- `.cpp` file with component logic and properties
+- `.h` file with class definition
+Components inherit from base Element class
+
+### Simulation Kernels (`qucs/extsimkernels/`)
+- **abstractspicekernel.cpp/h**: Base class for SPICE kernel interfaces
+  - Conditionally compiles QProcess code based on WITH_EXTERNAL_SIMULATORS
+  - Provides common netlist generation and output parsing
+- **ngspice.cpp/h**: Ngspice integration (primary kernel)
+  - Supports both external process (QProcess) and shared library modes
+  - Automatically selects mode based on build configuration
+- **ngspice_shared.cpp/h**: Ngspice shared library wrapper (when WITH_NGSPICE_SHARED enabled)
+  - Interfaces with libngspice via C API
+  - Implements callbacks for output, status, and data retrieval
+  - Emits Qt signals to integrate with existing architecture
+- **xyce.cpp/h**: Xyce simulator support
+- **spicecompat.cpp/h**: SPICE compatibility layer
+- **qucs2spice.cpp/h**: Qucs schematic to SPICE netlist converter
+
+### Visualization (`qucs/diagrams/`)
+- **diagram.cpp/h**: Base diagram/graph classes
+- **graph.cpp/h**: Data plotting
+- **marker.cpp/h**: Graph markers for measurements
+- **curvediagram.h**, **polardiagram.h**, etc.: Specialized plot types
+
+### Dialogs (`qucs/dialogs/`)
+Qt dialog implementations for settings, component properties, import/export, etc.
+
+### Utility Tools
+Separate GUI applications built alongside main app:
+- **qucs-filter/**: Filter design tool
+- **qucs-attenuator/**: Attenuator calculator
+- **qucs-transcalc/**: Transmission line calculator
+- **qucs-activefilter/**: Active filter design
+- **qucs-powercombining/**: Power combining calculator
+- **qucs-s-spar-viewer/**: S-parameter viewer
+
+### Libraries (`library/`)
+SPICE model libraries (`.lib` files) for various component types: BJT, MOSFETs, diodes, ICs, etc.
+
+### Geometry System (`qucs/geometry/`)
+Header-only geometry library for shapes and points. Has unit tests.
+
+## Code Style
+
+### C++ Standards
+- **C++20**: Standard for new code
+- **Qt6**: All Qt code uses Qt6 APIs
+- **Modern C++**: Prefer C++17/20 features over legacy approaches
+
+### Naming Conventions
+- **Variables/functions**: `camelCaseWithSmallFirstLetter`
+- **Classes**: CapitalizedCamelCase (Qt style)
+
+### Formatting
+- Use `clang-format` for all changes (config in `.clang-format`)
+- Format specific lines: `clang-format --lines=<start>:<end> path/to/file`
+- Key settings: 80 column limit, 2-space indent, pointer-left (`int* ptr`), braces on same line
+- **Always use braces** for `if`, `for`, `while`, etc., even for single statements
+
+### Required Patterns
+```cpp
+// Bad - forbidden
+if (condition)
+  doSomething();
+
+// Good - required
+if (condition) {
+  doSomething();
+}
+```
+
+## Git Workflow
+
+### Branch Strategy
+- **`current`**: Main development branch (use for PRs with new features)
+- **`release/YY.N`**: Release branches (use for bugfix PRs)
+- **`master`**: Stable releases
+
+### Commit Messages
+Format (max 80 columns):
+```
+Brief description on first line
+
+Optional detailed description after blank line.
+Can span multiple lines.
+```
+
+Examples from history:
+- `fix(WireLabel::mirrorX/Y): Handle axis input`
+- `Fix Monte Carlo ngspice template`
+
+### Pull Requests
+- **Bugfixes**: Base on `release/YY.N`, prefix branch with issue number (e.g., `310-fix-window-size`)
+- **Features**: Base on `current`
+- One logical unit per PR (single bugfix or feature)
+- Atomic commits, easy to review
+- PRs must merge without conflicts
+
+## CI/CD
+
+GitHub Actions workflow (`.github/workflows/deploy.yml`):
+- Builds on Linux (AppImage, Qt6)
+- Builds on push to `master`, `current`, `release/*` branches and tags
+- Check status: `gh pr checks` or `gh pr checks --watch`
+
+## LSP/IDE Support
+
+### clangd Setup
+`compile_commands.json` generated by CMake in `builddir/`:
+```bash
+cd builddir
+cmake ..
+cd ..
+ln -s ./builddir/compile_commands.json compile_commands.json
+```
+
+Configuration in `.clangd` file.
+
+## Project-Specific Notes
+
+### Qt Integration
+- Uses Qt `.ui` files for some dialogs (auto-compiled by CMake via `CMAKE_AUTOUIC`)
+- Qt MOC enabled (`CMAKE_AUTOMOC`)
+- Resource files (`.qrc`) for bitmaps/icons
+
+### Simulation Flow
+1. User creates schematic in GUI
+2. Schematic converted to SPICE netlist (via `qucs2spice`)
+3. Netlist sent to simulation kernel (typically ngspice)
+4. Results parsed and visualized in diagrams
+
+### Submodules
+- `qucsator_rf/` is a git submodule (currently empty placeholder)
+- Must run `git submodule init && git submodule update` after clone
+
+## Common Tasks
+
+### Adding a New Component
+1. Create `.cpp` and `.h` files in `qucs/components/`
+2. Inherit from base `Component` class
+3. Implement properties, SPICE conversion, and visual representation
+4. Add to component registry in components system
+
+### Debugging Build Issues
+- Check component library files in `library/` are installed
+- Verify Qt6 development packages present
+- Ensure flex/bison/gperf available for parser generation
+- Review CMake output for missing dependencies
+
+### Working with Schematic Editor
+Key interaction code in `mouseactions.cpp` and `schematic.cpp`. Canvas uses custom Qt3-compatibility scroll view (`Q3ScrollView`).
+
+### Translation Updates
+Run with `-DUPDATE_TRANSLATIONS=ON` to update `.ts` translation files from source.

CMakeLists.txt

@@ -51,6 +51,35 @@ if(NOT CMAKE_BUILD_TYPE STREQUAL "Debug")
     add_compile_definitions(QT_NO_DEBUG_OUTPUT)
 endif()
 
+# Simulator backend options
+option(WITH_NGSPICE_SHARED "Enable ngspice shared library support" OFF)
+option(WITH_EXTERNAL_SIMULATORS "Enable external simulator support (QProcess-based)" ON)
+
+if(WITH_NGSPICE_SHARED)
+    find_library(NGSPICE_LIBRARY NAMES ngspice libngspice)
+    find_path(NGSPICE_INCLUDE_DIR ngspice/sharedspice.h)
+
+    if(NGSPICE_LIBRARY AND NGSPICE_INCLUDE_DIR)
+        message(STATUS "Found ngspice shared library: ${NGSPICE_LIBRARY}")
+        message(STATUS "Found ngspice headers: ${NGSPICE_INCLUDE_DIR}")
+        set(NGSPICE_SHARED 1)
+    else()
+        message(WARNING "Ngspice shared library not found. WITH_NGSPICE_SHARED disabled.")
+        set(WITH_NGSPICE_SHARED OFF)
+        set(NGSPICE_SHARED 0)
+    endif()
+else()
+    set(NGSPICE_SHARED 0)
+endif()
+
+if(WITH_EXTERNAL_SIMULATORS)
+    set(EXTERNAL_SIMULATORS 1)
+    message(STATUS "External simulator support enabled")
+else()
+    set(EXTERNAL_SIMULATORS 0)
+    message(STATUS "External simulator support disabled")
+endif()
+
 enable_testing()
 
 add_subdirectory( qucs )

config.h.cmake

@@ -8,3 +8,9 @@
 #define WITH_SPICE "@WITH_SPICE@"
 
 #define GIT "@GIT@"
+
+#define WASM_BUILD "@WASM_BUILD"
+
+/* Simulator backend configuration */
+#define NGSPICE_SHARED @NGSPICE_SHARED@
+#define EXTERNAL_SIMULATORS @EXTERNAL_SIMULATORS@

qucs/extsimkernels/CMakeLists.txt

@@ -4,6 +4,11 @@
 INCLUDE_DIRECTORIES( ${CMAKE_CURRENT_SOURCE_DIR}
                      ${CMAKE_CURRENT_BINARY_DIR} )
 
+# Add ngspice include directory if shared library support is enabled
+if(WITH_NGSPICE_SHARED AND NGSPICE_INCLUDE_DIR)
+    INCLUDE_DIRECTORIES(${NGSPICE_INCLUDE_DIR})
+endif()
+
 #INCLUDES = $(X11_INCLUDES) $(QT_INCLUDES) -I$(top_srcdir)/qucs
 
 SET(EXTSIMKERNELS_HDRS
@@ -23,6 +28,11 @@ spicelibcompdialog.h
 CdlSettingsDialog.h
 )
 
+# Add ngspice_shared header if enabled
+if(WITH_NGSPICE_SHARED)
+    list(APPEND EXTSIMKERNELS_HDRS ngspice_shared.h)
+endif()
+
 SET(EXTSIMKERNELS_SRCS
 externsimdialog.cpp
 abstractspicekernel.cpp
@@ -41,6 +51,11 @@ spicelibcompdialog.cpp
 CdlSettingsDialog.cpp
 )
 
+# Add ngspice_shared source if enabled
+if(WITH_NGSPICE_SHARED)
+    list(APPEND EXTSIMKERNELS_SRCS ngspice_shared.cpp)
+endif()
+
 SET(EXTSIMKERNELS_MOC_HDRS
 externsimdialog.h
 abstractspicekernel.h
@@ -52,10 +67,21 @@ spicelibcompdialog.h
 CdlSettingsDialog.h
 )
 
+# Add ngspice_shared to MOC headers if enabled
+if(WITH_NGSPICE_SHARED)
+    list(APPEND EXTSIMKERNELS_MOC_HDRS ngspice_shared.h)
+endif()
+
 QT6_WRAP_CPP( EXTSIMKERNELS_MOC_SRCS ${EXTSIMKERNELS_MOC_HDRS} )
 
 
 ADD_LIBRARY(extsimkernels STATIC ${EXTSIMKERNELS_HDRS} ${EXTSIMKERNELS_SRCS} ${EXTSIMKERNELS_MOC_SRCS})
 
+# Link against ngspice shared library if enabled
+if(WITH_NGSPICE_SHARED AND NGSPICE_LIBRARY)
+    target_link_libraries(extsimkernels PUBLIC ${NGSPICE_LIBRARY})
+    message(STATUS "Linking extsimkernels with ngspice shared library: ${NGSPICE_LIBRARY}")
+endif()
+
 ADD_SUBDIRECTORY( xspice )