FEAT: Operation-based power estimation (#25)

* FEAT: Further README

* DOCS: Further wiring documentation

* DOCS: Further power theory

* FEAT: Intantaneous power extraction on SPICE

* REMOVE: Component section irrelevant

* FEAT: Further docs

docs/README.rst

@@ -1,7 +1,8 @@
-**P**\hotonic **I**\ntegrated **EL**\ectronics
-===============================================
+**P**\ hotonic **I**\ ntegrated **EL**\ ectronics
+=================================================
 
-|PyPI Name| |PyPI Version| |Build Status| |Documentation Status| |MIT| |Black|
+|PyPI Name| |PyPI Version| |Build Status| |Documentation Status| |MIT|
+|Black|
 
 Microservices to codesign photonics, electronics, communications,
 quantum, and more.
@@ -27,7 +28,8 @@ to easily connect them all together and extract the system performance.
 Examples
 --------
 
-Follow the many `examples in the documentation <https://piel.readthedocs.io/en/latest/examples.html>`__.
+Follow the many `examples in the
+documentation <https://piel.readthedocs.io/en/latest/examples.html>`__.
 
 Microservices Toolset
 ---------------------
@@ -37,36 +39,47 @@ microelectronics through the functionality of the
 `IIC-OSIC-TOOLS <https://github.com/iic-jku/iic-osic-tools>`__ and
 photonics via `GDSFactory <https://github.com/gdsfactory/gdsfactory>`__.
 
-.. image:: _static/img/piel_microservice_structure.png
+.. figure:: _static/img/piel_microservice_structure.png
+   :alt: image
+
+   image
 
 Some existing microservice dependency integrations are:
 
-* `cocotb <https://github.com/cocotb/cocotb>`__ - a coroutine based cosimulation library for writing VHDL and Verilog testbenches in Python.
-* `hdl21 <https://github.com/dan-fritchman/Hdl21>`__ - Analog Hardware Description Library in Python
-* `GDSFactory <https://github.com/gdsfactory/gdsfactory>`__ - An open source platform for end to-end photonic chip design and validation
-* `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.
-* `thewalrus <https://github.com/XanaduAI/thewalrus>`__ -A library for the calculation of hafnians, Hermite polynomials and Gaussian boson sampling.
-* `qutip <https://github.com/qutip/qutip>`__ - QuTiP: Quantum Toolbox in Python
+-  `cocotb <https://github.com/cocotb/cocotb>`__ - a coroutine based
+   cosimulation library for writing VHDL and Verilog testbenches in
+   Python.
+-  `hdl21 <https://github.com/dan-fritchman/Hdl21>`__ - Analog Hardware
+   Description Library in Python
+-  `GDSFactory <https://github.com/gdsfactory/gdsfactory>`__ - An open
+   source platform for end to-end photonic chip design and validation
+-  `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.
+-  `thewalrus <https://github.com/XanaduAI/thewalrus>`__ -A library for
+   the calculation of hafnians, Hermite polynomials and Gaussian boson
+   sampling.
+-  `qutip <https://github.com/qutip/qutip>`__ - QuTiP: Quantum Toolbox
+   in Python
 
 Contribution
 ------------
 
 If you feel dedicated enough to become a project maintainer, or just
 want to do a single contribution, let's do this together!
 
-
-.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
-    :target: https://github.com/psf/black
-.. |Build Status| image:: https://img.shields.io/travis/daquintero/piel.svg
+.. |PyPI Name| image:: https://img.shields.io/badge/pypi-piel-blue?style=for-the-badge
+   :target: https://pypi.python.org/pypi/piel
+.. |PyPI Version| image:: https://img.shields.io/pypi/v/piel.svg?style=for-the-badge
+   :target: https://pypi.python.org/pypi/piel
+.. |Build Status| image:: https://img.shields.io/travis/daquintero/piel.svg?style=for-the-badge
    :target: https://travis-ci.com/daquintero/piel
-.. |Documentation Status| image:: https://readthedocs.org/projects/piel/badge/?version=latest
+.. |Documentation Status| image:: https://readthedocs.org/projects/piel/badge/?style=for-the-badge
    :target: https://piel.readthedocs.io/en/latest/?version=latest
-.. |MIT| image:: https://img.shields.io/github/license/gdsfactory/gdsfactory
+.. |MIT| image:: https://img.shields.io/github/license/gdsfactory/gdsfactory?style=for-the-badge
    :target: https://choosealicense.com/licenses/mit/
-.. |PyPI Name| image:: https://img.shields.io/badge/pypi-piel-blue
-   :target: https://pypi.python.org/pypi/piel
-.. |PyPI Version| image:: https://img.shields.io/pypi/v/piel.svg
-   :target: https://pypi.python.org/pypi/piel
-.. |Updates| image:: https://pyup.io/repos/github/daquintero/piel/shield.svg
-   :target: https://pyup.io/repos/github/daquintero/piel/
+.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge
+   :target: https://github.com/psf/black

docs/autoapi/piel/index.rst

@@ -15,7 +15,6 @@ Subpackages
    :titlesonly:
    :maxdepth: 3
 
-   components/index.rst
    integration/index.rst
    models/index.rst
    tools/index.rst
@@ -1451,4 +1450,4 @@ Attributes
 
 
 .. py:data:: __version__
-   :value: '0.0.44'
+   :value: '0.0.45'

docs/examples.rst

@@ -14,5 +14,6 @@ Examples
    examples/03_sax_basics
    examples/03a_sax_cocotb_cosimulation
    examples//04_spice_cosimulation/04_spice_cosimulation
-   examples/04a_power_consumption_estimation
+   examples/04a_mixed_signal_photonic_cosimulation
    examples/05_quantum_integration_basics
+   examples/06_component_codesign_basics

docs/examples/04_spice_cosimulation/04_spice_cosimulation.py

@@ -5,6 +5,7 @@
 from gdsfactory.components import mzi2x2_2x2_phase_shifter
 import hdl21 as h
 import pandas as pd
+import numpy as np
 import piel
 import sys
 
@@ -396,7 +397,6 @@ class OperatingPointTb:
 # ```
 
 # #### A Simple Transient Simulation
-#
 
 # Let's assume we want to simulate in time how a pulse propagates through our circuit. A resistor on its own will have a linear relationship with the pulse, which means we should see how the current changes from the input pulse in time accordingly. For clarity, we will make a new testbench, even if there are ways to combine them.
 
@@ -480,9 +480,108 @@ class TransientTb:
     ],
     y_axis_title_list=["v(v.xtop.vvpulse)", "i(v.xtop.vvpulse)", "o4 Phase"],
 )
+simple_transient_plot.savefig(
+    "../../_static/img/examples/04_spice_cosimulation/simple_transient_plot.PNG"
+)
 
 # ![simple_transient_plot](../../_static/img/examples/04_spice_cosimulation/simple_transient_plot.PNG)
 
-# #### Automation
+# ##### Extracting Instantaneous Power and Resistance
+#
+# Now, we have the instantaneous current and voltage at a point in time. You can read some of the documentation in the `piel` website (TODO LINK) in order to realise the fundamental relationships of this signals. In this circuit, we know that the node `v(v.xtop.vvpulse)` is at the top of the resistor, and the circuit ground `vss` is at the bottom. We can read the SPICE netlist to determine this (TODO add automatic schematic mapper). The current `i(v.xtop.vvpulse)` flows across this resistor according to standard Ohm's law. So we can extract both the instantaneous power consumption and resistance just from these graphs. Note that this means that these values are subject to insignificant variations from the solver accuracy, so you might want to round to the nearest resistance values for example in some cases.
+#
+# For this simple example, it is trivial, and we will demonstrate it, but for more complex circuit examples, having a generic framework is important:
+
+transient_simulation_results["power(xtop.vpulse)"] = (
+    transient_simulation_results["v(xtop.vpulse_p)"]
+    * transient_simulation_results["i(v.xtop.vvpulse)"]
+)
+transient_simulation_results["resistance(xtop.vpulse)"] = np.round(
+    transient_simulation_results["v(xtop.vpulse_p)"]
+    / transient_simulation_results["i(v.xtop.vvpulse)"]
+)
+transient_simulation_results
+
+# Note that because the resistance is constant, the power consumption should only vary when there is a change in the signal input. The resistance will always remain constant as the signal voltage and current change, as it is a physical material, and it is easily verified.
+
+transient_simulation_results.iloc[20:40]
+
+# |    | Unnamed: 0 |   time | v(xtop.vpulse_p) | i(v.xtop.vvpulse) | power(xtop.vpulse) | resistance(xtop.vpulse) |
+# |---:|----------:|-------:|-----------------:|------------------:|-------------------:|-----------------------:|
+# | 20 |        20 | 0.00107 |           -0.986 |          0.000986 |        -0.000972196 |                   1000 |
+# | 21 |        21 | 0.00115 |           -0.97  |          0.00097  |        -0.0009409   |                   1000 |
+# | 22 |        22 | 0.00125 |           -0.95  |          0.00095  |        -0.0009025   |                   1000 |
+# | 23 |        23 | 0.00135 |           -0.93  |          0.00093  |        -0.0008649   |                   1000 |
+# | 24 |        24 | 0.00145 |           -0.91  |          0.00091  |        -0.0008281   |                   1000 |
+# | 25 |        25 | 0.00155 |           -0.89  |          0.00089  |        -0.0007921   |                   1000 |
+# | 26 |        26 | 0.00165 |           -0.87  |          0.00087  |        -0.0007569   |                   1000 |
+# | 27 |        27 | 0.00175 |           -0.85  |          0.00085  |        -0.0007225   |                   1000 |
+# | 28 |        28 | 0.00185 |           -0.83  |          0.00083  |        -0.0006889   |                   1000 |
+# | 29 |        29 | 0.00195 |           -0.81  |          0.00081  |        -0.0006561   |                   1000 |
+# | 30 |        30 | 0.00205 |           -0.79  |          0.00079  |        -0.0006241   |                   1000 |
+# | 31 |        31 | 0.00215 |           -0.77  |          0.00077  |        -0.0005929   |                   1000 |
+# | 32 |        32 | 0.00225 |           -0.75  |          0.00075  |        -0.0005625   |                   1000 |
+# | 33 |        33 | 0.00235 |           -0.73  |          0.00073  |        -0.0005329   |                   1000 |
+# | 34 |        34 | 0.00245 |           -0.71  |          0.00071  |        -0.0005041   |                   1000 |
+# | 35 |        35 | 0.00255 |           -0.69  |          0.00069  |        -0.0004761   |                   1000 |
+# | 36 |        36 | 0.00265 |           -0.67  |          0.00067  |        -0.0004489   |                   1000 |
+# | 37 |        37 | 0.00275 |           -0.65  |          0.00065  |        -0.0004225   |                   1000 |
+# | 38 |        38 | 0.00285 |           -0.63  |          0.00063  |        -0.0003969   |                   1000 |
+# | 39 |        39 | 0.00295 |           -0.61  |          0.00061  |        -0.0003721   |                   1000 |
+#
+
+simple_transient_plot_power_resistance = piel.visual.plot_simple_multi_row(
+    data=transient_simulation_results,
+    x_axis_column_name="time",
+    row_list=[
+        "resistance(xtop.vpulse)",
+        "power(xtop.vpulse)",
+    ],
+    y_axis_title_list=[r"resistance ($\Omega$)", r"power ($W$)"],
+)
+simple_transient_plot_power_resistance.savefig(
+    "../../_static/img/examples/04_spice_cosimulation/simple_transient_plot_power_resistance.PNG"
+)
+
+# ![simple_transient_plot_power_resistance](../../_static/img/examples/04_spice_cosimulation/simple_transient_plot_power_resistance.PNG)
+
+# So, we have extracted the power consumption throughout time for pulses we have configured. For the whole period of the simulation, we can extract the energy consumed as the integral of power for a time differential. Note that we expect the energy consumption of this particular circuit, where the resistor is constantly drawing current, to be constantly increasing in time. We can perform a cumulative sum over our `power(xtop.vpulse)` dataframe which is a discrete integral, and we can multiply that term with the time value to determine the total energy consumption at a point in time.
 
-# Now, these transient simulations are something you might want to very configure depending on the type of signals that you might want to verify. However, we can provide some basic parameterised simple functions such as step responses and so on. So instead of having to write everything above, you can also just run the following, for example: WIP
+transient_simulation_results["energy_consumed(xtop.vpulse)"] = (
+    transient_simulation_results["power(xtop.vpulse)"].cumsum()
+    * transient_simulation_results["time"]
+)
+transient_simulation_results
+
+simple_energy_consumed_plot = transient_simulation_results.plot(
+    x="time", y="energy_consumed(xtop.vpulse)"
+)
+simple_energy_consumed_plot.get_figure().savefig(
+    "../../_static/img/examples/04_spice_cosimulation/simple_energy_consumed_plot.PNG"
+)
+
+# ![simple_energy_consumed_plot](../../_static/img/examples/04_spice_cosimulation/simple_energy_consumed_plot.PNG)
+
+# A full visualisation of the signal is including the cumulative energy use:
+
+simple_transient_plot_full = piel.visual.plot_simple_multi_row(
+    data=transient_simulation_results,
+    x_axis_column_name="time",
+    row_list=[
+        "v(xtop.vpulse_p)",
+        "i(v.xtop.vvpulse)",
+        "resistance(xtop.vpulse)",
+        "power(xtop.vpulse)",
+        "energy_consumed(xtop.vpulse)",
+    ],
+    y_axis_title_list=[r"$V$", r"$A$", r"$\Omega$", r"$W$", r"$J$"],
+)
+simple_transient_plot_full.savefig(
+    "../../_static/img/examples/04_spice_cosimulation/simple_transient_plot_full.PNG"
+)
+
+# ![simple_transient_plot_full](../../_static/img/examples/04_spice_cosimulation/simple_transient_plot_full.PNG)
+
+# ### Driving our Phase Shifter
+#
+# We have demonstrated how we can extract a simple model of a resistor and create different types of `SPICE` simulations. Now, let's consider how would this affect the photonic performance in a phase-shifter context. One important aspect is that we need to create a mapping between our analogue voltage and a phase. Ideally, this should be a functional mapping.

docs/examples/04a_power_consumption_estimation.py → docs/examples/04a_mixed_signal_photonic_cosimulation.py

@@ -1,4 +1,8 @@
-# # Mixed-Signal & Photonic Power Consumption Calculation
+# # Mixed-Signal & Photonic Cosimulation
+
+# #### Automation
+
+# Now, these transient simulations are something you might want to very configure depending on the type of signals that you might want to verify. However, we can provide some basic parameterised simple functions such as step responses and so on. So instead of having to write everything above, you can also just run the following, for example: WIP
 
 # One desired output of an electrical model simulation is an extraction of the power consumption of the circuit. Fundamentally, this is dependent on the time and the operation performed. Hence, to estimate an average power consumption, it is more effective to define the power consumption of a particular operation, and extract the power consumption for the frequency at which this operation is performed.
 #

docs/examples/06_component_codesign_basics.py

@@ -0,0 +1,9 @@
+# # Component Codesign Basics
+
+# When we have photonic components driven by electronic devices, there is a scope that we might want to optimise certain devices to be faster, smaller, or less power-consumptive. It can be complicated to do this just analytically, so we would like to have the capability of integrating our design software for each of our devices with our simulation software of our electronics. There might be multiple  software tools to design different devices, and the benefit of integrating these tools via open-source is that co-design becomes much more feasible and meaningful.
+#
+# In this example, we will continue exploring the co-design of a thermo-optic phase shifter in continuation of all the previous examples. However, this time, we will perform some optimisation in its design parameters and related. We will use the `femwell` package that is part of the `GDSFactory` suite.
+#
+# ## Start from Femwell `TiN TOPS heater` example
+#
+# We will begin by extracting the electrical parameters of the basic `TiN TOPS heater` example provided in [`femwell`](https://helgegehring.github.io/femwell/photonics/examples/metal_heater_phase_shifter.html). We will create a function where we change the width of the heater, and we explore the change in resistance, but also in thermo-optic phase modulation efficiency.

docs/index.rst

@@ -13,7 +13,6 @@ Contents
    sections/environment/index
    sections/microservices/index
    sections/codesign/index
-   sections/components/index
    sections/models/index
    contributing
    sections/about/index

docs/sections/codesign/index.rst

@@ -5,5 +5,5 @@ Co-Design Functionality
     :caption: Contents:
 
     parametric
-    power_time_metrics
+    principles/index
     mixed_signal_electronic_photonic

docs/sections/codesign/principles/fundamentals.rst

@@ -0,0 +1,29 @@
+Fundamental Electronic Definitions
+==================================
+
+Read more in *The Art of Electronics* by Paul Horowitz and Winfield Hill.
+
+There are some important definitions we must account for in terms of analysing the data of our simulations.
+
+.. list-table:: Fundamental Definitions
+   :widths: 25 50 50
+   :header-rows: 1
+
+   * - Term
+     - Definition
+     - Unit
+   * - Voltage :math:`V`
+     - The work on electric charges.
+     - It takes :math:`1J` Joule to move :math:`1C` Coulomb of charge through a potential of :math:`1V` volt.
+   * - Current :math:`i`
+     - The rate of the flow of electric charge past a point.
+     - :math:`1A` amp defines the movement of the above :math:`1C` Coulomb of charge flows in :math:`1s` second.
+   * - Power :math:`W`
+     - For a differential of time, this is the rate energy consumed for that slice of time.
+     - :math:`W = VI` Watt defines the rate of energy flow of the above :math:`1J` Joule in :math:`1s` second.
+   * - Energy :math:`J`
+     - Applied power throughout a slice of time.
+     - :math:`J = Ws` Joule is equal to :math:`1W` Watt of power flowing throughout :math:`1s` second.
+
+
+Currents occur by placing a voltage through a device, and the rate of the current, hence the rate of the power consumption is dependent on the channel *impedance*. Now, this has an important effect on microwave engineering and system design.

docs/sections/codesign/principles/index.rst

@@ -0,0 +1,15 @@
+Fundamental Principles Theory
+=============================
+
+It is important to understand the fundamental physical relationships of consigning photonics and electronics systems. Really, we are combining two engineering fields: photonics engineering and electronics engineering. The overlap between the fields, and interconnected relationships, are essential to optimise the system design between them.
+
+.. toctree::
+    :caption: Contents:
+
+    fundamentals
+    passives
+    power_time_metrics
+
+.. include:: fundamentals.rst
+.. include:: passives.rst
+.. include:: power_time_metrics.rst