# Wrapping and checking functions

In some cases you might want to use pint with a pre-existing web service or library which is not units aware. Or you might want to write a fast implementation of a numerical algorithm that requires the input values in some specific units.

For example, consider a function to return the period of the pendulum within a hypothetical physics library. The library does not use units, but instead requires you to provide numerical values in certain units:

    >>> from simple_physics import pendulum_period
    >>> help(pendulum_period)
    Help on function pendulum_period in module simple_physics:

    pendulum_period(length)
    Return the pendulum period in seconds. The length of the pendulum
    must be provided in meters.

    >>> pendulum_period(1)
    2.0064092925890407

This behaviour is very error prone, in particular when combining multiple libraries. You could wrap this function to use Quantities instead:

    >>> from pint import UnitRegistry
    >>> ureg = UnitRegistry()
    >>> Q_ = ureg.Quantity
    >>> def mypp_caveman(length):
    ...     return pendulum_period(length.to(ureg.meter).magnitude) * ureg.second

and:

    >>> mypp_caveman(100 * ureg.centimeter)
    <Quantity(2.00640929, 'second')>

Pint provides a more convenient way to do this:

    >>> mypp = ureg.wraps(ureg.second, ureg.meter)(pendulum_period)

Or in the decorator format:

    >>> @ureg.wraps(ureg.second, ureg.meter)
    ... def mypp(length):
    ...     return pendulum_period(length)
    >>> mypp(100 * ureg.centimeter)
    <Quantity(2.00640929, 'second')>

wraps takes 3 input arguments:

> - ret: the return units.

>     Use None to skip conversion.

> - args: the inputs units for each argument, as an iterable.

>     Use None to skip conversion of any given element.

> - strict: if True all convertible arguments must be a Quantity

>     and others will raise a ValueError (True by default)

## Strict Mode

By default, the function is wrapped in strict mode. In this mode, the input arguments assigned to units must be a Quantities.

    >>> mypp(1. * ureg.meter)
    <Quantity(2.00640929, 'second')>
    >>> mypp(1.)
    Traceback (most recent call last):
    ...
    ValueError: A wrapped function using strict=True requires quantity for all arguments with not None units. (error found for meter, 1.0)

To enable using non-Quantity numerical values, set strict to False`.

    >>> mypp_ns = ureg.wraps(ureg.second, ureg.meter, False)(pendulum_period)
    >>> mypp_ns(1. * ureg.meter)
    <Quantity(2.00640929, 'second')>
    >>> mypp_ns(1.)
    <Quantity(2.00640929, 'second')>

In this mode, the value is assumed to have the correct units.

## Multiple arguments or return values

For a function with more arguments, use a tuple:

    >>> from simple_physics import pendulum_period2
    >>> help(pendulum_period2)
    Help on function pendulum_period2 in module simple_physics:

    pendulum_period2(length, swing_amplitude)
    Return the pendulum period in seconds. The length of the pendulum
    must be provided in meters. The swing_amplitude must be in radians.

    >>> mypp2 = ureg.wraps(ureg.second, (ureg.meter, ureg.radians))(pendulum_period2)
    ...

Or if the function has multiple outputs:

    >>> mypp3 = ureg.wraps((ureg.second, ureg.meter / ureg.second),
    ...                    (ureg.meter, ureg.radians))(pendulum_period_maxspeed)
    ...

If there are more return values than specified units, `None` is assumed for the extra outputs. For example, given the NREL SOLPOS calculator that outputs solar zenith, azimuth and air mass, the following wrapper assumes no units for airmass

    @ureg.wraps(('deg', 'deg'), ('deg', 'deg', 'millibar', 'degC'))
    def solar_position(lat, lon, press, tamb, timestamp):
        return zenith, azimuth, airmass

## Optional arguments

For a function with named keywords with optional values, use a tuple for all arguments:

    >>> @ureg.wraps(ureg.second, (ureg.meters, ureg.meters/ureg.second**2, None))
    ... def calculate_time_to_fall(height, gravity=Q_(9.8, 'm/s^2'), verbose=False):
    ...     """Calculate time to fall from a height h.
    ...
    ...     By default, the gravity is assumed to be earth gravity,
    ...     but it can be modified.
    ...
    ...     d = .5 * g * t**2
    ...     t = sqrt(2 * d / g)
    ...     """
    ...     t = math.sqrt(2 * height / gravity)
    ...     if verbose: print(str(t) + " seconds to fall")
    ...     return t
    ...
    >>> lunar_module_height = Q_(22, 'feet') + Q_(11, 'inches')
    >>> calculate_time_to_fall(lunar_module_height, verbose=True)
    1.1939473204801092 seconds to fall
    <Quantity(1.19394732, 'second')>
    >>> moon_gravity = Q_(1.625, 'm/s^2')
    >>> calculate_time_to_fall(lunar_module_height, gravity=moon_gravity)
    <Quantity(2.932051, 'second')>

## Specifying relations between arguments

In certain cases, you may not be concerned with the actual units and only care about the unit relations among arguments.

This is done using a string starting with the equal sign =:

    >>> @ureg.wraps('=A**2', ('=A', '=A'))
    ... def sqsum(x, y):
    ...     return x * x  + 2 * x * y + y * y

which can be read as the first argument (x) has certain units (we labeled them A), the second argument (y) has the same units as the first (A again). The return value has the unit of x squared (A**2)

You can use more than one label:

    >>> @ureg.wraps('=A**2*B', ('=A', '=A*B', '=B'))
    ... def some_function(x, y, z):
    ...     pass

With optional arguments

    >>> @ureg.wraps('=A*B', ('=A', '=B'))
    ... def get_displacement(time, rate=Q_(1, 'm/s')):
    ...     return time * rate
    ...
    >>> get_displacement(Q_(2, 's'))
    <Quantity(2, 'meter')>
    >>> get_displacement(Q_(2, 's'), Q_(1, 'deg/s'))
    <Quantity(2, 'degree')>

## Ignoring an argument or return value

To avoid the conversion of an argument or return value, use None

    >>> mypp3 = ureg.wraps((ureg.second, None), ureg.meter)(pendulum_period_error)

## Checking dimensionality

When you want pint quantities to be used as inputs to your functions, pint provides a wrapper to ensure units are of correct type - or more precisely, they match the expected dimensionality of the physical quantity.

Similar to wraps(), you can pass None to skip checking of some parameters, but the return parameter type is not checked.

    >>> mypp = ureg.check('[length]')(pendulum_period)

In the decorator format:

    >>> @ureg.check('[length]')
    ... def pendulum_period(length):
    ...     return 2*math.pi*math.sqrt(length/G)

If you just want to check the dimensionality of a quantity, you can do so with the built-in ‘check’ function.

    >>> distance = 1 * ureg.m
    >>> distance.check('[length]')
    True
    >>> distance.check('[time]')
    False