Utility

Utility functions and features

This module provides functions and features for scientific calculations and complex function inputs.

Example:

>>> import aguaclara.core.utility as ut
>>> ut.round_sig_figs(1234567, 3)
1230000

aguaclara.core.utility.optional_units(arg_positions, keys)

Wrap a function so that arguments may optionally have units.

This should be used as a function decorator; it will not do anything meaningful unless it is appended with a @ before another function.

Example:

@optional_units([0, 1], [‘num’, ‘step’]) def stepper(num, step=10, func=round):

step = step.to(num.units) num = func(num / step) * step return num

Args:

• arg_positions (int list): Position indices of positional and keyword arguments with optional units

• keys (str list): Names of positional and keyword arguments with optional units

aguaclara.core.utility.round_sf(num, figs=4)

Round a number to some amount of significant figures.

Args:

• num (float): Value to be rounded (optional units)

• figs (int): Number of significant digits to be rounded to (recommended, defaults to 4)

Note: This function will be deprecated after 21 Dec 2019. Use round_sig_figs instead.

aguaclara.core.utility.round_step(num, step=10)

Round a number to be a multiple of some step.

Args:

• num (float): Value to be rounded (optional units)

• step (float): Factor to which num will be rounded (defaults to 10).

Note:

step must have the same dimensionality as num, but not necessarily the same units (e.g. num: meters and step: centimeters are acceptable).

aguaclara.core.utility.ceil_step(num, step=10)

Like round_step(), but num is always rounded up.

aguaclara.core.utility.floor_step(num, step=10)

Like round_step(), but num is always rounded down.

aguaclara.core.utility.floor_nearest(x, array)

Get the nearest element of a NumPy array less than or equal to a value.

Args:

• x: Value to compare

• array (numpy.array): Array to search

aguaclara.core.utility.ceil_nearest(x, array)

Get the nearest element of a NumPy array greater than or equal to a value.

Args:

• x: Value to compare

• array (numpy.array): Array to search

aguaclara.core.utility.max(*args)

Get the maximum value of some Pint quantities with units.

Note:

• All quantities must have the same dimensionality, but can have different units.

• The output will have the same units as the first argument.

Example:

>>> from aguaclara.play import *
>>> ut.max(10 * u.m, 100 * u.cm, 32 * u.cm, 40 * u.inch, 40 * u.km)
<Quantity(40000.0, 'meter')>

aguaclara.core.utility.min(*args)

Like max(), but the minimum of the quantites.

aguaclara.core.utility.get_sdr(spec)

Get the SDR of a string spec with the form “sdrXX”.

Args:

• spec (str): The specification string to be parsed.

aguaclara.core.utility.list_handler()

Wraps a scalar function to output a NumPy array if passed one or more inputs as sequences (lists, tuples or NumPy arrays). For each sequence input, this wrapper will recursively evaluate the function with the sequence replaced by each of its elements and return the results in n-dimensional NumPy array, where n is the number of sequence inputs.

For a function “f” of one argument, f([x_1, …, x_n]) would be evaluated to [f(x_1), …, f(x_n)]. For a function passed multiple sequences of dimensions d_1, …, d_n (from left to right), the result would be a d_1 x … x d_n array.

aguaclara.core.utility.check_range(*args)

Check whether passed paramters fall within approved ranges.

Does not return anything, but will raise an error if a parameter falls outside of its defined range.

Input should be passed as an array of sequences, with each sequence having three elements:

[0] is the value being checked, [1] is the range parameter(s) within which the value should fall, and [2] is the name of the parameter, for better error messages.

If [2] is not supplied, “Input” will be appended as a generic name.

Range requests that this function understands are listed in the knownChecks sequence.

aguaclara.core.utility.array_qtys_to_strs(lst)

Convert Pint quantities in a NumPy array to strings.

Args:

• lst (numpy.ndarray Quantity): a list of values that has a Pint

  unit attached to it