how to use MESA star
a basic guide to get you started


Contents
Appetizer
Introduction
1. Setting up the parameters for a run—the ‘inlist’ file
2. Changing parameters during a run—stopping and restarting
3. Saving a model for future use or to send to someone
4. Using the standard logs and profiles
5. The “test suite” as a source of examples
6. Adding your own columns to the standard logs and profiles
7. Using Tioga to create MESA star pdf plots
8. Using PGstar for on-screen plots and movies
9. Adding your own code to control MESA star
10. A few hints


If you haven’t already done it, please stop now and join the MESA-users mailing-list.
Once you’ve joined, post your questions to the list.
And once you’ve learned a bit, please do your share of replying to posts on the list.

BTW: MESA is written using advanced features of modern Fortran which make it very different from Fortran 77 codes you might have previously seen (or written!). If you are not already familiar with the new and wonderful things that have been added, there are good resources available on the web—here’s one: Fortran 95 language features.


Appetizer

You can consider this to be an optional “pre-introduction” to stimulate your appetite for MESA star. It is step-by-step instructions to give you hands-on experience for one simple case before reading the details that follow below.

Assuming that you have successfully installed MESA, connect to the directory ‘star/test’ and open the file ‘inlist_first_thing_to_try’. It has the parameters to control our example run. When star starts up, it reads the file ‘inlist’ to get its instructions. I typically just use the inlist file to redirect star to the file with the actual instructions for the particular case I’m doing. In our example, you’re putting the details in the file ‘inlist_first_thing_to_try’. To instruct star to use it, you need to edit the file ‘inlist’ in the directory where you’ll be running star, i.e., you need to edit star/test/inlist. Here’s what ‘inlist’ should look like after you finish editing it:
&star_job
read_extra_star_job_inlist1=.true.
extra_star_job_inlist1_name=’inlist_first_thing_to_try’
/ ! end of star_job namelist

&controls
read_extra_controls_inlist1=.true.
extra_controls_inlist1_name=’inlist_first_thing_to_try’
/ ! end of controls namelist

&pgstar
read_extra_pgstar_inlist1=.true.
extra_pgstar_inlist1_name=’inlist_first_thing_to_try’
/ ! end of pgstar namelist

WARNING: If you cut-and-paste these lines from the webpage, you’ll probably need to fix the quotes. Fortran doesn’t like fancy quotes, so if the browser used anything other than the single or double quote you get on your keyboard, you’ll need to replace them.

After saving the newly edited inlist, do
./rn
This should run for about 60 steps before stopping with the following message:
stop because have dropped below central lower limit for h1

Go back to the editor look at inlist_first_thing_to_try. Search for ‘xa_central_lower_limit’. You’ll find that the limit is set to 0.5 which is why the run stopped. Edit the line to change the limit to 0.2 and then save the file.

We don’t need to start over from the beginning with the new limit on central h1; we can restart using a saved photo. If you scroll back in the terminal output from the run, you should find this:
save profile LOGS/log6.data 50
save photos/x050
So now we can restart using the photo x050.
./re x050

This resumes the run from model 50, but this time with a different limit because you’ve edited the inlist. The new limit will cause the run to stop when the central hydrogen drops below 0.2, which happens at about model 100 or so.

If you look in the LOGS directory you’ll find the files that were written during the run. Open the file star.log. It has a line for each step (including the steps that were redone by the restart). The log-.data files have information about particular models.

We are almost done, but before stopping, let’s save a model as a text file that can be used as a starting model at some later time. Edit inlist_first_thing_to_try and uncomment the line that says
save_model_number = 93
After saving the inlist, do
./re x090
Let it run until it gets to model 93 and reports that it has “saved to test.mod”. Then interrupt the run (CTRL-c works). Edit inlist_first_thing_to_try to recomment the “save_model_number” line and uncomment the line that says
load_saved_model = .true.
Save the edits and do
./rn

You should begin a new run that uses test.mod as its starting model.

Congratulations—you are now an experienced user of MESA star! But it would still be a good idea to keep on reading.


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


Create a work directory for your current project

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. In fact, I suggest you keep your working directories separate from your MESA directory. That will minimize the pain if someday you need to do a fresh checkout of MESA—or if you decide to keep an old version of MESA in addition to a new one.

Look at the work/README file for instructions about setting up your work directory. You might decide to have separate ones for various projects—that’s a convenient way to organize things if like most of us you’re doing several things at once.

Stop now and make a copy of the work directory. Edit the inlist_project to set the ‘mesa_data_dir’ parameter. Run the scripts to make and run:

./mk
./rn

You should get terminal output plus Xwindow plots. The run should automatically terminate and shouldn’t take more that a few minutes; if it is grinding for longer than that, do a CTRL-C to kill it and try to find out what went wrong—if you have trouble fixing it, send a plea for help to the mesa-users list (join first!).


1. setting up the parameters for a run—the ‘inlist’ file

The inlist file contains several “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/public/run_star_defaults.dek.

The run_star parameters are in the namelist that begins with the line:

&star_job
Note: the information here is for illustration only—for the “truth”, see
mesa/star/public/run_star_defaults.dek.

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 data/star_data/zams_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.

change_initial_z and new_z: like the change_z operation, but it is only done at the start of a run, not on restarts (i.e, it happens when you do ./rn, but not when you do ./re).

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
composition of accreted material
mesh adjustment
nuclear reactions
element diffusion
opacity
newton solver
timesteps
miscellaneous

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: There are pre-built zams models in the directory mesa/data/star_data/zams_models. There are files for various initial Z’s (NOTE: at present there is only Z=0.02, but we can add more if there is interest from users!) If you are loading a zams model, then initial_z must match one of the prebuilt values.

If you want a zams model for a value of initial_z that is not provided in the prebuilt models, you might try loading the closest available Z and then changing to the desired value as a separate operation. You can do that by using change_initial_z and new_z as described above. For example, if you want a zams model for initial_z of 0.01, but you can only find prebuilt zams for Z=0.02, then set initial_Z = 0.02 in the &controls section and set change_initial_z = .true. and new_z = 0.01 in the &star_job section.

You should check one or two cases to see if this method gives something close enough to what you’d get if you did the work of creating a pre zams model. There will inevitably be small differences, but hopefully they will be insignificant for your project. If however, you discover that change_initial_z isn’t giving good enough models for you, you’ll need to do the work of creating pre-main-sequence models for the desired Z and letting them evolve to zams. If you will be reusing those zams models many times, it will probably be worth creating a new set of zams prebuilt models to add to data/star_data/zams_models. That can be done by following the recipe in star/test_suite/create_zams. Please let me know if you want to do this, so I can help, and we can add the resulting file of zams models to the mesa distribution!

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. Saving a model for future use or to send to someone

We talked about photos as ways to restart a run. The photo file is a machine readable binary that is not designed for portablity 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 perhaps to send to someone for them to use with their mesa. One example of this is when you find some bug in mesa, and I want to see if I can reproduce it on my machine. I’ll ask you to save a model from just before the bug happens and send it to me in an email along with your inlist.

Say, for instance, you’ve hit a problem around model number 3087, and the last photo before that was saved to file photos/x050. Let’s save model 3051 for debugging.

Edit the &star_job section of your inlist to have

save_model_number = 3051
save_model_filename = 'test_3051.mod'

Then do

./re x050

It should write out model 3051 to the file you’ve specified. Take a look to see.

Then see if you can start up a run using the model you’ve just saved. Edit your inlist like this

!save_model_number = 3051
!save_model_filename = 'test_3051.mod'
load_saved_model = .true.
saved_model_name = 'test_3051.mod'

Then do

./rn

It should start up using your newly saved file. Check to see if it reproduces the problem you saw before. Typically it will, but it might not. Why? Because 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. So 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 I wanted to let you know so you wouldn’t be surprised by them.

Saved models are not just for debugging. They can be very useful in a variety of situations. For example, you might be investigating the effects of making small changes to mass and metallicity on main-sequence evolution. You could do this by creating a pre-main-sequence model for each set of parameters, but that might be a lot more work than necessary. You might instead be able to create a single pre-MS model, let it evolve until it is about to stop being fully convective, and then save that model for use as a starting model in the runs where you change the parameters. The controls change_initial_z and relax_initial_mass can be used to make the adjustments. The starting model is still fully convective, it isn’t yet doing nuclear burning, and it still has a ways to go to reach ZAMS, so the differences in your results should be tiny doing it this way compared to starting each time by creating a pre-MS model. And you’ll save a lot of time.


4. Using 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.


5. The “test suite” as a source of examples

You will find a wide range of sample cases in the MESA star “test_suite”. For example, “test_suite/high_mass” is set to run a 100 Msun star until the central hydrogen mass fraction has dropped to 0.5. It starts by creating a pre-main-sequence model of 100 Msun with Z=0.02, and then it “relaxes” Z down to 1e-5 before starting the evolution. When I checked last, it took under 200 steps to reach a central X of 0.5, and the run took a few minutes. To try it yourself,

cd star/test_suite/high_mass
./mk
./rn

You can do the same with any of the test_suite cases. And you might want to copy an inlist from the test suite to one of your working directories to use as a starting point for a project of your own. The README in test_suite has a list of the tests with a few words of explanation for each.


6. Adding your own columns to the standard logs and profiles

What do you do if your project requires keep logs of certain items that are not included in the options in the log_columns.list? Here’s a quick sketch:

open your work directory copy of src/run_star_extras.f

you should find this line: include ‘standard_run_star_extras.dek’

replace that line by the contents of the file standard_run_star_extras.dek
(it can be found in mesa/include).

for star.log columns:

edit how_many_extra_log_columns to return how many you want to add.
edit data_for_extra_log_columns to return the names and values.

similarly, for profile columns:

edit how_many_extra_profile_columns to return how many you want to add.
edit data_for_extra_profile_columns to return the names and values.

Now do ./mk in your work directory to compile your changes. Do a test run to check that the new columns are working.


7. using Tioga to create MESA star pdf 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.

PLEASE NOTE THAT TIOGA IS NOT SUPPORTED AS PART OF MESA. IF IT WORKS FOR YOU, THAT’S GREAT. IF NOT, GO BACK TO USING SM OR IDL. Well, actually, before you do anything that extreme, you might send an email to tioga-users to see if someone will help you.

PLEASE NOTE (PART 2): I’VE HACKED THESE SCRIPTS TOGETHER FOR MY OWN USE. THEY ARE UGLY (EVEN TO ME) AND FLAKY (FOR MY OWN USE, THEY ARE GOOD ENOUGH). So if you can get any value out of them, good for you. But understand that I’m not supporting them or providing tutorials for them.


8. Using PGstar for on-screen plots and movies

Watching lots of numbers fly by in the terminal window can provide some idea of how a run is going, but it is much better (and much more fun) to have windows with plots that change at each step. To make this possible with current technology, we need to give up the elegance of Tioga’s TeX and PDF model in order to get low-overhead and speed on both linux and Mac platforms. Consequently, PGstar is built on PGPLOT for creating plots using XWindows for on-screen plots and PNG for frames of movies to animate those plots.

In order to use PGstar, you need to have installed PGPLOT, XWindows, and a few libraries that they need. See the makefile_header in mesa/utils for details. You’ll also find pgplot.tar.bz2 in mesa/utils in case you need to install PGPLOT (thanks to Tim Pearson of CalTech for creating PGPLOT and giving us permission to distribute it with MESA).

The controls for PGstar are in another namefile that goes in your inlists. The full set of options are given in the file pgstar_defaults.dek in star/public.

Here’s an example of the “summary” window during a run for a 1Msun star. The panels on the left show the history at the surface (log L vs. log Teff) and the center (log Central Temperature vs. log Central Density). On the right are panels show profiles of temperature, density, nuclear burning, element abundances, energy transfer gradients, and entropy. At the bottom right there is a list of numeric values showing the current situation. All of this is updated on the screen at each step of the mesa/star run. It is a wonderful way to see what is going on. I highly recommend using it!

The “Temperature Density Profile” gives a good overview of the internal state of the star including convection and burning.

Here are samples of some of the other kinds of plots in PGstar. You can select the xaxis by editing the inlist—choices are mass, grid, radius, logR, logP, and log of exterior mass. The following plots use logP for x.

For the ‘profile’ plot, you can select the axes from a wide set of options (the same set as available for profile logs). The following example shows log opacity and adiabatic gradient as functions of logP.

To make movies, instruct PGstar to save “png” files during the run. Then later construct a movie from the png files using one of the programs that do that sort of thing. For example, Ehsan Moravveji recommends this free package on the mac: macscripter.

Here’s an email from Raphael Hirschi about making movies out of png/jpegs figures


9. Adding your own code to control MESA star

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 routines in your private working directory copy of run_star_extras.f (in work/src). The default version of run_star_extras simply includes the file star/public/standard_run_star_extras.dek (btw: ‘dek’ is ancient for ‘deck’ as in ‘card deck’—ask some old person what that means). Replace the “include” line in your run_star_extras by the code from the standard_run_star_extras so you can edit your copy. The routines in run_star_extras are called from the ‘do_run_star’ routine in star/test/src/run_star.f. From those routines, you have access to the star data structures and the star_lib routines. Your code can check the state of the model at the end of each step and change controls or save files or whatever else it want to do before the start of the new step.

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.


10. A few hints

It is an unfortunate truth that you often have to tune the inlist control parameters to fit the particular task you are attempting. How much time and effort that will require can vary from none when you are using a proven recipe from “off the shelf”, to painfully long if you are being a pioneer and trying something that hasn’t been done before.

Here are a few hints based on my experience.

Sometimes a failure to converge is simply caused by “grid starvation”. Try giving the code more points to work with by decreasing the value of “mesh_delta_coeff” and restarting from a step before the convergence problems started.

Use all the visualization tools you have available to get an idea of what’s going on. PGstar is a good start, but I also look at details using the Tioga scripts that are included with the release.

Post a message to mesa-users describing the problem. Perhaps someone else can give you some useful information—or at least some sympathy.

If you can’t find a recipe that works for your problem, try a different problem.

Okay—enough doom and gloom. Sometimes things work great, and you’d like to see if you can make them even better by improving the speed. You will of course need to check that the important results aren’t impacted. Here are a few things to try if you are feeling adventurous:

reduce mesh size by increasing the value of mesh_delta_coeff

allow convergence with a single iteration by setting newton_itermin = 1

don’t remesh at every step—try setting remesh_cnt = 2 or more

try doing the opposite of everything I just suggested

Finally, remember what Peter Eggleton told me when I was first getting started and asked him why something I was trying failed to converge. Peter patiently explained that with stellar evolution the only surprise is when the code does converge! And of course he’s right. Each step requires a root find for a highly non-linear relation involving anywhere from a few thousand to several 100’s of thousands of variables. It makes me tired just to think about it.

Let me close by emphasizing the importance of visualization. I strongly recommend using PGstar or something like it to make on-screen plots as the run progresses. And remember that it takes time to learn how to “play” the code—you’ll get better at it with experience.


web traffic stats SourceForge.net Logo Generated by webgen website design by
Andreas Viklund