FEAT: SPICE simulation data, system metrics documentation (#24)

* FEAT: Beginning to structure multi-domain simulation

* DOCS: System metrics analysis

* DOCS: Further

* FEAT: Transient and DC operating point simulations configured

* FEAT: Simulation data generated

* FEAT: Simulation data generated

* FEAT: Extracting data plots

* FEAT: Simulation data generated

* FEAT: Further docs

* FIX: SPICE include generators

* FEAT: Working SPICE

* FEAT: Fix docs

.gitignore

@@ -195,3 +195,4 @@ waves.shm/
 
 ivl_vhdl_work/
 RUN_*
+*.raw

CONTRIBUTING.rst

@@ -68,7 +68,7 @@ Ready to contribute? Here's how to set up `piel` for local development.
 
     $ mkvirtualenv piel
     $ cd piel/
-    $ python setup.py develop
+    $ pip install -e .
 
 4. Create a branch for local development::
 

README.md

@@ -1,15 +1,14 @@
 # **P**hotonic **I**ntegrated **EL**ectronics
-
 [![PyPI
-Name](https://img.shields.io/badge/pypi-piel-blue)](https://pypi.python.org/pypi/piel)
+Name](https://img.shields.io/badge/pypi-piel-blue?style=for-the-badge)](https://pypi.python.org/pypi/piel)
 [![PyPI
-Version](https://img.shields.io/pypi/v/piel.svg)](https://pypi.python.org/pypi/piel)
+Version](https://img.shields.io/pypi/v/piel.svg?style=for-the-badge)](https://pypi.python.org/pypi/piel)
 [![Build
-Status](https://img.shields.io/travis/daquintero/piel.svg)](https://travis-ci.com/daquintero/piel)
+Status](https://img.shields.io/travis/daquintero/piel.svg?style=for-the-badge)](https://travis-ci.com/daquintero/piel)
 [![Documentation
-Status](https://readthedocs.org/projects/piel/badge/?version=latest)](https://piel.readthedocs.io/en/latest/?version=latest)
-[![MIT](https://img.shields.io/github/license/gdsfactory/gdsfactory)](https://choosealicense.com/licenses/mit/)
-[![Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+Status](https://readthedocs.org/projects/piel/badge/?style=for-the-badge)](https://piel.readthedocs.io/en/latest/?version=latest)
+[![MIT](https://img.shields.io/github/license/gdsfactory/gdsfactory?style=for-the-badge)](https://choosealicense.com/licenses/mit/)
+[![Black](https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge)](https://github.com/psf/black)
 
 Microservices to codesign photonics, electronics, communications,
 quantum, and more.

docs/autoapi/piel/index.rst

@@ -111,6 +111,10 @@ Functions
    piel.get_file_line_by_keyword
    piel.read_file_lines
    piel.run_openlane_flow
+   piel.configure_ngspice_simulation
+   piel.configure_operating_point_simulation
+   piel.configure_transient_simulation
+   piel.run_simulation
    piel.convert_numeric_to_prefix
    piel.get_sdense_ports_index
    piel.sax_to_s_parameters_standard_matrix
@@ -1146,6 +1150,62 @@ Attributes
    :returns: None
 
 
+.. py:function:: configure_ngspice_simulation(run_directory: piel.config.piel_path_types = '.')
+
+   This function configures the NGSPICE simulation for the circuit and returns a simulation class.
+
+   :param run_directory: Directory where the simulation will be run
+   :type run_directory: piel_path_types
+
+   :returns: Configured NGSPICE simulation options
+   :rtype: simulation_options
+
+
+.. py:function:: configure_operating_point_simulation(testbench: hdl21.Module, **kwargs)
+
+   This function configures the DC operating point simulation for the circuit and returns a simulation class.
+
+   :param testbench: HDL21 testbench
+   :type testbench: Module
+   :param \*\*kwargs: Additional arguments to be passed to the operating point simulation such as name.
+
+   :returns: HDL21 simulation class
+   :rtype: Simulation
+
+
+.. py:function:: configure_transient_simulation(testbench: hdl21.Module, stop_time_s: float, step_time_s: float, **kwargs)
+
+   This function configures the transient simulation for the circuit and returns a simulation class.
+
+   :param testbench: HDL21 testbench
+   :type testbench: Module
+   :param stop_time_s: Stop time of the simulation in seconds
+   :type stop_time_s: float
+   :param step_time_s: Step time of the simulation in seconds
+   :type step_time_s: float
+   :param \*\*kwargs: Additional arguments to be passed to the transient simulation
+
+   :returns: HDL21 simulation class
+   :rtype: Simulation
+
+
+.. py:function:: run_simulation(simulation: hdl21.sim.Sim, simulator_name: Literal[ngspice] = 'ngspice', simulation_options: Optional[vlsirtools.spice.SimOptions] = None, to_csv: bool = True)
+
+   This function runs the transient simulation for the circuit and returns the results.
+
+   :param simulation: HDL21 simulation class
+   :type simulation: h.sim.Sim
+   :param simulator_name: Name of the simulator
+   :type simulator_name: Literal["ngspice"]
+   :param simulation_options: Simulation options
+   :type simulation_options: Optional[vsp.SimOptions]
+   :param to_csv: Whether to save the results to a csv file
+   :type to_csv: bool
+
+   :returns: Simulation results
+   :rtype: results
+
+
 .. py:function:: convert_numeric_to_prefix(value: float)
 
    This function converts a numeric value to a number under a SPICE unit closest to the base prefix. This allows us to connect a particular number real output, into a term that can be used in a SPICE netlist.

docs/autoapi/piel/tools/hdl21/index.rst

@@ -24,10 +24,70 @@ Functions
 
 .. autoapisummary::
 
+   piel.tools.hdl21.configure_ngspice_simulation
+   piel.tools.hdl21.configure_operating_point_simulation
+   piel.tools.hdl21.configure_transient_simulation
+   piel.tools.hdl21.run_simulation
    piel.tools.hdl21.convert_numeric_to_prefix
 
 
 
+.. py:function:: configure_ngspice_simulation(run_directory: piel.config.piel_path_types = '.')
+
+   This function configures the NGSPICE simulation for the circuit and returns a simulation class.
+
+   :param run_directory: Directory where the simulation will be run
+   :type run_directory: piel_path_types
+
+   :returns: Configured NGSPICE simulation options
+   :rtype: simulation_options
+
+
+.. py:function:: configure_operating_point_simulation(testbench: hdl21.Module, **kwargs)
+
+   This function configures the DC operating point simulation for the circuit and returns a simulation class.
+
+   :param testbench: HDL21 testbench
+   :type testbench: Module
+   :param \*\*kwargs: Additional arguments to be passed to the operating point simulation such as name.
+
+   :returns: HDL21 simulation class
+   :rtype: Simulation
+
+
+.. py:function:: configure_transient_simulation(testbench: hdl21.Module, stop_time_s: float, step_time_s: float, **kwargs)
+
+   This function configures the transient simulation for the circuit and returns a simulation class.
+
+   :param testbench: HDL21 testbench
+   :type testbench: Module
+   :param stop_time_s: Stop time of the simulation in seconds
+   :type stop_time_s: float
+   :param step_time_s: Step time of the simulation in seconds
+   :type step_time_s: float
+   :param \*\*kwargs: Additional arguments to be passed to the transient simulation
+
+   :returns: HDL21 simulation class
+   :rtype: Simulation
+
+
+.. py:function:: run_simulation(simulation: hdl21.sim.Sim, simulator_name: Literal[ngspice] = 'ngspice', simulation_options: Optional[vlsirtools.spice.SimOptions] = None, to_csv: bool = True)
+
+   This function runs the transient simulation for the circuit and returns the results.
+
+   :param simulation: HDL21 simulation class
+   :type simulation: h.sim.Sim
+   :param simulator_name: Name of the simulator
+   :type simulator_name: Literal["ngspice"]
+   :param simulation_options: Simulation options
+   :type simulation_options: Optional[vsp.SimOptions]
+   :param to_csv: Whether to save the results to a csv file
+   :type to_csv: bool
+
+   :returns: Simulation results
+   :rtype: results
+
+
 .. py:function:: convert_numeric_to_prefix(value: float)
 
    This function converts a numeric value to a number under a SPICE unit closest to the base prefix. This allows us to connect a particular number real output, into a term that can be used in a SPICE netlist.

docs/autoapi/piel/tools/hdl21/simulator/index.rst

@@ -13,10 +13,64 @@ Functions
 
 .. autoapisummary::
 
+   piel.tools.hdl21.simulator.configure_ngspice_simulation
+   piel.tools.hdl21.simulator.configure_operating_point_simulation
    piel.tools.hdl21.simulator.configure_transient_simulation
+   piel.tools.hdl21.simulator.run_simulation
 
 
 
-.. py:function:: configure_transient_simulation(circuit: hdl21.Module, stop_time_s: float, step_time_s: float)
+.. py:function:: configure_ngspice_simulation(run_directory: piel.config.piel_path_types = '.')
 
-   This function configures the transient simulation for the circuit.
+   This function configures the NGSPICE simulation for the circuit and returns a simulation class.
+
+   :param run_directory: Directory where the simulation will be run
+   :type run_directory: piel_path_types
+
+   :returns: Configured NGSPICE simulation options
+   :rtype: simulation_options
+
+
+.. py:function:: configure_operating_point_simulation(testbench: hdl21.Module, **kwargs)
+
+   This function configures the DC operating point simulation for the circuit and returns a simulation class.
+
+   :param testbench: HDL21 testbench
+   :type testbench: Module
+   :param \*\*kwargs: Additional arguments to be passed to the operating point simulation such as name.
+
+   :returns: HDL21 simulation class
+   :rtype: Simulation
+
+
+.. py:function:: configure_transient_simulation(testbench: hdl21.Module, stop_time_s: float, step_time_s: float, **kwargs)
+
+   This function configures the transient simulation for the circuit and returns a simulation class.
+
+   :param testbench: HDL21 testbench
+   :type testbench: Module
+   :param stop_time_s: Stop time of the simulation in seconds
+   :type stop_time_s: float
+   :param step_time_s: Step time of the simulation in seconds
+   :type step_time_s: float
+   :param \*\*kwargs: Additional arguments to be passed to the transient simulation
+
+   :returns: HDL21 simulation class
+   :rtype: Simulation
+
+
+.. py:function:: run_simulation(simulation: hdl21.sim.Sim, simulator_name: Literal[ngspice] = 'ngspice', simulation_options: Optional[vlsirtools.spice.SimOptions] = None, to_csv: bool = True)
+
+   This function runs the transient simulation for the circuit and returns the results.
+
+   :param simulation: HDL21 simulation class
+   :type simulation: h.sim.Sim
+   :param simulator_name: Name of the simulator
+   :type simulator_name: Literal["ngspice"]
+   :param simulation_options: Simulation options
+   :type simulation_options: Optional[vsp.SimOptions]
+   :param to_csv: Whether to save the results to a csv file
+   :type to_csv: bool
+
+   :returns: Simulation results
+   :rtype: results

docs/autoapi/piel/tools/index.rst

@@ -68,6 +68,10 @@ Functions
    piel.tools.get_file_line_by_keyword
    piel.tools.read_file_lines
    piel.tools.run_openlane_flow
+   piel.tools.configure_ngspice_simulation
+   piel.tools.configure_operating_point_simulation
+   piel.tools.configure_transient_simulation
+   piel.tools.run_simulation
    piel.tools.convert_numeric_to_prefix
    piel.tools.get_sdense_ports_index
    piel.tools.sax_to_s_parameters_standard_matrix
@@ -669,6 +673,62 @@ Attributes
    :returns: None
 
 
+.. py:function:: configure_ngspice_simulation(run_directory: piel.config.piel_path_types = '.')
+
+   This function configures the NGSPICE simulation for the circuit and returns a simulation class.
+
+   :param run_directory: Directory where the simulation will be run
+   :type run_directory: piel_path_types
+
+   :returns: Configured NGSPICE simulation options
+   :rtype: simulation_options
+
+
+.. py:function:: configure_operating_point_simulation(testbench: hdl21.Module, **kwargs)
+
+   This function configures the DC operating point simulation for the circuit and returns a simulation class.
+
+   :param testbench: HDL21 testbench
+   :type testbench: Module
+   :param \*\*kwargs: Additional arguments to be passed to the operating point simulation such as name.
+
+   :returns: HDL21 simulation class
+   :rtype: Simulation
+
+
+.. py:function:: configure_transient_simulation(testbench: hdl21.Module, stop_time_s: float, step_time_s: float, **kwargs)
+
+   This function configures the transient simulation for the circuit and returns a simulation class.
+
+   :param testbench: HDL21 testbench
+   :type testbench: Module
+   :param stop_time_s: Stop time of the simulation in seconds
+   :type stop_time_s: float
+   :param step_time_s: Step time of the simulation in seconds
+   :type step_time_s: float
+   :param \*\*kwargs: Additional arguments to be passed to the transient simulation
+
+   :returns: HDL21 simulation class
+   :rtype: Simulation
+
+
+.. py:function:: run_simulation(simulation: hdl21.sim.Sim, simulator_name: Literal[ngspice] = 'ngspice', simulation_options: Optional[vlsirtools.spice.SimOptions] = None, to_csv: bool = True)
+
+   This function runs the transient simulation for the circuit and returns the results.
+
+   :param simulation: HDL21 simulation class
+   :type simulation: h.sim.Sim
+   :param simulator_name: Name of the simulator
+   :type simulator_name: Literal["ngspice"]
+   :param simulation_options: Simulation options
+   :type simulation_options: Optional[vsp.SimOptions]
+   :param to_csv: Whether to save the results to a csv file
+   :type to_csv: bool
+
+   :returns: Simulation results
+   :rtype: results
+
+
 .. py:function:: convert_numeric_to_prefix(value: float)
 
    This function converts a numeric value to a number under a SPICE unit closest to the base prefix. This allows us to connect a particular number real output, into a term that can be used in a SPICE netlist.

docs/examples.rst

@@ -13,5 +13,6 @@ Examples
    examples/02_cocotb_simulation
    examples/03_sax_basics
    examples/03a_sax_cocotb_cosimulation
-   examples/04_spice_cosimulation
+   examples//04_spice_cosimulation/04_spice_cosimulation
+   examples/04a_power_consumption_estimation
    examples/05_quantum_integration_basics