FEAT: Pydantic v1 pinned requirements (#42)

* FEAT: Initialise basic principles of the piel example

* FEAT: Further documentation

* FEAT: Further schematic to layout

* FEAT: Tie down requirements

* FEAT: Pin requirements to pre-pydantic v2 compatibility

docs/examples/04a_analogue_circuit_layout_simulation/04a_analogue_circuit_layout_simulation.py

@@ -25,11 +25,50 @@
 #
 # So, as we can see, there currently are many separate relevant projects that solve different aspects of an integration flow. What we would like to do is to have an integrated flow where we could, for example, do some schematic-driven-layout or some layout-driven-schematic extraction. These are some of the objectives of the flow that we would like to demonstrate.
 
+# ## Going through the Basics
+
+# We will start off by importing the layout elements of the SKY130nm `gdsfactory` PDK process and understanding how we interact and map them to a schematic.
+
+import gdsfactory as gf
+import sky130.components as sc
+import sky130.tech as st
+
+import piel
+
+basic_component = sc.sky130_fd_sc_hd__a2111o_1()
+basic_component.plot_widget()
+
+# ![mzi2x2_2x2_phase_shifter](../../_static/img/examples/04a_analogue_circuit_layout_simulation/basic_sky130_fd_sc_hd__a2111o_1.PNG)
+
+# You can read more about the basics of using this PDK in this [gdsfactory SKY130nm example](https://gdsfactory.github.io/skywater130/notebooks/intro.html).
+
+# What we would like to do is create a mapping that we could extract from a `gdsfactory` layout to the `hdl21` model mapping. Let's extract a netlist in this case:
+
+basic_component.get_netlist()
+
+# ```python
+# {'connections': {},
+#  'instances': {},
+#  'placements': {},
+#  'ports': {},
+#  'name': 'sky130_fd_sc_hd__a2111o_1'}
+# ```
+
+# We know that these cells were imported from the raw gds files provided by skywater, which means they will not store raw geometrical connectivity. This is a feature that we would need to implement into gdsfactory or whatever backend can extract, the connectivity in a compatible way to `gdsfactory` from layer geometry.
+#
+# We know that when we do the recursive netlisting, we also do not get anything, as there is little connectivity that we can extract:
+
+basic_component.get_netlist_recursive()
+
+# We need to be able to extract a recursive netlist that allows us to map our cell instance to our component spice element.
+#
+# gdsfactory PR this recursive instance extraction, and then work on the mapping.
+
 # ## Schematic-Driven-Layout
 
 # A common analogue design flow is called schematic-driven-layout. What this entails, fundamentally, is that we design a circuit through a schematic, and then use that schematic to instruct, extract, constrain, and/or verify our circuit chip layout. This flow uses layout elements that are connected or tied to schematic symbols, and unique names that allow for identification and connectivity relationship.
 #
-# TODO ADD SOME REFERENCES EXPLAINING SCHEMATIC DRIVEN LAYOUT.
+# -  You can read [how this is done in Cadence](https://web.njit.edu/~tyson/cadence%20Layout_Tutorial.pdf)
 #
 # In an open-source flow, this could be, for example, demonstrated by creating a circuit using the `hdl21 schematic` tools. Each symbol would reference a specific `PCell` in the PDK. Now, we would use this individual element cell name to connect and extract to the `SPICE` model and also to the `layout` GDS cell. This allows us to connect to the separate tools for simulation and layout.
 #

docs/examples/designs/amaranth_driven_flow/amaranth_driven_flow/src/our_truth_table_module.v

@@ -5,27 +5,27 @@
 (* generator = "Amaranth" *)
 module top(phase_map_out, detector_in);
   reg \$auto$verilog_backend.cc:2083:dump_module$1  = 0;
-  (* src = "c:\\users\\dario\\documents\\phd\\piel\\piel\\tools\\amaranth\\construct.py:42" *)
+  (* src = "C:\\Users\\dario\\Documents\\phd\\piel\\piel\\tools\\amaranth\\construct.py:42" *)
   input [1:0] detector_in;
   wire [1:0] detector_in;
-  (* src = "c:\\users\\dario\\documents\\phd\\piel\\piel\\tools\\amaranth\\construct.py:42" *)
+  (* src = "C:\\Users\\dario\\Documents\\phd\\piel\\piel\\tools\\amaranth\\construct.py:42" *)
   output [1:0] phase_map_out;
   reg [1:0] phase_map_out;
   always @* begin
     if (\$auto$verilog_backend.cc:2083:dump_module$1 ) begin end
     (* full_case = 32'd1 *)
-    (* src = "c:\\users\\dario\\documents\\phd\\piel\\piel\\tools\\amaranth\\construct.py:56" *)
+    (* src = "C:\\Users\\dario\\Documents\\phd\\piel\\piel\\tools\\amaranth\\construct.py:57" *)
     casez (detector_in)
-      /* src = "c:\\users\\dario\\documents\\phd\\piel\\piel\\tools\\amaranth\\construct.py:59" */
+      /* src = "C:\\Users\\dario\\Documents\\phd\\piel\\piel\\tools\\amaranth\\construct.py:60" */
       2'h0:
           phase_map_out = 2'h0;
-      /* src = "c:\\users\\dario\\documents\\phd\\piel\\piel\\tools\\amaranth\\construct.py:59" */
+      /* src = "C:\\Users\\dario\\Documents\\phd\\piel\\piel\\tools\\amaranth\\construct.py:60" */
       2'h1:
           phase_map_out = 2'h2;
-      /* src = "c:\\users\\dario\\documents\\phd\\piel\\piel\\tools\\amaranth\\construct.py:59" */
+      /* src = "C:\\Users\\dario\\Documents\\phd\\piel\\piel\\tools\\amaranth\\construct.py:60" */
       2'h2:
           phase_map_out = 2'h3;
-      /* src = "c:\\users\\dario\\documents\\phd\\piel\\piel\\tools\\amaranth\\construct.py:59" */
+      /* src = "C:\\Users\\dario\\Documents\\phd\\piel\\piel\\tools\\amaranth\\construct.py:60" */
       2'h3:
           phase_map_out = 2'h3;
     endcase

docs/examples/designs/amaranth_driven_flow/amaranth_driven_flow/tb/our_truth_table_module.vcd

@@ -1,5 +1,5 @@
 $comment Generated by Amaranth $end
-$date 2023-08-25 09:34:27.528232 $end
+$date 2023-09-05 09:59:56.863592 $end
 $timescale 1 ps $end
 $scope module bench $end
 $scope module top $end

docs/sections/environment/tools_environment.rst

@@ -8,7 +8,16 @@ to note that not *all* tools require a Linux flow, and it is possible to
 do co-design at different stages in different environments. This could
 be useful to distributed teams, or at different stages of a design flow between prototyping a design and full optimisation iterations.
 
-To guarantee full functionality of ``piel``, the recommended environment installation is following the standard IIC-OSIC-TOOLS installation configuration. However, this table of tools compatibility is provided should you use a specific set of toolsets in a given environment. No functionality guarantees are provided in that case.
+One of the main complexities of multi-tool open source design is the version management of the tools, and making sure they all speak to each other without conflicting tool environment requirements. In ``piel``, we provide a set of environment solutions to guarantee the shared functionality between the toolsets. This means we forcibly tie down each tool version to what we know works and that our examples pass as a result. This means that if you want to upgrade to a latest version, you will need to do the upgrade and verification that the tool compatibility passes.
+
+The implementation of this consists of tying down the requirements of the primary dependencies of the project, but not the secondary ones. This means that we expect the secondary dependencies to resolve through the dependency management system when providing a suitable primary dependency environment.
+
+To guarantee full functionality of ``piel``, we provide some customised environment installations, particularly through ``nix`` in Linux.
+
+Dependency Environment Breakdown
+-----------------------------------------------
+
+This table of tools compatibility is provided should you use a specific set of toolsets in a given environment. No complete functionality guarantees are provided in this case.
 
 
 .. list-table:: Tools Compatibility
@@ -53,12 +62,3 @@ To guarantee full functionality of ``piel``, the recommended environment install
 This is a preliminary table, I mostly develop on Linux, you need to verify your system configuration or use the recommended Docker environment. TODO I am unsure about the OS X integrations.
 
 In the future, we will have custom installations for different types of users so they can install minimal dependencies for their use case.
-
-Multi-Platform Dependency Installation Commands
------------------------------------------------
-
-Maybe in the future I will write a mamba recepie for the piel installation.
-
-.. code-block::
-
-    mamba install ngspice -y # For NGPICE in any environment

piel/integration/gdsfactory_hdl21/conversion.py

@@ -9,7 +9,7 @@
 import copy
 import networkx as nx
 from sax.circuit import (
-    create_dag,
+    _create_dag,
     _ensure_recursive_netlist_dict,
     remove_unused_instances,
     _extract_instance_models,
@@ -126,7 +126,7 @@ def gdsfactory_netlist_with_hdl21_generators(
 
     recnet: RecursiveNetlist = _validate_net(netlist)
     dependency_dag: nx.DiGraph = _validate_dag(
-        create_dag(recnet, generators)
+        _create_dag(recnet, generators)
     )  # directed acyclic graph
     generators = _validate_models(
         {**(generators or {}), **instance_models}, dependency_dag
@@ -212,7 +212,7 @@ def gdsfactory_netlist_to_spice_string_connectivity_netlist(
 
     recnet: RecursiveNetlist = _validate_net(netlist)
     dependency_dag: nx.DiGraph = _validate_dag(
-        create_dag(recnet, models)
+        _create_dag(recnet, models)
     )  # directed acyclic graph
     models = _validate_models({**(models or {}), **instance_models}, dependency_dag)
 

setup.py

@@ -9,25 +9,24 @@
 
 requirements = [
     # "amaranth",  # Until they sort out their packaging issue, this dependency has to be installed separately. .
-    "amaranth-yosys",
+    "amaranth-yosys==0.25.0.0.post75",
     "cython==0.29.21",
-    "jupytext",
+    "jupytext==1.15.0",
     "Click>=7.0",
-    "cocotb",
-    "femwell",
-    "hdl21>=4",
-    "jax",
-    "jaxlib",
-    "gdsfactory==7.3.0",
-    "networkx",
+    "cocotb==1.8.0",
+    "femwell==0.1.8",
+    "hdl21==4.0.0",
+    "jax==0.4.14",
+    "jaxlib==0.4.14",
+    "gdsfactory==7.3.0",  # Pinned for pydantic <v2 compatibility.
+    "networkx==3.1",
     "numpy",
-    "openlane",
+    "openlane==2.0.0b8",
     "pandas",
-    "pydantic<2",  # Project requirements to maintain compatibility.
-    "qutip",
+    "qutip==4.7.2",
     "sax==0.8.8",  # Pinned for pydantic <v2 compatibility.
-    "thewalrus",
-    "vlsir>=4",
+    "thewalrus==0.21.0",
+    "vlsir==2.0.dev0",
 ]
 
 test_requirements = [
@@ -40,11 +39,13 @@
     python_requires=">=3.10",
     classifiers=[
         "Development Status :: 2 - Pre-Alpha",
-        "Intended Audience :: Developers",
+        "Intended Audience :: Science/Research",
         "License :: OSI Approved :: MIT License",
         "Natural Language :: English",
         "Programming Language :: Python :: 3",
         "Programming Language :: Python :: 3.10",
+        "Topic :: Scientific/Engineering",
+        "Topic :: Scientific/Engineering :: Physics",
     ],
     description="Photonic Integrated Electronics: microservices to codesign photonics, electronics, communications, quantum, and more.",
     entry_points={