[mesa-users] New public release 9575

[RICHARD H D TOWNSEND]

Dear MESA Community,

It is our great pleasure to announce MESA public release version 9575.
There are a number of changes we'd like to bring to your attention;
please see the release notes below.

Best wishes,

Rich (on behalf of Rob, Josiah, Evan, Aaron, Frank and Bill)

MESA 9575 - Release Notes
=========================

Opacities
---------

The kap module has been modified to make it easier to incorporate
alternative opacity tables, while preserving the normal behavior of
the default tables. The modifications come in 2 basic forms:

1) the naming convention for opacity table files has been streamlined
so that all X and Z values are now consistently written across all
different types of tables.

2) the input X and Z values required by the kap module are no longer
hard-coded in kap_def; they are now read from a configuration file
that is (optionally) read at run time. The number of X and Z values
are set in the file, along with the numbers Xs for each Z, and the
actual X and Z values. This is accomplished through the star_job
inlist through 'kappa_config_file'.

These changes should be completely transparent to users of the
standard kap tables. No changes have been made to the OP monochromatic
opacities either.

For users who update their mesa install through svn, kap_data will
need to be reinstalled after the update.

Pulsation
---------

*) Fixed code that adds atmosphere data to pulsation output files (as
 enabled by add_atmosphere_to_pulse_data). Previously, this code only
 worked correctly for the four atmosphere choices that perform a T-Tau
 integration: ‘Eddington_grey’, ‘Krishna_Swamy’, ‘solar_Hopf_grey’ and
 ‘Pacznski_grey’. In other cases, the code silently added on a
 ‘Paczynski_grey’ atmosphere instead of what was requested; typically,
 this led to density/temperature discontinuities at the transition
 between atmosphere and interior. In the fixed code, along with the
 four T-tau cases, the ‘simple_photosphere’ and ‘grey_and_kap’ options
 now function as they should; while the remaining options (e.g.,
 ‘photosphere_tables’) cause MESA to terminate with a message
 indicating that an atmosphere cannot be added.

*) Fixed the headers written to FGONG- and OSC-format pulsation output
 files; previously, some of the fields (e.g., stellar age) were being
 incorrectly set up.

*) MESA can now write pulsation output files that include
 composition/density discontinuities (in fact, this capability was
 present in release 8845, but undocumented). When a density
 discontinuity is detected in a model (see below for more details on
 how this is done), and the control flag
 ‘add_double_point_to_pulse_data’ is .TRUE. MESA writes a double point
 to the output file, containing the model values on either side of the
 discontinuity. Double points can easily be recognized in the file
 because they share the same radial (r) and mass (M_r) coordinate
 values. Recent releases of the GYRE pulsation code (5.0 onward)
 correctly treat double points by applying appropriate jump conditions
 in the pulsation equations.

 To control what MESA considers to be a density discontinuity, use the
 ‘threshold_grad_mu_for_double_point’ control. Cell faces where
 |grad_mu| = |d(ln mu)/d(ln P)| rises above this threshold are treated
 as density discontinuities. A typical threshold value might be
 somewhere in the range 1-10. To avoid having *too* many double points
 created, you can set an upper limit on the number using the
 ‘max_number_of_double_points’ control.

*) MESA by default now uses the ‘wide’ (version >= 1000) format when
 writing FGONG pulsation output files. This format was formalized
 during the 2015 Aarhus RGB Workshop in Birmingham, England.

*) Some of the pulsation output parameters have been renamed, as
 follows:

   save_pulsation_info_for_model_number -> save_pulse_data_for_model_number
   save_pulsation_info_when_terminate -> save_pulse_data_when_terminate
   save_pulsation_info_filename -> save_pulse_data_filename
   write_pulse_info_with_profile -> write_pulse_data_with_profile
   pulse_info_format -> pulse_data_format
   add_atmosphere_to_pulse_info -> add_atmosphere_to_pulse_data
   add_center_point_to_pulse_info -> add_center_point_to_pulse_data
   keep_surface_point_for_pulse_info -> keep_surface_point_for_pulse_data
   add_double_points_to_pulse_info -> add_double_points_to_pulse_data

*) Fixed incorrect filename when using write_gyre_for_best_model

Accretion
---------

Accretion with small timesteps has been improved, using a patch and
test case provided by Dean Townsley. Here is his commentary:

"The attached adjust_mass.f90 has some fixes for accretion with small
timesteps when the mass added in the step is similar to the mass of
the outer zone.  In the current code (I tested 8845), if the material
being added is not the same abundance as the surface already there,
the individual species accretion rates are wrong and the profiles get
messed up as well.  See the attached plots of h1 mass and the h1
profile after about 50 steps into adding mass. The test here is just
taking the current "wd" accretion test, setting the initial timestep
so that the initial added mass in a timestep is about half that in the
outer zone, and changing to helium-rich accreted material, though any
abundance different from what is already there will do.  Updates to
adjust_mass.f90 seem to fix things.

The main issues were:

- dm(k) was being used after revise_q_and_dq() was called but was not
  actually updated.  it is now updated with the dq's.

- the renorming of the dq's after the constant dm / constant dq
  boundary determination was done in a way that suffered from
  truncation problems when the the constant dq region is small. This
  caused the mass added in various species to be off (too small).  As
  you can see in the plots, the H mass could actually decrease even
  when accreting material with H in it!

- there was some code in there that seemed to be trying to fix this by
  rescaling abundances to match expectations in layers near the
  surface, but due to the need to keep abundances to sum to 1 and the
  fact that all the accreted masses were off in the same direction,
  this distorted the abundance profile instead of fixing the
  problem. (see the second set of plots) I have disabled this code now
  that the underlying problem appears to be fixed.

- there was a minor error in the way the abundance was computed for
  partially accreted cells.  This doesn't seem to have been having a
  major impact.

In fixing the second of these issues related to truncation, I
refactored the revise_q_and_dq() to work in 1-q instead of q
coordinates to reduce truncation issues.  The logic is otherwise the
same, just with 1-q as the coordinate.

I have also included a new test suite test to check for these issues.
This test reports failure for the current release (8845) but success
with the adjust_mass.f90 changes attached here.  While this test could
be done at the start of the "wd" test, starting from small timesteps
takes around 1200 steps which is a fair bit more than the current "wd"
test, which takes around 400.  Also it's a bit more clear to just test
it separately."

Miscellaneous
-------------

*) Added new pgstar plot production_plots which show the relative
 change in the abundances against the initial composition.

*) pgstar plots can now be used while mesa is using one of the relax
 routines to "relax" the model to a new state.

*) makefiles will now warn the user if $MESA_DIR variable is not set,
 or if using the SDK makefile (the default) if the SDK has not been
 initialized.

*) Cache files will now be written to the current working directory
 before being moved to the $MESA_DIR/data folder. This will stop
 multiple mesa runs, running simultaneously, from over writing the
 cache files leaving them in a inconsistent state. This should help
 those running MESA on clusters or otherwise running more than 1 mesa
 job at a time.

*) A new file $MESA_DIR/star/defaults/env_vars.list has been added
 which describes the environment variables MESA uses as well as few
 miscellaneous options.

*) fixed a bug in the color code that prevents the use of more than
 one bolometric correction file. In previous versions of MESA, when
 using bc’s from a second or subsequent file, the wrong column is
 returned.

*) Add test_suite case (custom_rate_c14ago18) exercising custom
 rate. This test case provides an example of how to set up and use one
 of your own reaction rates in MESA.  Physically, it is a WD slowly
 accreting He (with some N14, which has electron-captured to C14 at
 the base of the He layer).  It illustrates the effect of the
 c14(a,g)o18 rate on the ignition of the He.  The custom rate is that
 from Hashimoto et al. (1986) and is compared to the default "reaclib"
 rate that ships with MESA.

*) MESA now strictly respects max_timestep control. Previously, if you
 loaded a model that has a stored timestep greater than the requested
 max_timestep, the timestep would remain above the limit for several
 steps (since it could only shrink so much per step).

*) Fixed check_for_redo_MLT by using mlt_mixing_type, so that it now
 functions as documented.

*) Tweak convective zone boundary mesh controls, changing the effect
 of the convective zone boundary mesh controls xtra_coef_*_*_*_czb
 (hereafter "coef") and xtra_dist_*_*_*_czb (hereafter,
 "dist"). Previously, the meshing was adjusted by setting the value of
 delta_gval_max to be a linear blend between coef at the boundary and
 1.0 over a length dist * Hp (measured from the boundary).

 If you try to increase the resolution near the convective boundary by
 a significant factor, the linear blend means that delta_gval_max is
 only near the specified value of coef for a distance away from the
 boundary of order coef * dist.  So in practice, MESA increases the
 resolution over a significantly smaller region than you might expect.

 To fix this, the form of the blend is now a piecewise linear form
 that guarantees that delta_gval_max is near coef for at least half of
 dist.