MESA Summer School 2019: Lecture 1

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 has three inlist sections. Each section contains the options for a different aspect of MESA.

star_job

options for the program that evolves the star

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. We won't discuss pgstar in this lecture, but Frank will later this morning.

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?
• what microphysics data should MESA read?
• 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?

MESA's many inlist options are documented in the files

• $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.f 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.f 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.f. 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
  ! here is an example of calculating extra_heat for each cell.
  do k = 1, s% nz
     if (s% r(k) > 0.7*Rsun .and. s% r(k) < 0.9*Rsun) then
        s% extra_heat(k) = 1d3*exp(-10*(s% r(k) - 0.8*Rsun)**2)
     end if
  end do
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.

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.f 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.)

Recall that star_info contains the values for the parameters that you set in your controls inlist. That also means that you can set the value of these parameters by modifying the star_info structure. Since run_star_extras gives us hooks that can access the star_info at each step, that means we can modify parameters as the run proceeds. This often saves us the hassle of stopping, saving a model, editing the inlist, and restarting.