FEAT: Integration examples, addition of models, improved documentation (

#8)

* FEAT: Working file analysis

* FIX: Integration examples

* FEAT: Extend .gitignore for cocotb

* FEAT: Further filepath functionality

* FIX: Automation examples

* FEAT: Initialization of new project structures

* FEAT: Pre-modification of project structure

* FEAT: Begun project example restructure

* FEAT: Models, abstract components initialisation, and project structure restructure

* FEAT: Added new documentation structure

* DOCS: Improvements and images

* FEAT: Working cocotb simulation example

* FIX: Docs

.gitignore

@@ -104,3 +104,94 @@ ENV/
 # IDE settings
 .vscode/
 .idea/
+
+# Cocotb
+*.py[cod]
+
+# C extensions
+*.so
+*.dll
+
+# C objects
+*.o
+
+# Python and C++ code coverage
+.coverage
+.coverage.cocotb
+*.gcno
+*.gcda
+*.gcov
+
+# Packaging
+*.egg
+*.egg-info
+dist
+build
+eggs
+parts
+sdist
+obj
+develop-eggs
+.installed.cfg
+__pycache__
+.tox
+.nox
+.eggs
+
+# Vim tmp files
+*.swp
+*~
+
+# VSCode project files
+.vscode/
+*.code-workspace
+
+# Emacs tmp files
+\#*\#
+\.\#*
+
+# Mergetool tmp files
+*.orig
+*.bak
+
+# Waveforms
+*.vcd
+*.fst
+*.fst.hier
+
+# Results
+results.xml
+combined_results.xml
+
+# Debuggers
+.gdb_history
+
+# VCS files
+*.tab
+sim_build
+ucli.key
+
+# Pytest
+.pytest_cache
+
+# Cadence Incisive/Xcelium
+*.elog
+irun.log
+xrun.log
+irun.key
+xrun.key
+irun.history
+xrun.history
+INCA_libs
+xcelium.d
+ncelab_*.err
+xmelab_*.err
+ncsim_*.err
+xmsim_*.err
+bpad_*.err
+.bpad/
+.simvision/
+waves.shm/
+
+ivl_vhdl_work/
+RUN_*

.pre-commit-config.yaml

@@ -22,7 +22,7 @@ repos:
     rev: ad3ff374e97e29ca87c94b5dc7eccdd29adc6296
     hooks:
       - id: codespell
-        args: ["-L TE,TE/TM,te,ba,FPR,fpr_spacing,ro,nd,donot,schem"]
+        args: ["-L TE,TE/TM,te,ba,FPR,fpr_spacing,ro,nd,donot,schem,Synopsys"]
         additional_dependencies:
           - tomli
 

README.md

@@ -13,6 +13,7 @@ Photonic and electronic co-simulation system design tools interfaced with open-s
 * Co-simulation and optimisation between integrated photonic and electronic chip design.
 * System interconnection modelling in multiple environments.
 * Individual and interposer design integration.
+* Multi-domain electronics and photonics component models
 
 `piel` aims to provide an integrated workflow to co-design photonics and electronics. It does not aim to replace the individual functionality of each design tool, but rather provide a glue to easily connect them all together and extract the system performance.
 
@@ -25,13 +26,5 @@ Some individual tools already integrated are:
 * [OpenLane v1](https://github.com/The-OpenROAD-Project/OpenLane) - an automated RTL to GDSII flow based on several components including OpenROAD, Yosys, Magic, Netgen and custom methodology scripts for design exploration and optimization
 * [sax](https://github.com/flaport/sax) - S-parameter based frequency domain circuit simulations and optimizations using JAX.
 
-Coming next GDSFactory netlisting and layout integration.
-
 ## Environment Requirements
 * Please install the Linux Docker environment provided by [IIC-OSIC-TOOLS](https://github.com/iic-jku/iic-osic-tools).
-
-## Credits
-This package was created with Cookiecutter and the `audreyr/cookiecutter-pypackage` project template.
-
-- Cookiecutter: [https://github.com/audreyr/cookiecutter](https://github.com/audreyr/cookiecutter)
-- `audreyr/cookiecutter-pypackage`: [https://github.com/audreyr/cookiecutter-pypackage](https://github.com/audreyr/cookiecutter-pypackage)

docs/autoapi/piel/cocotb/core/index.rst

@@ -34,8 +34,7 @@ Attributes
 
 .. autoapisummary::
 
-   piel.cocotb.core.write_cocotb_makefile
-   piel.cocotb.core.make_cocotb
+   piel.cocotb.core.delete_simulation_output_files
 
 
 .. py:function:: check_cocotb_testbench_exists(design_directory: str | pathlib.Path) -> bool
@@ -55,20 +54,26 @@ Attributes
 
    If no design_sources_list is provided then it adds all the design sources under the `src` folder.
 
-   In the form::
-       Makefile
+   In the form
+   .. code-block::
+
+       #!/bin/sh
+       # Makefile
        # defaults
        SIM ?= icarus
        TOPLEVEL_LANG ?= verilog
 
+       # Note we need to include the test script to the PYTHONPATH
+       export PYTHONPATH =
+
        VERILOG_SOURCES += $(PWD)/my_design.sv
        # use VHDL_SOURCES for VHDL files
 
        # TOPLEVEL is the name of the toplevel module in your Verilog or VHDL file
-       TOPLEVEL = my_design
+       TOPLEVEL := my_design
 
        # MODULE is the basename of the Python test file
-       MODULE = test_my_design
+       MODULE := test_my_design
 
        # include cocotb's make rules to take care of the simulator setup
        include $(shell cocotb-config --makefiles)/Makefile.sim
@@ -90,20 +95,19 @@ Attributes
    :returns: None
 
 
+.. py:data:: delete_simulation_output_files
+
+
+
 .. py:function:: run_cocotb_simulation(design_directory: str) -> subprocess.CompletedProcess
 
-   Equivalent to running the cocotb makefile::
+   Equivalent to running the cocotb makefile
+   .. code-block::
+
        make
 
    :param design_directory: The directory where the design is located.
    :type design_directory: str
 
    :returns: The subprocess.CompletedProcess object.
    :rtype: subprocess.CompletedProcess
-
-
-.. py:data:: write_cocotb_makefile
-
-
-
-.. py:data:: make_cocotb

docs/autoapi/piel/cocotb/index.rst

@@ -33,8 +33,7 @@ Attributes
 
 .. autoapisummary::
 
-   piel.cocotb.make_cocotb
-   piel.cocotb.write_cocotb_makefile
+   piel.cocotb.delete_simulation_output_files
 
 
 .. py:function:: check_cocotb_testbench_exists(design_directory: str | pathlib.Path) -> bool
@@ -54,20 +53,26 @@ Attributes
 
    If no design_sources_list is provided then it adds all the design sources under the `src` folder.
 
-   In the form::
-       Makefile
+   In the form
+   .. code-block::
+
+       #!/bin/sh
+       # Makefile
        # defaults
        SIM ?= icarus
        TOPLEVEL_LANG ?= verilog
 
+       # Note we need to include the test script to the PYTHONPATH
+       export PYTHONPATH =
+
        VERILOG_SOURCES += $(PWD)/my_design.sv
        # use VHDL_SOURCES for VHDL files
 
        # TOPLEVEL is the name of the toplevel module in your Verilog or VHDL file
-       TOPLEVEL = my_design
+       TOPLEVEL := my_design
 
        # MODULE is the basename of the Python test file
-       MODULE = test_my_design
+       MODULE := test_my_design
 
        # include cocotb's make rules to take care of the simulator setup
        include $(shell cocotb-config --makefiles)/Makefile.sim
@@ -89,20 +94,19 @@ Attributes
    :returns: None
 
 
-.. py:data:: make_cocotb
+.. py:data:: delete_simulation_output_files
 
 
 
 .. py:function:: run_cocotb_simulation(design_directory: str) -> subprocess.CompletedProcess
 
-   Equivalent to running the cocotb makefile::
+   Equivalent to running the cocotb makefile
+   .. code-block::
+
        make
 
    :param design_directory: The directory where the design is located.
    :type design_directory: str
 
    :returns: The subprocess.CompletedProcess object.
    :rtype: subprocess.CompletedProcess
-
-
-.. py:data:: write_cocotb_makefile

docs/autoapi/piel/components/index.rst

@@ -0,0 +1,4 @@
+:py:mod:`piel.components`
+=========================
+
+.. py:module:: piel.components

docs/autoapi/piel/config/index.rst

@@ -0,0 +1,19 @@
+:py:mod:`piel.config`
+=====================
+
+.. py:module:: piel.config
+
+.. autoapi-nested-parse::
+
+   We create a set of parameters that can be used throughout the project for optimisation.
+
+
+
+Module Contents
+---------------
+
+.. py:data:: numerical_solver
+
+
+
+.. py:data:: nso

docs/autoapi/piel/file_system/index.rst

@@ -16,7 +16,13 @@ Functions
    piel.file_system.check_path_exists
    piel.file_system.check_example_design
    piel.file_system.copy_source_folder
+   piel.file_system.create_new_directory
+   piel.file_system.delete_path
+   piel.file_system.delete_path_list_in_directory
+   piel.file_system.get_files_recursively_in_directory
    piel.file_system.permit_script_execution
+   piel.file_system.permit_directory_all
+   piel.file_system.read_json
    piel.file_system.return_path
    piel.file_system.run_script
    piel.file_system.setup_example_design
@@ -57,6 +63,57 @@ Functions
    :returns: None
 
 
+.. py:function:: create_new_directory(directory_path: str | pathlib.Path) -> None
+
+   Creates a new directory.
+
+   If the parents of the target_directory do not exist, they will be created too.
+
+   :param directory_path: Input path.
+   :type directory_path: str | pathlib.Path
+
+   :returns: None
+
+
+.. py:function:: delete_path(path: str | pathlib.Path) -> None
+
+   Deletes a path.
+
+   :param path: Input path.
+   :type path: str | pathlib.Path
+
+   :returns: None
+
+
+.. py:function:: delete_path_list_in_directory(directory_path: str | pathlib.Path, path_list: list, ignore_confirmation: bool = False, validate_individual: bool = False) -> None
+
+   Deletes a list of files in a directory.
+
+   :param directory_path: Input path.
+   :type directory_path: str | pathlib.Path
+   :param path_list: List of files.
+   :type path_list: list
+   :param ignore_confirmation: Ignore confirmation. Default: False.
+   :type ignore_confirmation: bool
+   :param validate_individual: Validate individual files. Default: False.
+   :type validate_individual: bool
+
+   :returns: None
+
+
+.. py:function:: get_files_recursively_in_directory(path: str | pathlib.Path, extension: str = '*')
+
+   Returns a list of files in a directory.
+
+   :param path: Input path.
+   :type path: str | pathlib.Path
+   :param extension: File extension.
+   :type extension: str
+
+   :returns: List of files.
+   :rtype: file_list(list)
+
+
 .. py:function:: permit_script_execution(script_path: str | pathlib.Path) -> None
 
    Permits the execution of a script.
@@ -67,6 +124,27 @@ Functions
    :returns: None
 
 
+.. py:function:: permit_directory_all(directory_path: str | pathlib.Path) -> None
+
+   Permits a directory to be read, written and executed. Use with care as it can be a source for security issues.
+
+   :param directory_path: Input path.
+   :type directory_path: str | pathlib.Path
+
+   :returns: None
+
+
+.. py:function:: read_json(path: str | pathlib.Path) -> dict
+
+   Reads a JSON file.
+
+   :param path: Input path.
+   :type path: str | pathlib.Path
+
+   :returns: JSON data.
+   :rtype: json_data(dict)
+
+
 .. py:function:: return_path(input_path: str | pathlib.Path) -> pathlib.Path
 
    Returns a pathlib.Path to be able to perform operations accordingly internally.