antupy.CF#

antupy.CF(unit1: str | Unit, unit2: str | Unit) → Var[source]#

Conversion factor between two units. It returns a Var instance with the conversion factor and the unit label. If the units are not compatible, it raises a ValueError.

This function computes the multiplicative factor needed to convert a value from unit1 to unit2. The result is returned as a Var object containing the conversion factor and a compound unit representing the ratio.

Parameters:

unit1 (str or Unit) – The source unit (unit to convert from). Can be a unit string (e.g., “m”, “kg/s”) or a Unit object.
unit2 (str or Unit) – The target unit (unit to convert to). Can be a unit string (e.g., “km”, “g/s”) or a Unit object.

Returns:

A Var object where: - value: the numerical conversion factor - unit: compound unit representing unit2/unit1

Return type:

Var

Raises:

ValueError – If the units are not dimensionally compatible (e.g., trying to convert between length and mass units).
TypeError – If unit1 or unit2 are not valid unit types.

Examples

Basic unit conversions:

>>> from antupy import CF
>>> cf = CF("m", "km")
>>> print(cf.v)  # Get the numerical value
0.001
>>> print(cf)    # Show the full conversion factor
0.001 [km/m]

Energy unit conversion:

>>> cf_energy = CF("J", "kWh")
>>> print(cf_energy)
2.7777777777777776e-07 [kWh/J]

Flow rate conversion:

>>> cf_flow = CF("m3/s", "L/min")
>>> print(cf_flow)
60000.0 [L-min/m3-s]

Usage in unit conversion:

>>> # Convert 5 meters to kilometers
>>> distance_m = 5000  # meters
>>> distance_km = distance_m * CF("m", "km").v
>>> print(f"{distance_m} m = {distance_km} km")
5000 m = 5.0 km

Notes

The conversion factor represents how many units of unit2 equal one unit of unit1. For example, CF(“m”, “km”) returns 0.001 because 1 meter = 0.001 kilometers.

The function only works with dimensionally compatible units. For example, you cannot convert between “kg” (mass) and “m” (length).