[Mesa-users] New public release r12778
Josiah Schwab
jwschwab at ucsc.edu
Thu Mar 5 18:07:19 EST 2020
Hi All,
I'm pleased to announce the release of MESA r12778.
This release includes a number of backwards-incompatible changes,
including items related to the EOS, overshooting, and run_star_extras.
Please read the appended release notes carefully if you upgrade.
When upgrading, users must upgrade to the recently released 20.3.1 SDK.
The website will be updated shortly.
Josiah (on behalf of the MESA developers)
Changes since r12115
====================
SDK changes (Version 20.3.1 or later required)
----------------------------------------------
To use the this MESA release, you must upgrade your SDK to 20.3.1.
In previous releases of MESA, we have included the CR-LIBM library
(https://hal-ens-lyon.archives-ouvertes.fr/ensl-01529804/file/crlibm.pdf)
to provide versions of standard math functions (exp, log, sin, etc)
that guarantee correct rounding of floating-point numbers. In this new
release, we made the decision to move CR-LIBM into the software
development kit (SDK), where it properly belongs and can be maintained
as one of the pre-requisites of MESA.
This means that to use this release (and subsequent releases) of MESA,
you'll need to upgrade to version 20.3.1 of the SDK or later. MESA
checks the SDK version during compilation, and will stop with an error
message if the SDK is too old.
Backwards-incompatible changes
------------------------------
Replacement of crlibm_lib with math_lib
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MESA now talks to CR-LIBM via an intermediate module called
``math_lib``. To make sure any code you add can properly access the
CR-LIBM math routines, you'll need to make sure that a ``use
math_lib`` statement appears in the preamble of the file. At the same
time, you should remove any ``use crlibm_lib`` statements, as they will no
longer work (and are not needed). With ``math_lib``, the names of the
correctly rounded math functions are the same as the Fortran
intrinsics (i.e., they no longer have a ``_cr`` suffix).
Existing ``run_star_extras``, ``run_binary_extras``, or other
user-written code will need to be updated. To migrate, you should
replace ``use crlibm_lib`` with ``use math_lib`` and remove the ``_cr``
suffix from any math functions (e.g., ``exp_cr`` -> ``exp``).
Removal of DT2 and ELM EOS options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ELM and DT2 EOS options have been removed. (These options were
underpinned by HELM and OPAL/SCVH data, but used bicubic spline
interpolation in tables of lnPgas, lnS, and lnE as a way to get
numerically accurate 1st and 2nd partial derivatives with respect to
lnRho and lnT. A more detailed description can be found in previous
release notes and Appendix A.1 of MESA V.) These options were
introduced in r10398 and were turned on by default in r11532.
The numerical issues that ELM/DT2 were designed to address have been
dealt with via another approach. MESA now separately treats quantities
that appear in the equations (and happen to be partials) and the places
where these theoretically equivalent, but numerically different
quantities appear in the Jacobian (as partials of other quantities that
appear in the equations). This is an implementation detail that should
be transparent to users.
This change has two pleasant side effects. One, it lowers the memory
demands of many MESA models, which should aid users of virtualized,
containerized, or otherwise memory-constrained systems. Two, it
removes small, interpolation-related wiggles that were present in
partial derivative quantities such as \Gamma_1`.
These changes may require inlists that made use of DT2/ELM related
options to be updated.
The following ``controls`` options have been deleted:
* ``use_eosDT2``
* ``max_logT_for_max_logQ_eosDT2``
* ``max_logQ_for_use_eosDT2``
* ``use_eosELM``
* ``logT_max_for_ELM``
* ``logQ_min_for_ELM``
* ``check_elm_abar_zbar``
* ``check_elm_helm_agreement``
The following ``star_job`` options have been renamed:
* ``eosDT2PTEH_use_linear_interp_for_X`` to ``eosPTEH_use_linear_interp_for_X``
The following ``controls`` options have been renamed/removed, as well
as moved to ``star_job`` (see next entry):
* ``logRho_max_for_all_PTEH_or_DT2`` to ``logRho_max_for_all_PTEH``
* ``logRho_max_for_any_PTEH_or_DT2`` to ``logRho_max_for_any_PTEH``
* ``logQ_max_for_low_Z_PTEH_or_DT2`` (removed)
* ``logQ_max_for_high_Z_PTEH_or_DT2`` to ``logQ_max_for_PTEH``
Change in location of PTEH EOS options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Options that modify the parameters associated with the PTEH EOS have be
moved from ``controls`` to ``star_job``. This brings PTEH in line with
the behavior of the other component EOSes.
If you explicitly set any of following options in your inlist, you
will need to move them from ``controls`` to ``star_job``. Their
meaning and default values remain unchanged.
* ``use_eosPTEH_for_low_density``
* ``use_eosPTEH_for_high_Z``
* ``Z_for_all_PTEH``
* ``Z_for_any_PTEH``
* ``logRho_min_for_all_OPAL``
* ``logRho_min_for_any_OPAL``
* ``logRho_max_for_all_PTEH``
* ``logRho_max_for_any_PTEH``
In addition, you must add the new option ``set_eosPTEH_parameters =
.true.`` to ``star_job`` to indicate that these values should override
the eos module-level defaults.
The removal of DT2 (see previous entry) has also resulted in the
change that the ``controls`` option ``logQ_max_for_low_Z_PTEH_or_DT2`` has
been removed (as it applied primarily to DT2) and
``logQ_max_for_high_Z_PTEH_or_DT2`` (which applied primarily to PTEH)
has been renamed to ``logQ_max_for_PTEH`` and moved from ``controls``
to ``star_job``.
New overshooting controls
~~~~~~~~~~~~~~~~~~~~~~~~~
The new controls for overshooting, briefly described in the release
notes of version 12115, are now the default in MESA (and the old
controls have been removed). All test_suite cases now use these new
controls.
There are two schemes implemented in MESA to treat overshooting: a step
overshoot scheme and an exponential scheme that follows Herwig (2000)
(https://ui.adsabs.harvard.edu/abs/2000A%26A...360..952H/abstract).
The old "double exponential overshoot scheme" is no longer accessible
through simple controls. An example of how to implement such a scheme
via the ``other_overshooting_scheme`` hook is contained in the
``other_physics_hooks`` test suite case.
The new overshooting controls are based on convection-zone and
convection-boundary matching criteria. In the new set of controls, for
each convective boundary it is possible to define an
``overshoot_zone_type``, ``overshoot_zone_loc`` and an
``overshoot_bdy_loc``, as well as values for the overshooting
parameters.
The permitted values are the following:
* ``overshoot_scheme = exponential, step``
* ``overshoot_zone_type = burn_H, burn_He, burn_Z, nonburn, any``
* ``overshoot_zone_loc = core, shell, any``
* ``overshoot_bdy_loc = bottom, top, any``
The following controls assign values for the diffusive or step
overshooting parameters:
* ``overshoot_f``
* ``overshoot_f0``
* ``overshoot_D0``
* ``overshoot_Delta0``
overshoot_f0 is defined so that the switch from convective mixing to
overshooting happens at a distance overshoot_f0*Hp into the convection
zone from the estimated location where `grad_ad = grad_rad`, where Hp is
the pressure scale height at that location.
For exponential overshoot, D(dr) = D0*exp(-2*dr/(overshoot_f*Hp0) where
D0 is the diffusion coefficient D at point r0, Hp0 is the scale height
at r0.
For step overshoot: overshooting extends a distance overshoot_f*Hp0 from
r0 with constant diffusion coefficient D = overshoot_D0 +
overshoot_Delta0*D_ob where D_ob is the convective diffusivity at the
bottom (top) of the step overshoot region for outward (inward)
overshooting.
These "new" controls replace the following "old" controls:
* ``overshoot_f_above_nonburn_core``
* ``overshoot_f0_above_nonburn_core``
* ``overshoot_f_above_nonburn_shell``
* ``overshoot_f0_above_nonburn_shell``
* ``overshoot_f_below_nonburn_shell``
* ``overshoot_f0_below_nonburn_shell``
* ``overshoot_f_above_burn_h_core``
* ``overshoot_f0_above_burn_h_core``
* ``overshoot_f_above_burn_h_shell``
* ``overshoot_f0_above_burn_h_shell``
* ``overshoot_f_below_burn_h_shell``
* ``overshoot_f0_below_burn_h_shell``
* ``overshoot_f_above_burn_he_core``
* ``overshoot_f0_above_burn_he_core``
* ``overshoot_f_above_burn_he_shell``
* ``overshoot_f0_above_burn_he_shell``
* ``overshoot_f_below_burn_he_shell``
* ``overshoot_f0_below_burn_he_shell``
* ``overshoot_f_above_burn_z_core``
* ``overshoot_f0_above_burn_z_core``
* ``overshoot_f_above_burn_z_shell``
* ``overshoot_f0_above_burn_z_shell``
* ``overshoot_f_below_burn_z_shell``
* ``overshoot_f0_below_burn_z_shell``
* ``step_overshoot_f_above_nonburn_core``
* ``step_overshoot_f_above_nonburn_shell``
* ``step_overshoot_f_below_nonburn_shell``
* ``step_overshoot_f_above_burn_h_core``
* ``step_overshoot_f_above_burn_h_shell``
* ``step_overshoot_f_below_burn_h_shell``
* ``step_overshoot_f_above_burn_he_core``
* ``step_overshoot_f_above_burn_he_shell``
* ``step_overshoot_f_below_burn_he_shell``
* ``step_overshoot_f_above_burn_z_core``
* ``step_overshoot_f_above_burn_z_shell``
* ``step_overshoot_f_below_burn_z_shell``
* ``step_overshoot_D``
* ``step_overshoot_D0_coeff``
The "new" control ``overshoot_D_min`` replaces the "old" control
``D_mix_ov_limit``.
The "new" control ``overshoot_brunt_B_max`` replaces the "old" control
``max_brunt_B_for_overshoot``.
The "new" control ``overshoot_mass_full_on`` replaces the "old" control
``mass_for_overshoot_full_on``.
The "new" control ``overshoot_mass_full_off`` replaces the "old" control
``mass_for_overshoot_full_off``.
The following example will apply exponential overshoot, with f = 0.128
and f0 = 0.100, at the bottom of non-burning convective shells; and
exponential overshoot, with f = 0.014 and f0 = 0.004, at all other
convective boundaries.
overshoot_scheme(1) = 'exponential'
overshoot_zone_type(1) = 'nonburn'
overshoot_zone_loc(1) = 'shell'
overshoot_bdy_loc(1) = 'bottom'
overshoot_f(1) = 0.128
overshoot_f0(1) = 0.100
overshoot_scheme(2) = 'exponential'
overshoot_zone_type(2) = 'any'
overshoot_zone_loc(2) = 'any'
overshoot_bdy_loc(2) = 'any'
overshoot_f(2) = 0.014
overshoot_f0(2) = 0.004
Other examples are illustrated in the test_suite cases.
Examples for exponential overshooting can be found in the following test_suite cases:
* 1.4M_ms_op_mono
* 25M_pre_ms_to_core_collapse
* 5M_cepheid_blue_loop/inlist_cepheid_blue_loop
* 7M_prems_to_AGB/inlist_7M_prems_to_AGB
* accretion_with_diffusion
* agb
* axion_cooling
* black_hole
* c13_pocket
* cburn_inward
* envelope_inflation
* example_ccsn_IIp
* example_make_pre_ccsn
* gyre_in_mesa_rsg
* high_mass
* high_z
* hot_cool_wind
* magnetic_braking
* make_co_wd
* make_metals
* ppisn
* pre_zahb
* radiative_levitation
Examples for step overshooting can be found in the following test_suite cases:
* high_rot_darkening
* relax_composition_j_entropy
Version number
~~~~~~~~~~~~~~
The MESA ``version_number`` is now represented as a string internally
and in the headers of history/profile output. User scripts that
assume this is an integer may need to be revised.
``other_wind`` hook
~~~~~~~~~~~~~~~~~~~
The interface of the ``other_wind`` hook changed from
subroutine other_wind_interface(id, Lsurf, Msurf, Rsurf, Tsurf, w, ierr)
use const_def, only: dp
integer, intent(in) :: id
real(dp), intent(in) :: Lsurf, Msurf, Rsurf, Tsurf ! surface values (cgs)
real(dp), intent(out) :: w ! wind in units of Msun/year (value is >= 0)
integer, intent(out) :: ierr
end subroutine other_wind_interface
to
subroutine other_wind_interface(id, Lsurf, Msurf, Rsurf, Tsurf, X, Y, Z, w, ierr)
use const_def, only: dp
integer, intent(in) :: id
real(dp), intent(in) :: Lsurf, Msurf, Rsurf, Tsurf, X, Y, Z ! surface values (cgs)
real(dp), intent(out) :: w ! wind in units of Msun/year (value is >= 0)
integer, intent(out) :: ierr
end subroutine other_wind_interface
Existing user routines will need to be updated.
Removal of ``id_extra`` from ``run_star_extras.f``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Most routines in ``run_star_extras.f`` had an argument ``id_extra``.
This argument generally did not do anything and so has been removed.
Existing user routines will need to be updated.
A simple way to migrate from routines written for previous versions of
MESA is to find and replace the string ", id_extra" with the empty
string in ``run_star_extras.f``.
Change of ``extras_startup`` from function to subroutine
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The interface of ``extras_startup`` changed from ``integer function`` to
subroutine. The current empty version of this routine is
subroutine extras_startup(id, restart, ierr)
integer, intent(in) :: id
logical, intent(in) :: restart
integer, intent(out) :: ierr
type (star_info), pointer :: s
ierr = 0
call star_ptr(id, s, ierr)
if (ierr /= 0) return
end subroutine extras_startup
Existing user routines will need to be updated to reflect this new interface.
Hooks for extra header items
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The interface of the routines
+ ``how_many_extra_history_header_items``
+ ``data_for_extra_history_header_items``
+ ``how_many_extra_profile_header_items``
+ ``data_for_extra_profile_header_items``
has changed. If these routines are included in your
``run_star_extras.f`` (even if they have not been customized), you
will need to update them. You should replace the old versions with
integer function how_many_extra_history_header_items(id)
integer, intent(in) :: id
integer :: ierr
type (star_info), pointer :: s
ierr = 0
call star_ptr(id, s, ierr)
if (ierr /= 0) return
how_many_extra_history_header_items = 0
end function how_many_extra_history_header_items
subroutine data_for_extra_history_header_items(id, n, names, vals, ierr)
integer, intent(in) :: id, n
character (len=maxlen_history_column_name) :: names(n)
real(dp) :: vals(n)
type(star_info), pointer :: s
integer, intent(out) :: ierr
ierr = 0
call star_ptr(id,s,ierr)
if(ierr/=0) return
! here is an example for adding an extra history header item
! also set how_many_extra_history_header_items
! names(1) = 'mixing_length_alpha'
! vals(1) = s% mixing_length_alpha
end subroutine data_for_extra_history_header_items
integer function how_many_extra_profile_header_items(id)
integer, intent(in) :: id
integer :: ierr
type (star_info), pointer :: s
ierr = 0
call star_ptr(id, s, ierr)
if (ierr /= 0) return
how_many_extra_profile_header_items = 0
end function how_many_extra_profile_header_items
subroutine data_for_extra_profile_header_items(id, n, names, vals, ierr)
integer, intent(in) :: id, n
character (len=maxlen_profile_column_name) :: names(n)
real(dp) :: vals(n)
type(star_info), pointer :: s
integer, intent(out) :: ierr
ierr = 0
call star_ptr(id,s,ierr)
if(ierr/=0) return
! here is an example for adding an extra profile header item
! also set how_many_extra_profile_header_items
! names(1) = 'mixing_length_alpha'
! vals(1) = s% mixing_length_alpha
end subroutine data_for_extra_profile_header_items
Removal of inlist_massive_defaults
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The file inlist_massive_defaults has been removed from ``star``.
Copies of the inlist can now be found in the following test cases:
* 25M_pre_ms_to_core_collapse
* 25M_z2m2_high_rotation
* adjust_net
* black_hole
* envelope_inflation
* example_ccsn_IIp
* example_make_pre_ccsn
* magnetic_braking
* split_burn_20M_si_burn_qp
* split_burn_big_net_30M
* split_burn_big_net_30M_logT_9.8
Other changes
-------------
* The routines ``{alloc,move,store,unpack}_extra_info`` were removed
from ``standard_run_star_extras.inc``. (These routines were used to
store/retrieve information from photos.) If you have existing
``run_star_extras`` code that includes these routines, it will
continue to function. However, in new ``run_star_extras`` code, the
recommended way to store/retrieve data is using the
``other_photo_read`` and ``other_photo_write`` hooks. Examples can be
found in the `conductive_flame` and `brown_dwarf` test suite cases.
* The controls ``xtra_coef_os_*`` and ``xtra_dist_os_*`` which could
be used to modify ``mesh_delta_coeff`` in overshooting regions have
been removed. The same functionality is available using the
``other_mesh_delta_coeff_factor`` and an example implementation is
given in the ``agb`` test suite case.
* The output-related control ``alpha_bdy_core_overshooting`` and
related history options ``core_overshoot_{Hp,f,f0,hstep,r0}`` and
``{mass,radius}_bdy_core_overshooting`` have been removed.
* The ``star_data`` module was split out of the ``star`` module. The
source file describing the contents of the ``star_info`` data
structure is now located at ``star_data/public/star_data.inc``.
* If not provided with an argument, the ``./re`` script will now
restart from the most recent photo (determined by filesystem
modification time).
More information about the Mesa-users
mailing list