how to use MESA/STAR
a basic guide to get you started
Contents
Introduction
1. Setting up the parameters for a run—the ‘inlist’ file
2. Changing parameters during a run—stopping and restarting
3. Reading the the standard logs and profiles
4. Using Tioga to create MESA/STAR plots
5. Adding your own code
Introduction
Every module in MESA is a library, and MESA/STAR is no exception; the job of the MESA/STAR module is to 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.
But I assume that you’re like me and want to have a program that invokes the library routines to do multi-step stellar evolution. Such a program lives in the mesa/star/test directory and is created along with the rest of the MESA/STAR tests and utilities. The sources are in test/src/run_star.f if you’d like to see how it works.
One of the first things run_star does is read control parameters from the file named ‘inlist’ in star/test. For many users, it won’t be necessary to change any fortran code; you’ll probably be able to do what you want just by editing the inlist file in your favorite text editor.
The next few sections discuss the inlist file and explain how you can use it to setup a run and to change things as the run progresses. Once you’ve got the parameters set so that the evolution is working as you like, you’ll want to get detailed data and make pretty plots. There’s a section covering the standard logs and profiles that are created by MESA/STAR—they should be adequate for many tasks. But for more advanced applications, you’ll need to know how to add your own code to do things during a run such as modify controls or save special log information. The final section of this guide discusses how you can do that (it’s not too hard—really!).
Before getting into the details of running MESA/STAR, I suggest that you create a separate working directory rather than doing things in the star/test directory. The easiest way to set this up is to copy the star/work directory. You can put the copy anywhere you’d like and give it any name you’d like. It doesn’t need to be part of the MESA directory; you’ll provide a pathname to MESA as part of the setup. Look at the work/README file for instructions. You might decide to have separate work directories for various projects—that’s a convenient way to organize things if like most of us you’re doing several things at once.
1. setting up the parameters for a run—the ‘inlist’ file
The inlist file contains two “namelists”. A namelist is the fortran95 way of setting up a parameter file. Each definition in a namelist is of the form
name = value ! comment
Each name must be declared as a control in the program, but you don’t need to include all of the controls in the list, and the order of the list doesn’t matter. 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 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. If you don’t want to change a control, but you do want to keep in the list, simply comment out the line using a leading ’!’ in standard f95 notation.
Fortran supports structured values in namelists (arrays and derived types), but for simplicity, we only use scalar types (integers, doubles, logicals, and strings). Values are given using the usual fortran syntax.
the ‘star_job’ namelist
The first of the namelists in the inlist file contains control parameters for the run_star program, and the second has controls for the MESA/STAR routines.
For a complete list of the available star_job parameters with default values, look through mesa/star/test/src/run_star_defaults.dek.
The run_star parameters are in the namelist that begins with the line:
&star_jobNote: the information here is for illustration only—for the “truth”, see
mesa/star/test/src/run_star_defaults.dek.
job: The ‘job’ parameter should be set to 1, meaning that you are doing a standard stellar evolution run. The other values are for various special tasks such as the Roche lobe overflow experiment mentioned below.
save_model_number and save_model_filename: If ‘save_model_number’ is nonzero, then when the evolution model number is equal to the value of save_model_number, information about the current state of the run is written to the file named by the string value of save_model_filename. The data is written in text form and can be saved for use with future versions of MESA. You can use the saved model as a starting model for a new run by using load_saved_model.
load_saved_model and saved_model_name: If ‘load_saved_model’ is true, then the run begins by reading the information in the file named by the string value of ‘saved_model_name’. The default value of ‘load_saved_model’ is false, meaning that the initial model will be created in some other manner, with the starting mass and metallicity determined by parameters in the ‘controls’ namelist described below.
If ‘load_saved_model’ is false, the default behavior of the code is to create a ZAMS starting model by interpolating in mass and metallicity from a fairly large set of pre-built models. You can find these models in the star/starting_models directory. However, there may be times when you’d like to have a pre-main-sequence model or take a short-cut to some more advanced stage of evolution. The following flags provide several such options.
create_pre_main_sequence_model and pre_ms_t_c: If ‘create_pre_main_sequence_model’ is true, then run_star will ask MESA/STAR to create a pre-main sequence starting model with the given initial center temperature. If ‘pre_ms_T_c’ is unspecified, the default value of 0 will cause the system to pick an appropriate starting center temperature. The luminosity of the model will come from gravitational contraction at a uniform rate per gram choosen by the system to make the core of the pre-main sequence star convective.
After the initial model has been loaded, you can make various changes to it before starting the evolution. Here are some of the more common things you might want to do.
change_net and new_net_num: If ‘change_net’ is true, then the nuclear burning network for the model will be changed to the net specified by ‘new_net_num’. The inlist file contains several options for nets; for more details, see MESA/net.
change_y and new_y: changes only the abundances of hydrogen and helium to give the requested helium abundance while leaving metallicity unchanged.
change_z and new_z: changes the abundances of metals while keeping the relative ratios of hydrogen and helium the same at each point.
set_v_flag and new_v_flag: These controls let you determine whether or not a velocity variable is included in the evolution. If v_flag is false, the code does the usual quasi-hydrostatic evolution. If v_flag is true, each point gets a velocity variable and the momentum equation gets an added term for acceleration giving hydrodynamic evolution. If the ‘set_v_flag’ control is true, then v_flag is set to the value of the ‘new_v_flag’ parameter.
the ‘controls’ namelist
The second namelist in the inlist file is for MESA/STAR and the modules that it calls. There are lots of parameters! But to get started, you only need a few of them.
The controls are divided into the following sections:starting specifications
controls for output
when to stop
output of photos, logs, and profiles
mixing parameters
atmosphere
mass gain or loss
mesh adjustment
nuclear reactions
burn and mix
element diffusion
opacity
hydro equations
timesteps
controls for the evolve routine
Here are a few details to give you the idea. Note: the information here is for illustration only—for the “truth”, see
mesa/star/public/star_defaults.dek.
initial_mass: in Msun units. If you’re running with create_pre_main_sequence set true, then you can try anything you’d like for initial_mass; it might work or it might not. Try it and see. If your’re running with that flag set false, then the system will try to create a ZAMS model from pre-built models. The lowest mass for prebuilt models is currently 0.085 Msun, but you can probably get away with somewhat smaller values for initial_mass. At the high mass end, the current upper limit is around 25 Msun or so. If you request a ZAMS initial_mass that’s larger than the system thinks it can deal with, it will give you an error message and stop. If you want to do a mass that the system rejects because of limits in it’s pre-built ZAMS models, you can always set the create_pre_main_sequence flag true and try to create a starting model that way.
initial_z: any value from 0.0 to 0.4 should work. You are not limited to the values in the ‘starting_models’ directory of pre-built models. The code will interpolate for other Z values; you can even set initial_z to 0 to check that interesting case.
You may also want to change the default settings for how often output is produced.
log_cnt: The code will output log information when mod(model_number, log_cnt) = 0. Each log entry is a summary of state of the model that can be used to track the history of the evolution.
profile_interval: ‘profiles’ are text format records of structure of a particular model. The code will save the model profile info if this many models have elapsed since the last profile. Profiles are automatically saved at “key” events such as helium break-even. When a profile is saved, the terminal output will include a line such as ‘save profile for model number: 1105’.
max_num_profile_models: This limits the number of profiles that will be kept for a run. I added this control after one of my over-night runs filled my disc with profiles!
log_directory: This is where the logs and profiles are written. There is more information about the contents of this directory in a later section of this guide.
2. changing parameters during a run—stopping and restarting
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. For use with debugging, 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. Even then, saving the information is a nontrivial overhead, so you want to control how often it happens.
Also, it should be emphasized that the photos are not intended for long-term storage of models—the ‘save_model_number’ scheme described above is meant for that purpose. Instead the photos are intended for use during one specific run. In particular, when you update to a new version of MESA/STAR, you should expect your existing photo files to become obsolete. If you have a lengthy run in progress when you want to update MESA, then you should do ‘save_model_number’ to save state before starting the update, and then do ‘load_saved_model’ to resume the evolution after you have done the update.
photostep and photo_directory: The value of ‘photostep’ determines how often the restart files are written, and the value of ‘photo_directory’ determines where they are written. If photostep is greater than 0 and mod(model_number, photostep)==0, a restart photo is saved. To prevent overflowing the disc with a huge number of photos, the code uses only the last 3 digits of the model number in creating a file name—except when the last 3 digits are ‘000’, in which case the entire model number is used for the file name. So, for example, if photostep is 10, then model 1040 will be saved as ‘x040’ while model 1000 will be saved as ‘1000’. The terminal output includes lines such as ‘save photos/x040’.
When the system starts up, it looks for a file called ‘restart_photo’ in the current directory. If it finds that file, it assumes that it is a restart snapshot and reads the binary data to prepare for restarting the evolution run. There are scripts called ‘rn’ and ‘re’ in the star/test directory that make this scheme easy to use. The ‘rn’ script is used to start a run. It deletes any restart_photo file before starting the evolution program. The ‘re’ script is used to do a restart. It takes a command line argument that is the name of a snapshot file in the test/photos directory and copies that file to ‘restart_photo’ before starting the evolution program.
Most controls can be changed during a run using this scheme. For example, you can use ‘change_net’, ‘change_Y’, ‘change_Z’, ‘set_v_flag’, or ‘relax_mass’ from the star_job namelist. We’ve covered the others above—here’s what relax_mass does.
relax_mass and new_mass: perhaps you’d like to simulate an extreme mass loss event such as a common envelope phase on the RGB. Stop the run when you have a restart photo for the time when you’d like to remove the mass. Set ‘relax_mass’ to true, and set ‘new_mass’ to the desired new star mass in Msun units. The system cannot adjust to a large change in mass all at once; it needs to do lots of little mass losses spread over many timesteps. This is done “on the side” as a separate evolution run that is not recorded in the log files. When the requested new mass is reached, the normal evolution run resumes.
Note that like many things in stellar evolution, sometimes this process works and sometimes it doesn’t. If it fails, you might be doing too much too fast; try a smaller mass change and see if that works. You should also make sure that you aren’t trying to remove mass down into a burning region. For example, if you want to remove most of an envelope that is on top of a burning shell, you’ll need to do it in stages. Remove mass down to a location that is well above the burning; for example, down to logT = 6 or so should work. Then let that model run for several steps such that the temperature gradient can adjust and the burning region can retreat to a deeper level in the remaining envelope. Then repeat the process, again only removing mass down to the new, deeper, burning region.
Of course you can also change things in the controls namelist. For instance, you might want to change the frequency of saving profiles or restart photos. Or you might change the maximum timestep or turn accretion or winds on or off. At any point in a run, you can even switch the nuclear reaction net along with the set of isotopes or add/remove velocity variables at each point. Basically, any parameter or operation that is available at the start of a run can be used during a run as well. Give it a try!
3. reading the the standard logs and profiles
Recall that logs and profiles are written to the directory named by the value of the LOG_DIRECTORY parameter. The default for this is ‘LOGS’, so unless you change things, that’s where you’ll find standard files.
The history for the run is saved, one line per logged model, in the file ‘star.log’. The frequency of log entries in star.log is set by the value of the LOG_CNT parameter described above. The first line of star.log has column numbers, the second line has column names, and the following lines have the corresponding values. In case of a backup or a restart, lines are not removed from the star.log; instead new values are simply appended to the end of the file. As a result the model_numbers are not guaranteed to be monotonically increasing in the log. The code that uses the log must bear the burden of removing lines that have been made obsolete by subsequent restarts or backups. This can most easily be done by storing the data into arrays as it is read using the model_number as the array index. That way you’ll automatically discard obsolete values by overwriting them with the newer ones that appear later in the log file.
The set of data written to the log is determined by a control file that is read at startup. The file is specified by the log_columns_file entry in your inlist. The default version of this file lives in mesa/data/star_data/log_columns.list—it describes the full list of the available options.
While star.log holds the history of the run, one line at a time, the profiles contain detailed information about a selected set of models, one model per file. The total number of retained profiles is set by the MAX_NUM_PROFILE_MODELS control parameter. Which model profiles are currently saved is listed in the profiles.index file. For each profile, there is a line in profiles.index giving the model number, its priority, and its log file number. Priority level 2 is for models saved because of some special event in the evolution such as the onset of helium burning. Priority level 1 is for models saved because the number of models since the most recent profile has reached the currently setting of the PROFILE_INTERVAL parameter. The log file number is an integer from 1 to MAX_NUM_PROFILE_MODELS. The name of the profile log file is determined by the log number. For example, if the log file number is 15, the profile data will be found in the file named ‘log15.data’.
Each profile includes both a set of global properties of the star, such as its age, and a large set of properties for each point in the model of the star given one line per point. In each case, the lines of data are preceeded by a line with column numbers and a line with column names.
The set of data written to the profile is determined by a control file that is read at startup. The file is specified by the profile_columns_file entry in your inlist. The default version of this file lives in mesa/data/star_data/profile_columns.list—it describes the available options.
4. using Tioga to create MESA/STAR plots
Since I make lots of plots for stellar evolution, I’ve spent a significant amount of time and effort on creating plotting scripts. As you may know, I’ve even created a new plotting program called Tioga because I wasn’t satisfied with the available alternatives. More information can be found at my tioga webpage including a tutorial. Here’s a paragraph describing the system:
Tioga is for creating figures and plots with high quality text and graphics in PDF format. Text is processed directly by TeX (not an emulation), and the graphics covers a broad range of PDF features including images, curves, clipping, and transparency.
In MESA/STAR/test you’ll find directories called ‘star_history’ and ‘star_profile’ that contain the Tioga plotting scripts that I’ve written for use with the star logs and profiles. There are separate top-level scripts in each directory. For example, in star_profile there are scripts to show the profile plots by grid point, by mass, by logP, by radius, or by log(xm). Similarly, in star_history there are scripts to show the log history plots by model number, by age, or by log(years before present). The scripts that actually do the work of creating plots can be found in the ‘lib’ directories in star_history and star_profile.
If you are happy with your current non-Tioga plotting tools, by all means keep using them. But if you’d like to try using Tioga for your stellar evolution plots, you’re welcome to give my scripts a try.
5. adding your own code
Before discussing the details of how to add code, let’s briefly discuss the API for MESA/STAR. The procedural interface is found in the file star/public/star_lib.f. The run_star module calls routines defined here, so you can use it as an example of how it goes. For many situations, you won’t actually need to call any of these routines; it will be enough to inspect the data and perhaps modify control parameters. The data for a star lives in a derived type called “star_info” that is defined in public/star_def.f. You refer to the star either using an integer “id” or a pointer to an instance of the star_info type, which is consistently named “s” in the code. There are 2 main sections to the star_info: the data defined in star_data.dek should be read-only for your code, while the controls defined in star_controls.dek can be modified at any time during a run. For example, if for some reason you want to limit the timestep after the luminosity reaches a certain value, you might do something like this:
if (s% log_luminosity > 3) &
s% max_timestep = 1d6*secyer ! limit dt to 1 Myr
So now that you have an idea of the API available, where should your new code go?
The easiest way to add things is to edit the routine in test/src/run_star.f that does the main evolution loop. I’ve put in several examples to show how this can be done, so open run_star.f and take a look. The function called ‘check_model’ is the place to find the additions. The check_model routine in run_star calls the ‘star_check_model’ routine in the MESA/STAR module. One of the things that star_check_model does is update the logs and profiles. So if you want to do something that will change what goes in those files, you need to do it before calling star_check_model. You’ll find an example of that at the start of check_model in run_star.
There is a control in star_controls.dek called ‘mass_loc_for_extra_log_info’, and logs contain entries for various values at the location in the star specified by this parameter (such as lgR_at_mass_loc, lgT_at_mass_loc, xh1_at_mass_loc, and others). The block of code at the beginning of check_model sets mass_loc_for_extra_log_info to the bottom of the innermost convective zone that is above the current h1 boundary. This is a specific instance of a general theme—you can add code to check_model to check the current state of the model and change control parameters accordingly. In this case, the code finds the base of the convection zone and changes the mass_loc_for_extra_log_info parameter. In some other situation, you might want to check the luminosity and change the rate of mass loss using your own verion of a formula such as Reimers’ or Blocker’s winds. You can’t change the model data, but you can look at it and change the controls.
The check_model routine also has the option of terminating the run. You’ll find an example in the block of code with the comment “stop when star hydrogen mass drops to specified level”.
Another common task to do in check_model is to save extra log information. There’s an example of that in the block with the comment “save color magnitude info”.
Of course you aren’t limited to making changes in check_model as the only way of adding your own special purpose code. There’s an example of a completely separate application in the rlo_exp.f file in the test/src directory. The ‘do_rlo_exp’ routine in rlo_exp.f is called from the main program in run.f when the inlist job parameter is set to 5. You might want to try running it to see what it does. If you look at the code, you’ll find that it has it’s own controls file called ‘inlist_rlo’ that it reads to get starting parameters (mprimary, msecondary, and initial_period_in_days). It also makes use of the extra_work and extra_iwork arrays to save and restore data so it can work with restarts.
Just for fun, and to show what you can do with the MESA/STAR API, here are some plots from a
recent run of the rlo_exp code (you can run it by changing the job pararmeter in the inlist file). The run simulates
a 1 Msun star with an 0.8 Msun companion in a binary that initially has a 12 hour orbital period.
As the 1 Msun star ascends the RGB, it fills its Roche lobe and starts dumping mass onto the companion.
Here’s a plot of the mass of the donor over time. Note the “period gap” at around 8.5 Gyr where
mass loss temporarily stops, and also note that the mass has been reduced all the way down to 0.01 Msun at the end (pdf).
The mass transfer changes the properties of the binary, and in particular the orbital period goes through a minimum as shown here—the y axis is log10(binary period in seconds); the minimum is about 1 hour (pdf).
svn updates
If you decide to add your own code, remember that you’ll need to patch things whenever you update the MESA sources. If you’ve edited run_star.f, svn update will let you know by a line like the following:
C star/test/src/run_star.f
The ‘C’ means that there’s a conflict between your copy of run_star.f and the version in the MESA distribution. If you then look at your star/test/src directory, you’ll find 3 verions of run_star: run_star.f, run_star.f.mine, and run_star.f.rxxx, where ‘xxx’ is the revision number of the update. As you might guess, run_star.f.mine is your copy, and run_star.f.rxxx is the MESA version. In the file run_star.f you’ll find the conflicts marked with lines such as ”<<<<<<< .mine” and ”>>>>>>> .rxxx”. If you forget to fix things, the compiler will choke on these extra lines to remind you. If you are making major changes, you might want to put them in a separate file and just modify run_star by adding a call to your routine.
working directories
You may have noticed the little stub module in the file run_star_extras.f; the check_model_extras function that you find there doesn’t do anything in the default version of the file. It is called from the check_model routine in run_star, but immediately returns. In your working directory, you’ll also find a copy of run_star_extras.f, and it is this copy that is compiled and loaded to create your working version of star. So the recommended way to add code is to do things in your working version of check_model_extras. That way you can easily have different code extensions for different projects and maintain a clean separation between the standard run_star code in star/test and your extra additions.
website design by
Andreas Viklund