spicebind 0.0.1__tar.gz

spicebind-0.0.1/.github/workflows/docs.yml

@@ -0,0 +1,61 @@
+name: Docs
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      env:
+        DEBIAN_FRONTEND: noninteractive
+      run: |
+        sudo apt-get install \
+          --yes --no-install-recommends \
+          doxygen ngspice iverilog ngspice-dev libngspice0-dev
+    - name: Install Python packages
+      run: |
+        pip install -e ".[docs]"
+        pip install nox
+    - name: Build docs
+      run: |
+        nox -s docs
+
+
+    - name: Upload static files as artifact
+      id: deployment
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: .nox/.cache/docs_out
+
+  # Deploy job
+  deploy:
+    # Add a dependency to the build job
+    needs: build
+    # Only deploy on main branch
+    if: github.ref == 'refs/heads/main'
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    # Specify runner + deployment step
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

spicebind-0.0.1/.github/workflows/tests.yml

@@ -0,0 +1,26 @@
+name: Tests
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.12"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install system dependencies
+      run: |
+        sudo apt-get install ngspice iverilog ngspice-dev libngspice0-dev
+    - name: Install nox
+      run: |
+        pip install nox
+    - name: Run tests
+      run: |
+        nox -s test

spicebind-0.0.1/.gitignore

@@ -0,0 +1,212 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
+#  you could uncomment the following to ignore the enitre vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# cocotb
+sim_build
+
+spicebind/*.vpi
+
+
+# Vim tmp files
+*.swp
+*~
+
+# VSCode project files
+.vscode/
+*.code-workspace
+
+# Emacs tmp files
+\#*\#
+\.\#*

spicebind-0.0.1/CMakeLists.txt

@@ -0,0 +1,100 @@
+cmake_minimum_required(VERSION 3.15)
+project(spicebind_vpi LANGUAGES CXX)
+
+
+# Call CMake with:  cmake -DNGSPICE_ROOT=/path/to/ngspice <src_dir>
+set(NGSPICE_ROOT "" CACHE PATH
+    "Root of an NGSpice installation containing include/ and lib/."
+)
+
+if(NOT NGSPICE_ROOT)
+    # Try to locate the ngspice executable first
+    find_program(NGSPICE_EXE
+        NAMES ngspice          # ngspice.exe on Windows is also matched
+        DOC   "Full path to the ngspice executable"
+    )
+
+    if(NGSPICE_EXE)
+        # bin  -> parent -> install root
+        get_filename_component(NGSPICE_BIN_DIR "${NGSPICE_EXE}" DIRECTORY)
+        get_filename_component(NGSPICE_ROOT    "${NGSPICE_BIN_DIR}" DIRECTORY)
+
+        message(STATUS "Found ngspice executable:  ${NGSPICE_EXE}")
+        message(STATUS "Inferred NGSPICE_ROOT:     ${NGSPICE_ROOT}")
+    # else()
+    #     message(FATAL_ERROR
+    #         "Could not find 'ngspice' in your PATH and NGSPICE_ROOT was not "
+    #         "given.  Either install NGSpice or run CMake with "
+    #         "-DNGSPICE_ROOT=/path/to/ngspice."
+    #     )
+    endif()
+endif()
+
+
+# ---------------------------------------------------------------------------
+#  Source files and common configuration
+# ---------------------------------------------------------------------------
+set(SPICEBIND_SRC
+    cpp/Config.cpp
+    cpp/AnalogDigitalInterface.cpp
+    cpp/NgSpiceCallbacks.cpp
+    cpp/VpiCallbacks.cpp
+    cpp/vpi_module.cpp
+)
+
+set(_ngspice_possible_libdirs
+    "${NGSPICE_ROOT}/lib"
+)
+
+# Function to configure a VPI target with common settings
+function(configure_vpi_target target_name)
+    set_target_properties(${target_name} PROPERTIES
+        CXX_STANDARD 17
+        POSITION_INDEPENDENT_CODE ON
+        PREFIX ""          # stop CMake from adding "lib"
+        SUFFIX ".vpi"      # final name: ${target_name}.vpi
+        LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/spicebind"
+    )
+
+    target_include_directories(${target_name}
+        PRIVATE
+            ${CMAKE_CURRENT_SOURCE_DIR}/cpp
+            ${NGSPICE_ROOT}/include
+    )
+
+    target_link_directories(${target_name} PRIVATE ${_ngspice_possible_libdirs})
+    target_link_libraries(${target_name} PRIVATE ngspice)
+endfunction()
+
+# ---------------------------------------------------------------------------
+#  RELEASE variant
+# ---------------------------------------------------------------------------
+add_library(spicebind_vpi SHARED ${SPICEBIND_SRC})
+configure_vpi_target(spicebind_vpi)
+
+# ---------------------------------------------------------------------------
+#  DEBUG variant
+# ---------------------------------------------------------------------------
+add_library(spicebind_vpi_debug SHARED ${SPICEBIND_SRC})
+configure_vpi_target(spicebind_vpi_debug)
+
+# ► debug-specific compile flags ◄
+target_compile_definitions(spicebind_vpi_debug PRIVATE DEBUG)
+target_compile_options(spicebind_vpi_debug PRIVATE
+    $<$<CXX_COMPILER_ID:MSVC>:/Zi /Od>
+    $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-g -O0>
+)
+
+# convenience meta-target:  cmake --build . --target debug
+add_custom_target(debug ALL DEPENDS spicebind_vpi_debug)
+
+# ---------------------------------------------------------------------------
+#  Installation for Python packaging
+# ---------------------------------------------------------------------------
+# Install VPI files to the Python package directory
+install(FILES 
+    $<TARGET_FILE:spicebind_vpi>
+    $<TARGET_FILE:spicebind_vpi_debug>
+    DESTINATION spicebind
+    COMPONENT python_package
+)

spicebind-0.0.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Tomasz Hemperek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

spicebind-0.0.1/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.2
+Name: spicebind
+Version: 0.0.1
+Summary: SpiceBind is a bridge that embeds the ngspice analog engine inside VPI-capable Verilog simulator for mixed-signal co-simulation.
+Author: Tomasz Hemperek
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Project-URL: Homepage, https://github.com/themperek/spicebind
+Project-URL: Repository, https://github.com/themperek/spicebind
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: cocotb; extra == "dev"
+Requires-Dist: numpy; extra == "dev"
+Requires-Dist: matplotlib; extra == "dev"
+Requires-Dist: cocotbext-spi; extra == "dev"
+Requires-Dist: tomli; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=8.2; extra == "docs"
+Requires-Dist: breathe; extra == "docs"
+Requires-Dist: sphinx-book-theme==1.1.3; extra == "docs"
+Requires-Dist: sphinx-design>=0.6.1; extra == "docs"
+Requires-Dist: sphinxcontrib-spelling>=5.3.0; extra == "docs"
+Requires-Dist: pyenchant; extra == "docs"
+Requires-Dist: sphinx-argparse-cli; extra == "docs"
+Requires-Dist: sphinx-autobuild; extra == "docs"
+Requires-Dist: sphinx-codeautolink; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Description-Content-Type: text/markdown
+
+# SpiceBind
+
+[![Tests](https://github.com/themperek/spicebind/actions/workflows/tests.yml/badge.svg)](https://github.com/themperek/spicebind/actions/workflows/tests.yml)
+[![Docs](https://github.com/themperek/spicebind/actions/workflows/docs.yml/badge.svg)](https://themperek.github.io/spicebind/)
+
+SpiceBind is a lightweight bridge that enables co-simulation of **analog [ngspice](https://ngspice.sourceforge.io/)** circuits alongside **HDL simulators**. This tool allows design engineers to seamlessly integrate SPICE-accurate analog models into their existing digital verification flows.
+
+⚠️ **Note**: This is an early release. We welcome feedback and contributions from the community.
+
+### Key Benefits
+
+- **Preserve Your Existing Flow**: Keep your RTL, testbenches, and waveform viewers unchanged
+- **SPICE Accuracy**: Replace any module with a SPICE-based analog model for accurate analog simulation
+- **Unified Timeline**: Analog and digital domains run in synchronization
+- **Zero Vendor Lock-in**: Works with open-source tools like Icarus Verilog up to commercial simulators (to be tested)
+- **Verification Ready**: Compatible with [cocotb](https://www.cocotb.org/) for Python-based verification
+
+### Use Cases
+
+Perfect for ASIC designers working on:
+- Mixed-signal SoCs with analog IP blocks
+- ADCs, DACs, and data converters
+- PLLs, oscillators, and clock generation circuits
+- Power management units
+- Sensor interfaces and analog front-ends
+
+## How It Works
+
+SpiceBind enables you to write Verilog source code that includes an empty Verilog module and have it implemented by ngspice. Here's how the magic happens:
+
+### The Process
+
+1. **Create a Verilog Module Shell**: Write a Verilog module with the desired interface (inputs and outputs). The module body can be empty - it will be implemented in SPICE.
+
+2. **Design the SPICE Implementation**: Create a corresponding SPICE netlist that implements the analog behavior of your module.
+
+3. **Name-Based Connection**: 
+   - **Verilog input ports** appear in the SPICE circuit as external voltage sources
+   - **Selected SPICE circuit nodes** drive the Verilog output ports
+   - Connections are established by **matching names** between Verilog ports and SPICE nodes
+
+4. **VPI Integration**: A VPI (Verilog Procedural Interface) module links to ngspice's shared library, enabling communication between the digital simulator and the analog engine.
+
+### Example Flow
+
+```
+Verilog: input real vin    →    SPICE: Vvin external_node 0 0 external
+Verilog: output [3:0] code ←    SPICE: circuit nodes code[3], code[2], code[1], code[0]
+```
+
+During simulation, the VPI module:
+- Reads values from Verilog input ports and sets corresponding SPICE voltage sources
+- Runs SPICE analysis for the current time step  
+- Reads SPICE node voltages and drives corresponding Verilog output ports
+
+This creates a co-simulation where analog and digital domains remain synchronized on a unified timeline.
+
+## Installation
+
+### Prerequisites
+
+- C++ compiler with C++17 support
+- ngspice library and development headers
+- Verilog VPI compatible simulator (tested with [Icarus Verilog](https://github.com/steveicarus/iverilog))
+- Python 3.6+ (optional)
+
+### Build Instructions
+
+Clone the repository:
+```bash
+git clone https://github.com/themperek/spicebind.git
+cd spicebind
+```
+
+**Option 1: Standalone VPI Module**
+```bash
+mkdir build && cd build
+cmake ..
+cmake --build .
+cmake --build . --target debug  # Optional: builds debug version
+```
+
+**Option 2: Python Integration**
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+### 1. Define Your Analog Block
+
+Create a Verilog module with matching SPICE netlist with external voltage sources and ouptut ports.
+
+**Verilog module** (e.g., `adc.v`):
+```verilog
+module adc(
+    input  real vin,
+    output reg [3:0] code
+);
+endmodule
+```
+
+**SPICE netlist** (e.g., `adc.cir`):
+```spice
+* External voltage source for input
+Vvin adc_in 0 0 external
+
+* ADC subcircuit instantiation
+Xadc adc_in code[3] code[2] code[1] code[0] sar_adc
+
+* Simulation settings
+.tran 1ns 1
+```
+
+### 2. Configure Environment
+
+Set the required environment variables:
+```bash
+export SPICE_NETLIST=adc.cir
+export HDL_INSTANCE=tb.adc
+export VCC=3.3
+```
+
+### 3. Run Simulation
+
+For Icarus Verilog:
+```bash
+vvp -M $(spicebind-vpi-path) -m spicebind_vpi tb.vvp
+```
+
+See the `examples/` directory for complete working examples.
+
+### Multiple Instance Support
+
+For designs with multiple analog blocks, configure each instance in your SPICE netlist with full hierarchical paths:
+
+**SPICE netlist**:
+```spice
+* First ADC instance
+Vtb.adc.vin vin 0 0 external
+Xadc vin tb.adc.code[3] tb.adc.code[2] tb.adc.code[1] tb.adc.code[0] sar_adc
+
+* Inverter instance
+Vtb.inv.A inv_a 0 0 external
+Xinv inv_a tb.inv.Y inv
+
+.tran 1ns 1
+```
+
+**Environment configuration**:
+```bash
+export HDL_INSTANCE=tb.adc,tb.inv
+```
+
+### Configuration Options
+
+- `SPICE_NETLIST`: Path to your SPICE netlist file
+- `HDL_INSTANCE`: Comma-separated list of HDL instance paths
+- `VCC`: Supply voltage for analog simulation
+- Additional options available in the documentation
+
+## Documentation
+
+For detailed documentation, examples, and API reference, visit: [https://themperek.github.io/spicebind/](https://themperek.github.io/spicebind/)
+
+## Contributing
+
+We welcome contributions! Please see our contributing guidelines and feel free to:
+- Report bugs and request features via GitHub Issues
+- Submit pull requests for improvements
+- Share your use cases and examples
+
+## Roadmap
+
+- [ ] Enhanced testing and validation
+- [ ] Bidirectional bus support
+- [ ] Automatic SPICE wrapper generation