piel.tools.cocotb
=================

.. py:module:: piel.tools.cocotb


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/piel/tools/cocotb/core/index
   /autoapi/piel/tools/cocotb/data/index


Attributes
----------

.. autoapisummary::

   piel.tools.cocotb.delete_simulation_output_files
   piel.tools.cocotb.get_simulation_output_files


Functions
---------

.. autoapisummary::

   piel.tools.cocotb.check_cocotb_testbench_exists
   piel.tools.cocotb.configure_cocotb_simulation
   piel.tools.cocotb.run_cocotb_simulation
   piel.tools.cocotb.get_simulation_output_files_from_design
   piel.tools.cocotb.read_simulation_data
   piel.tools.cocotb.simple_plot_simulation_data


Package Contents
----------------

.. py:function:: check_cocotb_testbench_exists(design_directory: str | pathlib.Path) -> bool

   Checks if a Cocotb testbench exists in the specified design directory.

   :param design_directory: The directory where the design files are located.
   :type design_directory: str | pathlib.Path

   :returns: True if a Cocotb testbench exists, False otherwise.
   :rtype: bool

   .. rubric:: Examples

   >>> check_cocotb_testbench_exists("/path/to/design")
   True


.. py:function:: configure_cocotb_simulation(design_directory: str | pathlib.Path, simulator: piel.types.digital.HDLSimulator, top_level_language: piel.types.digital.HDLTopLevelLanguage, top_level_verilog_module: str, test_python_module: str, design_sources_list: list | None = None) -> pathlib.Path

   Configures a Cocotb simulation by generating a Makefile in the specified directory.

   This function creates a Makefile required to run Cocotb simulations. It includes paths to design source files and sets up the simulator and language options.

   :param design_directory: The directory where the design files are located.
   :type design_directory: str | pathlib.Path
   :param simulator: The simulator to use for the simulation.
   :type simulator: Literal["icarus", "verilator"]
   :param top_level_language: The top-level HDL language used in the design.
   :type top_level_language: Literal["verilog", "vhdl"]
   :param top_level_verilog_module: The top-level Verilog module name.
   :type top_level_verilog_module: str
   :param test_python_module: The Python test module name for Cocotb.
   :type test_python_module: str
   :param design_sources_list: A list of design source file paths. Defaults to None.
   :type design_sources_list: list | None, optional

   :returns: The path to the generated Makefile.
   :rtype: pathlib.Path

   .. rubric:: Examples

   >>> configure_cocotb_simulation("/path/to/design", "icarus", "verilog", "top_module", "test_module")
   PosixPath('/path/to/design/tb/Makefile')


.. py:data:: delete_simulation_output_files

.. py:function:: run_cocotb_simulation(design_directory: str, raise_error: bool = False) -> subprocess.CompletedProcess

   Runs the Cocotb simulation by executing the Makefile in the specified design directory.

   :param design_directory: The directory where the design files are located.
   :type design_directory: str

   :returns: The completed process object containing the result of the simulation run.
   :rtype: subprocess.CompletedProcess

   .. rubric:: Examples

   >>> run_cocotb_simulation("/path/to/design")


.. py:data:: get_simulation_output_files

.. py:function:: get_simulation_output_files_from_design(design_directory: piel.types.PathTypes, extension: str = 'csv') -> list

   Returns a list of all simulation output files in the specified design directory.

   :param design_directory: The path to the design directory.
   :type design_directory: PathTypes
   :param extension: The file extension to filter by. Defaults to "csv".
   :type extension: str, optional

   :returns: A list of paths to the simulation output files in the design directory.
   :rtype: list

   .. rubric:: Examples

   >>> get_simulation_output_files_from_design("/path/to/design")
   [PosixPath('/path/to/design/tb/out/output1.csv'), PosixPath('/path/to/design/tb/out/output2.csv')]


.. py:function:: read_simulation_data(file_path: piel.types.PathTypes, *args, **kwargs) -> pandas.DataFrame

   Reads simulation files from a specified file into a Pandas dataframe.

   :param file_path: The path to the simulation files file.
   :type file_path: PathTypes

   :returns: The simulation files as a Pandas dataframe.
   :rtype: pd.DataFrame

   .. rubric:: Examples

   >>> read_simulation_data("/path/to/simulation/output.csv")
   # Returns a dataframe with the contents of the CSV file.


.. py:function:: simple_plot_simulation_data(simulation_data: pandas.DataFrame)

   Plots simulation files using Bokeh for interactive visualization.

   :param simulation_data: The simulation files to plot, containing columns 't' for time and 'x' for signal values.
   :type simulation_data: pd.DataFrame

   :returns: Displays an interactive plot.
   :rtype: None

   .. rubric:: Examples

   >>> files = pd.DataFrame({"t": [0, 1, 2, 3], "x": [0, 1, 0, 1]})
   >>> simple_plot_simulation_data(files)
   # Displays an interactive Bokeh plot.