Add ngspice shared library support #1497

robtaylor · 2025-10-09T02:43:59Z

Summary

Add support for using ngspice as a shared library (libngspice) instead of external process execution
Add CMake configuration options: WITH_NGSPICE_SHARED (default OFF) and WITH_EXTERNAL_SIMULATORS (default ON)
Create NgspiceShared wrapper class for the shared library API
Support three build configurations:
1. Both modes enabled (development/testing)
2. Shared library only (WebAssembly/Emscripten compatible - no QProcess dependency)
3. External process only (current default behavior)
Implement unified SimulatorError enum for type-safe error handling across both backends

Test plan

Build with default configuration (external simulators only)
Build with WITH_NGSPICE_SHARED=ON WITH_EXTERNAL_SIMULATORS=OFF
Build with both options enabled
Verify CI builds pass on all platforms
Test runtime functionality with shared library backend

🤖 Generated with Claude Code

ra3xdh · 2025-10-09T04:40:45Z

CLAUDE.md

+
+### Simulation Flow
+1. User creates schematic in GUI
+2. Schematic converted to SPICE netlist (via `qucs2spice`)


This statement is totally wrong. qucs2spice serves only for conversion of some library models that don't provide SPICE netlist. See the qucs2spice.cpp and look for its usage in the code.

ra3xdh · 2025-10-09T04:41:45Z

CLAUDE.md

+4. Results parsed and visualized in diagrams
+
+### Submodules
+- `qucsator_rf/` is a git submodule (currently empty placeholder)


This is also wrong. It is not an empty placeholder.

ra3xdh · 2025-10-09T04:42:36Z

CLAUDE.md

+### Debugging Build Issues
+- Check component library files in `library/` are installed
+- Verify Qt6 development packages present
+- Ensure flex/bison/gperf available for parser generation


Flex/bison is required only for QucsatorRF

ra3xdh · 2025-10-09T04:43:00Z

CLAUDE.md

+- 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`).


Q3ScrollView view is not is use anymore.

Just noting that currently Schematic still derives from Q3ScrollView. Should I update the CLAUDE.md to note that it is deprecated?

robtaylor · 2025-10-09T11:21:31Z

Wow, thank you for the early review! I just treated a draft PR for the CI 😅

You're a great maintainer!

Address maintainer review comments on PR ra3xdh#1497: 1. Correct qucs2spice description - it's for library model format conversion, not general schematic-to-netlist conversion 2. Fix qucsator_rf description - it's a real RF simulator submodule, not an empty placeholder 3. Move flex/bison from required to optional dependencies (only needed for QucsatorRF) 4. Remove Q3ScrollView statement as it's deprecated 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

robtaylor · 2025-10-09T12:21:42Z

Wow, thank you for the early review! I just treated a draft PR for the CI 😅

You're a great maintainer!

Could you approve CI runs for me?

Address maintainer review comments on PR ra3xdh#1497: 1. Correct qucs2spice description - it's for library model format conversion, not general schematic-to-netlist conversion 2. Fix qucsator_rf description - it's a real RF simulator submodule, not an empty placeholder 3. Move flex/bison from required to optional dependencies (only needed for QucsatorRF) 4. Remove Q3ScrollView statement as it's deprecated 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

robtaylor

Some notes. Also I feel like there's a clash gonna happen with your approach and AbstractSpiceKernel, but not sure...

robtaylor · 2025-10-10T13:20:58Z

qucs/extsimkernels/abstractspicekernel.cpp

+#if EXTERNAL_SIMULATORS
    return a_simProcess->waitForFinished(10000);
+#else
+    return true; // For shared library mode, blocking isn't needed


Hmm, as the caller fetches results immediately after calling this, we should block for now.
Worth doing another PR to make simulation runs non-blocking.

robtaylor · 2025-10-10T13:22:23Z

qucs/extsimkernels/abstractspicekernel.h

+#if EXTERNAL_SIMULATORS
+    ProcessFailedToStart = static_cast<int>(QProcess::FailedToStart),        // 0
+    ProcessCrashed = static_cast<int>(QProcess::Crashed),                    // 1
+    ProcessTimedOut = static_cast<int>(QProcess::Timedout),                  // 2
+    ProcessWriteError = static_cast<int>(QProcess::WriteError),              // 3
+    ProcessReadError = static_cast<int>(QProcess::ReadError),                // 4
+    ProcessUnknownError = static_cast<int>(QProcess::UnknownError)           // 5
+#else


Given that we switch on the process codes to output the right SimulatorError, it seems this isn't needed?

robtaylor · 2025-10-10T13:24:39Z

qucs/extsimkernels/CMakeLists.txt

If we error out at the top level if WITH_NGSPICE_SHARED is set and NGSPICE_INCLUDE_DIR/NGSPICE_LIBRARY is not found, then these if statement can just use WITH_NGSPICE_SHARED

It might also be neater to collect these all together in one place.

robtaylor · 2025-10-10T13:26:40Z

qucs/extsimkernels/CMakeLists.txt

+# Add test for ngspice shared library if enabled
+if(WITH_NGSPICE_SHARED AND NGSPICE_LIBRARY)
+    add_executable(test_ngspice_shared test_ngspice_shared.cpp)
+    target_link_libraries(test_ngspice_shared PRIVATE extsimkernels Qt6::Core)
+    add_test(NAME NgspiceSharedTest COMMAND test_ngspice_shared)
+    message(STATUS "NgspiceShared test enabled")
+endif()


I think a top level TESTS_ENABLED flag would be useful here.

robtaylor · 2025-10-10T13:29:55Z

qucs/extsimkernels/ngspice.cpp

+void Ngspice::onSharedOutputReceived(const QString &text)
+{
+    a_output += text;
+    if (a_console != nullptr) {
+        a_console->insertPlainText(text);
+        a_console->moveCursor(QTextCursor::End);
+    }
+}
+


It appears this is not called from anywhere!

Document Qucs-S architecture, build system, code organization, and development workflows to help contributors understand the codebase. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

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 - SimulatorError enum uses sequential auto-assignment (NoError=0, then 1,2,3...) - Background commands (bg_*) rejected in shared library mode - Thread-safe signal emission using Qt::QueuedConnection - Updated Xyce simulator for conditional QProcess support Error handling: - Fixed ExternSimDialog to use SimulatorError instead of QProcess::ProcessError - All signal connections updated to use unified error enum - Comprehensive error messages for both backends - Test suite validates enum uniqueness and error handling 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>

Create automated test to verify ngspice shared library integration: - Tests basic initialization of NgspiceShared class - Runs simple voltage divider circuit simulation - Verifies Qt signals/callbacks work correctly - Tests error handling for invalid commands/netlists - Validates vector data retrieval from simulation results Test runs via ctest when WITH_NGSPICE_SHARED=ON is enabled. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Create Qt Test-based UI regression test framework: - Add tests/test_ngspice_integration.cpp with Qt Test framework - Tests NgspiceShared initialization, simulation, signals, and data retrieval - Tests run automatically in CI via ctest Add CI support for running tests: - Install xvfb for headless Qt testing on Linux - Run ctest after build step with verbose output - Tests validate NgspiceShared integration works correctly The test suite provides: - Automated validation of ngspice shared library integration - Signal/slot mechanism testing - Simulation result verification - Foundation for future UI regression tests 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Expanded NgspiceSharedTest to verify behavioral parity between shared library mode and traditional external process execution. This helps detect any behavioral differences introduced by the shared library implementation. Changes: - Added NgspiceExternalProcess helper class to run ngspice as external process (QProcess-based) for comparison - Added test_shared_vs_external() that runs the same circuit through both execution modes - Verifies both modes produce expected outputs (analysis completion, output vectors, node voltages) - Uses single global NgspiceShared instance to avoid multiple initialization issues (ngspice shared library doesn't handle repeated init/cleanup well in same process) - Added proper cleanup to prevent abort signals during test teardown Test results: - Both modes successfully complete circuit simulation - Both modes produce comparable outputs with expected vectors - Shared library: Returns structured vector data via API - External process: Produces text output with analysis results - All 3 test suites pass (GeometryTest, NgspiceSharedTest, NgspiceIntegration) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

This commit adds test_simulation_types.cpp which validates different SPICE simulation types supported by NgspiceShared: Test cases added: - DC operating point analysis with voltage divider - AC frequency sweep analysis with RC filter - Transient time-domain analysis with RC step response - Complex RC filter frequency response validation - RC step response with time constant verification All tests use raw SPICE netlists and verify: - Simulation execution completes successfully - Output vectors are generated correctly - Expected nodes/data are present in results Updated CLAUDE.md with comprehensive documentation on: - New test executable and what it covers - Guidelines for writing simulation type tests - Example SPICE netlist structure for tests All 5 tests pass (including new simulation types test). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Changes: - Add libngspice0-dev to Ubuntu dependencies - Enable WITH_NGSPICE_SHARED=ON in CMake configuration This allows simulation type tests (DC, AC, Transient) to run in CI instead of being skipped. The tests validate NgspiceShared integration with actual circuit simulations. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Critical fixes: - Fix memory leak in test cleanup by explicitly deleting NgspiceShared - Remove duplicate test file from qucs/extsimkernels/ directory - Remove duplicate test build configuration from CMakeLists.txt Major improvements: - Add libngspice to macOS CI dependencies (brew install libngspice) - Enable WITH_NGSPICE_SHARED=ON in macOS CI build configuration - Clarify background command rejection comments in ngspice_shared.cpp (ngspice shared library has built-in threading via cbBGThreadRunning) These changes address the critical and major issues identified in code review while maintaining backward compatibility and test coverage. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

ra3xdh reviewed Oct 9, 2025

View reviewed changes

ra3xdh added the AI generated label Oct 9, 2025

robtaylor force-pushed the feature/ngspice-shared-library branch 2 times, most recently from 672a604 to 9f84c23 Compare October 10, 2025 12:57

robtaylor commented Oct 10, 2025

View reviewed changes

robtaylor and others added 5 commits October 11, 2025 07:05

robtaylor force-pushed the feature/ngspice-shared-library branch from ac8bf91 to 53147e8 Compare October 11, 2025 06:07

robtaylor and others added 3 commits October 14, 2025 23:23

Uh oh!

Add ngspice shared library support #1497

Are you sure you want to change the base?

Add ngspice shared library support #1497

Uh oh!

Conversation

robtaylor commented Oct 9, 2025

Summary

Test plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ra3xdh Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

robtaylor commented Oct 9, 2025

Uh oh!

robtaylor commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

robtaylor left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ra3xdh Oct 9, 2025 •

edited

Loading

robtaylor commented Oct 9, 2025 •

edited

Loading