pysystemc - SystemC python binding using cppyy

Category	Status
CI/CD
Project
Docs
Meta
Standards

Python bindings for SystemC using cppyy. Write Python testbenches and modules while using the native C++ simulation kernel and on-demand template instantiation. The PyPI distribution is pysystemc; the Python import namespace is amal.eda.systemc.

Project origins

The original idea and initial implementation were hand coded. Development later also began using vibe coding with AI assistance to extend the implementation, tests, and documentation.

Why Python and cppyy?

SystemC provides a C++ simulation kernel, typed channels, and a rich modeling library. Python adds a convenient way to assemble models and experiment with them. You can change stimulus, testbench logic, logging, waveform selection, and model connections in Python, then rerun the simulation without rebuilding the existing C++ model libraries.

cppyy was chosen for its support for C++ templates and runtime features. It makes native C++ classes and templates accessible from Python and allows C++ bridge code to be compiled within the running Python environment. For example, sc_uint[17], sc_biguint[137], and sc_signal[sc_uint[17]] can be requested when a script runs, rather than requiring a binding library with a predefined list of types and widths. Its Cling interpreter compiles the necessary template specializations and bridge code on demand. This still involves compilation, but it happens within the running Python environment instead of a separate C++ build-and-link cycle.

Python modules can register methods and threads with the native SystemC kernel, while existing C++ models continue to execute as C++. This lets a testbench load configuration files, generate parameterized stimulus, inspect results, and use Python analysis tools around the same simulation. SystemC still controls time, delta cycles, and process scheduling; Python callbacks add overhead when the simulation crosses the language boundary.

This flexibility is especially useful during exploration and verification: change a test scenario or a traced signal in a script and rerun it. Changes to the implementation of a compiled C++ model still require rebuilding that model. SystemC's elaboration rules also still apply: most structural connections are made before simulation starts. Dynamic processes can be spawned during a run, but arbitrary structural changes remain constrained by native elaboration rules. Python thread reset and kill preserve scheduler unwind through the guarded wait adapter; see the supported behavior documentation for lifecycle constraints.

Quickstart

Load Python 3.14 and install uv, then run:

make setup
make example-hello-py
make example-counter-py
make test

Setup installs dependencies and builds SystemC 2.3.4 with pthreads. Existing UV_* environment settings are honored. To run the C++ hello example, use make example-hello-cpp.

Use make test-parallel or make coverage-parallel to run tests in two isolated pytest workers. Override the worker count with TEST_WORKERS=4, and select tests with ARGS="tests/test_cli.py tests/test_repl.py". Each simulation still runs in a fresh subprocess; coverage combines data from workers and their child processes.

Detailed setup, validation, and logging instructions are in the documentation.

Examples

Use uv run pysystemc --version for the installed version and uv run pysystemc --help for command help. Start an interactive Python playground with uv run pysystemc repl; it preloads sc_core, sc_dt, TLM, cppyy and the public kernel names. The prompt supports syntax highlighting, tab completion, multiline definitions, line editing and persistent history. Use pysystemc help repl for history options. The Makefile provides make cli, make cli ARGS=version and make repl; both targets forward ARGS for additional command options.

uv run pysystemc-cpp model.cpp -- --cycles 20 compiles native C++ sources and forwards arguments after -- to sc_main. The compatibility script examples/run_sysc_cpp.py uses the same packaged runner.

There are a few C++ and Python examples in examples/ directory.

Some examples adapted from:

• Learn SystemC with Examples
• Brief SystemC getting started tutorial

For build options, header repair, logging controls, and validation, see the development guide.

References

• Accellera
  • SystemC
  • SystemC Verification (SCV)
  • UVM-SystemC
  • CRAVE constrained randomization
  • FC4SC functional coverage
  • PySysC - A Python package to make SystemC usable from Python using conan/cppyy
    • Python and SystemC
• systemc_python - use systemc through cppyy
• pysc - Python bindings for SystemC using pure Python API
• pysc - Python SystemC implementation of USI (Universal Scripting Interface) using swig
  • Transparent SystemC Model Factory for Scripting Languages
• bsmedit - C/C++/SystemC Visualizer docs
• gsysc - Graphical environment for SystemC
• Python binding generators
  • swig - build Python extension
  • cppyy - Python-C++ bindings interface based on Cling/LLVM
  • pybind11
  • CFFI
  • Boost.Python
  • Shiboken

The CLI also runs as python -m amal.eda.cli; help and version commands do not load the native kernel.