Turnover mess

[jordanflitter]

We use turnover masses to regulate star formation in too massive/light halos ("duty cycle"). This the mathematical model we use for the duty cycle:

$$ f_\mathrm{duty}^\mathrm{ACG}\left(M_h\right)=\exp\left(-M_\text{turn-lower}^\mathrm{ACG}/M_h\right) $$ $$ f_\mathrm{duty}^\mathrm{MCG}\left(M_h\right)=\exp\left(-M_\text{turn-lower}^\mathrm{MCG}/M_h\right)\exp\left(-M_h/M_\text{turn-upper}^\mathrm{MCG}\right) $$

Apparently, as was noted in #688, there have been some changes in the logic in how to determine the turnover masses between v3 and v4, at least when mini-halos are turned on (this creates some confusion, like in #726).

Turnover masses in spin temperature calculations in v4 (SOURCE_MODEL=“E-INTEGRAL”, USE_MINI_HALOS=True)

• ACG lower turnover mass is given by the maximum between M_TURN and the output of atomic_cooling_threshold(z’’)
• MCG upper turnover mass is given by the output of atomic_cooling_threshold(z’’)
• MCG lower turnover mass is given by (the filtered version of) the maximum between M_TURN and the output of lyman_werner_threshold(z’) (note the latter function is evaluated at z', not z'')

Turnover masses in spin temperature calculations in v3 (USE_MINI_HALOS=True)

• ACG lower turnover mass is given by the output of atomic_cooling_threshold(z’’) - This is a bit different than what we have in v4! (since there is no max operation between that value and M_TURN)
• MCG upper turnover mass is given by the output of atomic_cooling_threshold(z’’)
• MCG lower turnover mass is given by (the filtered version of) the maximum between between the output of lyman_werner_threshold(z’) with the local LW flux and v_cb, and the output of lyman_werner_threshold(z’) with zero LW flux and VAVG (if we have FIX_VCB_AVG=True). There is also protection that this value will not be greater than pow(10, LOG10_MTURN_MAX)=1e10. - This is different than what we have in v4!

Moreover, the logic for the turnover masses in v4 depends on the chosen SOURCE_MODEL. For example, if SOURCE_MODEL="L-INTEGRAL" (or has discrete halos) and USE_MINI_HALOS=True, then the ACG (MCG) lower turnover mass is taken to be the maximum between (1) M_TURN, (2) reionization feedback mass and (3) output of atomic_cooling_threshold(z) (lyman_werner_threshold(z)). The difference in the logics between different source models is confusing and makes it much more difficult to compare between them!

Finally, in both v3 and v4, if USE_MINI_HALOS=False, then the ACG lower turnover mass is just M_TURN, while completely ignoring the atomic cooling threshold and the reionization feedback. It's very confusing that ACG properties (e.g. emissivities/fluxes) depend on whether or not MCGs/mini-halos are present in the simulation.

After discussing with @andreimesinger and @steven-murray we agreed that we should:

• Rename the astro param M_TURN -> M_TURN_STELLAR_FEEDBACK, since the current name is very confusing! (we should have a deprecation warning that tells users that M_TURN is deprecated)
• Set M_TURN_STELLAR_FEEDBACK default to 5 if USE_MINI_HALOS=True, or 8.7 otherwise. Update: this is not possible since M_TURN_STELLAR_FEEDBACK lives in AstroParams, while USE_MINI_HALOS lives in AstroOptions!
• Raise a warning if the user sets M_TURN_STELLAR_FEEDBACK on a value larger than 6 with USE_MINI_HALOS=True. Update: apparently we already had this warning (with the lower threshold being 8). I did however change the warning message to stress that such configuration doesn't make sense!
• Fix the above logic in v4! The ACG lower turnover mass should be identical to the MCG upper turnover mass!
• Fix the above logic in v4! Make the logic for the turnover masses to be the same, regardless the chosen SOURCE_MODEL (up to the known bug in SpinTemperatureBox.c where the reionization feedback cannot be accounted since that module does not receive the previous IonizedBox - see Reionization feedback is ignored in SpinTemperatureBox.c when SOURCE_MODEL being "E-INTEGRAL" or "CONST-ION-EFF" #470).
• Introduce a new REIONIZATION_FEEDBACK_MODEL enum with the options "NONE", "ACG", "MCG", and "BOTH". This would make it easier to determine whether the ACG turnover mass should be inhomogeneous or not.
• Fix the above logic in v4! The ACG lower turnover mass should be the same, regardless if USE_MINI_HALOS is True or False.
• In a new markdown file called M_TURN.rst, document the current logic of the turnover masses in v4 + their logic history in previous versions. Specify any current inconsistencies we have in the code at the moment (e.g. Reionization feedback is ignored in SpinTemperatureBox.c when SOURCE_MODEL being "E-INTEGRAL" or "CONST-ION-EFF" #470).
• Also mention the logic change between v3 and v4 in updates_from_v3.rst.