Advanced: Parameter Units

In this tutorial we will learn about how units are handled in the frontend and how to translate between different units.

Setup

Let's first make sure we have the latest version of PHOEBE 2.3 installed (uncomment this line if running in an online notebook session such as colab).


In [1]:
#!pip install -I "phoebe>=2.3,<2.4"

In [2]:
import phoebe
from phoebe import u,c

In [3]:
logger = phoebe.logger(clevel='WARNING')

In [4]:
b = phoebe.default_binary()

Units

Each FloatParameter or FloatArrayParameter has an associated unit. Let's look at the 'sma' Parameter for the binary orbit.


In [5]:
b.get_parameter(qualifier='sma', component='binary', context='component')


Out[5]:
<Parameter: sma=5.3 solRad | keys: description, value, quantity, default_unit, limits, visible_if, copy_for, readonly, advanced>

From the representation above, we can already see that the units are in solar radii. We can access the units directly via get_default_unit.


In [6]:
b.get_parameter(qualifier='sma', component='binary', context='component').get_default_unit()


Out[6]:
$\mathrm{R_{\odot}}$

Calling get_value returns only the float of the value in these units.


In [7]:
b.get_parameter(qualifier='sma', component='binary', context='component').get_value()


Out[7]:
5.3

Alternatively, you can access an astropy quantity object that contains the value and unit by calling get_quantity.


In [8]:
b.get_parameter(qualifier='sma', component='binary', context='component').get_quantity()


Out[8]:
$5.3 \; \mathrm{R_{\odot}}$

Both get_value and get_quantity also accept a unit argument which will return the value or quantity in the requested units (if able to convert). This unit argument takes either a unit object (we imported a forked version of astropy units from within PHOEBE) or a string representation that can be parsed.


In [9]:
b.get_parameter(qualifier='sma', component='binary', context='component').get_value(unit=u.km)


Out[9]:
3687210.0

In [10]:
b.get_parameter(qualifier='sma', component='binary', context='component').get_quantity(unit='km')


Out[10]:
$3687210 \; \mathrm{km}$

Similarly when setting the value, you can provide either a Quantity object or a value and unit. These will still be stored within PHOEBE according to the default_unit of the Parameter object.


In [11]:
b.get_parameter(qualifier='sma', component='binary', context='component').set_value(3800000*u.km)

In [12]:
b.get_parameter(qualifier='sma', component='binary', context='component').get_quantity()


Out[12]:
$5.4621245 \; \mathrm{R_{\odot}}$

In [13]:
b.get_parameter(qualifier='sma', component='binary', context='component').set_value(3900000, unit='km')

In [14]:
b.get_parameter(qualifier='sma', component='binary', context='component').get_quantity()


Out[14]:
$5.6058646 \; \mathrm{R_{\odot}}$

If for some reason you want to change the default units, you can, but just be careful that this could cause some float-point precision issues.


In [15]:
b.get_parameter(qualifier='sma', component='binary', context='component').set_default_unit('mm')

In [16]:
b.get_parameter(qualifier='sma', component='binary', context='component').get_quantity()


Out[16]:
$3.9 \times 10^{12} \; \mathrm{mm}$

In [17]:
b.get_parameter(qualifier='sma', component='binary', context='component').get_quantity(unit='solRad')


Out[17]:
$5.6058646 \; \mathrm{R_{\odot}}$