Overhaul docs for scaling relation parameters, update solar reference values and rename Teff_sun to astero_Teff_sun (#571, closes #298)

Author: warrickball

binary/test_suite/double_bh/history_columns.list

@@ -584,8 +584,7 @@
          ! sqrt(2) pi^2/(integral of brunt_N/r dr)
       !log_delta_Pg
       !nu_max ! estimate from scaling relation (microHz)
-         ! nu_max = nu_max_sun * M/Msun / ((R/Rsun)^2 (Teff/Teff_sun)^0.5)
-         ! with nu_max_sun = 3100 microHz, Teff_sun = 5777
+         ! nu_max = nu_max_sun * M/Msun / ((R/Rsun)^2 (Teff/astero_Teff_sun)^0.5)
       !nu_max_3_4th_div_delta_nu ! nu_max^0.75/delta_nu
       !acoustic_cutoff ! 0.5*g*sqrt(gamma1*rho/P) at surface
       !acoustic_radius ! integral of dr/csound (seconds)

binary/test_suite/evolve_both_stars/history_columns.list

@@ -529,8 +529,7 @@
          ! sqrt(2) pi^2/(integral of brunt_N/r dr)
       !log_delta_Pg
       !nu_max ! estimate from scaling relation (microHz)
-         ! nu_max = nu_max_sun * M/Msun / ((R/Rsun)^2 (Teff/Teff_sun)^0.5)
-         ! with nu_max_sun = 3100 microHz, Teff_sun = 5777
+         ! nu_max = nu_max_sun * M/Msun / ((R/Rsun)^2 (Teff/astero_Teff_sun)^0.5)
       !nu_max_3_4th_div_delta_nu ! nu_max^0.75/delta_nu
       !acoustic_cutoff ! 0.5*g*sqrt(gamma1*rho/P) at surface
       !ng_for_nu_max ! = 1 / (nu_max*delta_Pg)

binary/test_suite/jdot_ls_check/history_columns.list

@@ -529,8 +529,7 @@
          ! sqrt(2) pi^2/(integral of brunt_N/r dr)
       !log_delta_Pg
       !nu_max ! estimate from scaling relation (microHz)
-         ! nu_max = nu_max_sun * M/Msun / ((R/Rsun)^2 (Teff/Teff_sun)^0.5)
-         ! with nu_max_sun = 3100 microHz, Teff_sun = 5777
+         ! nu_max = nu_max_sun * M/Msun / ((R/Rsun)^2 (Teff/astero_Teff_sun)^0.5)
       !nu_max_3_4th_div_delta_nu ! nu_max^0.75/delta_nu
       !acoustic_cutoff ! 0.5*g*sqrt(gamma1*rho/P) at surface
       !ng_for_nu_max ! = 1 / (nu_max*delta_Pg)

binary/test_suite/jdot_ml_check/history_columns.list

@@ -529,8 +529,7 @@
          ! sqrt(2) pi^2/(integral of brunt_N/r dr)
       !log_delta_Pg
       !nu_max ! estimate from scaling relation (microHz)
-         ! nu_max = nu_max_sun * M/Msun / ((R/Rsun)^2 (Teff/Teff_sun)^0.5)
-         ! with nu_max_sun = 3100 microHz, Teff_sun = 5777
+         ! nu_max = nu_max_sun * M/Msun / ((R/Rsun)^2 (Teff/astero_Teff_sun)^0.5)
       !nu_max_3_4th_div_delta_nu ! nu_max^0.75/delta_nu
       !acoustic_cutoff ! 0.5*g*sqrt(gamma1*rho/P) at surface
       !ng_for_nu_max ! = 1 / (nu_max*delta_Pg)

binary/test_suite/star_plus_point_mass/history_columns.list

@@ -529,8 +529,7 @@
          ! sqrt(2) pi^2/(integral of brunt_N/r dr)
       !log_delta_Pg
       !nu_max ! estimate from scaling relation (microHz)
-         ! nu_max = nu_max_sun * M/Msun / ((R/Rsun)^2 (Teff/Teff_sun)^0.5)
-         ! with nu_max_sun = 3100 microHz, Teff_sun = 5777
+         ! nu_max = nu_max_sun * M/Msun / ((R/Rsun)^2 (Teff/astero_Teff_sun)^0.5)
       !nu_max_3_4th_div_delta_nu ! nu_max^0.75/delta_nu
       !acoustic_cutoff ! 0.5*g*sqrt(gamma1*rho/P) at surface
       !ng_for_nu_max ! = 1 / (nu_max*delta_Pg)

binary/test_suite/star_plus_point_mass_explicit_mdot/history_columns.list

@@ -529,8 +529,7 @@
          ! sqrt(2) pi^2/(integral of brunt_N/r dr)
       !log_delta_Pg
       !nu_max ! estimate from scaling relation (microHz)
-         ! nu_max = nu_max_sun * M/Msun / ((R/Rsun)^2 (Teff/Teff_sun)^0.5)
-         ! with nu_max_sun = 3100 microHz, Teff_sun = 5777
+         ! nu_max = nu_max_sun * M/Msun / ((R/Rsun)^2 (Teff/astero_Teff_sun)^0.5)
       !nu_max_3_4th_div_delta_nu ! nu_max^0.75/delta_nu
       !acoustic_cutoff ! 0.5*g*sqrt(gamma1*rho/P) at surface
       !ng_for_nu_max ! = 1 / (nu_max*delta_Pg)

binary/test_suite/wind_fed_bhhmxb/history_columns.list

@@ -529,8 +529,7 @@
          ! sqrt(2) pi^2/(integral of brunt_N/r dr)
       !log_delta_Pg
       !nu_max ! estimate from scaling relation (microHz)
-         ! nu_max = nu_max_sun * M/Msun / ((R/Rsun)^2 (Teff/Teff_sun)^0.5)
-         ! with nu_max_sun = 3100 microHz, Teff_sun = 5777
+         ! nu_max = nu_max_sun * M/Msun / ((R/Rsun)^2 (Teff/astero_Teff_sun)^0.5)
       !nu_max_3_4th_div_delta_nu ! nu_max^0.75/delta_nu
       !acoustic_cutoff ! 0.5*g*sqrt(gamma1*rho/P) at surface
       !ng_for_nu_max ! = 1 / (nu_max*delta_Pg)

docs/source/changelog.rst

@@ -28,6 +28,15 @@ Previously we had logic to determine if a extra history value should be saved
 as an int or a float (users can only provide data as a float). This was error
 prone, so now we save extra history values as floats.
 
+Asteroseismic scaling relations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The default values of the parameters ``delta_nu_sun`` and ``nu_max_sun`` used in the asteroseismic scaling relations
+have been updated to the values reported by `Lund et al. (2017) <https://ui.adsabs.harvard.edu/abs/2017ApJ...835..172L/abstract>`_
+(:math:`\Delta\nu_\odot = \mathrm{134.91}\,\mu\mathrm{Hz}` and :math:`\nu_{\mathrm{max},\odot} = \mathrm{3078}\,\mu\mathrm{Hz}`).
+The parameter ``Teff_sun`` has been renamed ``astero_Teff_sun`` to avoid confusion
+with the fixed constant ``Teffsun`` in the ``const`` module.  ``astero_Teff_sun``'s
+default value has been set to 5772 K, as in `IAU 2015 Resolution B3 <https://ui.adsabs.harvard.edu/abs/2015arXiv151007674M>`_.
 
 .. _New Features main:
 
@@ -47,7 +56,6 @@ to a ``rates_list`` file, or by using the option ``filename_of_special_rate``.
 Several examples in the test suite now make use of these rates, such as
 massive stars and models for building white dwarfs.
 
-
 Maximum net size
 ~~~~~~~~~~~~~~~~
 

star/defaults/controls.defaults

@@ -7594,43 +7594,59 @@
 
       ! get_delta_nu_from_scaled_solar
       ! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+      ! If ``get_delta_nu_from_scaled_solar`` is ``.false.``, the
+      ! large separation ``delta_nu`` is the inverse of the sound
+      ! crossing time from one side of the star to the other, through
+      ! the center.  This is sometimes called the "asymptotic" large
+      ! separation.
 
-      ! use scaled solar values
+      ! Otherwise, ``delta_nu`` is calculated from the asteroseismic
+      ! scaling relations (see `Ulrich 1986`_, `Brown et al. 1991`_
+      ! and `Kjeldsen & Bedding 1995`_) using solar reference values
+      ! ``nu_max_sun``, ``delta_nu_sun`` and ``astero_Teff_sun``.
+
+      ! ``nu_max`` is always computed from the scaling relation.
+
+      ! .. _Ulrich 1986: https://ui.adsabs.harvard.edu/abs/1986ApJ...306L..37U
+      ! .. _Brown et al. 1991:  https://ui.adsabs.harvard.edu/abs/1991ApJ...368..599B
+      ! .. _Kjeldsen & Bedding 1995: https://ui.adsabs.harvard.edu/abs/1995A%26A...293...87K
 
       ! ::
 
     get_delta_nu_from_scaled_solar = .false.
 
-
       ! nu_max_sun
       ! ~~~~~~~~~~
-
-      ! solar value of ``nu_max``
-
-      ! ::
-
-    nu_max_sun = 3100d0
-
-
       ! delta_nu_sun
       ! ~~~~~~~~~~~~
+      ! astero_Teff_sun
+      ! ~~~~~~~~~~~~~~~
 
-      ! solar value of ``delta_nu``
+      ! Solar reference values used in the asteroseismic scaling relations
+      ! for ``delta_nu`` (if ``get_delta_nu_from_scaled_solar`` is ``.false.``)
+      ! and ``nu_max`` (always).
 
-      ! ::
+      ! The default ``nu_max_sun`` is the Sun-as-as-star value reported by `Lund
+      ! et al. (2017)`_, which is consistent with but conceptually
+      ! different from the result of 3073.59 ± 0.18 μHz by `Kiefer et
+      ! al. (2018)`_.
 
-    delta_nu_sun = 135d0
+      ! The default ``delta_nu_sun`` is also taken from `Lund et al. (2017)`_.
 
+      ! The default ``astero_Teff_sun`` is the value adopted in IAU 2015 Resolution B3.
+      ! This should not be confused with the constant ``Teffsun``, which is always
+      ! equal to the IAU value and not controlled by a parameter.  The "asteroseismic"
+      ! value can be changed in case one needs to reproduce previous calculations
+      ! using the scaling relations.
 
-      ! Teff_sun
-      ! ~~~~~~~~
-
-      ! solar value of Teff
+      ! .. _Lund et al. (2017): https://ui.adsabs.harvard.edu/abs/2017ApJ...835..172L
+      ! .. _Kiefer et al. (2018): https://ui.adsabs.harvard.edu/abs/2018SoPh..293..151K
 
       ! ::
 
-    Teff_sun = 5777d0
-
+    nu_max_sun = 3078d0 ! μHz
+    delta_nu_sun = 134.91d0 ! μHz
+    astero_Teff_sun = 5772d0 ! kelvin
 
       ! delta_Pg_mode_freq
       ! ~~~~~~~~~~~~~~~~~~

star/defaults/history_columns.list

@@ -740,8 +740,7 @@
          ! sqrt(2) pi^2/(integral of brunt_N/r dr)
       !log_delta_Pg
       !nu_max ! estimate from scaling relation (microHz)
-         ! nu_max = nu_max_sun * M/Msun / ((R/Rsun)^2 (Teff/Teff_sun)^0.5)
-         ! with nu_max_sun = 3100 microHz, Teff_sun = 5777
+         ! nu_max = nu_max_sun * M/Msun / ((R/Rsun)^2 (Teff/astero_Teff_sun)^0.5)
       !nu_max_3_4th_div_delta_nu ! nu_max^0.75/delta_nu
       !acoustic_cutoff ! 0.5*g*sqrt(gamma1*rho/P) at surface
       !acoustic_radius ! integral of dr/csound (seconds)