Running MESA

This page has information about how to use MESA to evolve a single star. It assumes you have already installed MESA (see Installing MESA).

The $MESA_DIR directory has lots of subdirectories. Most of these subdirectories are modules (the “M” in MESA) that provides some specific functionality (e.g., “kap” provides routines for calculating opacities). The most important module is “star”, which contains the module that knows how to put the capabilities of all the other modules together and advance the state of a stellar model by a single step and then suggest a new time increment for the next step. Basically, that’s all it does.

You came here for a program that can use these modules to do multi-step stellar evolution. You’re in luck, because such a program lives in the star/work directory, so that’s where we’ll start.

Make a copy of the star/work directory

You should perform and store your work somewhere other than the main MESA directory. This will make your life simpler when you do a fresh checkout of a new MESA version at some point in the future. Therefore each time you want to start a new MESA project, you should make a new copy of the star/work directory. Let’s do that for this tutorial.

cp -r $MESA_DIR/star/work tutorial

Now that we have our copy of the work directory, we need to compile the code that lives in it.

cd tutorial
./mk

Set up configuration files

The work directory already contains a set of simple configuration files that will evolve a 15 solar mass star through on to the zero-age main sequence (core hydrogen ignition). For now, you won’t need to edit anything, but you should take a look at each of these files.

inlist

This is the first inlist file that MESA reads when it starts. The file inlist is often used to direct MESA to read one or more other inlist files.

There are five sections (technically fortran “namelists”) in star inlist files:

  • star_job - options for the program that evolves the star
  • eos - options for the MESA eos module
  • kap - options for the MESA kap module
  • controls - options for the MESA star module
  • pgstar - options for on-screen plotting

Each definition in a namelist is of the form

name = value ! comment

Values are specified using the normal fortran syntax. Blank lines and comment lines can be freely included in the list. Blanks at the start of a line containing a name-value pair are okay too so you can (and should) indent things to make them more readable.

All of the controls are given reasonable default values at initialization, so you only need to set the ones that you actually want to change.

! This is the first inlist file that MESA reads when it starts.

! This file tells MESA to go look elsewhere for its configuration
! info. This makes changing between different inlists easier, by
! allowing you to easily change the name of the file that gets read.

&star_job

    read_extra_star_job_inlist1 = .true.
    extra_star_job_inlist1_name = 'inlist_project'

/ ! end of star_job namelist


&eos

    read_extra_eos_inlist1 = .true.
    extra_eos_inlist1_name = 'inlist_project'

/ ! end of eos namelist


&kap

    read_extra_kap_inlist1 = .true.
    extra_kap_inlist1_name = 'inlist_project'

/ ! end of kap namelist


&controls

    read_extra_controls_inlist1 = .true.
    extra_controls_inlist1_name = 'inlist_project'

/ ! end of controls namelist


&pgstar

    read_extra_pgstar_inlist1 = .true.
    extra_pgstar_inlist1_name = 'inlist_pgstar'

/ ! end of pgstar namelist

inlist_project

These are the options that we’ll use to construct a 15 solar mass star from a pre-main sequence model and then stop the evolution once we reach the zero-age main sequence (ZAMS).

! inlist to evolve a 15 solar mass star

! For the sake of future readers of this file (yourself included),
! ONLY include the controls you are actually using.  DO NOT include
! all of the other controls that simply have their default values.

&star_job
  ! see star/defaults/star_job.defaults

  ! begin with a pre-main sequence model
    create_pre_main_sequence_model = .true.

  ! save a model at the end of the run
    save_model_when_terminate = .false.
    save_model_filename = '15M_at_TAMS.mod'

  ! display on-screen plots
    pgstar_flag = .true.

/ ! end of star_job namelist


&eos
  ! eos options
  ! see eos/defaults/eos.defaults

/ ! end of eos namelist


&kap
  ! kap options
  ! see kap/defaults/kap.defaults
  use_Type2_opacities = .true.
  Zbase = 0.02

/ ! end of kap namelist


&controls
  ! see star/defaults/controls.defaults

  ! starting specifications
    initial_mass = 15 ! in Msun units
    initial_z = 0.02

  ! when to stop

    ! stop when the star nears ZAMS (Lnuc/L > 0.99)
    Lnuc_div_L_zams_limit = 0.99d0
    stop_near_zams = .true.

    ! stop when the center mass fraction of h1 drops below this limit
    xa_central_lower_limit_species(1) = 'h1'
    xa_central_lower_limit(1) = 1d-3

  ! wind

  ! atmosphere

  ! rotation

  ! element diffusion

  ! mlt

  ! mixing

  ! timesteps

  ! mesh

  ! solver
     ! options for energy conservation (see MESA V, Section 3)
     energy_eqn_option = 'dedt'
     use_gold_tolerances = .true.

  ! output

/ ! end of controls namelist

inlist_pgstar

This houses the options for on-screen plotting. Feel free to ignore these for now, but to learn more, have look at the Using PGSTAR section of this website.

&pgstar
  ! see star/defaults/pgstar.defaults

  ! MESA uses PGPLOT for live plotting and gives the user a tremendous
  ! amount of control of the presentation of the information.

  ! show HR diagram
  ! this plots the history of L,Teff over many timesteps
    HR_win_flag = .true.

  ! set static plot bounds
    HR_logT_min = 3.5
    HR_logT_max = 4.6
    HR_logL_min = 2.0
    HR_logL_max = 6.0

  ! set window size (aspect_ratio = height/width)
    HR_win_width = 6
    HR_win_aspect_ratio = 1.0


  ! show temperature/density profile
  ! this plots the internal structure at single timestep
    TRho_Profile_win_flag = .true.

  ! add legend explaining colors
    show_TRho_Profile_legend = .true.

  ! display numerical info about the star
    show_TRho_Profile_text_info = .true.

  ! set window size (aspect_ratio = height/width)
    TRho_Profile_win_width = 8
    TRho_Profile_win_aspect_ratio = 0.75

/ ! end of pgstar namelist

Run MESA

Running the code is now as simple as typing

./rn

MESA will keep you updated via terminal output that looks like this:

       step    lg_Tmax     Teff     lg_LH      lg_Lnuc     Mass       H_rich     H_cntr     N_cntr     Y_surf   eta_cntr   zones  retry
   lg_dt_yr    lg_Tcntr    lg_R     lg_L3a     lg_Lneu     lg_Mdot    He_core    He_cntr    O_cntr     Z_surf   gam_cntr   iters
     age_yr    lg_Dcntr    lg_L     lg_LZ      lg_Lphoto   lg_Dsurf   C_core     C_cntr     Ne_cntr    Z_cntr   v_div_cs       dt_limit
__________________________________________________________________________________________________________________________________________________

        800   7.455602  2.821E+04   4.211546   4.211546  15.000000  15.000000   0.699864   0.001978   0.280000  -5.912231    873      0
   2.364495   7.455602   0.837935 -33.599828   3.029214 -99.000000   0.000000   0.279998   0.009380   0.020000   0.014924      3
 4.5570E+04   0.596891   4.432022 -11.138110 -99.000000  -9.090996   0.000000   0.002618   0.002085   0.020138  0.000E+00    varcontrol

MESA will also display some pgstar plots that look like:

HR Diagram
TRho Profile

This should run for about 850 steps before stopping with the following message:

stop because Lnuc_div_L >= Lnuc_div_L_zams_limit

Resuming MESA

You are not limited to using the same parameter settings for an entire run. You can stop the run, edit the inlist file, and restart with new settings. This stop-restart mechanism has been carefully constructed so that if you restart from an intermediate state without changing any controls, you’ll get exactly the same results. For that to work, the saved information must be complete, and that means there’s a lot of it. To make this run fast, the restart information is dumped in binary format. These binary dumps are referred to as “photos” and are saved in a subdirectory with the same name.

It should be emphasized that the photos are not intended for long-term storage of models. In particular, when you update to a new version of MESA star, you should expect your existing photo files to become obsolete.

If you scroll back in the terminal output from the run, you should find a line that looks like (though the number may differ slightly between MESA versions):

save photos/x849 for model 849

indicating that one of these snapshots was automatically saved when the run terminated.

Open up inlist_project in your editor. You can see there were two stopping conditions,

! stop when the star nears ZAMS (Lnuc/L > 0.99)
Lnuc_div_L_zams_limit = 0.99d0
stop_near_zams = .true.

! stop when the center abundance by mass of h1 drops below this limit
xa_central_lower_limit_species(1) = 'h1'
xa_central_lower_limit(1) = 1d-3

As MESA indicated in the termination message, we stopped because of the first condition (naturally, ZAMS is before H-exhaustion). Turn off this stopping condition by editing your inlist so that

stop_near_zams = .false.

and save the inlist file.

Now we can restart using the photo and our new settings. Try it.

./re x849

This resumes the run from model 849, but this time the run will stop when our other condition is satisfied, when the central hydrogen drops below 1e-3. This will happen at about model number 975.

Saving a model

Remember that the photo file is a machine readable binary that is not designed for portability to different machines or even to different versions of MESA. So we need another way to save a model so we can use it later, perhaps as a starting model for later runs, or to send to someone for them to use with their own copy of MESA. For example, if you find some bug in MESA, and the developers will want to see if they can reproduce it on their machines. You’ll be asked to save a model from just before the bug happens and send it in an email along with your inlist.

Let’s save a model file at the end of our run. Go to the following lines to the &star_job section of your inlist:

! save a model at the end of the run
save_model_when_terminate = .false.
save_model_filename = '15M_at_TAMS.mod'

Tell MESA that you want to save a model file at the end by editing your inlist and changing save_model_when_terminate to true.

Save the file and then restart MESA from the same point as before.

./re x849

This time when the run terminates MESA will save a model named 15M_at_TAMS.mod. Take a look and see.

Loading a model

Now you could begin studying the post-main sequence evolution of stars, starting a new MESA run using the model you’ve just saved. In order to do this your inlist might look like:

&star_job
  ! see star/defaults/star_job.defaults

  ! start a run from a saved model
  load_saved_model = .true.
  load_model_filename = '15M_at_TAMS.mod'

  ! display on-screen plots
  pgstar_flag = .true.

/ !end of star_job namelist

&eos
  ! eos options
  ! see eos/defaults/eos.defaults

/ ! end of eos namelist


&kap
  ! kap options
  ! see kap/defaults/kap.defaults
  use_Type2_opacities = .true.
  Zbase = 0.02

/ ! end of kap namelist


&controls
  ! see star/defaults/controls.defaults

  ! options for energy conservation (see MESA V, Section 3)
  use_dedt_form_of_energy_eqn = .true.
  use_gold_tolerances = .true.

  ! configure mass loss on RGB & AGB
  cool_wind_RGB_scheme = 'Dutch'
  cool_wind_AGB_scheme = 'Dutch'
  RGB_to_AGB_wind_switch = 1d-4
  Dutch_scaling_factor = 0.8

/ ! end of controls namelist

If you want to try this out, save the preceding text as a file named inlist_load in your work directory. Then edit your main inlist file so that it will use inlist_load instead of inlist_project everywhere within inlist (i.e., extra_star_job_inlist1_name and extra_controls_inlist1_name).

Then as usual, do

./rn

and MESA will start up using your newly saved file. Unlike the photos, saved models don’t have a complete snapshot of the internal state of the system. Photos are guaranteed to give the same results; saved models are not. There may be small differences when you run a saved model compared to what you saw in the run before you saved it. The differences should be minor, so you shouldn’t have to worry, but don’t be surprised by them.

Learning about the many MESA options

After looking at the previous inlist, your more pressing question may be “where did those options come from?” and “how do I find the options appropriate for my problem?”. Your first stop should be the instrument papers, which discuss the most important flags.

The files that contain a description of all of the MESA options and their default values live in the directory

$MESA_DIR/star/defaults

The options are organized by the namelist that they are a part of. So the file controls.defaults contains a discussion of options in the controls namelist.

Suppose we want to learn more about what this “Dutch_wind” is. Searching in controls.defaults for the word “Dutch” quickly leads to the following summary of these options.

      ! Dutch_scaling_factor
      ! ~~~~~~~~~~~~~~~~~~~~

      ! The "Dutch" wind scheme for massive stars combines results from several papers,
      ! all with authors mostly from the Netherlands.

      ! The particular combination we use is based on
      ! Glebbeek, E., et al, A&A 497, 255-264 (2009) [more Dutch authors!]

      ! For Teff > 1e4 and surface H > 0.4 by mass, use Vink et al 2001
      ! Vink, J.S., de Koter, A., & Lamers, H.J.G.L.M., 2001, A&A, 369, 574.

      ! For Teff > 1e4 and surface H < 0.4 by mass, use Nugis & Lamers 2000
      ! Nugis, T.,& Lamers, H.J.G.L.M., 2000, A&A, 360, 227
      ! Some folks use 0.8 for non-rotating mdoels (Maeder & Meynet, 2001).

      ! ::

    Dutch_scaling_factor = 0d0


      ! Dutch_wind_lowT_scheme
      ! ~~~~~~~~~~~~~~~~~~~~~~

      ! For Teff < 1e4

      ! Use de Jager if ``Dutch_wind_lowT_scheme = 'de Jager'``
      ! de Jager, C., Nieuwenhuijzen, H., & van der Hucht, K. A. 1988, A&AS, 72, 259.

      ! Use van Loon if ``Dutch_wind_lowT_scheme = 'van Loon'``
      ! van Loon et al. 2005, A&A, 438, 273.

      ! Use Nieuwenhuijzen if ``Dutch_wind_lowT_scheme = 'Nieuwenhuijzen'``
      ! Nieuwenhuijzen, H.; de Jager, C. 1990, A&A, 231, 134

      ! ::

    Dutch_wind_lowT_scheme = 'de Jager'

You can browse through the .defaults files to familiarize yourself with what’s available. It can be easy to be overwhelmed by the shear number of options. That’s where the test_suite comes in handy.