Mesa Study Note #1: Running MESA
Running MESA
On how to use MESA to evolve a star. The ***$MESA_DIR*** directory has many subdirectories. Most of these subdirectories are modules ("M" in MESA) that provide some specific functionality (for example, "kap" provides routines for calculating opacity). The most important module is "star", which contains a module that knows how to put the functionality of all the other modules together, advances the state of a star model through one step, and then establishes a new time increment for the next step. Basically, that's what it's all about.
Here is for a program that can perform multi-step stellar evolution with these modules. Such programs are located in the star/work directory, and we'll start there.
1. Make a copy of the star/work directory
Execute and store work elsewhere than the main MESA directory. This will simplify things when an update is made to a new MESA version at some point in the future. Therefore, whenever a new MESA project is started, a new copy of the star/work directory should be created.
cp -r $MESA_DIR/star/work tutorial
Copied the working copy and started compiling the code in it.
cd tutorial ./mk
2. Set up configuration files
The working directory already contains a simple set of configuration files to evolve from a 15 solar mass star to the zero-age main sequence (core hydrogen ignition). Now, without editing anything, take a look at the files.
2.1. inlist
This is the first inline list file that MESA reads when it starts up. File inlist is usually used to instruct MESA to read one or more other inlist files.
The stellar file inlist contains five sections (technically fortran "namelists"):
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
The definitions in the name list are of the form:
name = value ! comment
Values are specified using normal fortran syntax. Blank lines and comment lines can be freely included in the list. It's also okay to start a line containing name-value pairs with spaces, so you can (and should) indent your content to make it more readable.
All controls have sensible defaults when initialized, so only set those 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
2.2. inlist_project
We will use these options to construct a 15-solar-mass star from a pre-main sequence model and then stop evolving when it reaches 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
2.2. inlist_pgstar
This contains options for drawing on the screen.
&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
3. Run MESA
Running the code is now as easy as typing:
./rn
MESA will be kept updated with terminal output:
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 show some pgstar graphs like this:
This should run for about 850 steps, then stop with the following message:
stop because Lnuc_div_L >= Lnuc_div_L_zams_limit
4. Resuming MESA
You are not limited to using the same parameter settings throughout the run. It is possible to stop the operation, edit the inlist file, and restart with the new settings. This stop-restart mechanism is carefully constructed so that if you restart from an intermediate state without changing any controls, you will get exactly the same result. To do this, the information saved must be complete, which means there is a lot of information. To make it fast, restart information is dumped in binary format. These binary dumps are called "photos" and are saved in a subdirectory with the same name.
It should be emphasized that the photos are not suitable for long-term storage of models. In particular, existing photo files should be expected to be out of date when updating to a new version of MESA star.
If you scroll back in the running terminal output, you should find a line like the following (although the numbers may vary slightly between MESA versions):
save photos/x849 for model 849
Instructs to automatically save one of the snapshots when the run terminates.
Open inlist_project in an editor. It can be seen that there are two stop 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 points out in the termination message, we stop because of the first condition (ZAMS is naturally before h is exhausted). Turn off this stop condition by editing inlist:
stop_near_zams = .false.
and save the inlist file.
Now reboot with photos and new settings. Give it a try.
./re x849
This will resume operation of the Type 849, but this time, when our other conditions are met, the operation will stop when the central hydrogen drops below 1e-3. This will happen around the Type 975.
5. Saving a model
Photo files are machine-readable binary files, it is not designed to be portable to different machines or even different versions of MESA. So we need another way to save the model so we can use it later, maybe as an initial model for later runs, or send it to someone to use with their own copy of MESA.
Save a model file at the end of the run. Go to the following line in the &star_job section of 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 inlist and changing save_model_when_terminate to true.
Save the file and restart MESA from the same location as before.
./re x849
This time when the run ends, MESA will save a model called 15M_at_TAMS.mod.
6. Loading a model
The post-main-sequence evolution of stars can now be studied, starting a new MESA run using the model just saved. In order to do this, the list might look like this:
&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) energy_eqn_option = 'dedt' 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 it out, save the preceding text as a file named inlist_load in your working directory. Make sure the file ends with a blank new line. Then edit the main inlist file so that it uses inlist_load instead of inlist_project everywhere in the inlist (ie extra_star_job_inlist1_name and extra_controls_inlist1_name).
Then continue:
./rn
MESA will start with the newly saved file. Unlike photos, saved models do not have a complete snapshot of the internal state of the system. Photos are guaranteed to give the same results; saved models do not. When running a saved model, there may be minor differences compared to the model seen in the run prior to saving. The difference should be small.
7. Learning about the many MESA options
After reading the preceding list, the more pressing questions may be "Where did these options come from?" and "How do I find the right one?"
Files containing descriptions of all MESA options and their defaults are located in this directory:
$MESA_DIR/star/defaults
Options are organized by the list of names they belong to. Therefore, the file controls.defaults contains a discussion of the options in the list of control names.
Suppose we want to know more about what this "Dutch_wind" is. Search for the word "Dutch" in controls.defaults and you'll soon find 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 the .defaults file to familiarize yourself with what's available. Too many choices, use test_suite.