piel.integration.gdsfactory_hdl21.conversion
============================================

.. py:module:: piel.integration.gdsfactory_hdl21.conversion

.. autoapi-nested-parse::

   `sax` has very good GDSFactory integration functions, so there is a question on whether implementing our own circuit
   construction, and SPICE netlist parser from it, accordingly. We need in some form to connect electrical measurement to our
   parsed netlist, in order to apply SPICE passive values, and create connectivity for each particular device. Ideally,
   this would be done from the component instance as that way the component model can be integrated with its geometrical
   parameters, but does not have to be done necessarily. This comes down to implementing a backend function to compile
   SAX compiled circuit.



Functions
---------

.. autoapisummary::

   piel.integration.gdsfactory_hdl21.conversion.convert_connections_to_tuples
   piel.integration.gdsfactory_hdl21.conversion.get_matching_connections
   piel.integration.gdsfactory_hdl21.conversion.get_matching_port_nets
   piel.integration.gdsfactory_hdl21.conversion.gdsfactory_netlist_with_hdl21_generators
   piel.integration.gdsfactory_hdl21.conversion.gdsfactory_netlist_to_spice_string_connectivity_netlist


Module Contents
---------------

.. py:function:: convert_connections_to_tuples(connections: dict)

   Convert from:

   .. code-block::

       {
       'straight_1,e1': 'taper_1,e2',
       'straight_1,e2': 'taper_2,e2',
       'taper_1,e1': 'via_stack_1,e3',
       'taper_2,e1': 'via_stack_2,e1'
       }

   to:

   .. code-block::

       [(('straight_1', 'e1'), ('taper_1', 'e2')), (('straight_1', 'e2'), ('taper_2', 'e2')), (('taper_1', 'e1'),
       ('via_stack_1', 'e3')), (('taper_2', 'e1'), ('via_stack_2', 'e1'))]


.. py:function:: get_matching_connections(names: list, connections: dict)

   This function returns a list of tuples that match the names of the connections.

   :param names: List of names to match
   :param connections: Dictionary of connections to match

   :returns: List of tuples that match the names of the connections


.. py:function:: get_matching_port_nets(names, connections)

.. py:function:: gdsfactory_netlist_with_hdl21_generators(gdsfactory_netlist: dict, generators=None)

   This function allows us to map the ``hdl21`` measurement dictionary in a `sax`-like implementation to the ``GDSFactory`` netlist. This allows us to iterate over each instance in the netlist and construct a circuit after this function.]

   Example usage:

   .. code-block::

       >>> import gdsfactory as gf
       >>> from piel.integration.gdsfactory_hdl21.conversion import gdsfactory_netlist_with_hdl21_generators
       >>> from piel.measurement.physical.electronic import get_default_models
       >>> gdsfactory_netlist_with_hdl21_generators(gdsfactory_netlist=gf.components.mzi2x2_2x2_phase_shifter().get_netlist(exclude_port_types="optical"),generators=get_default_models())

   :param gdsfactory_netlist: The netlist from ``GDSFactory`` to map to the ``hdl21`` measurement dictionary.
   :param generators: The ``hdl21`` measurement dictionary to map to the ``GDSFactory`` netlist.

   :returns: The ``GDSFactory`` netlist with the ``hdl21`` measurement dictionary.


.. py:function:: gdsfactory_netlist_to_spice_string_connectivity_netlist(gdsfactory_netlist: dict, models=None)

   Not for the `hdl21` design flow, but useful for other SPICE level conversions.

   This function maps the connections of a netlist to a node that can be used in a SPICE netlist. SPICE netlists are
   in the form of:

   .. code-block:: spice

       RXXXXXXX N1 N2 <VALUE> <MNAME> <L=LENGTH> <W=WIDTH> <TEMP=T>

   This means that every instance, is an electrical type, and we define the two particular nodes in which it is
   connected. This means we need to convert the gdsfactory dictionary netlist into a form that allows us to map the
   connectivity for every instance. Then we can define that as a line of the SPICE netlist with a particular
   electrical model. For passives this works fine when it's a two port network such as sources, or electrical
   elements. However, non-passive elements like transistors have three connection or more which are provided in an ordered form.

   This means that the order of translations is as follows:

   .. code-block::

       1. Extract all instances and required measurement from the netlist, and assign the corresponding parameters on instantiation.
       2. Verify that the measurement have been provided. Each model describes the type of component this is, how many connection it requires and so on.
       3. Map the connections to each instance port as part of the instance dictionary.

   We should get as an output a dictionary in the structure:

   .. code-block::

       {
           instance_1: {
               ...
               "connections": [('straight_1,e1', 'taper_1,e2'),
                               ('straight_1,e2', 'taper_2,e2')],
               'spice_nets': {'e1': 'straight_1__e1___taper_1__e2',
                       'e2': 'straight_1__e2___taper_2__e2'},
               'spice_model': <function piel.measurement.physical.electronic.spice.resistor.basic_resistor()>},
           }
           ...
       }