# irfpy.util.unitq¶

Unit handling using external “quantities” module.

Code author: Yoshifumi Futaana

Note

This module uses ‘’quantities’’ package. I appreciate the author, Darren Dale, for providing the software.

https://github.com/python-quantities/python-quantities

irfpy.util.unitq handles the unit (dimension) based on the quantities package. See http://pythonhosted.org/quantities/ for detailed documentation on the quantities package.

irfpy.util.unitq adds some functionalies:

• Shorter names (aliases) of the dimension.

• r() (alias of rescale())

• n() (get the value - remove units)

• s() (get the simplified form based on the current system – default MKSA system)

• u() (get the unit in the string format)

Usage

>>> import irfpy.util.unitq as u


to use the unitq module.

Then, you can make a quantity of “8.57 m” simply as

>>> print(8.57 * u.m)
8.57 m


Numerical calculation is simply done.

>>> l = 8.57 * u.m   # 8.57 meter
>>> t = 2.48 * u.s   # 2.48 seconds
>>> v = l / t    # Get the speed
>>> print('{:.3f}'.format(v))
3.456 m/s


Or you can make a unit object using unit() function (or nit(), with the module name u, it can be called u.nit).

>>> print(u.nit('300 MPa'))    # 300 Mega pascal
300.0 MPa


The attribute s (or simplified for long) convert the unit.

>>> print(u.nit('3.6 km/h').s)
1.0 m/s


You can remove the unit to get the normal numpy ndarray with the attribute of n.

>>> val = [8.57, 2.55] * u.m
>>> val_arr = val.n     #  .n will return the numpy array
>>> print(val_arr, isinstance(val_arr, np.ndarray))
[8.57  2.55] True


The new array is a new instance, so changes are not propageted.

>>> val_arr[0] = 1.55
>>> print(val)   # The change in the new array will not affect the original
[8.57  2.55] m


The solid angle is supported. But when you simplify to MKSA, it will go to dimensionless.

>>> print(3.5 * u.sr)
3.5 sr
>>> print((1.5 * u.sr)**2)
2.25 sr**2
>>> print(((0.3 * u.sr)**2).s)   # .s is to simplify. sr is unitless.
0.09 dimensionless


Electron volt is used both energy and temperature. This could be ambiguous. The default eV is for energy. A new unit of eV_asT (or eVT in short) is defined. The function r() rescales the unit.

>>> ev = 1 * eV_asT    # A new unit eV_asT has been defined.
>>> print(ev.r('K'))   # .r is to rescale the unit
11604.5052897 K


In summary, the following functions / attributes can be used.

• n (numpy) returns the numpy.array expression of the quantity (5.0 or [2.0, 3.5]).

• u (unit) returns the string expression of the units (kg or cm/s).

• s (simplified) is an alias to simplified().

• r (rescale) is an alias to rescale().

• ns (numpy simplified) returns the numpy.array after being simplified.

• nr (numpy rescaled) returns the numpy.array after being rescaled.

• us (unit simplified) returns the string expression of the unit after being simplified.

• ur (unit rescaled) returns the string expression of the unit after begin rescaled.

In the following, a series of sample is seen.

Constant with units are defined under the namespace of “k”. For example the Planck constant can be obtained as.

>>> h = u.k.Planck_constant   # Planck constant
>>> print(h)
1 h (Planck_constant)

>>> print(h.n)   # Get the value in the unit of Planck_constant
1.0
>>> print(h.u)   # The unit is h (Planck_constant).
h


Let’s see this value in the MKSA system with simplified attribute.

>>> print(h.simplified)
6.62606896e-34 kg*m**2/s

>>> print(h.ns)   # This expression simplifies the quantity, then return as a value.
6.62606896e-34
>>> print(h.us)    # This returns the unit of simplified quantity.
kg*m**2/s


Rescaling to another unit is also done using the function r, nr and ur.

>>> print('{:.3e}'.format(h.r('g*cm^2/s')))   # Rescale to the g cm^2 / s
6.626e-27 g*cm**2/s

>>> print('%.3e' % h.nr('g*cm^2/s'))  # Return the rescaled value (float) only.
6.626e-27

>>> print(h.ur('g*cm^2/s'))  # Return the rescaled unit
g*cm**2/s


Dynamic definition of the unit

Dynamic definition means that based on the defined unit, SI prefix is added and dynamically defined. For example, Giga year is not defined by default.

>>> print(u.Gyr)
Traceback (most recent call last):
...
AttributeError: module 'irfpy.util.unitq' has no attribute 'Gyr'


However, once you use unit() function, “Gyr” is defined. >>> three_giga_year = u.nit(‘3 Gyr’) >>> print(three_giga_year) 3000000000.0 yr >>> print(u.Gyr) # Gyr was defined automatically 1 Gyr

Convert list of unit array to the single unit array

Sometimes, one need to iterate some calculation then you may get a list of unit array. As a simple example,

>>> l = [1, 2, 3] * u.m
>>> t = 1 * u.s
>>> print(l / t)
[1. 2. 3.] m/s


For this simple example of calculating the velocity, the above division is sufficient. But if a calculation becomes more complicated, iteration may not be avoided.

Such a case, one can rewrite the velocity calculation as

>>> v = [l_ / t for l_ in l]    # This is not equal to "l / t".
>>> print(v)
[array(1.) * m/s, array(2.) * m/s, array(3.) * m/s]


The result is not very easy to handle as unit array.

>>> print(v.rescale('cm/s'))   # Rescale does not work.   doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
...
AttributeError: 'list' object has no attribute 'rescale'


The function asarray() can be used to convert a list of unit arrays to a single unit array.

>>> v2 = asarray(v)
>>> print(v2)
[1. 2. 3.] m/s
>>> print(v2.rescale('cm/s'))
[100. 200. 300.] cm/s

irfpy.util.unitq.asarray(a, unit=None)[source]

From the input array-like to make as unit array.

Parameters:
• a (Array like.) – Array like input. All elements should be values with units, equivalent for all.

• unit – The unit to be used. It should not be a text representation. Use to wrap u.nit('m') instead of ‘m’.

Returns:

An array fully with a single unit.

A simple one

>>> from irfpy.util import unitq as u
>>> a_in = [3, 4, 5] * u.m
>>> a_out = u.asarray(a_in, unit=u.cm)    # This should work as if the rescale function
>>> print(a_out)
[300. 400. 500.] cm

>>> a_out = u.asarray([3, 4, 5], unit=u.km)   # This also should work as if the [3, 4, 5] * u.km
>>> print(a_out)
[3. 4. 5.] km

>>> a_in = [3 * u.cm, 4 * u.m, 5 * u.km]   # A list. Input unit shall be connected to each component.
>>> a_out = asarray(a_in)     # In this case, the input array shall be converted to the first element unit, and converted to the unit array
>>> print(a_out)
[3.e+00 4.e+02 5.e+05] cm

>>> a_in = [[3 * u.cm, 4 * u.m, 5 * u.mm], [15, 20, 30] * u.mm]   # (3, 2) shape
>>> a_out = asarray(a_in, unit=u.nit('mm'))
>>> print(a_out)
[[  30. 4000.    5.]
[  15.   20.   30.]] mm

class irfpy.util.unitq.k2[source]

Bases: object

MKSA scalar constant.

Deprecated since version 4.2.5: Use irfpy.util.constant module.

>>> print('%.3e' % k2.amu)
1.661e-27

amu = array(1.66053878e-27)

AMU

e = array(1.60217649e-19)

Elementary charge

m_p = array(1.67262164e-27)

Proton mass

irfpy.util.unitq.CUnit

Alias to CompoundUnit

irfpy.util.unitq.cu_pflux = 1 (1 /cm**2 /s)

Unit of particle flux

irfpy.util.unitq.cu_flux = 1 (1 /cm**2 /s)

Unit of particle flux

irfpy.util.unitq.cu_eflux = 1 (eV/cm**2 /s)

Unit of energy flux

irfpy.util.unitq.cu_diffflux = 1 (1/cm**2 /sr /eV / s)

Unit of differential particle flux

irfpy.util.unitq.cu_ediffflux = 1 (eV/cm**2 /sr /eV/s)

Unit of differential energy flux

irfpy.util.unitq.cu_gfactor = 1 (cm**2 * sr * eV/eV)

Unit of g-factor

irfpy.util.unitq.eVT = UnitQuantity('electron_volt_temperature', 11604.5052897 * K, 'eVT')

Electron volt used as temperature

irfpy.util.unitq.eV_asE = UnitQuantity('electron_volt', 1.60217653e-19 * J, 'eV')

Electron volt used as energy (quantities defined object)

Steredian, an alias

irfpy.util.unitq.qe = UnitQuantity('elementary_charge', 1.602176487e-19 * C, 'e')

Unit charge, an alias

irfpy.util.unitq.rydberg_energy = UnitQuantity('rydberg_energy', 0.5 * E_h, 'E_Ry')

Rydberg energy. It is about 13.6 eV, and half of the Hartree.

irfpy.util.unitq.si_prefix = {'D': 10.0, 'E': 1e+18, 'G': 1000000000.0, 'M': 1000000.0, 'P': 1000000000000000.0, 'T': 1000000000000.0, 'Y': 1e+24, 'Z': 1e+21, 'a': 1e-18, 'atto': 1e-18, 'c': 0.01, 'centi': 0.01, 'd': 0.1, 'da': 10.0, 'deca': 10.0, 'deci': 0.1, 'exa': 1e+18, 'f': 1e-15, 'femto': 1e-15, 'giga': 1000000000.0, 'h': 100.0, 'hecto': 100.0, 'k': 1000.0, 'kilo': 1000.0, 'm': 0.001, 'mega': 1000000.0, 'micro': 1e-06, 'milli': 0.001, 'n': 1e-09, 'nano': 1e-09, 'p': 1e-12, 'peta': 1000000000000000.0, 'pico': 1e-12, 'tera': 1000000000000.0, 'u': 1e-06, 'y': 1e-24, 'yocto': 1e-24, 'yotta': 1e+24, 'z': 1e-21, 'zepto': 1e-21, 'zetta': 1e+21}

SI prefix

A dictionary of unit.

It maps the name of the unit and the UnitQuantity object.

irfpy.util.unitq.nit(string_units, verbose=False)[source]

Return the unit object corresponding to the given expression

>>> import irfpy.util.unitq as u
>>> print(3 * u.nit('kg'))
3.0 kg


As you see the above example, the name comes for above convenstion :).

Each unit should be one word: 'kg' or 's'. For the multiple of units, separate by space or aster or dot.: e.g. 'J s' or 'J*s' or 'J.s'. 'Js' not allowed. Devision is '/'. '1/s', m/s. For the power, you may use ** or ^. No space before and after the operator. e.g. 'm2', 'm^2' or 'm**2

Anyway, it is highly recommended to make * or space between units and numbers to multiply. Also, ‘^’ is recommended to be added, but not spaces around. ('m2' and 'm 2' provide different result. 'm^2' and 'm*2')

Parenthesis () not supported.

>>> print(u.nit('m'))
1 m (meter)
>>> print(u.nit(' 3 m'))
3.0 m
>>> print(u.nit('m/s'))
1.0 m/s
>>> print(u.nit('J s'))
1.0 s*J
>>> print(u.nit('J2 s'))
1.0 s*J**2
>>> print(u.nit('J2 s-2'))
1.0 J**2/s**2
>>> print(u.nit('J3 s-1 .8'))
0.8 J**3/s
>>> print(u.nit('3 / 2'))   # Even usual number calculation.
1.5
>>> #  print u.nit('3**2')    ## But this is not possible
>>> print(u.nit('s0.5'))   # Fractional unit ok.
1.0 s**0.5
>>> #print u.nit('3.s')   # Will be error
>>> #print u.nit('.3s')   # Will be error
>>> print(u.nit('s.K 3.'))
3.0 s*K
>>> #print u.nit('s.K3.') # Will be error
>>> print(u.nit('m2'))
1.0 m**2
>>> print(u.nit('m 2'))
2.0 m
>>> print(u.nit('m^2'))
1.0 m**2
>>> print(u.nit('m*2'))
2.0 m


It will guess the SI prefix.

>>> print(u.nit('pC'))   # Pico coulon
1e-12 C
>>> pprint(u.nit('TeV').rescale('eV'), fmt='%.2e')   # Tera eV
1.00e+12 eV


Differential flux, for example

>>> print(u.nit('3e8 /cm2 /sr /s /eV'))
300000000.0 1/(cm**2*s*sr*eV)
>>> pprint(u.nit('3e8 /cm2 /sr /s /eV').simplified, fmt='%.3e')
1.872e+31 s/(kg*m**4)

>>> print(nit('3 /cm2 nm sr/s J/A cd'))  # I don't know this unit...
3.0 nm*cd*sr*J/(cm**2*s*A)
>>> pprint(nit('3 /cm2 nm sr/s J/A cd').simplified, fmt='%.2e')  # I don't know this unit...
3.00e-05 kg*m*cd/(s**3*A)

irfpy.util.unitq.unit(string_units, verbose=False)

An alias

irfpy.util.unitq.make_unitful_function(func, unitlist, runit, offset=0)[source]

Make unitful function.

Parameters:
• func – Physical function (formula)

• unitful – List of the unit in the order of the argument of func.

• runit – Unit of the returned value of func.

• offset – If set, the unitlist is started to be applied to the argument after offset. This is used for when this function is applied for an object method, whose 0-th argument is the object.

When you implement a physical function (or formula), it is usually a good idea to have internal expression of float or numpy.array.

This is usually very fast, and easy to extend.

On the other hand, you may also want to make “unitful” version, particularly for step-by-step calculation in the interactive shell.

This function produces a function of “unitful” version from the float or numpy.array version of function.

Example follows.

>>> import irfpy.util.unitq as u

>>> def PE(m_si, h_si):
...     return 9.8 * m_si * h_si


The above function calculate the gravity potential. It is implincitly assumes float (or numpy array) argument in the MKSA system.

>>> print(PE(1.5, 20.0))
294.0


Something with 1.5 kg mass is placed at 20.0 m, the gravity potential is 294.0 J (at the Earth).

If you want to calculate with unit, PE cannot handle it properly.

>>> print(PE(1.5 * u.kg, 20.0 * u.m))
294.0 kg*m


The value is ok, but the unit is not in Joule, so that I cannot convert it.

>>> pprint(PE(1500 * u.g, 2000 * u.cm), fmt='%.4e')
2.9400e+07 g*cm


The example gives more complicated situation. Again, the unit is not consistent.

To solve this problem, I suggest to make the unitful function. The unitful version of the function can be made via

>>> PE_u = make_unitful_function(PE, [u.kg, u.m], u.J)


The first argument is the unitless function, the second argument is a list of unit assumed in the PE function in the order, and the third argument is the unit returned in the KE function.

>>> print(PE_u(1500 * u.g, 2000 * u.cm).rescale(J))
294.0 J


The :make_unitful_function: returns a wrapped function (PE_u) of the original function (PE). When called the wrapped function, the argument is first converted to float/np.array by stripping the given units used in the original function (mass is ‘kg’ and height is ‘m’ here). Then, the original function is executed with float/np.array. Finally, the given unit (the result is ‘J’) is added to the output float/np.array, to be returned by the new function.

Use of offset

If you have formula as an method of some class. Let’s try to find out the Moon gravity calculator class.

>>> class MoonGravity:
...     def __init__(self):
...         self.g = 1.625   # m/s2, gravitation of Moon
...     def PE(self, mass, distance):
...         return self.g * mass * distance
>>> mg = MoonGravity()
>>> print(mg.PE(1.5, 20))
48.75


A new class, namely the unitful class may be generated as follows.

>>> class MoonGravity_u(MoonGravity):
...     def __init__(self):
...         MoonGravity.__init__(self)
...     PE = make_unitful_function(MoonGravity.PE, [kg, m], J, offset=1)
>>> mg_u = MoonGravity_u()
>>> print(mg_u.PE(1500 * g, 2000 * cm))
48.75 J


Here to define (override) new PE, offset=1 is given. This is because MoonGravity.PE method will take the object as the 0-th argument, which should not be unit-converted.

irfpy.util.unitq.make_unitful_function2(func, argunitarr, retunitarr)[source]

Improved factory of make_unitful_function(), allowing tuple of return.

Parameters:
• func – Physical function (formula)

• argunitarr – List of unit in the order of the argument of func. Units or None.

• retunitarr – List of unit of the returned value of func. Units or None.

When you implement a physical function (or formula), it is usually a good idea to have internal expression of float or numpy.array.

This is usually very fast, and easy to extend.

On the other hand, you may also want to make “unitful” version, particularly for step-by-step calculation in the interactive shell.

This function produces a function of “unitful” version from the float or numpy.array version of function.

Example follows.

Suppose you make a function to calculate the kinetic energy and the momentum. The argument is the mass and the velocity. Also, you may want to give an argument for which unit conversion is not needed, and to return a status flag, which is also not a physical unit.

The function should look like kene, mom, stat = enemom(mass, vel, name). The list of the units of the argument is [u.kg, u.m / u.s, None] and that for return values is [u.J, u.kg * u.m / u.s, None].

>>> def enemom(mass, vel, name):
...     ke = mass * vel * vel / 2.
...     mom = mass * vel
...     stat = len(name)    # Immitate the status.
...     return ke, mom, stat
>>> print(enemom(10., 30., 'sample'))
(4500.0, 300.0, 6)


If you want to make a unitful version,

>>> enemom_u = make_unitful_function2(enemom, [kg, m / s, None], [J, kg * m / s, None])
>>> print(enemom(10. * kg, 30. * m / s, 'unitful sample'))
(array(4500.) * kg*m**2/s**2, array(300.) * kg*m/s, 14)


Todo

Known issue. If the retunitarr is scalar, the argument is transfered to make_unitful_function(). However, the None argument is not supported for make_unitful_function().

irfpy.util.unitq.use_plasma()[source]

Use space plasma familier system as default.

Length in cm, mass in AMU, temperature in eV, and time in s.

>>> import irfpy.util.unitq as u
>>> print((1 * u.km ** 3).simplified)
1000000000.0 m**3
>>> u.use_plasma()
>>> pprint((1 * u.km ** 3).simplified, fmt='%.1e')
1.0e+15 cm**3

>>> pprint((30000 * u.K).simplified)
2.585 eVT

>>> u.use_mksa()
>>> print((30000 * u.K).simplified)
30000.0 K

irfpy.util.unitq.use_mksa()[source]
irfpy.util.unitq.use(system=None, currency=None, current=None, information=None, length=None, luminous_intensity=None, mass=None, substance=None, temperature=None, time=None)

Alias to set_default_units provided by qunatities

irfpy.util.unitq.pprint(value, fmt='%.3f', *args, **kwds)[source]

Print the value in easily-readable way.

Parameters:
• value – A quantity

• fmt – Format. Only effective if the value has shape (), namely float.

• kwds – Keywords given to irfpy.util.with_context.printoptions() Only effective if value is array. precision and suppress are frequently used.

>>> pprint(np.sqrt(np.arange(3000)) * kg, precision=3, suppress=True)
[  0.      1.      1.414 ...  54.745  54.754  54.763] kg
>>> pprint(1.537732343e-10 * g, fmt='%.5e')
1.53773e-10 g

irfpy.util.unitq.pp(value, fmt='%.3f', *args, **kwds)

Alias for pprint()