Updated MSP treatments.

[yuzhesong]

Replaces #1082

Includes pulsar accretion treatments calculated with BOOST ODE integrator and other fixes, including solution to #1002

[ilyamandel]

Options.cpp:

    if (!DEFAULTED("neutron-star-accretion-in-ce")) {                                                                         // neutron star accretion in common envelope
        std::tie(found, m_NeutronStarAccretionInCE.type) = utils::GetMapKey(m_NeutronStarAccretionInCE.typeString, NS_ACCRETION_IN_CELabel, m_NeutronStarAccretionInCE.type);
        COMPLAIN_IF(!found, "Unknown Neutron Star Equation of State");
    }

Why is the complaint about an unknown NS EoS? This is about accretion, not EoS...

Same file,

    case _("neutron-star-accretion-in-ce")                      : POPULATE_RET(NS_ACCRETION_IN_CELabel);                        break;
    case _("neutron-star-equation-of-state")                    : POPULATE_RET(NS_EOSLabel);                                    break;

Format / capitalisation of labels different from other labels?

changelog.h:

• comments should be edited for English grammar
• "deltaAngularMomentumByPulsarAccretion()" -- that's not the name of the function, check capitalisation
• "- Update to NS::UpdateMagneticFieldAndSpin(), specifically adding" <- adding what?

A new option has been added. That means:

• the program options documentation needs to be updated accordingly
• a new default YAML should be created
• whats-new.rst should probably be updated

NS.cpp:

• comments for DeltaAngularMomentumByPulsarAccretion need to be adjusted for English grammar (e.g., "Calculate the magnetic field... and also returns"), correct capitalisation of function name, correct number and list of return variables in the tuple (the comment sometimes lists three, sometimes four -- the function returns three), correct ordering and list of input parameters, etc.

Do we need to pass parameters like p_Mass? This does not appear to be a static function, and a neutron star known its own mass -- would the argument passed in ever be different than m_Mass? Ditto for some of the other variables.

Why p_MassGainPerTimeStep? Isn't the important thing just the mass gain?

double newPulsarMagneticField = (initialMagField_G - magFieldLowerLimit_G) * exp(-p_MassGainPerTimeStep / p_Kappa) + magFieldLowerLimit_G;

If initialMagField_G was, say, zero to begin with, it will end up having a non-zero value but still one less than magFieldLowerLimit_G. I don't understand the logic...

More to come later.

[ilyamandel]

Aside: @yuzhesong , if this replaces #1082 , can we delete that one?

[yuzhesong]

@ilyamandel

Thanks for the review! Making changes to the codes...

To some of your points:

Do we need to pass parameters like p_Mass? This does not appear to be a static function, and a neutron star known its own mass -- would the argument passed in ever be different than m_Mass? Ditto for some of the other variables.

NS::DeltaAngularMomentumByPulsarAccretion() is used for the integration for NS in RLOF as a dynamic ODE, so certain parameters needs to be updated. mass, magnetic field, spin frequency etc are all updated throughout all iterations.

Why p_MassGainPerTimeStep? Isn't the important thing just the mass gain?

p_MassGainPerTimeStep is the mass gain for that specific time step. If the name is confusing, I can change it to p_MassGain.

double newPulsarMagneticField = (initialMagField_G - magFieldLowerLimit_G) * exp(-p_MassGainPerTimeStep / p_Kappa) + magFieldLowerLimit_G;

If initialMagField_G was, say, zero to begin with, it will end up having a non-zero value but still one less than magFieldLowerLimit_G. I don't understand the logic...

I don't quite understand the issue with this? It's following Eq. 12 in arxiv:1912.02415 to calculate the decay of magnetic field from mass accretion. There wouldn't be any physical situation in a NS's evolution for the magnetic field to be low enough, certainly not zero. The magnetic field needs to be evolved from a certain value, either decays through spin down or mass accretion. The birth value is drawn from a distribution specified by the program options, and the lower limit of magnetic field should be always lower than that entire distribution.

Aside: @yuzhesong , if this replaces #1082 , can we delete that one?

Yes, #1082 can be deleted

[jeffriley]

Placeholder - I have some changes I'd like made.

[ilyamandel]

Just a quick note that I have to go offline now (else I'll have to swim over to Tasmania as the ferry will leave without me), so I'll have to return to the review, which I haven't quite finished, in January of 2025. Happy New Year!

[jeffriley]

In addition to @ilyamandel's comments:

In void NS::CalculateAndSetPulsarParameters() you have the following code:

m_PulsarDetails.spinPeriod    = CalculateBirthSpinPeriod();                                         // spin period in ms
m_PulsarDetails.spinFrequency = _2_PI / (m_PulsarDetails.spinPeriod * SECONDS_IN_MS);

CalculateBirthSpinPeriod() can return a value of 0.0 by design (e.g. when OPTIONS->PulsarBirthSpinPeriodDistribution() == ZERO, which is actually the default), which results in a divide-by-zero error - and sets
m_PulsarDetails.spinFrequency to INF, and we then use that value as a parameter to NS::CalculateSpinDownRate(), propagating the error...

At a minimum there should be a check here for spin period = 0.0, but if the user has specified pulsar-birth-spin-period-distribution ZERO (or left it at the default value), it seems to me we don't need to call NS::CalculateAndSetPulsarParameters() at all,

NS::SpinDownIsolatedPulsar() also divides by m_PulsarDetails.spinFrequency - do we even need to call NS::SpinDownIsolatedPulsar() if m_PulsarDetails.spinFrequency == 0.0? At least put a check at the top of the function to check for zero spin and exit immediately.

Ditto for NS::UpdateMagneticFieldAndSpin() - can wet put a check at the top of the function to check for zero spin and exit immediately?

How much of the pulsar code can we actually avoid (and should avoid to prevent divide-by-zero errors) if we know the star is not spinning?

[yuzhesong]

@jeffriley

Added solution to issue #1257

[ilyamandel]

@yuzhesong :

p_MassGainPerTimeStep is the mass gain for that specific time step. If the name is confusing, I can change it to p_MassGain.

That sounds like a good solution.

double newPulsarMagneticField = (initialMagField_G - magFieldLowerLimit_G) * exp(-p_MassGainPerTimeStep / p_Kappa) + magFieldLowerLimit_G;

If initialMagField_G was, say, zero to begin with, it will end up having a non-zero value but still one less than magFieldLowerLimit_G. I don't understand the logic...

I don't quite understand the issue with this? It's following Eq. 12 in arxiv:1912.02415 to calculate the decay of magnetic field from mass accretion. There wouldn't be any physical situation in a NS's evolution for the magnetic field to be low enough, certainly not zero. The magnetic field needs to be evolved from a certain value, either decays through spin down or mass accretion. The birth value is drawn from a distribution specified by the program options, and the lower limit of magnetic field should be always lower than that entire distribution.

I would not assume that initialMagField_G is lower than magFieldLowerLimit_G. You never know in advance what silly choices someone else might make. :-) A safer solution could be as follows:

double newPulsarMagneticField = initialMagField_G < magFieldLowerLimit_G ? magFieldLowerLimit_G : (initialMagField_G - magFieldLowerLimit_G) * exp(-p_MassGainPerTimeStep / p_Kappa) + magFieldLowerLimit_G;

[ilyamandel]

double p = R_CM_6 * R_CM_6 / (mass_g * mass_g * mDot);

in NS::DeltaAngularMomentumByPulsarAccretion_Static()

This is not correct and does not match Eq. (10) of https://www.arxiv.org/pdf/1912.02415 (see powers of M and Mdot).

@yuzhesong , typos happen, but this is going very slowly because typos seem to be particularly common in this code and we are all busy... I suggest that you check that your code is yielding correct results (as compared to some alternative code that you write independently, say, in Python or Matlab) for a range of parameter choices -- otherwise, we'll be reviewing this for a while. ;-)

[Aside: if you haven't done it yet, I would also personally recommend re-deriving quantities like the Alfven radius yourself; I find that once you've derived something and therefore understood the scalings, copy-paste typo errors when copying equations are less likely.]