MESA Summer School 2021: Lecture 1

MESA (Modules for Experiments in Stellar Astrophysics) is composed of modules. These are collections of Fortran files that serve a common purpose. When you list the contents of $MESA_DIR, most of the subdirectories that you see are modules.

Some modules like interp_1d (also interp_2d, math, mtx) provide supporting numerical routines and so you will rarely, if ever, need to think about them and how they work. (The exception being if you want to do something like interpolate a 1D function in Fortran yourself.)

Other modules like eos (also atm, const, kap, net, neu) provide key physical inputs/ingredients. Doing good science with MESA will require you to have a high-level understanding of what these modules do and a basic knowledge of their assumptions and limitations. (Advanced usage of MESA, say high-precision modeling of an unusual kind of star, may require a detailed understanding!)

Finally, some modules like star (also astero and binary) provide the routines needed to evolve stellar models and report their properties. What you may think of as "running MESA" is the execution of a program that uses the capabilities provided by the star module to evolve a stellar model.

MESA now has documentation that lives in the source tree ($MESA_DIR/docs) and is version controlled along with the rest of MESA. This documentation is hosted online by ReadTheDocs and is available at https://docs.mesastar.org/. Bookmark this site and spend some time getting familiar with what it contains! For example, there is a page summarizing the MESA modules.

This documentation is a work in progress, but should already be useful. It will continue to grow and improve in the coming years. (MESA is now hosted on GitHub and if you see areas for improvement, you are welcome to contribute.)

The documentation is versioned. Right now, there are only two versions: r15140 (the current release) and latest (the development version). In the future, when multiple releases exist, you will want to be careful to use the documentation that matches the MESA version you're using. Controls on the lower left of the page (collapsed by default) allow you to switch versions.

MESA has hundreds of thousands of lines of code, so when you want to learn how something works, finding the relevant code can be a challenge. This will get easier as you get familiar with the layout and structure of MESA, but it is also worth investing some time in general techniques for searching through source code.

Tools like grep — or more advanced variants like ack, ag, or rg — allow you to rapidly search through the code base for occurrences of a given string or pattern. These tools are helpful for finding where a particular function/subroutine is defined or called or where a particular variable is used.

For example, if you execute the command grep -rI Josiah * while in $MESA_DIR you can see every occurrence of my name in the source code. (The -r argument means recursive; the -I argument excludes binary files.)

Answering your own questions about how MESA works often requires a mixture of the documentation and source code detective work. The documentation can give you a high-level overview or a hint about where else to look, but the source code is what has the details and is ultimately the "truth".

Each time you want to start a MESA project, you should make a new copy of the star/work directory.

cp -r $MESA_DIR/star/work my_new_project

In this case, we have prepared and provided a work directory for you. Download, unpack, and enter this work directory.

unzip lecture1.zip
cd lecture1

MESA/star currently has five inlist sections. Each section contains the options for a different aspect of MESA.

star_job

options for the program that evolves the star

eos

options for the MESA eos module (new!)

kap

options for the MESA kap module (new!)

controls

options for the MESA star module

pgstar

options for on-screen plotting

The distinction between star_job and controls can be a little subtle.

star_job contains options that answer questions like:

• how should MESA obtain the initial model?
• are there any changes MESA should make to the initial model?
• where should MESA store its output?

controls contains options that answer questions like:

• what conditions should cause MESA to stop evolving the model?
• which angular momentum transport processes should MESA consider?
• what numerical tolerances should MESA's solvers use?

eos and kap contain options for the equation of state and opacity modules, respectively, and answer questions like:

• what component EOSes should be used and where should they be blended?
• what composition should be assumed when calculating the opacity?

MESA's many inlist options have their default values set in *.defaults files. These files also provide documentation of the options.

For a specific module, this file (or files) is located in <module>/defaults/. So for example, the EOS defaults are described in $MESA_DIR/eos/defaults/eos.defaults. The directory $MESA_DIR/star/defaults contains star_job.defaults, controls.defaults, and pgstar.defaults.

You can directly read these defaults files as plain text. Alternatively, they are rendered as part of the online documentation.

The individual module defaults appear under Module Documentation

• $MESA_DIR/eos/defaults/eos.defaults
• $MESA_DIR/kap/defaults/kap.defaults

while the star (and also binary and astero) defaults appear under Reference

• $MESA_DIR/star/defaults/star_job.defaults
• $MESA_DIR/star/defaults/controls.defaults
• $MESA_DIR/star/defaults/pgstar.defaults

They are roughly sorted into groups of related options. When you're searching for an option, see if it seems to match any of the section headings and then look there first. If that fails, try searching for some key words.

Note that inlists can point to other inlists. This can be useful for keeping things organized. In the lecture1 directory, inlist points MESA to inlist_project and inlist_pgstar.

MESA already knows how to output a tremendous amount of information. The two key file types are history files, which store the value of scalar quantities (e.g., mass, luminosity) at different timesteps and profile files which store the value of spatially varying quantities within the model (e.g., density, pressure) at a single timestep.

Each output file contains two types of data. First there are headers, which are single values associated with the file (e.g., the version of MESA that generated the file). Then there are columns, which are lists of numbers (e.g., the luminosity at each timestep or the pressure in each cell).

The contents of MESA's output files is not directly controlled via inlists. The default output is set by the files

$MESA_DIR/star/defaults/history_columns.list
$MESA_DIR/star/defaults/profile_columns.list

In order to customize the output, you copy these files to your work directory.

cp $MESA_DIR/star/defaults/history_columns.list .
cp $MESA_DIR/star/defaults/profile_columns.list .

Then, open up history_columns.list or profile_columns.list in a text editor and comment/uncomment any lines to add/remove the columns of interest ('!' is the comment character.)

You can use run_star_extras.f90 to define your own columns and headers in your history and profile files. We will discuss this later today.

MESA provides hooks to override or modify many of its built-in routines. (These routines mostly affect things that occur within "take step" box of the flowchart.) These are referred to as "other" routines. There are two main steps needed to take advantage of this functionality: (1) writing the other routine and (2) instructing MESA to use this routine.

Navigate to $MESA_DIR/star/other, where you will see a set of files named with the pattern other_*.f90. In general, find the one corresponding to the physics (or numerics) that you want to alter. Open one up and read through it. Many of the files contain comments and examples.

Note that we do not want to directly edit these files. Instead we want to copy the template routine into our copy of run_star_extras.f90 and then further modify it there. The template routines are usually named either null_other_* or default_other_*.

In this example, we will focus on other_energy.f90. Open up this file. Copy the subroutine default_other_energy and paste it into your run_star_extras.f90. It should be at the same "level" as the other subroutines in that file (that is, contained within the run_star_extras module.).

subroutine default_other_energy(id, ierr)
  use const_def, only: Rsun
  integer, intent(in) :: id
  integer, intent(out) :: ierr
  type (star_info), pointer :: s
  integer :: k
  ierr = 0
  call star_ptr(id, s, ierr)
  if (ierr /= 0) return
  s% extra_heat(:) = s% extra_power_source
  return
end subroutine default_other_energy

The variable s% extra_heat is an additional specific (per mass) heating rate that will be included. Note that this routine already does something; default_other_energy is responsible for making the extra_power_source control work. Go ahead and remove that bit, the existing example, and rename it to lecture1_other_energy.

In Fortran, you can write expressions that operate on the whole array at once (like s% extra_heat(:) = s% extra_power_source). However, it is often simplest to explicitly set the value of extra_heat (or some other array) one value at a time, by using a loop. While we're looking code with a loop, it is a good time to mention that in MESA, the outermost zone is at k=1 and the innermost zone is at k=s% nz. Arrays may also have a size in excess of nz, but only elements 1 through nz are meaningful.

subroutine lecture1_other_energy(id, ierr)
  integer, intent(in) :: id
  integer, intent(out) :: ierr
  type (star_info), pointer :: s
  integer :: k
  ierr = 0
  call star_ptr(id, s, ierr)
  if (ierr /= 0) return

  ! calculate extra_heat for each cell
  do k = 1, s% nz
     s% extra_heat(k) = 0
  end do

end subroutine lecture1_other_energy

If you read the comments in other_energy.f90 (and you should), you can see that the file tells us how to have MESA use our other_* routine. Perform these steps (hint: you will need to edit both your run_star_extras.f90 and your inlists).

It is often useful to do some of your analysis in run_star_extras. At runtime, you have access to more information about the star than will be in the history and profile files. Additionally, by allowing you to only record the final quantities of interest, this can help make your MESA output smaller and your subsequent analysis easier. (This is particularly useful if you are running large sets of MESA models.)