Best practices

During the project

When you begin a new project you should generally use the most recent MESA release. Unless you encounter bugs that negatively impact your work, stick with that version throughout the project. If you’re starting from a set of input files that were designed for an older version, we suggest you invest some time porting it to the latest version, as if you run into any issues this will make it much easier for the community to assist you.

Before modifying any source code in the main MESA directory, check if these changes cannot be applied locally in your work folder using the hooks provided by MESA. If you have a use case that cannot be completed with the provided set of hooks, you can always contact us to request a new one.

The MESA test suite (star/test_suite and binary/test_suite) is a valuable source of examples and a good first stop when setting up a new problem with MESA. Looking at the test suite inlists is a quick way to familiarize yourself with the set of options relevant to your problem. More information is available on how to use a test suite case as a starting point for your own work directory.

You should always perform some sort of convergence study to ensure that your results are not sensitive to the time or mass resolution of your models. Please note, and this is very important, that MESA defaults will generally NOT be optimal or even acceptable for your particular science cases. It is the user’s responsibility to ensure that the MESA options and controls they choose are appropriate for the physics they want to study. This will usually require appropriate testing and critical analysis of the models obtained.

Throughout your project, the best way to solicit community help and input is via a message to the mesa-users@lists.mesastar.org mailing list.

An example

We will use the test suite case semiconvection. Begin in the directory where you do your MESA work.

cp -r $MESA_DIR/star/test_suite/semiconvection .

In old MESA revisions, there were hard-coded references in the test_suite to set the variable MESA_DIR = ../../../.. . This practice has been removed in current revisions. If you are running this tutorial with an old revision of MESA, comment out or delete that line in the makefile, the rn script, the ck script, and in inlist_semiconvection_header. If you are running with any MESA revision after r23.05.1, ignore this comment and read on.

Now clean the directory,

./clean

build the executable,

./mk

and run the executable

./rn

After a few minutes the run will terminate and you should see

stop because have dropped below central lower limit for h1
    0.3994694345E+00    0.4000000000E+00

        322   7.308040   6658.804   0.741142   0.741142   1.500000   1.500000   0.399469   0.007663   0.280000  -2.316624   1653      0
   6.698970   7.308040   0.246241 -37.781812  -0.571349 -99.000000   0.000000   0.580264   0.004769   0.020000   0.076565      5
 1.2920E+09   2.005522   0.740760  -5.854865 -41.276481  -7.412372   0.000000   0.000042   0.002098   0.020266  0.000E+00        max_dt
                               rel_E_err    1.0067953870393901D-12
                       log_rel_run_E_err      -10.0905601615909450

save LOGS/profile8.data for model 322
save photos/x322 for model 322
 saved to final.mod
termination code: xa_central_lower_limit

                 runtime (minutes), retries, steps        4.92         0       322


                              mixing type at 0.125 Msun    1.0000000000000000D+00    1.0000000000000000D+00    1.0000000000000000D+00
                              mixing type at 0.135 Msun    3.0000000000000000D+00    3.0000000000000000D+00    3.0000000000000000D+00
                              mixing type at 0.145 Msun    0.0000000000000000D+00    0.0000000000000000D+00    0.0000000000000000D+00
                                                   logT    7.2062697504202102D+00    7.1500000000000004D+00    7.3099999999999996D+00
                                                 logRho    1.7886843044807488D+00    1.7500000000000000D+00    1.8000000000000000D+00

all values are within tolerances

Let’s add some pgstar plots to visualize what is happening. There are three files to edit. First, copy the default history_columns.list to your work directory

cp $MESA_DIR/star/defaults/history_columns.list .

and modify your local history_columns.list

 add

     mixing_regions 20
     burning_regions 20

change

     !log_center_T ! temperature
     !log_center_Rho ! density

to

     log_center_T ! temperature
     log_center_Rho ! density

  and save the file changes.

Second, modify inlist_semiconvection_header

change

    !read_extra_pgstar_inlist(1) = .true.
    !extra_pgstar_inlist_name(1)= 'inlist_semiconvection'

to
    read_extra_pgstar_inlist(1) = .true.
    extra_pgstar_inlist_name(1)= 'inlist_semiconvection'

 and save the file changes.

Third, modify inlist_semiconvection to change the pgstar namelist to

add to the star_job namelist:

    pgstar_flag = .true.
    save_pgstar_files_when_terminate = .true.


and to make the stopping condition more precise, add to the controls namelist:

    when_to_stop_rtol = 1e-4
    when_to_stop_atol = 1e-4

and finally replace the pgstar namelist with

&pgstar

    pgstar_interval = 1

    Grid4_win_flag = .true.
    Grid4_win_width = 8
    Kipp_mass_max = 0.2 ! (Msun units) negative means use default
    Kipp_show_mixing = .true.
    Kipp_show_burn = .false.
    Kipp_show_luminosities = .true.
    Kipp_show_mass_boundaries = .false.

    Grid4_file_flag = .true.
    Grid4_file_dir = 'pgstar_out'
    Grid4_file_prefix = 'grid4_'
    Grid4_file_interval = 10
    Grid4_file_width = -1
    Grid4_file_aspect_ratio = -1

/ ! end of pgstar namelist

 and save the file changes.

Now run the executable egain

./rn

and you should see a pgstar window appear on your screen:

../_images/grid4_000322.svg



Explore Physics Variations

Make the following changes to your inlist_semiconvection:

change

  max_model_number = 1000

to

  max_model_number = 40000

and change

  history_interval = 10

to

  history_interval = 1

Experiment with the reaction network

Change the nuclear reaction network new_net_name = pp_and_cno_extras.net (this test suite case), basic.net (default), approx21.net, and mesa_49.net.

1) Are all the reported values still within their tolerances at the end of a run?
2) Are the results for the growth of the convective core mass, HR diagram, and final hydrogen profile the same?
3) Why are the results the same or different?

Note

For the 2021 MESA Summer School, each table should do all 4 reaction networks. Participants with the fastest machines should to the larger networks.

It is usually useful to examine history and profile quantities.

Change the default control namelist parameter log_directory = `LOGS` to the more descriptive log_directory = `TableNN_network_name` where NN is your table number and network_name is one of the choices above, for example, log_directory = `Table08_approx21`.

After the runs, each table should upload their log_directory to our shared Dropbox directory timmes/Experiment01.

The TAs will plot our crowd-sourced growth of the convective core mass, HR diagram, and final hydrogen profile.

When finished, return the chosen reaction network to the testcase value of pp_and_cno_extras.net.

Experiment with the convective mixing length

Change the mixing length of convection mixing_length_alpha = 1.0 to 3.0 in steps of 0.1, which will include 2.0 (default) and 1.8 (this test suite case). Repeat answering the questions above.

Note

For the 2021 MESA Summer School, each TA will be given a block of 4 values, one for each participant at their table. The TA will then distribute the values to the team.

Change the default control namelist parameter log_directory = `LOGS` to the more descriptive log_directory = `TableNN_NpN` where NN is your table number and NpN is your value, for example, log_directory = `Table03_1p8`.

After a run is complete, each participant should upload a log_directory to our shared Dropbox directory timmes/Experiment02.

The TAs will plot our crowd-sourced growth of the convective core mass, HR diagram, and final hydrogen profile.

When finished, return mixing_length_alpha to the test case value of 1.8.

Experiment with the semiconvective mixing length

Change the scale of semiconvection mixing alpha_semiconvection = 0.0 to 0.5 in steps of 0.02, which will include 0.0 (default) and 0.1 (this test suite case). Repeat answering the questions above.

Note

For the 2021 MESA Summer School, each TA will be given a block of 4 values, one for each participant at their table. The TA will then distribute the values to the team.

Change the default control namelist parameter log_directory = `LOGS` to the more descriptive log_directory = `TableNN_NpNN` where NN is your table number and NpNN is your value, for example, log_directory = `Table11_1p80`.

After a run is complete, each participant should upload a log_directory to our shared Dropbox directory timmes/Experiment03.

The TAs will plot our crowd-sourced growth of the convective core mass, HR diagram, and final hydrogen profile.

When finished, return alpha_semiconvection to the test case value of 0.1.

Explore Numerical Convergence

Experiment with the mass resolution I

Change the mass resolution setting max_dq = 5.0e-2, 2.0e-2, 1.0e-2 (default), 5.0e-3, 2.0e-3, and 1.0e-3. Repeat answering the questions above.

Note

For the 2021 MESA Summer School, each TA will be given a block of 4 values, one for each participant at their table. The TA will then distribute the values to the team.

Change the default control namelist parameter log_directory = `LOGS` to the more descriptive log_directory = `TableNN_NpNNN` where NN is your table number and NpNNN is your value, for example, log_directory = `Table05_0p002`.

After a run is complete, each participant should upload a log_directory to our shared Dropbox directory timmes/Experiment04.

The TAs will plot our crowd-sourced growth of the convective core mass, HR diagram, and final hydrogen profile.

When finished, return max_dq to its default value.

Experiment with the mass resolution II

Change the mass resolution setting mesh_delta_coeff = 0.2 to 2.0 in steps of 0.2, which will include the default value of 1.0. Repeat answering the questions above.

Note

For the 2021 MESA Summer School, each TA will be given a block of 4 values, one for each participant at their table. The TA will then distribute the values to the team.

Change the default control namelist parameter log_directory = `LOGS` to the more descriptive log_directory = `TableNN_NpNNN` where NN is your table number and NpN is your value, for example, log_directory = `Table08_1p2`.

After a run is complete, each participant should upload a log_directory to our shared Dropbox directory timmes/Experiment05.

The TAs will plot our crowd-sourced growth of the convective core mass, HR diagram, and final hydrogen profile.

When finished, return mesh_delta_coeff to its default value of 1.0.

Experiment with the temporal resolution

Change the temporal resolution setting max_years_for_timestep = 1.0e8, 5.0e7, 2.0e7, 1.0e7, 5.0e6, 2.0e6, and 1.0e6. Repeat answering the questions above.

Note

For the 2021 MESA Summer School, each TA will be given a block of 4 values, one for each participant at their table. The TA will then distribute the values to the team.

Change the default control namelist parameter log_directory = `LOGS` to the more descriptive log_directory = `TableNN_NeN` where NN is your table number and NeN is your value, for example, log_directory = `Table01_2e7`.

After a run is complete, each participant should upload a log_directory to our shared Dropbox directory timmes/Experiment06.

The TAs will plot our crowd-sourced growth of the convective core mass, HR diagram, and final hydrogen profile.

When finished, return max_years_for_timestep to its default value of 0.0.

Create An Article for Publication

Gather your science and write it up for publication.

Note

For the 2021 MESA Summer School, each table should team-craft a 250 word maximum Research Notes abstract, and then upload their abstract, named TableNN_abstract.txt where NN is your table number, for example, Table10_abstract.txt, to our shared Dropbox directory timmes/Abstracts.

In the article

You should provide a clear statement of which version of MESA was used in the calculation. We also recommend noting which version of the MESA SDK was used to compile MESA.

Citing MESA

You should cite all of the available MESA instrument papers at the time of the MESA version being used, as MESA is sum of this work. Currently, that is:

Modules for Experiments in Stellar Astrophysics
\citep[MESA][]{Paxton2011, Paxton2013, Paxton2015, Paxton2018, Paxton2019, Jermyn2023}.

MESA critically rests on the hard work of many researchers who have generated the input microphysics data that underpins the eos, kap, net, and neu modules. We therefore encourage users to briefly summarize these, including appropriate citations.

The MESA EOS is a blend of the OPAL \citep{Rogers2002}, SCVH
\citep{Saumon1995}, FreeEOS \citep{Irwin2004}, HELM \citep{Timmes2000},
PC \citep{Potekhin2010}, and Skye \citep{Jermyn2021} EOSes.

Radiative opacities are primarily from OPAL \citep{Iglesias1993,
Iglesias1996}, with low-temperature data from \citet{Ferguson2005}
and the high-temperature, Compton-scattering dominated regime by
\citet{Poutanen2017}.  Electron conduction opacities are from
\citet{Cassisi2007} and \citet{Blouin2020}.

Nuclear reaction rates are from JINA REACLIB \citep{Cyburt2010}, NACRE \citep{Angulo1999} and
additional tabulated weak reaction rates \citet{Fuller1985, Oda1994,
Langanke2000}.  Screening is included via the prescription of \citet{Chugunov2007}.
Thermal neutrino loss rates are from \citet{Itoh1996}.

Note that this only summarizes the “default” capabilities, of the currently released version of MESA. If you are making use of other microphysics options, employing prescriptions such as wind mass loss rates, or using older versions of MESA, please consult the documentation for appropriate references.

In the the MESA binary module, by default:

Roche lobe radii in binary systems are computed using the fit of
\citet{Eggleton1983}.  Mass transfer rates in Roche lobe
overflowing binary systems are determined following the
prescription of \citet{Ritter1988}.

A BibTex file with these references is available.

Citing included tools

If you are making use of an instrument that is provided in MESA (e.g., ADIPLS, GYRE, RSP, or STELLA), please make sure to include citations to the papers that describe it.

  • ADIPLS \citep{ChristensenDalsgaard2008}

  • GYRE \citep{Townsend2013, Townsend2018}

  • RSP \citep{Smolec2008}

  • STELLA \citep{Blinnikov2004, Baklanov2005, Blinnikov2006}

Citing the MESASDK

The MESASDK can be cited via its Zenodo link for MacOS and for Linux. Citations should also contain the version of the MESASDK used, individual Zenodo DOI’s are available for each MESASDK version.

A BibTex file with these references is available.

Citing MESA Zenodo community contributions

If you are making use of material that has been shared by the MESA Zenodo community, please make sure to include citations to the Zenodo repository that you leveraged and the science article(s) that describe the capability.

At the end of the project

You should make all information needed for others to recreate your MESA results publicly available. This includes your inlists and run_star_extras/run_binary_extras, the MESA version and the MESA SDK version (or compiler version for non-SDK builds), as well as any modifications to MESA that you may have made.

We recommend using Zenodo for this purpose. Zenodo assigns digital object identifiers (DOIs) for each entry, providing an immutable way to reference an upload in a publication. The service is also backed by the CERN data infrastructure, ensuring the safety of data and its long-term availability. As Zenodo allows uploads of up to 50GB, this gives the possibility to not only share the input files, but also your simulation data products.

Warning

Beware that once an entry is published in Zenodo it cannot be removed, but new versions can be included if amendments are needed. While setting up an upload in Zenodo, or testing the service, you can make use of the “sandbox” first. The “sandbox” allows you to see how a final entry would look before submitting the real thing to the main service.

We have created a Zenodo community with which you can associate your Zenodo uploads. You can find guidelines for what to include with your Zenodo upload under the MESA Community curation policy. The MESA Marketplace will remain in use as an aggregator portal, and we request users to inform us of new uploads so that they are highlighted there as well.