Note

This tutorial was generated from a Jupyter notebook that can be downloaded here.

Getting started

Here, we will explain the basics that are needed to get started with tulips. tulips creates visualizations of stellar evolution based on output from the MESA stellar evolution code. To read MESA output files, tulips uses the mesaPlot package. Here we will show you how to load a MESA model and how you can explore its properties. We will use jupyter notebooks to show the tutorials. With this application you can edit and run python code via a web browser. Have a look here for information on how to download and use it.

Loading a MESA model

To show the functionalities of the mesaPlot output, we use a pre-computed MESA stellar model of an \(11 M_{\odot}\) star. In order to explore the properties of this model, we can create a mesaPlot object called m11, in which all the information about the stellar model will be stored. MESA produces two types of output files:

• history.data files that contain the evolution of one-dimensional properties of the stellar model, such as its radius.

• profile.data files that contain a snapshot of the interior stellar structure at a particular moment in time. For example, this file can contain the temperature as a function of the radius/mass coordinate

In the example below, we show how to load the output of a MESA history file with mesaPlot, after which we can access its properties.

# Interactive matplotlib plotting for jupyter lab
%matplotlib inline

# If you use jupyter notebook
# %matplotlib notebook

import matplotlib.pyplot as plt
import mesaPlot as mp

EXAMPLE_DIR = "../../tulips/MESA_DIR_EXAMPLE/"

m11 = mp.MESA() # Create MESA object
m11.loadHistory(filename_in=EXAMPLE_DIR + 'history.data')

Tip

To copy all lines of code in a cell, you can just click on the copy button in the upper right corner!

Accessing properties

After the history output file has been loaded, properties such as the mass, age or radius of the star can be accessed through the hist property.

star_age = m11.hist.star_age # Access star age
log_R = m11.hist.log_R # Access star log radius

In order to have a look at the different properties that are stored, type m11.hist. and press Tab. This will show you a list of the information that can be accessed. You can use these properties to make simple plots. For extensive documentation about mesaPlot, have a look at the mesaPlot GitHub page.

Creating your first tulips diagram

Now that we have explored the basic properties of our star, we are ready to visualize it using tulips! tulips is capable of generating different kinds of diagrams, which are shown at the Homepage. For demonstration, we will plot one of these diagrams: the perceived color diagram. This can be done using just one command, passing our MESA object m11 to the perceived_color function from tulips. It will show us the perceived color and size of the star at a single point in time, specified by the time index time_ind. For now, we only want to plot at time_ind = 0.

import tulips

tulips.perceived_color(m11, time_ind=0, fig_size=(8,6))
plt.show()

Here is your first tulips plot! We see a blue \(10.5 M_{\odot}\) star. The x and y axis show the radius of the star. The color represents the temperature of the star in the same way we would observe it: blue is hot, red is cooler. On the bottom left we see an inset Herzsprung Russel diagram, showing that this star is just at the beginning of the main sequence. We can use this first diagram to verify if everything looks fine, before moving on to making an animation.

Note

time_ind refers to an index that follows every model stored in a MESA history.data file. This means the first model is at index 0 and the last is at index -1. It depends on your model which age this corresponds to. The powerful thing about time_ind is that it lets you find out some specific times very easily through numpy functions. For example, if you want to create a model of a star at the point when it finishes hydrogen burning, you can look for the model where the central hydrogen mass fraction is very small, like end_hburn_index = np.where(m11.hist.center_h1 < 1e-4)[0][0].

Creating your first tulips animation

Once you are happy with it, it would be interesting to see how the star is evolving and how that reflects in its appearance. Therefore, we can create an animation of the evolution of the star. To view the animation, we first have to save it. Afterwards we can open it with the Video function from the IPython library. It is not possible to see the animation without saving it. Let’s create an animation of our stellar model:

tulips.perceived_color(m11, time_ind=(0, -1, 10), fps=30, output_fname="perceived-color-test")
plt.show()

Creating animation

from IPython.display import Video

Video("perceived-color-test.mp4", embed=True, width=700, height=600)

Now, time_ind contains the start index, the end index, and the time step. The fps keyword (which stands for “frames per second”) helps control the speed of the resulting video. More information and all the options can be found in the function docstring and in the tulips API. The function docstring can be found by typing tulips.perceived_color() and press Shift + Tab inside the parenthesis. The animation is saved as .mp4 file in a directory, which you can specify with output_fname. You can then call the Video function with the specified name. We can now see the star changing over time in radius, color and mass while it follows its track on the Herzsprung Russel diagram.