This web documentation corresponds to the most recent MESA release (r10398). Documentation for past versions can be found here.
If you find errors or formatting issues, please email Josiah Schwab using this link.
This page documents the MESA options that are part of the binary_controls namelist. It is autogenerated from the file $MESA_DIR/binary/defaults/binary_controls.defaults.
Boxes like
show the default value of each option. To override the default values, add an entry to the binary_controls namelist in your inlist.
Contents 
specifications for starting model ¶
m1 ¶
Initial mass of star 1 in Msun units. Not used when loading a saved model.
same caveats as initial_mass
in star/defaults/controls.defaults apply
m2 ¶
Initial mass of star 2 in Msun units. Not used when loading a saved model.
same caveats as initial_mass
in star/defaults/controls.defaults apply
initial_period_in_days ¶
Initial orbital period in days.
initial_separation_in_Rsuns ¶
Initial separation measured in Rsuns. Only used when initial_period_in_days < 0
initial_eccentricity ¶
Initial eccentricity of the system
controls for output ¶
history_name ¶
Name of file for binary output
history_interval ¶
append an entry to the history.data file when
mod(model_number, history_interval) = 0
.
append_to_star_history ¶
If true, then the columns from the binary_history
are also included
in each of the stars history files.
NOTE: if .false., then pgstar cannot access binary data
log_directory ¶
Directory for binary output
history_dbl_format ¶
history_int_format ¶
history_txt_format ¶
Format for double, int and text in binary output
photo_interval ¶
photo_digits ¶
These overwrite the numbers set for photo_interval
and photo_digits
for each
star, so that profiles are outputted simultaneously
terminal_interval ¶
write info to terminal when mod(model_number, terminal_interval) = 0
.
write_header_frequency ¶
output the log header info to the terminal when
mod(model_number, write_header_frequency*terminal_interval) = 0
.
extra_binary_terminal_output_file ¶
if not empty, output terminal info to this file in addition to terminal.
this does not capture all of the terminal output – just the common items.
it is intended for use in situations where you cannot directly see the terminal
output such as when running on a cluster. if you want to be able to monitor
the progress for such cases, you can set extra_binary_terminal_output_file = 'log'
and then do tail f log to view the terminal output as it is recorded in the file.
timestep controls ¶
The terminal output during evolution includes a short string for the ‘dt_limit’. This is to give you some indication of what is limiting the time steps. Here’s a dictionary mapping those terminal strings to the corresponding control parameters. These only include limits from binary, to see the limits from star refer to star/default/controls.defaults
terminal output related parameter
'b_companion' timestep limited by companion
'b_RL' fr
'b_jorb' fj
'b_envelope' fm
'b_separation' fa
'b_eccentricity' fe
'b_deltam' fdm
fm ¶
fa ¶
fr ¶
fj ¶
fe ¶
Timestep controls based on relative changes. After each step an upper limit is set on the timestep based on changes on different quantities. If the quantity is X and the change in one timestep dX, then this limit is given by
dt_next_max = dt * fX*abs(X / dX)
each of these controls deals with the following:
 fm: envelope mass
 fa: binary separation
 fr: change in (rrl)/rl
 fj: change in orbital angular momentum
 fe: change in orbital eccentricity
fm_limit ¶
fr_limit ¶
fe_limit ¶
Limits to timestep controls give by fm, fr and fe. As these three quantities evolve naturally to zero, following strictly the timestep limit given by fX would reduce timesteps infinetely. These fX_limit avoid this problem by computing the limit to the timestep as
dt_next_max = dt * fX*abs(max(abs(X),fX_limit) / dX)
If any of these fX_limit
is smaller than zero it is ignored.
fr_dt_limit ¶
Minimum timestep limit allowed for the fr control in years.
fdm ¶
Limits the timestep based on the expected fractional change of mass of the donor,
dt_next_max = fdm * s% mstar / abs(s% star_mdot)
dt_softening_factor ¶
Weight factor to average max_timestep
with old one (in log space) as in
dt_next_max = 10**(dt_softening_factor*log10(dt_next_max_old) + &
(1dt_softening_factor)*log10(dt_next_max))
where dt_next_max_old
is the limit used in the previous step. This is meant
to avoid large changes in dt. Values must be < 1 and >= 0.
varcontrol_{stage} ¶
Allows binary to set varcontrol_target
for each star depending on the
stage of evolution. Ignored if < 0. Each one controls the following stages,

varcontrol_case_a
:varcontrol_target
for both stars during mass transfer from a core hydrogen burning star. 
varcontrol_case_b
:varcontrol_target
for both stars during mass transfer from a core hydrogen depleted star. 
varcontrol_ms
:varcontrol_target
for a star that has not depleted core H. 
varcontrol_post_ms
:varcontrol_target
for a star that has depleted core H.
when to stop ¶
accretor_overflow_terminate ¶
terminate evolution if (rrl)/rl is bigger than this for accretor
terminate_if_initial_overflow ¶
terminate evolution if first model of run is overflowing
terminate_if_L2_overflow ¶
terminate evolution if there is overflow through the second Lagrangian point Amount of overflow needed to reach L2 implemented as in Marchant et al. (2016), A&A, 588, A50
mass transfer controls ¶
ignore_rlof ¶
If true, then ignore Roche lobe overflow (i.e., no mass will be transferred)
mass_transfer_* ¶
Transfer efficiency controls. alpha, beta, delta and gamma parameters as described in Tauris & van den Heuvel 2006 section 16.4.1, transfer efficiency is given by 1alphabetadelta.
These only affect mass that is lost from the donor due to mass transfer, winds from each star will carry away angular momentum from the vicinity of each even when transfer efficiency is unity. Each of these represent the following:
 alpha : fraction of mass lost from the vicinity of the donor as fast wind
 beta : fraction of mass lost from the vicinity of the accretor as fast wind
 delta : fraction of mass lost from circumbinary coplanar toroid
 gamma : radius of the circumbinary coplanar toroid is
gamma**2 * orbital_separation
limit_retention_by_mdot_edd ¶
Limit accretion using mdot_edd
. The current implementation is intended for use with
black hole accretors, as in e.g. Podsiadlowski, Rappaport & Han (2003), MNRAS, 341, 385.
For other accretors mdot_edd
should be set with use_this_for_mdot_edd
, the hook
use_other_mdot_edd
, or by appropriately setting use_this_for_mdot_edd_eta
.
Note: MESA versions equal or lower than 8118 used eta=1 and did not correct
the accreted mass for the energy lost by radiation.
If accreted material radiates an amount of energy equal to L=eta*mtransfer_rate*clight**2
,
then accretion is assumed to be limited to the Eddington luminosity,
Ledd = 4*pi*cgrav*Mbh*clight/kappa
which results in the Eddington massaccretion rate
mdot_edd = 4*pi*cgrav*Mbh/(kappa*clight*eta)
the efficiency eta is determined by the properties of the last stable circular orbit, and for a BH with no initial spin it can be expressed in terms of the initial BH mass Mbh0 and the current BH mass,
eta = 1sqrt(1(Mbh/Mbh0)**2)
for Mbh < sqrt(6) Mbh0. For BHs with initial spins different from zero, an effective Mbh0 can be computed, corresponding to the mass the black hole would have needed to have with zero spin to reach the current mass and spin.
use_es_opacity_for_mdot_edd ¶
If .true., then the opacity for mdot_edd
is computed as 0.2*(1+X)
If .false., the opacity of the outermost cell of the donor is used
use_this_for_mdot_edd_eta ¶
Fixed mdot_edd_eta
, if negative, eta will be computed consistently as material is accreted.
Values should be between ~0.060.42, the minimum corresponding to a BH with spin parameter a=0, and the maximum to a=1.
use_radiation_corrected_transfer_rate ¶
If true, then reduce the increase in mass of the BH to account for the radiated energy eta*mtransfer_rate_clight**2
so that in a timestep
delta_Mbh = (1eta)*mass_transfer_rate*dt
initial_bh_spin ¶
Initial spin parameter of the black hole “a”. Must be between 0 and 1. Evolution of BH spin is done with eq. (6) of King & Kolb (1999), MNRAS, 305, 654
use_this_for_mdot_edd ¶
Fixed mdot_edd
in Msun/yr, ignored if negative
mdot_scheme ¶
How to compute mass transfer. Options are:
 “Ritter” : Ritter 1988, A&A, 202, 93
 “Kolb” : Optically thick overflow of Kolb & Ritter 1990, A&A, 236, 385
 “roche_lobe” : Set mass transfer rate such that the donor remains inside its Roche lobe. Only works implicitly.
 “contact” : Extends the roche_lobe scheme to include contact systems as in Marchant et al. (2016), A&A, 588, A50
explicit mass transfer computation. ¶
MESA can compute mass transfer rates either explicitly (at the beggining
of the step) or implicitly (iterating the solution until the mass transfer
rate matches the value computed at the end of the step). The explicit method
is used if max_tries_to_achieve <= 0
.
cur_mdot_frac ¶
Average the explicit mass transfer rate computed with the old in order to smooth large changes.
mass_transfer = mass_transfer_old * cur_mdot_frac + (1cur_mdot_frac) * mass_transfer
max_explicit_abs_mdot ¶
Limit the explicit mass transfer rate to max_explicit_abs_mdot
, in Msun/secyer
implicit mass transfer computation. ¶
max_tries_to_achieve ¶
The implicit method will modify the mass transfer rate and redo the step until
it either finds a solution, or the number of tries goes above max_tries_to_achieve
.
if max_tries_to_achieve <= 0
the explicit method is used.
implicit_scheme_tolerance ¶
Tolerance for which a solution is considered valid. For the Ritter and Kolb schemes if we call mdot the mass transfer rate used for the step, and mdot_end the one computed at the end of it, a solution is valid if
(mdotmdot_end)/mdot_end < b% implicit_scheme_tolerance
For the roche_lobe scheme, a solution will be considered valid if
implicit_scheme_tolerance < (rrl)/rl < 0
When using the roche_lobe scheme smaller values of order 1d3 or smaller are recommended.
initial_change_factor ¶
change_factor_fraction ¶
implicit_lambda ¶
The implicit scheme works by adjusting the mass transfer rate from the previous
step until it finds a solution. If the mass transfer needs to increase/reduce after
a try, then it is multiplied/divided by change_factor
. initial_change_factor
provides
the initial value for this parameter, however, since at certain points the mass
transfer rate will increase steeply and at others remain mostly constant from step
to step, MESA adjusts the value of the change factor to make it easier to find
solutions. Whenever the mass transfer rate changes from the previous value, MESA
will modify the change_factor
according to:
if(mass_transfer_rate < mass_transfer_prev) then
change_factor = change_factor*(1.0implicit_lambda) &
+ implicit_lambda*(1+change_factor_fraction*(mass_transfer_rate/mass_transfer_prev1))
else
change_factor = change_factor*(1.0implicit_lambda) &
+ implicit_lambda*(1+change_factor_fraction*(mass_transfer_prev/mass_transfer_rate1))
change_factor = change_factor*(1.0implicit_lambda) &
+ implicit_lambda*(1+change_factor_fraction*(mass_transfer_rate/mass_transfer_prev1))
end if
Choosing implicit_lambda = 0
will keep the change factor constant.
max_change_factor ¶
min_change_factor ¶
Maximum and minimum values for the change_factor
num_tries_for_increase_change_factor ¶
change_factor_increase ¶
If after every num_tries_for_increase_change_factor
iterations the implicit scheme does not have upper
and lower bounds for the mass transfer rate, multiply change_factor
by change_factor_increase
. Ignored if
num_tries_for_increase_change_factor < 1
. Increase is limited to max_change_factor
.
starting_mdot ¶
When using the roche_lobe
scheme, if the donor overflows for the first time
use starting_mdot
(in Msun/secyer) as an initial guess for the mass transfer rate.
roche_min_mdot ¶
When using the roche_lobe
scheme, if mass transfer rate is below roche_min_mdot
(in Msun/secyer) and the donor is not overflowing its roche lobe, assume detachment
and stop mass transfer.
min_mdot_for_implicit ¶
For any choice except for the roche_lobe
scheme mass transfer will be computed explicitly
until the explicit computation of mdot is > min_mdot_for_implicit
(in Msun/secyer),
even if max_tries_to_achieve
> 0. This is to avoid spending many iterations when the stars
are detached and the explicit calculation gives very low values of mdot.
max_implicit_abs_mdot ¶
Limit the implicit mass transfer rate to max_implicit_abs_mdot
, in Msun/secyer
report_rlo_solver_progress ¶
Set true to see info about the iterations to compute mass transfer from RLOF
Tidal wind enhancement ¶
do_enhance_wind_* ¶
Use the Tout & Eggleton mechanism to tidally enhance the wind mass loss from one or both components according to:
Mdot_w = Mdot_w * ( 1 + B_wind * min( (R/RL)^6, 0.5^6 ) )
Tout & Eggleton 1988,MNRAS,231,823 (eq. 2)
“_1” refers to first star, “_2” to the second one.
tout_B_wind_* ¶
The B_wind
parameter from the previous equation. Default value is
taken from Tout & Eggleton 1988,MNRAS,231,823
“_1” refers to first star, “_2” to the second one.
Wind mass accretion ¶
do_wind_mass_transfer_* ¶
transfer part of the mass lost due to stellar winds from the mass losing component to its companion. Using the BondyHoyle mechanism. “_1” refers to first star, “_2” to the second one.
wind_BH_alpha_* ¶
BondyHoyle accretion parameter for each star. The default is 3/2 taken from Hurley et al. 2002, MNRAS, 329, 897, in agreement with Boffin & Jorissen 1988, A&A, 205, 155 “_1” refers to first star, “_2” to the second one.
max_wind_transfer_fraction_* ¶
Upper limit on the wind transfer fraction for star * “_1” refers to first star, “_2” to the second one.
orbital jdot controls ¶
do_jdot_gr ¶
Include gravitational wave radiation in jdot
do_jdot_ml ¶
Include loss of angular momentum via mass loss. The parameters
mass_transfer_*
determine the fractions of mass lost from the vincinity
of the donor, the accretor, or a circumbinary coplanar toroid.
do_jdot_ls ¶
Fix jdot such that the total angular momentum of the system is conserved, except for loses due to other jdot mechanisms, or angular momentum loss from winds. This is meant to take care of LS coupling due to tides.
do_jdot_missing_wind ¶
Usually MESA computes stellar AM loss due to winds by taking the angular momentum from
the removed layers of the star. However, when mass transfer is included, wind mass
loss and mass accretion are added up, and only the remainder, if corresponding to
net mass loss, contributes to stellar AM loss. jdot_missing_wind
compensates for this,
by removing from the orbit an amount of angular momentum equal to the mass lost
that does not contribute to stellar AM loss, times the specific angular momentum
at the surface.
do_jdot_mb ¶
Include magnetic braking as in Rappaport, Verbunt, and Joss. apj, 275, 713731. 1983.
include_accretor_mb ¶
If true, the contribution to jdot from magnetic braking of the accretor is also taken into account.
magnetic_braking_gamma ¶
gamma exponent for magnetic braking.
keep_mb_on ¶
If true keep magnetic braking even when radiative core goes away.
jdot_multiplier ¶
Multiply total jdot by this factor.
NOTE: jdot_ls
is not affected by this.
rotation and sync controls ¶
do_j_accretion ¶
If true, compute accretion of angular momentum following A.3.3 of de Mink et al. 2013, ApJ, 764, 166. Otherwise, incoming material is assumed to have the specific angular momentum of the surface of the accretor.
do_tidal_sync ¶
If true, apply tidal torque to the star
sync_type_* ¶
Timescale for orbital synchronisation. “_1” refers to first star, “_2” to the second one. Options are:
 “Instantaneous” : Keep the star synced to the orbit.
 “Orb_period” : Sync in the timescale of the orbital period.
 “Hut_conv” : Sync timescale following Hurley et al. 2002, MNRAS, 329, 897 for convective envelopes.
 “Hut_rad” : Sync timescale following Hurley et al. 2002, MNRAS, 329, 897 for radiative envelopes.
 “None” : No sync for this star.
sync_mode_* ¶
Where angular momentum is deposited for synchronization. “_1” refers to first star, “_2” to the second one. Options are:
 “Uniform” : Each layer is synced independently given the sync timescale.
Ftid_* ¶
Tidal strength factor. Synchronisation and circularisation timescales are divided by this. “_1” refers to first star, “_2” to the second one.
do_initial_orbit_sync_* ¶
Relax rotation of star to orbital period at the beggining of evolution. “_1” refers to first star, “_2” to the second one.
tidal_reduction ¶
tidal_reduction
accounts for the reduction in the effectiveness of convective
damping of the equilibrium tide when the tidal forcing period is less than the
convective turnover period of the largest eddies. It corresponds to the exponent
in eq. (32) of Hurley et al. 2002, MNRAS, 329, 897
tidal_reduction
= 1 follows Zahn(1966, 1989), while tidal_reduction
= 2 follows
Goldreich & Nicholson (1977).
eccentricity controls ¶
do_tidal_circ ¶
If true, apply tidal circularisation
circ_type_* ¶
Mechanism for circularisation. Options are: “_1” refers to first star, “_2” to the second one.
 “Hut_conv” : Circ timescale following Hurley et al. 2002, MNRAS, 329, 897 for convective envelopes.
 “Hut_rad” : Circ timescale following Hurley et al. 2002, MNRAS, 329, 897 for radiative envelopes.
 “None” : no tidal circularisation
use_eccentricity_enhancement ¶
Flag to turn on Soker eccentricity enhancement
max_abs_edot_tidal ¶
Maximum absolute value for tidal edot (in 1/s). If the computed tidal edot goes above this, then it is fixed at this maximum
max_abs_edot_enhance ¶
Maximum absolute value for eccentricity enhancement (in 1/s). If the computed edot goes above this, then it is fixed at this maximum
min_eccentricity ¶
If after a step eccentricity < min_eccentricity
, then fix it at this value
max_eccentricity ¶
If after a step eccentricity > max_eccentricity
, then fix it at this value
anomaly_steps ¶
For phase dependent processes, the orbit is divided into this number of steps in the true anomaly, to integrate through a full orbit and obtain the secular changes
irradiation controls ¶
accretion_powered_irradiation ¶
Flag to turn on irradiation of the donor due to accretion onto a compact object.
accretor_radius_for_irrad ¶
Radius in cm for accreting object, e.g., 10km for ns.
col_depth_for_eps_extra ¶
Energy from irradiation will be deposited in the outer
4*Pi*R^2*col_depth_for_eps_extra
grams of the star.
use_accretor_luminosity_for_irrad ¶
Flag to turn on irradiation based on the luminosity of the accretor and binary
separation. Requires evolve_both_stars = .true.
in binary_job inlist.
irrad_flux_at_std_distance ¶
std_distance_for_irradiation ¶
If irrad_flux_at_std_distance > 0
then irradiation flux is computed as
s% irradiation_flux = b% irrad_flux_at_std_distance * &
(b% std_distance_for_irradiation/b% separation)**2
max_F_irr ¶
Limit irradiation by this amount.
miscellaneous controls ¶
keep_donor_fixed ¶
keep star 1 as donor, even if accretor is closer to filling roche lobe
mdot_limit_donor_switch ¶
Do not change donor if mass transfer is larger than this (given in Msun/secyer). Avoids erratic changes when both stars are filling their roche loches.
use_other_{hook} ¶
Logicals to deploy the use_other routines.