Klencki+ 2025 AM loss prescription (#1425)

* klencki AM loss

* changelog

* fixed changelog to have an mm change, since this is technically a breaking change

* added old macleod-linear AM options to depracted list

* what's new

* typos

* new yaml

Author: reinhold-willcox

compas_python_utils/preprocessing/compasConfigDefault.yaml

@@ -1,5 +1,5 @@
 ##~!!~## COMPAS option values
-##~!!~## File Created Mon Aug 18 13:37:46 2025 by COMPAS v03.23.02
+##~!!~## File Created Tue Aug 19 15:39:23 2025 by COMPAS v03.25.00
 ##~!!~##
 ##~!!~## The default COMPAS YAML file (``compasConfigDefault.yaml``), as distributed, has
 ##~!!~## all COMPAS option entries commented so that the COMPAS default value for the
@@ -149,8 +149,8 @@ numericalChoices:
 #    --critical-mass-ratio-white-dwarf-non-degenerate-accretor: 0.000000   # Default: 0.000000
 #    --mass-transfer-fa: 0.500000                                          # Default: 0.500000                                                                                                                                                                         # Only if using mass-transfer-accretion-efficiency-prescription = 'FIXED'
 #    --mass-transfer-jloss: 1.000000                                       # Default: 1.000000                                                                                                                                                                         # Only if using mass-transfer-angular-momentum-loss-prescription = 'FIXED'
-#    --mass-transfer-jloss-macleod-linear-fraction-degen: 0.500000         # Default: 0.500000
-#    --mass-transfer-jloss-macleod-linear-fraction-non-degen: 0.500000     # Default: 0.500000
+#    --mass-transfer-jloss-linear-fraction-degen: 0.500000                 # Default: 0.500000
+#    --mass-transfer-jloss-linear-fraction-non-degen: 0.500000             # Default: 0.500000
 #    --mass-transfer-thermal-limit-C: 10.000000                            # Default: 10.000000
 #    --zeta-adiabatic-arbitrary: 10000.00                                  # Default: 10000.00
 #    --zeta-main-sequence: 2.000000                                        # Default: 2.000000
@@ -263,7 +263,7 @@ stringChoices:
 #    --case-BB-stability-prescription: 'ALWAYS_STABLE'                     # Default: 'ALWAYS_STABLE'               # Options: ['ALWAYS_UNSTABLE','TREAT_AS_OTHER_MT','ALWAYS_STABLE_ONTO_NSBH','ALWAYS_STABLE']
 #    --critical-mass-ratio-prescription: 'NONE'                            # Default: 'NONE'                        # Options: ['HURLEY_HJELLMING_WEBBINK','GE','GE_IC','CLAEYS','NONE']
 #    --stellar-zeta-prescription: 'SOBERMAN'                               # Default: 'SOBERMAN'                    # Options: ['ARBITRARY','HURLEY','SOBERMAN']
-#    --mass-transfer-angular-momentum-loss-prescription: 'ISOTROPIC'       # Default: 'ISOTROPIC'                   # Options: ['ARBITRARY','MACLEOD_LINEAR','CIRCUMBINARY','ISOTROPIC','JEANS']
+#    --mass-transfer-angular-momentum-loss-prescription: 'ISOTROPIC'       # Default: 'ISOTROPIC'                   # Options: ['ARBITRARY','KLENCKI_LINEAR','MACLEOD_LINEAR','CIRCUMBINARY','ISOTROPIC','JEANS']
 #    --mass-transfer-accretion-efficiency-prescription: 'THERMAL'          # Default: 'THERMAL'                     # Options: ['FIXED','THERMAL']
 #    --mass-transfer-rejuvenation-prescription: 'STARTRACK'                # Default: 'STARTRACK'                   # Options: ['STARTRACK','HURLEY']
 #    --mass-transfer-thermal-limit-accretor-multiplier: 'CFACTOR'          # Default: 'CFACTOR'                     # Options: ['ROCHELOBE','CFACTOR']
@@ -273,7 +273,7 @@ stringChoices:
 #    --common-envelope-formalism: 'ENERGY'                                 # Default: 'ENERGY'                      # Options: ['TWO_STAGE','ENERGY']
 #    --common-envelope-lambda-prescription: 'LAMBDA_NANJING'               # Default: 'LAMBDA_NANJING'              # Options: ['LAMBDA_DEWI','LAMBDA_KRUCKOW','LAMBDA_NANJING','LAMBDA_LOVERIDGE','LAMBDA_FIXED']                                                     # Xu & Li 2010
 #    --common-envelope-mass-accretion-prescription: 'ZERO'                 # Default: 'ZERO'                        # Options: ['CHEVALIER','MACLEOD','UNIFORM','CONSTANT','ZERO']
-#    --common-envelope-second-stage-gamma-prescription: 'ISOTROPIC'        # Default: 'ISOTROPIC'                   # Options: ['ARBITRARY','MACLEOD_LINEAR','CIRCUMBINARY','ISOTROPIC','JEANS']
+#    --common-envelope-second-stage-gamma-prescription: 'ISOTROPIC'        # Default: 'ISOTROPIC'                   # Options: ['ARBITRARY','KLENCKI_LINEAR','MACLEOD_LINEAR','CIRCUMBINARY','ISOTROPIC','JEANS']
 
     ### TIDES
 #    --tides-prescription: 'NONE'                                          # Default: 'NONE'                        # Options: ['KAPIL2025','PERFECT','NONE']

online-docs/pages/User guide/Program options/program-options-list-defaults.rst

@@ -892,7 +892,7 @@ Default = THERMAL
 
 **--mass-transfer-angular-momentum-loss-prescription** |br|
 Mass Transfer Angular Momentum Loss prescription. |br|
-Options: { JEANS, ISOTROPIC, CIRCUMBINARY, MACLEOD_LINEAR, ARBITRARY } |br|
+Options: { JEANS, ISOTROPIC, CIRCUMBINARY, KLENCKI_LINEAR, MACLEOD_LINEAR, ARBITRARY } |br|
 Default = ISOTROPIC
 
 **--mass-transfer-fa** |br|
@@ -905,14 +905,14 @@ Specific angular momentum with which the non-accreted system leaves the system.
 Used when ``--mass-transfer-angular-momentum-loss-prescription = ARBITRARY``, ignored otherwise. |br|
 Default = 1.0
 
-**--mass-transfer-jloss-macleod-linear-fraction-degen** |br|
+**--mass-transfer-jloss-linear-fraction-degen** |br|
 Specific angular momentum interpolation fraction for degenerate accretors, linear between 0 and 1 corresponding to the accretor and L2 point. |br|
-Used when ``--mass-transfer-angular-momentum-loss-prescription = MACLEOD_LINEAR``, ignored otherwise. |br|
+Used when ``--mass-transfer-angular-momentum-loss-prescription = KLENCKI_LINEAR`` or ``MACLEOD_LINEAR``, ignored otherwise. |br|
 Default = 0.5
 
-**--mass-transfer-jloss-macleod-linear-fraction-non-degen** |br|
+**--mass-transfer-jloss-linear-fraction-non-degen** |br|
 Specific angular momentum interpolation fraction for non-degenerate accretors, linear between 0 and 1 corresponding to the accretor and L2 point. |br|
-Used when ``--mass-transfer-angular-momentum-loss-prescription = MACLEOD_LINEAR``, ignored otherwise. |br|
+Used when ``--mass-transfer-angular-momentum-loss-prescription = KLENCKI_LINEAR`` or ``MACLEOD_LINEAR``, ignored otherwise. |br|
 Default = 0.5
 
 **--mass-transfer-rejuvenation-prescription** |br|
@@ -1550,7 +1550,7 @@ Go to :ref:`the top of this page <options-props-top>` for the full alphabetical
 --critical-mass-ratio-helium-HG-non-degenerate-accretor, --critical-mass-ratio-helium-MS-degenerate-accretor, --critical-mass-ratio-helium-MS-non-degenerate-accretor, 
 --critical-mass-ratio-helium-giant-degenerate-accretor, --critical-mass-ratio-helium-giant-non-degenerate-accretor, --critical-mass-ratio-white-dwarf-degenerate-accretor, 
 --critical-mass-ratio-white-dwarf-non-degenerate-accretor, --eddington-accretion-factor, --mass-transfer, --use-mass-transfer, --mass-transfer-accretion-efficiency-prescription, 
---mass-transfer-angular-momentum-loss-prescription, --mass-transfer-fa, --mass-transfer-jloss, --mass-transfer-jloss-macleod-linear-fraction-degen, --mass-transfer-jloss-macleod-linear-fraction-non-degen, 
+--mass-transfer-angular-momentum-loss-prescription, --mass-transfer-fa, --mass-transfer-jloss, --mass-transfer-jloss-linear-fraction-degen, --mass-transfer-jloss-linear-fraction-non-degen, 
 --mass-transfer-rejuvenation-prescription, --mass-transfer-thermal-limit-accretor, --mass-transfer-thermal-limit-accretor-multiplier, --mass-transfer-thermal-limit-C, --retain-core-mass-during-caseA-mass-transfer, 
 --stellar-zeta-prescription, --zeta-adiabatic-arbitrary, --zeta-main-sequence, --zeta-radiative-giant-star 
 

online-docs/pages/whats-new.rst

@@ -3,6 +3,18 @@ What's new
 
 Following is a brief list of important updates to the COMPAS code.  A complete record of changes can be found in the file ``changelog.h``.
 
+**03.25.00 August 19, 2025**
+
+* Added KLENCKI_LINEAR AM loss, which is linear in the specific AM gamma instead of the orbital separation (as in MACLEOD_LINEAR).
+
+This is based on the variations explored in Klencki+ 2025, and is very similar in construction to the MACLEOD_LINEAR option, 
+with both requiring an interpolation fraction f set by the user. Therefore, the following options are deprecated:
+
+    * ``--mass-transfer-jloss-macleod-linear-fraction-degen``     in favor of ``--mass-transfer-jloss-linear-fraction-degen``     
+    * ``--mass-transfer-jloss-macleod-linear-fraction-non-degen`` in favor of ``--mass-transfer-jloss-linear-fraction-non-degen`` 
+
+and the replacement options apply for both MACLEOD_LINEAR and KLENCKI_LINEAR.
+
 **03.24.00 August 19, 2025**
 
 * Updated Maltsev remnant mass prescription to include the 3 variants described in Willcox+ 2025 (bimodality paper). 

src/BaseBinaryStar.cpp

@@ -1861,18 +1861,32 @@ double BaseBinaryStar::CalculateGammaAngularMomentumLoss_Static(const double p_D
             } break;
 
         case MT_ANGULAR_MOMENTUM_LOSS_PRESCRIPTION::MACLEOD_LINEAR : {                                                              // linear interpolation on separation between accretor and L2 point
-            // interpolate in separation between a_acc and a_L2, both normalized to units of separation a
+            // Interpolate linearly in separation between a_acc and a_L2, both normalized to units of separation a
             double q        = p_AccretorMass / p_DonorMass;
             double qPlus1   = 1.0 + q;
             double aL2      = std::sqrt(M_SQRT2);                                                                                   // roughly, coincides with CIRCUMBINARY_RING def above
             double aAcc     = 1.0 / qPlus1;
             double fMacleod = p_IsAccretorDegenerate 
-                                ? OPTIONS->MassTransferJlossMacLeodLinearFractionDegen() 
-                                : OPTIONS->MassTransferJlossMacLeodLinearFractionNonDegen();
+                                ? OPTIONS->MassTransferJlossLinearFractionDegen() 
+                                : OPTIONS->MassTransferJlossLinearFractionNonDegen();
             double aGamma   = aAcc + (aL2 - aAcc) * fMacleod;
             gamma           = aGamma * aGamma * qPlus1 * qPlus1 / q;
             } break;
 
+        case MT_ANGULAR_MOMENTUM_LOSS_PRESCRIPTION::KLENCKI_LINEAR : {                                                              // linear interpolation on separation between accretor and L2 point
+            // Interpolate linearly in specific AM loss parameter gamma
+            double q        = p_AccretorMass / p_DonorMass;
+            double qPlus1   = 1.0 + q;
+            double qPlus1SquaredByQ = qPlus1 * qPlus1 / q;
+            double aL2      = std::sqrt(M_SQRT2);                                                                                   // roughly, coincides with CIRCUMBINARY_RING def above
+            double aAcc     = 1.0 / qPlus1;
+            double gammaL2  = aL2 * aL2 * qPlus1SquaredByQ;
+            double gammaAcc = aAcc * aAcc * qPlus1SquaredByQ;
+            double fKlencki = p_IsAccretorDegenerate 
+                                ? OPTIONS->MassTransferJlossLinearFractionDegen() 
+                                : OPTIONS->MassTransferJlossLinearFractionNonDegen();
+            gamma = gammaAcc + (gammaL2 - gammaAcc) * fKlencki;
+            } break;
         default:                                                                                                                    // unknown prescription
             // the only way this can happen is if someone added an MT_ANGULAR_MOMENTUM_LOSS_PRESCRIPTION
             // and it isn't accounted for in this code.  We should not default here, with or without a warning.

src/LogTypedefs.h

@@ -936,8 +936,8 @@ enum class PROGRAM_OPTION: int {
 
     MT_FRACTION_ACCRETED,
     MT_JLOSS,
-    MT_JLOSS_MACLEOD_LINEAR_FRACTION_DEGEN,
-    MT_JLOSS_MACLEOD_LINEAR_FRACTION_NON_DEGEN,
+    MT_JLOSS_LINEAR_FRACTION_DEGEN,
+    MT_JLOSS_LINEAR_FRACTION_NON_DEGEN,
     MT_REJUVENATION_PRESCRIPTION,
     MT_THERMALLY_LIMITED_VARIATION,
 
@@ -1166,8 +1166,8 @@ const COMPASUnorderedMap<PROGRAM_OPTION, std::string> PROGRAM_OPTION_LABEL = {
 
     { PROGRAM_OPTION::MT_FRACTION_ACCRETED,                             "MT_FRACTION_ACCRETED" },
     { PROGRAM_OPTION::MT_JLOSS,                                         "MT_JLOSS" },
-    { PROGRAM_OPTION::MT_JLOSS_MACLEOD_LINEAR_FRACTION_DEGEN,           "MT_JLOSS_MACLEOD_LINEAR_FRACTION_DEGEN" },
-    { PROGRAM_OPTION::MT_JLOSS_MACLEOD_LINEAR_FRACTION_NON_DEGEN,       "MT_JLOSS_MACLEOD_LINEAR_FRACTION_NON_DEGEN" },
+    { PROGRAM_OPTION::MT_JLOSS_LINEAR_FRACTION_DEGEN,                   "MT_JLOSS_LINEAR_FRACTION_DEGEN" },
+    { PROGRAM_OPTION::MT_JLOSS_LINEAR_FRACTION_NON_DEGEN,               "MT_JLOSS_LINEAR_FRACTION_NON_DEGEN" },
     { PROGRAM_OPTION::MT_REJUVENATION_PRESCRIPTION,                     "MT_REJUVENATION_PRESCRIPTION" },
     { PROGRAM_OPTION::MT_THERMALLY_LIMITED_VARIATION,                   "MT_THERMALLY_LIMITED_VARIATION" },
 
@@ -1757,8 +1757,8 @@ const std::map<PROGRAM_OPTION, PROPERTY_DETAILS> PROGRAM_OPTION_DETAIL = {
 
     { PROGRAM_OPTION::MT_FRACTION_ACCRETED,                                     { TYPENAME::DOUBLE,     "PO_MT_Fraction_Accreted",                   "-",         24, 15}},
     { PROGRAM_OPTION::MT_JLOSS,                                                 { TYPENAME::DOUBLE,     "PO_MT_JLoss",                               "-",         24, 15}},
-    { PROGRAM_OPTION::MT_JLOSS_MACLEOD_LINEAR_FRACTION_DEGEN,                   { TYPENAME::DOUBLE,     "PO_MT_JLoss_Macleod_Linear_Frac_Degen",     "-",         24, 15}},
-    { PROGRAM_OPTION::MT_JLOSS_MACLEOD_LINEAR_FRACTION_NON_DEGEN,               { TYPENAME::DOUBLE,     "PO_MT_JLoss_Macleod_Linear_Frac_Non_Degen", "-",         24, 15}},
+    { PROGRAM_OPTION::MT_JLOSS_LINEAR_FRACTION_DEGEN,                           { TYPENAME::DOUBLE,     "PO_MT_JLoss_Linear_Frac_Degen",             "-",         24, 15}},
+    { PROGRAM_OPTION::MT_JLOSS_LINEAR_FRACTION_NON_DEGEN,                       { TYPENAME::DOUBLE,     "PO_MT_JLoss_Linear_Frac_Non_Degen",         "-",         24, 15}},
     { PROGRAM_OPTION::MT_REJUVENATION_PRESCRIPTION,                             { TYPENAME::INT,        "PO_MT_Rejuvenation_Prscrptn",               "-",          4, 1 }},
     { PROGRAM_OPTION::MT_THERMALLY_LIMITED_VARIATION,                           { TYPENAME::INT,        "PO_MT_Thermally_Lmtd_Variation",            "-",          4, 1 }},
 

src/Options.cpp

@@ -483,8 +483,8 @@ void Options::OptionValues::Initialise() {
 
     // Mass transfer angular momentum loss prescription options
     m_MassTransferJloss                                             = 1.0;
-    m_MassTransferJlossMacLeodLinearFractionDegen                   = 0.5;
-    m_MassTransferJlossMacLeodLinearFractionNonDegen                = 0.5;
+    m_MassTransferJlossLinearFractionDegen                          = 0.5;
+    m_MassTransferJlossLinearFractionNonDegen                       = 0.5;
 
     m_MassTransferAngularMomentumLossPrescription.type              = MT_ANGULAR_MOMENTUM_LOSS_PRESCRIPTION::ISOTROPIC_RE_EMISSION;
     m_MassTransferAngularMomentumLossPrescription.typeString        = MT_ANGULAR_MOMENTUM_LOSS_PRESCRIPTION_LABEL.at(m_MassTransferAngularMomentumLossPrescription.type);
@@ -1491,14 +1491,14 @@ bool Options::AddOptions(OptionValues *p_Options, po::options_description *p_Opt
             ("Fraction of specific angular momentum which non-accreted matter removes from the system (default = " + std::to_string(p_Options->m_MassTransferJloss) + ")").c_str()
         )
         (
-            "mass-transfer-jloss-macleod-linear-fraction-degen",
-            po::value<double>(&p_Options->m_MassTransferJlossMacLeodLinearFractionDegen)->default_value(p_Options->m_MassTransferJlossMacLeodLinearFractionDegen),                                                                                    
-            ("Interpolation fraction for jloss prescription for degenerate accretors, requires --mass-transfer-angular-momentum-loss-prescription=MACLEOD_LINEAR. 0 is gamma_acc, 1 is gamma_L2 (default = " + std::to_string(p_Options->m_MassTransferJlossMacLeodLinearFractionDegen) + ")").c_str()
+            "mass-transfer-jloss-linear-fraction-degen",
+            po::value<double>(&p_Options->m_MassTransferJlossLinearFractionDegen)->default_value(p_Options->m_MassTransferJlossLinearFractionDegen),                                                                                    
+            ("Interpolation fraction for jloss prescription for degenerate accretors, requires --mass-transfer-angular-momentum-loss-prescription=MACLEOD_LINEAR or KLENCKI_LINEAR. 0 is gamma_acc, 1 is gamma_L2 (default = " + std::to_string(p_Options->m_MassTransferJlossLinearFractionDegen) + ")").c_str()
         )
         (
-            "mass-transfer-jloss-macleod-linear-fraction-non-degen",
-            po::value<double>(&p_Options->m_MassTransferJlossMacLeodLinearFractionNonDegen)->default_value(p_Options->m_MassTransferJlossMacLeodLinearFractionNonDegen),                                                                                    
-            ("Interpolation fraction for jloss prescription for non-degenerate accretors, requires --mass-transfer-angular-momentum-loss-prescription=MACLEOD_LINEAR. 0 is gamma_acc, 1 is gamma_L2 (default = " + std::to_string(p_Options->m_MassTransferJlossMacLeodLinearFractionNonDegen) + ")").c_str()
+            "mass-transfer-jloss-linear-fraction-non-degen",
+            po::value<double>(&p_Options->m_MassTransferJlossLinearFractionNonDegen)->default_value(p_Options->m_MassTransferJlossLinearFractionNonDegen),                                                                                    
+            ("Interpolation fraction for jloss prescription for non-degenerate accretors, requires --mass-transfer-angular-momentum-loss-prescription=MACLEOD_LINEAR or KLENCKI_LINEAR. 0 is gamma_acc, 1 is gamma_L2 (default = " + std::to_string(p_Options->m_MassTransferJlossLinearFractionNonDegen) + ")").c_str()
         )
         (
             "mass-transfer-thermal-limit-C",                               
@@ -5045,8 +5045,8 @@ COMPAS_VARIABLE Options::OptionValue(const T_ANY_PROPERTY p_Property) const {
 
         case PROGRAM_OPTION::MT_FRACTION_ACCRETED                           : value = MassTransferFractionAccreted();                                       break;
         case PROGRAM_OPTION::MT_JLOSS                                       : value = MassTransferJloss();                                                  break;
-        case PROGRAM_OPTION::MT_JLOSS_MACLEOD_LINEAR_FRACTION_DEGEN         : value = MassTransferJlossMacLeodLinearFractionDegen();                        break; 
-        case PROGRAM_OPTION::MT_JLOSS_MACLEOD_LINEAR_FRACTION_NON_DEGEN     : value = MassTransferJlossMacLeodLinearFractionNonDegen();                     break; 
+        case PROGRAM_OPTION::MT_JLOSS_LINEAR_FRACTION_DEGEN                 : value = MassTransferJlossLinearFractionDegen();                               break; 
+        case PROGRAM_OPTION::MT_JLOSS_LINEAR_FRACTION_NON_DEGEN             : value = MassTransferJlossLinearFractionNonDegen();                            break; 
         case PROGRAM_OPTION::MT_REJUVENATION_PRESCRIPTION                   : value = static_cast<int>(MassTransferRejuvenationPrescription());             break;
         case PROGRAM_OPTION::MT_THERMALLY_LIMITED_VARIATION                 : value = static_cast<int>(MassTransferThermallyLimitedVariation());            break;