MESA Summer School 2017: 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 lecture1

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:

• when should MESA 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 (e.g. density, pressure) at a single timestep.

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 history and/or profile columns. This capability is covered on the MESA website; we will not cover it 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_*.f. In general, find the one corresponding to the physics (or numerics) that you want to alter. Open it 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.f. 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 (kudos if you spot the error), 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

end subroutine lecture1_other_energy

If you read the comments in other_energy.f (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 columns.

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 to access to 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.

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

cp -r $MESA_DIR/binary/work lecture1-binary

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

unzip lecture1-binary.zip
cd lecture1-binary

The contents of the binary/work directory should look similar to a standard star work directory, only doubled. There are now two inlists (called inlist1 and inlist2) and two LOGS directories (called LOGS1 and LOGS2).

The file inlist_project now contains the binary namelists &binary_job and &binary_controls. These have analogous roles to the &star_job and &controls namelists in a regular star/work directory.

There are only a few possible controls in &binary_job, which are documented in $MESA_DIR/binary/defaults/binary_job.defaults. This is where you specify the inlists for each of the stellar models (via inlist_names). Those files will be regular inlists for MESA/star, where you can load/save models, change nuclear networks, do what you're used to doing in MESA/star. You also choose whether to evolve both stars (one star could be a point mass) and whether to follow Roche lobe overflow. In this example, our binary_job namelist is

&binary_job

  ! each star has its own inlists
    inlist_names(1) = 'inlist1'
    inlist_names(2) = 'inlist2'

  ! in this example, we will evolve stellar models for both stars
    evolve_both_stars = .true.

/ ! end of binary_job namelist

The options in the &binary_controls inlists, which may be more unfamiliar, are documented in $MESA_DIR/binary/defaults/binary_controls.defaults. Most importantly, this is where we set the initial orbit of the binary and determine how mass and angular momentum are transferred.

In this example, our binary_controls namelist is

&binary_controls

  ! since we load stellar models, we do not need to specify masses
  ! if we were using a point mass we would need to set its mass

  ! we need to set the initial orbital properties of the binary
  initial_period_in_days = 0.027777777777777778d0 ! 40min

  ! choose the types of angular momentum losses we consider
  do_jdot_mb = .false.
  do_jdot_gr = .true.
  do_jdot_ml = .true.
  do_jdot_ls = .true.

  ! make frequent terminal output
  terminal_interval = 5
  write_header_frequency = 1

/ ! end of binary_controls namelist

Again, binary behaves much like star, so before you can run you must issue the command

./mk

MESA evolves a binary system by independently solving the structure of each component star and the orbital parameters, all using the same timestep. The timestep could be limited by changes in either star or by changes in the binary properties.

In the src/ subdirectory of a binary work directory there is a file run_binary_extras.f. This provides routines analogous to those in run_star_extras.f, but that apply to the binary evolution.

Importantly, there is still a run_star_extras.f with all of the same routines we know and love.