piel.conversion.core
====================

.. py:module:: piel.conversion.core

.. autoapi-nested-parse::

   This module provides a set of utilities for converting between common files measurement to facilitate the representation of information across different toolsets.



Attributes
----------

.. autoapisummary::

   piel.conversion.core.convert_tuple_to_string
   piel.conversion.core.a2d


Functions
---------

.. autoapisummary::

   piel.conversion.core.convert_array_type
   piel.conversion.core.convert_2d_array_to_string
   piel.conversion.core.absolute_to_threshold
   piel.conversion.core.convert_to_bits
   piel.conversion.core.convert_dataframe_to_bits


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

.. py:function:: convert_array_type(array: piel.types.core.ArrayTypes, output_type: piel.types.core.PackageArrayType)

   Converts an array to the specified output type.

   :param array: The input array which can be of type numpy.ndarray or jax.ndarray.
   :type array: ArrayTypes
   :param output_type: The desired output type, which can be "qutip", "jax", "numpy", "list", "tuple", or a tuple of integers (TupleIntType).
   :type output_type: PackageArrayType

   :returns: The converted array in the specified output type.

   :raises ValueError: If the specified output type is not recognized or not supported.

   .. rubric:: Examples

   >>> convert_array_type(np.array([1, 2, 3]), "jax")
   DeviceArray([1, 2, 3], dtype=int32)

   >>> convert_array_type(jnp.array([1, 2, 3]), "numpy")
   array([1, 2, 3])

   >>> convert_array_type(np.array([1, 2, 3]), TupleIntType)
   (1, 2, 3)


.. py:data:: convert_tuple_to_string

.. py:function:: convert_2d_array_to_string(list_2D: list[list]) -> str

   Converts a 2D array of binary files into a single string of binary values.

   :param list_2D: A 2D array of binary files where each sublist contains a single binary value.
   :type list_2D: list[list]

   :returns: A string of binary files.
   :rtype: str

   .. rubric:: Examples

   >>> convert_2d_array_to_string([[0], [0], [0], [1]])
   '0001'


.. py:function:: absolute_to_threshold(array: piel.types.core.ArrayTypes, threshold: float = 1e-06, dtype_output: int | float | bool = int, output_array_type: piel.types.core.PackageArrayType = 'jax') -> piel.types.core.PackageArrayType

   Converts an array of optical transmission values to single-bit digital signals based on a threshold.

   :param array: The input array of any dimension representing optical transmission values.
   :type array: ArrayTypes
   :param threshold: The threshold value to determine the digital signal. Defaults to 1e-6.
   :type threshold: float, optional
   :param dtype_output: The desired files type for the output values. Defaults to int.
   :type dtype_output: int | float | bool, optional
   :param output_array_type: The desired output array type. Defaults to "jax".
   :type output_array_type: PackageArrayType, optional

   :returns: The array with values converted to digital signals (0 or 1) based on the threshold and specified output type.

   :raises ValueError: If the input array is not a numpy or jax array.

   .. rubric:: Examples

   >>> absolute_to_threshold(jnp.array([1e-7, 0.1, 1.0]), threshold=1e-5, output_array_type="numpy")
   array([0, 1, 1])


.. py:data:: a2d

.. py:function:: convert_to_bits(bits: piel.types.digital.AbstractBitsType) -> piel.types.digital.BitsType

   Converts an AbstractBitsType to a BitsType (binary string format).

   :param bits: The digital bits to convert. Can be a string, bytes, or integer.
   :type bits: AbstractBitsType

   :returns: The converted bits in binary string format (without '0b' prefix).
   :rtype: BitsType

   :raises TypeError: If the input type is not supported.


.. py:function:: convert_dataframe_to_bits(dataframe: pandas.DataFrame, ports_list: piel.types.digital.LogicSignalsList) -> pandas.DataFrame

   Converts specified integer columns in the dataframe to their binary string representations.

   :param dataframe: The simulation files as a Pandas dataframe.
   :type dataframe: pd.DataFrame
   :param ports_list: List of column names (connection) to convert to binary string format.
   :type ports_list: LogicSignalsList

   :returns: The dataframe with specified columns converted to binary string format.
   :rtype: pd.DataFrame