Resokit.units Tutorial

This tutorial is a guide to use ResoKit.units package. ResoKit.units includes tools for unit manipulation.

In this brief tutorial we show how to use it.

Import ResoKit and the necessary packages

[1]:

import resokit as rk

import resokit.units as runits

Available units

The internal units criteria is the MKS system of units.

The dictionary runits.UNITS contains all available units.

[2]:

runits.UNITS

[2]:

mappingproxy({'mass': {'g': 0.001,
               'gr': 0.001,
               'kg': 1.0,
               'ton': 1000.0,
               'me': 5.9722e+24,
               'mj': 1.89813e+27,
               'ms': 1.989e+30},
              'distance': {'cm': 0.01,
               'm': 1.0,
               'km': 1000.0,
               're': 6371000.0,
               'rj': 69911000.0,
               'rs': 695700000.0,
               'au': 149597800000.0,
               'pc': 3.0857e+16},
              'time': {'sec': 1.0,
               's': 1.0,
               'min': 60.0,
               'hour': 3600.0,
               'day': 86400.0,
               'year': 31557600.0,
               'yr': 31557600},
              'angle': {'rad': 1.0, 'deg': 0.017453292519943295},
              'density': {'rhow': 999.9999999999999,
               'rhos': 1410.198225159322,
               'rhoj': 1326.1748914558502,
               'rhoe': 5513.443375519388}})

The trailing “e”, “j”, “s”, “w” correspond to “Earth”, “Jupiter”, “Sun”, and “water”.

Note: All functions in this package cast the input unit string to lowercase.

Nevertheless, the output units standard are

Planet:
- mass: Jupiter masses
- radius: Jupiter radii
- semimajor-axes: au
- period (time): days
Star:
- mass: Solar masses
- radius: Solar radii
- distance: parsecs
- period (time): days

More information about the units can be found at:

Convert function

The convert function is useful to convert values between units from_unit and to_unit.

[3]:

runits.convert(1, from_units="Mj", to_units="Ms")

[3]:

0.0009543137254901961

Here, we converted 1 Jupiter mass to Solar masses.

This can be done with multiple values too:

[4]:

runits.convert(1, 5.2, 1e-2, 4, 6, from_units="Mj", to_units="Ms")

[4]:

[0.0009543137254901961,
 0.00496243137254902,
 9.543137254901961e-06,
 0.0038172549019607842,
 0.005725882352941176]

If we try a conversion between non allowed units, an error is raised:

[5]:

runits.convert(1, from_units="Mj", to_units="Rs")

---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[5], line 1
----> 1 runits.convert(1, from_units="Mj", to_units="Rs")

File ~/Documentos/git/ResoKit/resokit/units/units.py:170, in convert(from_units, to_units, power, *values)
    168 factor = 1.0
    169 for fu, tu, pw in zip(from_units, to_units, powers):
--> 170     factor *= _convert_units(fu, tu, power=pw)
    172 if not values:
    173     return factor

File ~/Documentos/git/ResoKit/resokit/units/units.py:99, in _convert_units(from_unit, to_unit, power)
     96         dest = unit_dict[to_unit]
     97         return (origin / dest) ** power
---> 99 raise ValueError(
    100     f"Cannot convert '{from_unit}' to '{to_unit}': incompatible or unknown."
    101 )

ValueError: Cannot convert 'mj' to 'rs': incompatible or unknown.

Multiple dimensional units

This function also allows the conversion between more than 1D units (eg. \(km^2 \rightarrow au^2\)), using the argument power.

[6]:

runits.convert(1, from_units="km", to_units="au", power=2)

[6]:

4.46837472302927e-17

Compound units

Sometimes, a conversion between compound units is needed (eg. \(km\,s^{-2} \rightarrow au\,yr^{-2}\)). This can also be done with the convert function, using the power argument.

[7]:

runits.convert(1, from_units=("km", "s"), to_units=("au", "yr"), power=(1, -2))

[7]:

6657063.925806398

Application to system

Let’s load Kepler-47 system. See then main tutorial for more info.

[8]:

k47 = rk.load.from_eu("kepler47", exact_match=False)
k47

Looking for star system 'kepler47' in eu database.
 Loading the entire dataset...
  Reading exoplanet_eu.csv directly from /home/egianuzzi/.resokit_data/exoplanet_eu.zip...
Updated stored index in memory.
Stored dataset in memory.
 Found a very close star match: 'Kepler-47 A' in eu dataset.
 Loading the almost exact match...
Checking if 'Kepler-47 A' is a binary system...
 Binary system found in ['Kepler47'], in p-type binary orbit.
Creating system 'Kepler-47'.
 Using binary star 'Kepler-47'.
 3 planets created.

[8]:

StaticSystem: 'Kepler-47'
 Star 1:
  Kepler-47 A
 Star 2:
  Kepler-47 B
 Planets:
  Kepler-47 (AB)b
  Kepler-47 (AB)d
  Kepler-47 (AB)c
 [circumbinary system]
from 'eu' data source.

We can check the system planets radii…

[9]:

radii = k47.get_item("radius", error=True)
radii

[9]:

	radius	radius_err_min	radius_err_max
Kepler-47 (AB)b	0.2700	0.0110	0.0110
Kepler-47 (AB)d	0.6281	0.0437	0.0589
Kepler-47 (AB)c	0.4100	0.0180	0.0180

This radii are in Jupiter radius units; but we can visualize them in Earth units using:

[10]:

runits.convert(radii, from_units="rj", to_units="re")

[10]:

	radius	radius_err_min	radius_err_max
Kepler-47 (AB)b	2.962795	0.120706	0.120706
Kepler-47 (AB)d	6.892340	0.479534	0.646328
Kepler-47 (AB)c	4.499060	0.197520	0.197520