Begin The Great Documention

astero/defaults/astero_pgstar.defaults

@@ -36,9 +36,11 @@
          echelle_file_dir = 'png'
          echelle_file_prefix = 'echelle'
          echelle_best_model_file_prefix = ''
+
 !          ! if non-empty save best chi^2 model file
 !          ! e.g. 'best_model_echelle'
 !          ! note: this is enabled even if echelle_file_flag = .false.
+
          echelle_file_interval = 5 ! output when mod(model_number,echelle_file_interval)==0
          echelle_file_width = -1 ! negative means use same value as for window
          echelle_file_aspect_ratio = -1 ! negative means use same value as for window
@@ -72,9 +74,11 @@
          ratios_file_dir = 'png'
          ratios_file_prefix = 'ratios'
          ratios_best_model_file_prefix = ''
+
 !          ! if non-empty save best chi^2 model file
 !          ! e.g., 'best_model_ratios'
 !          ! note: this is enabled even if ratios_file_flag = .false.
+
          ratios_file_interval = 5 ! output when mod(model_number,ratios_file_interval)==0
          ratios_file_width = -1 ! negative means use same value as for window
          ratios_file_aspect_ratio = -1 ! negative means use same value as for window

docs/source/developing/test_suite.rst

@@ -224,7 +224,7 @@ When a test is run through ``each_test_run``, a file ``testhub.yml``
 will be produced.  This is the information that will be reported to
 the TestHub by ``mesa_test``.  The file will look similar to this:
 
-.. code-block:: none
+.. code-block:: yaml
 
     ---
     test_case: make_co_wd
@@ -346,7 +346,7 @@ For example, in ``c13_pocket``, the ``run_star_extras`` sets::
 
 which results in the additional output
 
-.. code-block:: none
+.. code-block:: yaml
 
     - inlist: inlist_c13_pocket_header
       ...

docs/source/index.rst

@@ -11,7 +11,10 @@ MESA is written primarily in Fortran with a modular, flexible design that facili
 
 🚀 New to MESA? Start with the :ref:`Quickstart<quickstart:Quickstart>` guide to set up and run your first models.
 
-📖 Experienced users may find the :ref:`Reference and Defaults<reference:Reference and Defaults>` page most valuable for exploring the code’s features and input parameters. The :ref:`Test Suite<test_suite:Test Suite>` provides example problems for testing and showcasing MESA, serving as a project starting point but often requiring modifications for science-grade accuracy.
+📖 Experienced users may find the :ref:`Reference and Defaults<reference:Reference and Defaults>`
+   page most useful for exploring the code’s features and input parameters.
+   The :ref:`Test Suite<test_suite:Test Suite>` provides example problems for testing and showcasing MESA,
+   serving as a project starting point but often requiring modifications for science-grade accuracy.
 
 Check out the full documentation below.
 
@@ -34,4 +37,3 @@ Check out the full documentation below.
    faq
    known_bugs
    news
-

docs/source/installation.rst

@@ -48,7 +48,7 @@ system. There's a template to get you started at
 :file:`$MESA_DIR/utils/makefile_header_non_mesasdk`.
 
 Regardless of whether you use the MESA SDK or ifort, and whether your
-machine runs MacOS or linux, the output of MESA should be bit-for-bit
+machine runs MacOS or Linux, the output of MESA should be bit-for-bit
 identical.  If it's not, this is considered to be a bug. (This has
 been the case since Release 5819 in early January 2014.)
 
@@ -98,11 +98,11 @@ startup file in an existing one).
 Here is an example from a machine that uses bash as its shell (and hence
 uses export to set variables):
 
-.. code-block:: bash
+.. code-block:: shell
 
     # set MESA_DIR to be the directory to which you downloaded MESA
     # The directory shown is only an example and must be modified for your particular system.
-    export MESA_DIR=/Users/jschwab/Software/mesa-r21.12.1
+    export MESA_DIR=/Users/my_username/Software/mesa-r24.08.1
 
     # set OMP_NUM_THREADS to be the number of cores on your machine
     export OMP_NUM_THREADS=2
@@ -115,9 +115,13 @@ uses export to set variables):
     # add shmesa (the MESA command line tool) to your PATH
     export PATH=$PATH:$MESA_DIR/scripts/shmesa
 
-Note (Jan 2025): due to some changes in MacOS 15.2/15.3, if you see the error `ld: library 'z' not found` on a Mac, and you are using MESA SDK version <= 24.10.1, you may also need to add:
+Note (Jan 2025): due to some changes in MacOS 15.2/15.3,
+if you see the error
+`ld: library 'z' not found`
+on a Mac you may also need to add:
 
-.. code-block:: bash
+
+.. code-block:: shell
 
     export SDKROOT=$(xcrun --sdk macosx --show-sdk-path)
 

docs/source/summer_schools.rst

@@ -39,11 +39,11 @@ We aim for 50-50 gender representation (50% men, 50% women and gender minorities
 
 - reserve accommodation. Hotel room blocks can be booked for discounted rates. Some universities are willing to provide discounted bulk accommodation through their own facilities (e.g. dorms), as was the case at Santa Barbara.
 
-- open the application for students. A template for this is available from Meridith Joyce, Earl Bellinger, or Eoin Farrell (MESAdev). A Google form is a good way to provide the application. Be aware that summer schools have been oversubscribed by more than a factor of 2 in recent years, and be prepared to rank applications in a systematic way. We aim for 50-50 gender representation among students and have a track record of achieving 35%-45% participation from women and gender minorities, on average.
+- open the application for students. A template for this is available from Meridith Joyce, Earl Bellinger, or Eoin Farrell (MESA-dev). A Google form is a good way to provide the application. Be aware that summer schools have been oversubscribed by more than a factor of 2 in recent years, and be prepared to rank applications in a systematic way. We aim for 50-50 gender representation among students and have a track record of achieving 35%-45% participation from women and gender minorities, on average.
 
 6 months out (February)
 -----------------------
-- post the Summer School website. Bill Wolf (MESAev) has been the web manager for many Summer Schools
+- post the Summer School website. Bill Wolf (MESA-dev) has been the web manager for many Summer Schools
 
 - assign TAs to lecturers. We recommend assigning one first-time TA, one returning TA, and one very experienced TA per lecturer. This ensures that new TAs receive excellent training while the more experienced TAs can provide leadership on the development of exercises and management of the group. Please be aware that it has not been a requirement  historically that the lecturers have any experience with MESA. It is the lecturers' jobs to develop the scientific program and contribute their subject expertise. It is the TAs jobs to turn the lecturers' science into accessible, MESA-based exercises.
 
@@ -52,7 +52,7 @@ We aim for 50-50 gender representation (50% men, 50% women and gender minorities
 --------------------
 - close applications
 
-- make selections among applications. An admissions rubric used for the 2022, 2023, and 2024 Summer School programs is available from Meridith Joyce (MESAdev)
+- make selections among applications. An admissions rubric used for the 2022, 2023, and 2024 Summer School programs is available from Meridith Joyce (MESA-dev)
 
 - email the supervisors of potential attendees to confirm that they have their advisor's permission and funding to attend. Be aware that some prospective students may apply without having secured funding and without their advisor's knowledge.
 

kap/defaults/kap.defaults

@@ -493,11 +493,12 @@
 ! -------------
 
     ! These are arrays of size(10) that can be used to pass in custom information to kap ::
+    ! ::
 
-    kap_ctrl(:) = 0d0
-    kap_integer_ctrl(:) = 0
-    kap_logical_ctrl(:) = .false.
-    kap_character_ctrl(:) = ''
+      kap_ctrl(:) = 0d0
+      kap_integer_ctrl(:) = 0
+      kap_logical_ctrl(:) = .false.
+      kap_character_ctrl(:) = ''
 
 
 ! Extra inlist controls
@@ -507,13 +508,13 @@
    ! It works recursively, so the extras can read extras too.
 
 
-         ! read_extra_kap_inlist(1..5)
-         ! ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-         ! extra_kap_inlist_name(1..5)
-         ! ~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   ! read_extra_kap_inlist(1..5)
+   ! ~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   ! extra_kap_inlist_name(1..5)
+   ! ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-         ! If ``read_extra_kap_inlist(i)`` is true, then read ``&eos`` from the file ``extra_kap_inlist_name(i)``.
-         ! ::
+   ! If ``read_extra_kap_inlist(i)`` is true, then read ``&eos`` from the file ``extra_kap_inlist_name(i)``.
+   ! ::
 
       read_extra_kap_inlist(:) = .false.
       extra_kap_inlist_name(:) = 'undefined'

star/defaults/controls.defaults

@@ -216,7 +216,7 @@
       ! log_directory
       ! ~~~~~~~~~~~~~
 
-      ! for data files about the run
+      ! directory for data files about the run
 
       ! ::
 
@@ -226,7 +226,7 @@
       ! do_history_file
       ! ~~~~~~~~~~~~~~~
 
-      ! history file is created if this is true
+      ! a history file is created if this is true
 
       ! ::
 
@@ -1105,7 +1105,7 @@
       ! ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
       ! stop when the center entropy is above/below the upper/lower limit.
-      ! in kerg per baryon
+      ! in kerg per baryon, where kerg = (erg K^-1)
 
       ! ::
 
@@ -1119,7 +1119,7 @@
       ! ~~~~~~~~~~~~~~~~~~~~~~~
 
       ! stop when the max entropy is above/below the upper/lower limit.
-      ! in kerg per baryon
+      ! in kerg per baryon, where kerg = (erg K^-1)
 
       ! ::
 
@@ -1173,7 +1173,7 @@
       ! Lower limits on surface mass fractions.
       ! Stop when surface abundance drops below this limit.
       ! Can have up to ``num_xa_surface_limits`` of these (see ``star_def`` for value)
-      ! ``xa_surface_lower_limit_species`` contains an isotope name as defined in ``chem_def.f``
+      ! ``xa_surface_lower_limit_species`` contains an isotope name as defined in ``chem_def.f90``
       ! ``xa_surface_lower_limit`` contains the lower limit value
 
       ! ::
@@ -1236,7 +1236,7 @@
       ! HB_limit
       ! ~~~~~~~~
 
-      ! For detecting horizontal branch.
+      ! For detecting when the model has completed the horizontal branch.
       ! Only applies when center abundance by mass of h1 is < 1d-4.
       ! Stop when the center abundance by mass of he4 drops below this limit.
 
@@ -1288,6 +1288,8 @@
       ! star_species_mass_max_limit_iso
       ! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+      ! Stop when a particular species mass in units of Msun exceeds these limits.
+
       ! ::
 
     star_species_mass_min_limit = 0
@@ -1962,6 +1964,9 @@
       ! ~~~~~~~~~~~~~~~~~~~~~~
 
       ! stop when Lnuc/L is greater than this limit.
+      ! Here, Lnuc refers to the total thermal power from all burning, including photodisintegrations,
+      ! ``power_nuc_burn`` in the history_columns.list file.
+      ! L is the luminosity at the photosphere.
 
       ! ::
 
@@ -1972,6 +1977,9 @@
       ! ~~~~~~~~~~~~~~~~~~~~~~
 
       ! stop when Lnuc/L is less than this limit.
+      ! Here, Lnuc refers to the total thermal power from all burning, including photodisintegrations,
+      ! ``power_nuc_burn`` in the history_columns.list file.
+      ! L is the luminosity at the photosphere.
 
       ! ::
 
@@ -2012,7 +2020,7 @@
       ! Pgas_div_P_limit
       ! ~~~~~~~~~~~~~~~~
 
-      ! criteria for stopping on Pgas/P
+      ! stop when Pgas/P <= Pgas_div_P_limit
 
       ! ::
 
@@ -2022,7 +2030,7 @@
       ! Pgas_div_P_limit_max_q
       ! ~~~~~~~~~~~~~~~~~~~~~~
 
-      ! stop if Pgas/P < this limit at any location with ``q <= Pgas_div_P_limit_max_q``
+      ! stop if Pgas/P < Pgas_div_P_limit at any location with ``q <= Pgas_div_P_limit_max_q``
       ! values near unity skip the outer envelope
 
       ! ::
@@ -4108,8 +4116,8 @@
 
     D_mix_rotation_min_tau_full_off = 0d0
 
-          ! D_mix_rotation_max_tau_full_on
-      ! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+      ! D_mix_rotation_max_tau_full_on
+      ! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
       ! Use rotational components of ``D_mix`` for locations where tau >= this.
       ! For numerical stability, turn off rotational part of ``D_mix`` at very low tau.
@@ -5632,6 +5640,7 @@
 
       ! Maximum number of grid points allowed.
       ! Array allowed to grow arbitrarily large if max_allowed_nz <= 0
+      ! If nz > max_allowed_nz, MESA will prematurely exit and call this error. 
 
       ! ::
 

star/defaults/profile_columns.list

@@ -472,11 +472,11 @@
    !sch_stable ! 1 if grada > gradr, 0 otherwise
    !ledoux_stable ! 1 if gradL > gradr, 0 otherwise
 
-   !grada_sub_gradT
+   !grada_sub_gradT ! grada-gradT at cell boundary
    !gradT_sub_grada ! gradT-grada at cell boundary 
    !gradT_div_grada ! gradT/grada at cell boundary 
 
-   !gradr_sub_gradT
+   !gradr_sub_gradT ! gradr-gradT at cell boundary
    !gradT_sub_gradr ! gradT-gradr at cell boundary 
    !gradT_div_gradr ! gradT/gradr at cell boundary 
 
@@ -489,28 +489,28 @@
    !gradr_div_grada ! gradr/grada_face; > 1 => Schwarzschild unstable for convection
    !gradr_sub_grada ! gradr - grada_face; > 0 => Schwarzschild unstable for convection
 
-   !gradL_sub_gradr
-   !gradP_div_rho
-   !gradT_excess_effect
-   !gradT_rel_err
-   !gradT_sub_a
-   !grada_face
-   !grada_sub_gradr
-   !diff_grads
-   !log_diff_grads
-
-   !mlt_D
-   !mlt_Gamma
-   !mlt_Y_face
-   !mlt_Zeta
-   !mlt_gradT
-   !mlt_log_abs_Y
-   !mlt_vc
-   !log_mlt_vc
-   !dvc_dt_TDC_div_g 
-
-   !superad_reduction_factor
-   !conv_vel_div_mlt_vc
+   !gradL_sub_gradr ! gradL-gradr at cell boundary
+   !gradP_div_rho ! finite difference (deltaP/deltam)* 4*pi*r^2, at cell boundary
+   !gradT_excess_effect ! 1 - alpha, where alpha is the gradT_excess_alpha from mlt++
+   !gradT_rel_err ! gradT - actual_gradT / gradT, actual_gradT = deltaT/deltaP from finite difference
+   !gradT_sub_a !  same as gradT_sub_grada ! gradT-grada at cell boundary 
+   !grada_face ! grada at cell boundary
+   !grada_sub_gradr ! grada-gradr at cell boundary 
+   !diff_grads ! gradr - gradL at cell boundary 
+   !log_diff_grads ! log10(diff_grads)
+
+   !mlt_D ! The chemical diffusion coefficient (cm^2/s)
+   !mlt_Gamma ! The convective efficiency parameter from the mlt equation, Gamma=(grad-gradE)/(gradE-gradL)
+   !mlt_Y_face ! The superadiabaticity Y = dlnT/dlnP - grada, or dlnT/dlnP - gradL at cell boundary
+   !mlt_Zeta ! convective efficiency as Zeta = (gradr-gradT)/(gradr-grada)
+   !mlt_gradT ! same as gradT, mlt/TDC value for dlnT/dlnP.
+   !mlt_log_abs_Y ! log10(abs(Y_face)) 
+   !mlt_vc    ! convective velocity from mlt/TDC in cm/s
+   !log_mlt_vc ! log10(mlt_vc)
+   !dvc_dt_TDC_div_g ! dimensionless ratio of convective velocity to g
+
+   !superad_reduction_factor ! gamma_factor from superad_reduction
+   !conv_vel_div_mlt_vc ! conv_vel from any convection model (including RSP) / mlt_vc, for comparison 
 
    !log_Lconv
    !log_Lconv_div_L

star/defaults/star_job.defaults

@@ -689,6 +689,8 @@
       ! set hydrogen and helium mass fractions according to the following:
       ! If no h2 in current net, then this will be added to h1.
       ! If no he3 in current net, then this will be added to he4.
+      ! When ``set_uniform_initial_composition = .false.``, defer to
+      ! composition controls in ``star/defaults/controls.defaults``.
 
       ! ::
 

star/defaults/star_job_dev.defaults

@@ -117,7 +117,8 @@
 
     save_photo_number = -1
     save_photo_filename = ''
-!   !save_photo_when_terminate = .true.
+
+!   ! save_photo_when_terminate = .true.
 
       ! create_merger_model !!! EXPERIMENTAL
       ! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~