{"id":10174,"library":"pyvcd","title":"Python VCD File Support","description":"pyvcd is a Python library designed for working with Value Change Dump (VCD) files. It provides functionalities for both reading and writing these standard files used to record signal activity in digital logic simulations. The current version is 0.4.1, and releases are generally made on an as-needed basis for bug fixes or minor enhancements.","status":"active","version":"0.4.1","language":"en","source_language":"en","source_url":"https://github.com/pyvcd/pyvcd","tags":["VCD","digital design","simulation","EDA","waveform"],"install":[{"cmd":"pip install pyvcd","lang":"bash","label":"Install pyvcd"}],"dependencies":[],"imports":[{"symbol":"VCDWriter","correct":"from pyvcd import VCDWriter"},{"symbol":"VCDReader","correct":"from pyvcd import VCDReader"}],"quickstart":{"code":"from datetime import datetime\nfrom pyvcd import VCDWriter\n\n# Create a VCD file named 'test.vcd'\nwith VCDWriter(open('test.vcd', 'w'), timescale='1 ns', date=datetime.now()) as writer:\n    # Enter a scope named 'top' of type 'module'\n    scope = writer.scope_stack.enter_scope('top', 'module')\n    \n    # Define a 1-bit 'clk' wire and change its value over time\n    writer.change(scope.var('clk', 'wire', 1), 0, 0)   # At time 0, clk is 0\n    writer.change(scope.var('clk', 'wire', 1), 1, 100) # At time 100 ns, clk is 1\n    writer.change(scope.var('clk', 'wire', 1), 0, 200) # At time 200 ns, clk is 0\n    \n    # Define another 1-bit 'rst_n' wire\n    writer.change(scope.var('rst_n', 'wire', 1), 1, 0)\n    writer.change(scope.var('rst_n', 'wire', 1), 0, 100)\n    writer.change(scope.var('rst_n', 'wire', 1), 1, 200)\n    \n    # Leave the current scope\n    writer.scope_stack.leave_scope()\n\nprint(\"VCD file 'test.vcd' generated successfully.\")","lang":"python","description":"This example demonstrates how to create a VCD file, define a module scope, declare signals (wires), and record their value changes over time using `VCDWriter`."},"warnings":[{"fix":"Always use `VCDWriter` as a context manager: `with VCDWriter(open('file.vcd', 'w'), ...) as writer:`","message":"Forgetting to use `VCDWriter` in a `with` statement or manually `close()` the writer can lead to incomplete or corrupted VCD files, as internal buffers might not be flushed to disk.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure `timescale` (e.g., '1 ns', '1 ps', '1 us') accurately reflects the time units used for your simulation data.","message":"The `timescale` argument to `VCDWriter` is crucial for the correct interpretation of timestamps by VCD viewers. Missetting it (e.g., '1ps' when the simulation operates in '1ns' increments) will result in incorrect timing displays.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure values passed to `writer.change()` for `wire` types are integers. For bit-string representations, consider converting to integer or ensuring your VCD viewer handles them correctly.","message":"Signal values are expected to be integers for `wire` types by default. Providing non-integer values without proper conversion can lead to `TypeError` or `ValueError` or incorrect data representation in the VCD file.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Before calling `writer.change()`, ensure the variable has been defined with `scope.var('signal_name', 'wire', width)` and that the returned variable object is used.","cause":"Attempting to change a signal's value that has not yet been defined within the current or parent scope using `scope.var()`.","error":"ValueError: Cannot change unknown variable."},{"fix":"Ensure all `writer.change()` calls and other write operations happen within the `with VCDWriter(...) as writer:` block, or that the file object passed to `VCDWriter` remains open for the duration of writing.","cause":"Attempting to write to the VCD file after the file object or the `VCDWriter` has been closed (e.g., after the `with` block exits, or if `writer.close()` was explicitly called too early).","error":"IOError: [Errno 9] Bad file descriptor"},{"fix":"Always use `VCDWriter` within a `with` statement: `with VCDWriter(open('my.vcd', 'w'), ...) as writer:`. This ensures `close()` is called automatically, flushing all buffers.","cause":"The file stream or the `VCDWriter` was not properly closed, leading to unwritten buffered data not being flushed to disk.","error":"VCD file appears empty or truncated when opened in a viewer."}]}