piel.units ========== .. py:module:: piel.units .. autoapi-nested-parse:: These functions contain relevant functionality for unit conversion and related. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/piel/units/geometry/index /autoapi/piel/units/match/index /autoapi/piel/units/power/index /autoapi/piel/units/string/index /autoapi/piel/units/time/index Functions --------- .. autoapisummary:: piel.units.dBm2vpp piel.units.dBm2watt piel.units.dBm2vrms piel.units.vpp2dBm piel.units.vrms2vpp piel.units.vpp2vrms piel.units.vrms2dBm piel.units.vrms2watt piel.units.watt2vrms piel.units.watt2dBm piel.units.Hz2s piel.units.s2Hz piel.units.awg2m2 piel.units.prefix2int piel.units.match_unit_abbreviation piel.units.get_unit_by_datum Package Contents ---------------- .. py:function:: dBm2vpp(dBm: piel.types.NumericalTypes, impedance: piel.types.NumericalTypes = 50.0) -> piel.types.NumericalTypes Converts power from dBm to Vpp (peak-to-peak voltage) in a specified impedance network. The conversion is performed using the following steps: 1. Convert dBm to Watts: .. math:: P_{ ext{Watt}} = 10^{\left( rac{P_{ ext{dBm}}}{10} ight)} imes 10^{-3} 2. Convert Watts to Vrms: .. math:: V_{ ext{rms}} = \sqrt{P_{ ext{Watt}} imes Z} 3. Convert Vrms to Vpp: .. math:: V_{ ext{pp}} = V_{ ext{rms}} imes \sqrt{2} imes 2 Args: - dBm (NumericalTypes): Power level in dBm (can be int, float, or numpy array). - impedance (float): The network impedance in ohms. Default is 50 ohms. Returns: - NumericalTypes: Vpp value, in the same type as the input. .. py:function:: dBm2watt(dBm: piel.types.NumericalTypes) -> piel.types.NumericalTypes Converts power from dBm (decibel-milliwatts) to Watts. The conversion is performed using the following equation: .. math:: P_{ ext{Watt}} = 10^{\left( rac{P_{ ext{dBm}}}{10} ight)} imes 10^{-3} Args: - dBm (NumericalTypes): Power level in dBm (can be int, float, or numpy array). Returns: - NumericalTypes: Power level in Watts, in the same type as the input. .. py:function:: dBm2vrms(dBm: piel.types.NumericalTypes, impedance: piel.types.NumericalTypes = 50.0) -> piel.types.NumericalTypes Converts power from dBm to Vrms (root mean square voltage) in a specified impedance network. The conversion is performed using the following steps: 1. Convert dBm to Watts: .. math:: P_{ ext{Watt}} = 10^{\left( rac{P_{ ext{dBm}}}{10} ight)} imes 10^{-3} 2. Convert Watts to Vrms: .. math:: V_{ ext{rms}} = \sqrt{P_{ ext{Watt}} imes Z} Args: - dBm (NumericalTypes): Power level in dBm (can be int, float, or numpy array). - impedance (float): The network impedance in ohms. Default is 50 ohms. Returns: - NumericalTypes: Vrms value, in the same type as the input. .. py:function:: vpp2dBm(vpp: piel.types.NumericalTypes, impedance: piel.types.NumericalTypes = 50.0) -> piel.types.NumericalTypes Converts Vpp (peak-to-peak voltage) to dBm in a specified impedance network. The conversion is performed using the following steps: 1. Convert Vpp to Vrms: .. math:: V_{ ext{rms}} = rac{V_{ ext{pp}}}{\sqrt{2} imes 2} 2. Convert Vrms to Watts: .. math:: P_{ ext{Watt}} = rac{V_{ ext{rms}}^2}{Z} 3. Convert Watts to dBm: .. math:: P_{ ext{dBm}} = 10 imes \log_{10}\left( rac{P_{ ext{Watt}}}{10^{-3}} ight) Args: - vpp (NumericalTypes): Vpp value. - impedance (float): The network impedance in ohms. Default is 50 ohms. Returns: - NumericalTypes: Power level in dBm, in the same type as the input. .. py:function:: vrms2vpp(vrms: piel.types.NumericalTypes) -> piel.types.NumericalTypes Converts Vrms (root mean square voltage) to Vpp (peak-to-peak voltage). The conversion is performed using the following equation: .. math:: V_{ ext{pp}} = V_{ ext{rms}} imes \sqrt{2} imes 2 Args: - vrms (NumericalTypes): Vrms value. Returns: - NumericalTypes: Vpp in the same type as the input. .. py:function:: vpp2vrms(vpp: piel.types.NumericalTypes) -> piel.types.NumericalTypes Converts Vpp (peak-to-peak voltage) to Vrms (root mean square voltage). The conversion is performed using the following equation: .. math:: V_{ ext{rms}} = rac{V_{ ext{pp}}}{\sqrt{2} imes 2} Args: - vpp (NumericalTypes): Vpp value. Returns: - NumericalTypes: Vrms value, in the same type as the input. .. py:function:: vrms2dBm(vrms: piel.types.NumericalTypes, impedance: piel.types.NumericalTypes = 50.0) -> piel.types.NumericalTypes Converts Vrms (root mean square voltage) to dBm in a specified impedance network. The conversion is performed using the following steps: 1. Convert Vrms to Watts: .. math:: P_{ ext{Watt}} = rac{V_{ ext{rms}}^2}{Z} 2. Convert Watts to dBm: .. math:: P_{ ext{dBm}} = 10 imes \log_{10}\left( rac{P_{ ext{Watt}}}{10^{-3}} ight) Args: - vrms (NumericalTypes): Vrms value. - impedance (float): The network impedance in ohms. Default is 50 ohms. Returns: - NumericalTypes: Power level in dBm, in the same type as the input. .. py:function:: vrms2watt(vrms: piel.types.NumericalTypes, impedance: piel.types.NumericalTypes = 50.0) -> piel.types.NumericalTypes Converts Vrms (root mean square voltage) to power in Watts for a given impedance. The conversion is performed using the following equation: .. math:: P_{ ext{Watt}} = rac{V_{ ext{rms}}^2}{Z} Args: - vrms (NumericalTypes): Vrms value. - impedance (float): The network impedance in ohms. Returns: - NumericalTypes: Power level in Watts, in the same type as the input. .. py:function:: watt2vrms(watt: piel.types.NumericalTypes, impedance: piel.types.NumericalTypes = 50.0) -> piel.types.NumericalTypes Converts power in Watts to Vrms (root mean square voltage) for a given impedance. The conversion is performed using the following equation: .. math:: V_{ ext{rms}} = \sqrt{P_{ ext{Watt}} imes Z} Args: - watt (NumericalTypes): Power level in Watts. - impedance (float): The network impedance in ohms. Defaults to 50.0 Ohms. Returns: - NumericalTypes: Vrms in the same type as the input. .. py:function:: watt2dBm(watt: piel.types.NumericalTypes) -> piel.types.NumericalTypes Converts power from Watts to dBm (decibel-milliwatts). The conversion is performed using the following equation: .. math:: P_{ ext{dBm}} = 10 imes \log_{10}\left( rac{P_{ ext{Watt}}}{10^{-3}} ight) Args: - watt (NumericalTypes): Power level in Watts (can be int, float, or numpy array). Returns: - NumericalTypes: Power level in dBm, in the same type as the input. .. py:function:: Hz2s(hz: piel.types.NumericalTypes) -> piel.types.NumericalTypes Convert frequency in Hertz (Hz) to time period in seconds (s). :param hz: Frequency in Hz :return: Time period in seconds (s) .. py:function:: s2Hz(s: piel.types.NumericalTypes) -> piel.types.NumericalTypes Convert time period in seconds (s) to frequency in Hertz (Hz). :param s: Time period in seconds (s) :return: Frequency in Hertz (Hz) .. py:function:: awg2m2(awg: int) -> float Converts an AWG value to meters squared. Reference: https://en.wikipedia.org/wiki/American_wire_gauge :param awg: AWG value. :type awg: ing :returns: Cross sectional area in meters squared. :rtype: float .. py:function:: prefix2int(s: str) -> int Converts a string with a number and optional suffix into an integer. Supported suffixes: 'k' or 'K' - Thousand 'm' or 'M' - Million 'b' or 'B' - Billion 't' or 'T' - Trillion .. rubric:: Examples '17.03k' -> 17030 '17K' -> 17000 '2.5M' -> 2500000 '500' -> 500 '-3.2B' -> -3200000000 :param s: The string to convert. :type s: str :returns: The integer representation of the input string. :rtype: int :raises ValueError: If the string format is invalid or contains unsupported suffixes. .. py:function:: match_unit_abbreviation(unit_str: str) -> piel.types.units.Unit Matches a unit string to a predefined Unit instance. :param unit_str: The unit abbreviation extracted from a column name (e.g., "s", "v", "dB"). :type unit_str: str :returns: The corresponding Unit instance. :rtype: Unit :raises ValueError: If the unit string does not match any predefined units. .. py:function:: get_unit_by_datum(datum: str) -> Optional[piel.types.Unit] Retrieves a Unit instance based on the datum type. :param datum: The datum type (e.g., 'voltage', 'current'). :type datum: str :returns: The corresponding Unit instance if found, else None. :rtype: Optional[Unit]