piel.connectivity
=================

.. py:module:: piel.connectivity


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/piel/connectivity/core/index


Functions
---------

.. autoapisummary::

   piel.connectivity.create_all_connections
   piel.connectivity.create_component_connections
   piel.connectivity.create_sequential_component_path
   piel.connectivity.create_connection_list_from_ports_lists
   piel.connectivity.get_port_index_from_name


Package Contents
----------------

.. py:function:: create_all_connections(ports: list[piel.types.Port], connection_factory: Optional[Callable[[list[piel.types.Port]], piel.types.Connection]] = None, connection_type_output: Optional[piel.types.ConnectionTypes] = Connection) -> list[piel.types.ConnectionTypes]

   This function receives a list of connection and creates the connections between them as two-port relationships.
   It returns a list of connections. More than two connection can be provided, and it will create all the possible connections.

   :param ports: The connection list to create connections.
   :type ports: list[Port]
   :param connection_factory: A function that creates a connection object from a list of connection.
                              The function should receive a list of connection and return a connection object.
                              If not provided, a default connection factory will be used.
                              The default connection factory creates a tuple of connection as a connection object.
                              The default is None.
   :type connection_factory: Optional[Callable[[list[Port]], Connection]], optional
   :param connection_type_output: The type of connection object to return.

                                  If not provided, the default connection factory will be used.

                                  The default is None
   :type connection_type_output: Optional[type[Connection]], optional

   :returns: A list of connections that were created.
   :rtype: list[Connection]


.. py:function:: create_component_connections(components: list[piel.types.ComponentTypes], connection_reference_str_list: list[str] | list[list[str]]) -> list[piel.types.ConnectionTypes]

   The way this function works is by composing the connection namespaces from the names of the components,
   and a given connection dot notation which corresponds to that component.

   .. rubric:: Notes

   The dot notation would be in the format ``"component_1.port1"``. Hence, the input to a connection would be
   ``["component1.port1", "component2.port1"]`` and this function would compile into generating the corresponding
   connection. This is by splitting the component name and port name accordingly and then programmatically acquiring
   the corresponding `Port` reference and creating the `Connection` from this.

   :param components: The components to create connections from.
   :type components: list[ComponentTypes]
   :param connection_reference_str_list: The list of strings that represent the connections to create.
   :type connection_reference_str_list: list[str] | list[list[str]]

   :returns: The list of connections created from the components.
   :rtype: list[ConnectionTypes]


.. py:function:: create_sequential_component_path(components: list[piel.types.ComponentTypes], name: str = '', **kwargs) -> piel.types.ComponentTypes

   This function takes in a list of components and creates a sequential path connectivity of components with all the connection defined in each component.
   By default, the connectivity will be implemented with the first two connection of the components. There is a clear input and output on each component.
   The timing metric calculations is provided by the timing model of each connection of the component, if there is none defined it will assume a default zero
   time connectivity between the relevant connection. For the output component collection, it will output the timing of the network as a whole based on the
   defined subcomponents.
   This will create an output component with all the subcomponents, TODO more than two connection, and the list of connection

   Creates a sequential path connectivity of components with all the connection defined in each component.

   Parameters:
   -----------
   components : List[ComponentTypes]
         A list of components to be connected sequentially.

   Returns:
   --------
   :
   ComponentTypes
       A new component that encapsulates the sequential path of input components.


.. py:function:: create_connection_list_from_ports_lists(port_connection_list: list[list[piel.types.Port]]) -> list[piel.types.ConnectionTypes]

   When a list of a list of connection is provided, we construct all the required connections accordingly. TODO more docs.


.. py:function:: get_port_index_from_name(port: piel.types.Port, starting_index: int | None = None) -> int

   Extracts the numerical index from a port identifier and adjusts based on starting index.
   If port numbering starts at 0, adds 1. If starts at 1 or is None, leaves as is.

   Parameters:
   - port (int or str): The port identifier.
   - starting_index (int, optional): The starting index (0 or 1). Defaults to None.

   Returns:
   - int: The adjusted numerical index of the port.

   Raises:
   - ValueError: If starting_index is not 0, 1, or None.
   - ValueError: If the port string does not contain a numerical index.
   - TypeError: If the port is neither int nor str.