Configuration files for COSMIC

How to write a configuration file

The cosmic-pop command-line executable cannot run without a configuration file. Each of the sections below lists inputs for COSMIC’s modified version of BSE. Each input has a description of the allowed values and an example of what that section might look like in the INI format; recommended default settings for many parameters are given after their description in boldface.

Here is a link to the most recent stable release version of the default inifile for COSMIC: Stable Version INIFILE

Here is a link to the unstable development version of the default inifile for COSMIC: Development Version INIFILE

filters

binary_state

Each binary system will end its evolution in one of three states

0 : the system is still a binary at the end its evolution

1 : the system merged before the end of its evolution

2 : the system was disrupted before the end of its evolution

timestep_conditions

timestep_conditions allow a user to pick specific time resolutions to print at targeted stages of the binary evolution. This is used in conjunction with the [bse] section value dtp to determine the timestep resolution for printing to the bcm array.

As an example, if you only want to print to the bcm array with 1.0 Myr timesteps while a binary has not merged or been disrupted you would specify this as:

timestep_conditions =[['binstate==0', 'dtp=1.0']]

Special examples include

timestep_conditions = 'dtp=None' : only the final time step is printed to the bcm array

timestep_conditions = 'dtp=1.0' : a single timestep applied to all evolutionary stages of the binary

[filters]
; binary_state determines which types of binaries endstates to retain
; 0 alive today, 1 merged, 2 disrupted
; default = [0,1]
binary_state = [0,1]

; timestep_conditions allow a user to pick specific time resolutions
; to print at targeted stages of the binary evolution
; This is used in conjunction with the [bse] section value dtp to determine the resolution
; at which thing are printed into the so called bcm array
; For example, if you only want dtp set to a value while the system is
; intact i.e. has not merged or been disrupted you could do so with the following
; timestep_conditions =[['binstate==0', 'dtp=1.0']]
; Special examples include
; timestep_conditions = 'dtp=None', only the final time step is printed to the bcm array
; timestep_conditions = 'dtp=1.0', a single timestep applied to all evolutionary stages of the binary
timestep_conditions = 'dtp=None'

sampling

`sampling_method`	Select which models to use to generate an initial sample of binary parameters at Zero Age Main Sequence `independent` : initialize binaries with independent parameter distributions for the primary mass, mass ratio, eccentricity, separation, and binary fraction `multidim` : initialize binaries with multidimensional parameter distributions according to Moe & Di Stefano 2017
`SF_start`	Sets the time in the past when star formation initiates in Myr. For a start time at the beginning of a Hubble time, specify: `SF_start` : 13700.0
`SF_duration`	Sets the duration of constant star formation from `SF_start` in Myr. For a single burst specify: `SF_duration` : 0.0 For a constant star formation over a Hubble time, specify: `SF_duration` : 13700.0
`metallicity`	Single value for the metallicity of the population. COSMIC expects an absolute metallicity (i.e., not units of zsun). For example, if you would like to run a population at Solar metallicity and specify zsun=0.02, you would want to set metallicity=0.02.

[sampling]
; Specify if you would like to sample initial conditions via
; the independent method (independent) or would like to sample
; initial conditions follow Moe & Di Stefano (2017) (multidim)
sampling_method = multidim

; Sets the time in the past when star formation initiates in Myr
SF_start = 13700.0

; Sets the duration of constant star formation in Myr
SF_duration = 0.0

; Metallicity of the population of initial binaries
metallicity = 0.02

[convergence]

`convergence_params`	A list of parameters you would like to verify have converged to a single distribution shape when running cosmic-pop from the command line. Options include: `mass_1`, `mass_2`, `sep`, `porb`, `ecc`, `massc_1`, `massc_2`, `rad_1`, `rad_2`
`convergence_limits`	Specifies limits for parameters included in the `convergence_params` list. For each parameter specified in `convergence_limits`, the lower and upper limit must be included. `convergence_limits = {'mass_1' : [5, 10], 'sep' : [0, 10]}`
`pop_select`	Selects the stage of the evolution at which you would like to check for convergence. This will filter for systems that satisfy the final_kstar1 and final_kstar2 selections from the command line call of cosmic-pop at the following states: `formation`: computes convergence on binary properties at formation with user-specified final kstars `1_SN`: computes convergence on binary properties just before the first supernova for the population with user-specified final kstars `2_SN`: computes convergence on binary properties just before the second supernova for the population with user-specified final kstars `disruption`: computes convergence on binary properties just before disruption of the population with user-specified final kstars `final_state`: computes convergence on binary properties after the full evolution specified by the user-supplied evolution time and with the user specified final kstars `XRB_form`: computes convergence on binary properties at the start of RLO following the first supernova on the population with user-specified final kstars
`match`	`match` provides the tolerance for the convergence calculation and is calculated as match = Log₁₀ (1-convergence) match = -5.0
`apply_convergence_limits`	`apply_convergence_limits` will filter the binary population, including the bcm, bpp, initCond, and kick_info DataFrames to only contain the binaries that satisfy the constraints from `convergence_limits` `True`: bcm, bpp, initCond, kick_info will contain only the binaries which are in the population that was used to check for convergence `False`: bcm, bpp, initCond, kick_info will contain all systems which satisfy the final kstar and pop_select selection and will not be filtered based on the convergence limits apply_convergence_limits = False

[convergence]
; A list of parameters you would like to verify have converged
; to a single distribution shape.
; Options include mass_1, mass_2, sep, porb, ecc, massc_1, massc_2
; rad_1, rad_2
convergence_params = [mass_1,mass_2,porb,ecc]

; convergence_limits is a dictionary that can contain limits for convergence params
; convergence_limits = {"mass_1" : [0, 20], "sep" : [0,5000]}
convergence_limits = {}

; formation computes convergence on binary properties
; at formation with user-specified final kstars

; 1_SN computes convergence on binary properties
; just before the first supernova for the population with
; user-specified final kstars

; 2_SN computes convergence on binary properties
; just before the second supernova for the population with
; user-specified final kstars

; disruption computes convergence on binary properties
; just before disruption of the population with
; user-specified final kstars

; final_state computes convergence on binary properties
; after the full evolution specified by the user-supplied evolution time
; and with the user specified final kstars

; XRB_form computes convergence on binary properties
; at the start of RLO following the first supernova on the population with
; user-specified final kstars
pop_select = formation

; apply_convergence_limits filters the evolved binary population
; to only the binaries that satisfy the convergence limits
; selection criteria if True
apply_convergence_limits = False

; match provides the tolerance for the convergence calculation
; and is calculated as match = log10(1-convergence)
; default = -5.0
match = -5.0

[rand_seed]

rand_seed

Seed used to for numpy.random.seed

[rand_seed]
; random seed int
seed = 42

[bse]

Note

Although this is all one section, we have grouped the flags/parameters which get passed to the binary stellar evolution code into types. Each group will start with a note to indicate the type of parameter or flag.

Note

SAMPLING FLAGS

pts1

determines the timesteps chosen in each evolution phase as decimal fractions of the time taken in that phase for Main Sequence (MS) stars

pts1 = 0.001 following Bannerjee+2019 for NS/BH progenitors

pts1 = 0.05 following Hurley+2000 for WD progenitors

pts2

determines the timesteps chosen in each evolution phase as decimal fractions of the time taken in that phase for Giant Branch (GB, CHeB, AGB, HeGB) stars

pts2 = 0.01 following Hurley+2000

pts3

determines the timesteps chosen in each evolution phase as decimal fractions of the time taken in that phase for HG, HeMS stars

pts3 = 0.02 following Hurley+2000

;;;;;;;;;;;;;;;;;;;;;;
;;; SAMPLING FLAGS ;;;
;;;;;;;;;;;;;;;;;;;;;;

; pts1,pts2,pts3 determine the timesteps chosen in each
;                 pts1 - MS                  (default = 0.001, see Banerjee+ 2019)
pts1 = 0.001
;                 pts2 - GB, CHeB, AGB, HeGB (default = 0.01)
pts2 = 0.01
;                 pts3 - HG, HeMS            (default = 0.02)
pts3 = 0.02

Note

METALLICITY FLAGS

zsun

Sets the metallicity of the Sun which primarily affects stellar winds. Note that the wind prescriptions are calibrated to zsun = 0.019 as described in Vink+2001.

zsun = 0.014 following Asplund 2009

;;;;;;;;;;;;;;;;;;;;;;;;;
;;; METALLICITY FLAGS ;;;
;;;;;;;;;;;;;;;;;;;;;;;;;
; specify the value for Solar metallicity, which primarily affects
; winds in BSE; note that Vink+2001 winds for OB stars are calibrated to zsun = 0.019
; default = 0.014 (Asplund 2009)
zsun = 0.014

Note

WIND FLAGS

`windflag`	Selects the model for wind mass loss for each star `0` : Standard SSE/BSE (Hurley+2000) `1` : StarTrack (Belczynski+2008) `2` : Metallicity dependence for O/B stars and Wolf Rayet stars (Vink+2001, Vink+2005) `3` : Same as 2, but LBV-like mass loss for giants and non-degenerate stars beyond the Humphreys-Davidson limit windflag = 3
`eddlimflag`	Adjusts the dependence of mass loss on metallicity for stars near the Eddington limit (see Grafener+2011, Giacobbo+2018). `0` : does not adjust metallicity dependence for stars near the Eddington limit `1` : adjusts metallicity dependence for stars near the Eddington limit as in Giacobbo+2018. eddlimflag = 0
`neta`	Reimers mass-loss coefficient (Equation 106 of SSE). Note: this equation has a typo. There is an extra ${\eta}$ out front; the correct rate is directly proportional to ${\eta}$ . See also Kurdritzki+1978, Section Vb for discussion. `positive value` : supplies ${\eta}$ to Equation 106 of SSE paper neta = 0.5
`bwind`	Binary enhanced mass loss parameter. See Equation 12 of BSE paper. `positive value` : supplies B_w to Equation 12 of BSE paper bwind = 0, inactive for single
`hewind`	Helium star mass loss parameter: 10^-13 hewind L^2/3 gives He star mass-loss. Equivalent to 1 - ${\mu}$ in the last equation on page 19 of SSE. hewind = 0.5
`beta`	Wind velocity factor: v_wind ² goes like beta. See Equation 9 of BSE paper. `negative value` : StarTrack (Belczynski+2008) `positive value` : supplies ${\beta}$ _w to Equation 9 of BSE paper beta = -1
`xi`	Wind accretion efficiency factor, which gives the fraction of angular momentum lost via winds from the primary that transfers to the spin angular momentum of the companion. Corresponds to ${\mu}$ _w in Equation 11 of BSE paper. `positive value` : supplies ${\mu}$ _w in Equation 11 of BSE paper xi = 0.5
`acc2`	Bondi-Hoyle wind accretion factor where the mean wind accretion rate onto the secondary is proportional to acc2. See Equation 6 in BSE paper. `positive value` : supplies ${\alpha}$ _w in Equation 6 in BSE paper acc2 = 1.5

;;;;;;;;;;;;;;;;;;
;;; WIND FLAGS ;;;
;;;;;;;;;;;;;;;;;;

; windflag sets the wind prescription
; windflag=0: stock BSE; windflag=1: StarTrack 2008
; windflag=2: Vink+2001; windflag=3: Vink+2005 (Vink plus LBV winds)
; default = 3
windflag = 3

; neta is the Reimers mass-loss coefficent
; for more information, see Kudritzki & Reimers 1978, A&A 70, 227
; default = 0.5
neta = 0.5

; bwind is the binary enhanced mass loss parameter
; bwind it is always inactive for single stars
; default = 0.0
bwind = 0.0

; hewind is a helium star mass loss factor, between 0 and 1
; only applies if windflag=0, otherwise it is overwritten
; default = 0.5
hewind = 0.5

; beta is wind velocity factor: proportional to vwind^2
; beta<0: follows StarTrack 2008; beta=0.125: stock BSE
; default = -1
beta = -1

; xi is the wind accretion efficiency factor, which gives the fraction of angular momentum lost via winds from the primary that transfers to the spin angular momentum of the companion
; default = 1.0
xi = 1.0

; acc2 sets the Bondi-Hoyle wind accretion factor onto companion
; default = 1.5
acc2 = 1.5

Note

COMMON ENVELOPE FLAGS

Note: there are cases where a common envelope is forced regardless of the critical mass ratio for unstable mass transfer. In the following cases, a common envelope occurs regardless of the choices below:

contact : the stellar radii go into contact (common for similar ZAMS systems)

periapse contact : the periapse distance is smaller than either of the stellar radii (common for highly eccentric systems)

core Roche overflow : either of the stellar radii overflow their component’s Roche radius (in this case, mass transfer from the convective core is always dynamically unstable)

alpha1

Common-envelope efficiency parameter which scales the efficiency of transferring orbital energy to the envelope. See Equation 71 in Hurley+2002.

positive values : supplies ${\alpha}$ to Equation 71 in Hurley+2002

alpha1 = 1.0

lambdaf

Binding energy factor for common envelope evolution. The initial binding energy of the stellar envelope goes like 1 / ${\lambda}$ . See Equation 69 in Hurley+2002.

positive values : uses variable lambda prescription detailed in appendix of Claeys+2014 where lambdaf is the fraction of the ionization energy that can go into ejecting the envelope; to use this prescription without extra ionization energy, set lambdaf=0

negative values : fixes ${\lambda}$ to a value of -1.0* lambdaf

lambdaf = 0.0

ceflag

Selects the de Kool 1990 model to set the initial orbital energy using the total mass of the stars instead of the core masses as in Equation 70 of Hurley+2002.

0 : Uses the core mass to calculate initial orbital energy as in Equation 70 of Hurley+2002

1 : Uses the de Kool 1990 model

ceflag = 1

cekickflag

Selects which mass and separation values to use when a supernova occurs during the CE and a kick needs to be applied.

0 : uses pre-CE mass and post-CE sep (BSE default)

1 : uses pre-CE mass and sep values

2 : uses post-CE mass and sep

cekickflag = 2

cemergeflag

Determines whether stars that begin a CE without a distinct core-envelope boundary automatically lead to merger in a CE. These systems include: kstars = [0,1,2,7,8,10,11,12]. Note that while the optimal choice is cemergeflag=1 according to Belczynski+2008, cemergeflag=0 allows for both options to be explored, since it is trivial to remove these systems from a population in post processing.

0 : allows the CE to proceed (optimistic CE)

1 : causes these systems to merge in the CE (pessimistic CE)

cemergeflag = 1

cehestarflag

Uses fitting formulae from Tauris+2015 for evolving RLO systems with a helium star donor and compact object accretor. NOTE: this flag will override cekickflag if set

0 : does NOT use Tauris+2015 at all

1 : uses Tauris+2015 fits for final period only

2 : uses Tauris+2015 fits for both final mass and final period

cehestarflag = 0

qcflag

Selects model to determine critical mass ratios for the onset of unstable mass transfer and/or a common envelope during RLO. NOTE: this is overridden by qcrit_array if any of the values are non-zero.

0 : follows Section 2.6 of Hurley+2002 (Default BSE)

1 : same as 0 but with Hjellming & Webbink 1987 for GB/AGB stars

2 : follows Table 2 of Claeys+2014

3 : same as 2 but with Hjellming & Webbink 1987 for GB/AGB stars

4 : follows Section 5.1 of Belcyznski+2008 except for WD donors which follow BSE

5 : follows Section 2.3 of Neijssel+2020; mass transfer from stripped stars is always assumed to be dynamically stable

qcflag = 1

Comparison of qcrit Values (Donor Mass/Accretor Mass) For Each Donor Kstar Type Across Flag Options
kstar	qc=0	qc=1	qc=2	qc=3	qc=4	qc=5
0	0.695	0.695	0.695 / 1.0	0.695 / 1.0	3.0	1.717
1	3	3	1.6 / 1.0	1.6 / 1.0	3.0	1.717
2	4	4	4.0 / 4.7619	4.0 / 4.7619	3.0	3.825
3	Eq.2	Eq.1	Eq.2 / 1.15	Eq.1 / 1.15	3.0	Eq.1
4	3	3	3.0 / 3.0	3.0 / 3.0	3.0	3
5	Eq.2	Eq.1	Eq.2 / 1.15	Eq.1 / 1.15	3.0	Eq.1
6	Eq.2	Eq.1	Eq.2 / 1.15	Eq.1 / 1.15	3.0	Eq.1
7	3	3	3.0 / 3.0	3.0 / 3.0	1.7	inf
8	0.784	0.784	4.0 / 4.7619	4.0 / 4.7619	3.5	inf
9	0.784	0.784	0.784 / 1.15	0.784 / 1.15	3.5	inf
10-14	0.628	0.628	3.0 / 0.625	3.0 / 0.625	0.628	0.628

Eq.1: qc = 0.362 + 1.0/(3.0*(1.0 - massc(j1)/mass(j1))), which is from Hjellming & Webbink 1983

Eq.2: qc = (1.67d0-zpars(7)+2.d0*(massc(j1)/mass(j1))**5)/2.13d0, which is from Claeys+ 2014

qcrit_array

Array of dimensions (1,16) specifying user-input values for the critical mass ratios that govern the onset of unstable mass transfer and a common envelope. Each item is set individually for its associated kstar, and a value of 0.0 will apply the prescription specified qcflag for that kstar.

Note: there are cases where a common envelope is forced regardless of the critical mass ratio for unstable mass transfer; these cases include when a natal kick causes a a large enough eccentricity that the radius of the stellar companion is larger than the orbital pericenter distance, and when two stars expand to fill their Roche lobes at the same time.

qcrit_array = [0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0]

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; COMMON ENVELOPE FLAGS ;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; alpha1 is the common-envelope efficiency parameter
; default = 1.0
alpha1 = 1.0

; lambdaf is the binding energy factor for common envelope evolution
; lambdaf>0.0 uses variable lambda prescription in appendix of Claeys+2014
; lambdaf<0 uses fixes lambda to a value of -1.0*lambdaf
; default = 0.5
lambdaf = 0.5

; ceflag=1 used the method from de Kool 1990 for setting the initial orbital energy
; ceflag=0 does not use this method (uses the core mass to calculate initial orbital energy)
; default = 1
ceflag = 1

; cekickflag determined the prescription for calling kick.f in comenv.f
; 0: default BSE
; 1: uses pre-CE mass and sep values
; 2: uses post-CE mass and sep
; default = 2
cekickflag = 2

; cemergeflag determines whether stars without a core-envelope boundary automatically lead to merger in CE
; cemergeflag=1 turns this on (causes these systems to merge)
; default = 1
cemergeflag = 1

; cehestarflag uses fitting formulae from TLP, 2015, MNRAS, 451 for evolving RLO systems with a helium star donor and compact object accretor
; this flag will override choice made by cekickflag if set
; 0: off
; 1: fits for final period only
; 2: fits for both final mass and final period
; default = 0
cehestarflag = 0

; qcflag is an integer flag that sets the model to determine which critical mass ratios to use for the onset of unstable mass transfer and/or a common envelope. NOTE: this is overridden by qcrit_array if any of the values are non-zero.
; 0: standard BSE
; 1: BSE but with Hjellming & Webbink, 1987, ApJ, 318, 794 GB/AGB stars
; 2: following binary_c from Claeys+2014 Table 2
; 3: following binary_c from Claeys+2014 Table 2 but with Hjellming & Webbink, 1987, ApJ, 318, 794 GB/AGB stars
; 4: following StarTrack from Belczynski+2008 Section 5.1. WD donors follow standard BSE
; 5: following COMPAS from Neijssel+2020 Section 2.3. Stripped stars are always dynamically stable
; default = 5 for double compact object progenitors, 3 for DWD progenitors
qcflag = 5

; qcrit_array is a 16-length array for user-input values for the critical mass ratios that govern the onset of unstable mass transfer and a common envelope
; each item is set individually for its associated kstar, and a value of 0.0 will apply prescription of the qcflag for that kstar
; default = [0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0]
qcrit_array = [0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0]

Note

KICK FLAGS

`kickflag`	Sets the particular natal kick prescription to use. Note that `sigmadiv`, `bhflag`, `bhsigmafrac`, `aic`, and `ussn`, which are described below, are only used when `kickflag=0` `0` : The standard COSMIC kick prescription, where kicks are drawn from a bimodal distribution with standard FeCCSN getting a kick drawn from a Maxwellian distribution with dispersion parameter `sigma` and ECSN/USSN are drawn according to `sigmadiv`. This setting has additional possible options for `bhflag`, `bhsigmafrac`, `aic` and `ussn`. `-1` : Natal kicks are drawn according to `sigma` and scaled by the ejecta mass and remnant mass following Eq. 1 of Giacobbo & Mapelli 2020 `-2` : Natal kicks are drawn according to `sigma` and scaled by just the ejecta mass following Eq. 2 of Giacobbo & Mapelli 2020 `-3` : Natal kicks are drawn according to Eq. 1 of Bray & Eldridge 2016 default = 0
`sigma`	Sets the dispersion in the Maxwellian for the SN kick velocity in km/s `positive value` : sets Maxwellian dispersion default = 265.0
`bhflag`	Sets the model for how SN kicks are applied to BHs, where bhflag != 0 allows for velocity kick at BH formation `0` : no BH kicks `1` : fallback-modulated kicks following Fryer+2012 `2` : kicks decreased by ratio of BH mass to NS mass (1.44 Msun); conserves linear momentum `3` : BH natal kicks are not decreased compared to NS kicks and are drawn from the same Maxwellian distribution with dispersion = sigma set above bhflag = 1
`bhsigmafrac`	Sets a fractional modification which scales down sigma for BHs. This works in addition to whatever is chosen for bhflag, and is applied to sigma before the bhflag prescriptions are applied `values between [0, 1]` : reduces sigma by bhsigmafrac bhsigmafrac = 1.0
`sigmadiv`	Sets the modified ECSN kick strength `positive values` : divide sigma (defined above) by sigmadiv `negative values` : sets ECSN kicks to be drawn from a Maxwellian distribution with dispersion given by sigmadiv sigmadiv = -20.0
`ecsn`	Allows for electron capture SNe and sets the maximum He-star mass (at core helium depletion) that will result in an ECSN `0` : turns off ECSN `positive values` : sets maximum He-star mass for ECSN; BSE (Hurley+2002) and StarTrack (Belczynski+2008) use ecsn = 2.25, while Podsiadlowksi+2004 argues that binarity can increase this to ecsn = 2.5 ecsn = 2.25
`ecsn_mlow`	Sets the low end of the ECSN mass range `positive values` : sets maximum He-star mass for ECSN; BSE (Hurley+2002) uses ecsn_mlow = 1.6, StarTrack (Belczynski+2008) uses ecsn_mlow = 1.85, Podsiadlowksi+2004 argues that binarity can decrease this to ecsn_mlow = 1.4 ecsn_mlow = 1.6
`aic`	Reduces kick strengths for accretion induced collapse SN according to sigmadiv `0` : AIC SN receive kicks drawn from Maxwellian with dispersion = sigma defined above `1` : sets kick strength according to sigmadiv; NOTE that this will apply even if ecsn = 0.0 aic = 1
`ussn`	Reduces kicks according to the sigmadiv selection for ultra-stripped supernovae, assumed to happen if a He-star undergoes a CE with a compact companion `0` : USSN receive kicks drawn from Maxwellian with dispersion = sigma defined above `1` : sets kick strength according to sigmadiv ussn = 1
`pisn`	Allows for (pulsational) pair instability supernovae and sets either the model to use or the maximum mass of the remnant. `0` : no pulsational pair instability SN `-1` : uses the formulae from Spera & Mapelli 2017 `-2` : uses a polynomial fit to Table 1 in Marchant+2018 `-3` : uses a polynomial fit to Table 5 in Woosley 2019 `positive values` : turns on pulsational pair instability and pair instability SNe, and sets the maximum mass of the allowed remnant (i.e., the bottom of the pair instability mass gap). He core masses between pisn and 65 Msun are assumed to go through pulsational pair instability and limit the He core mass to pisn, while He core masses from 65-135 Msun are assumed have a pair instability SN and leave no remnant. pisn = -2
`polar_kick_angle`	Sets the opening angle of the SN kick relative to the pole of the exploding star, where 0 gives strictly polar kicks and 90 gives fully isotropic kicks `values between [0, 90]` : sets opening angle for SN kick polar_kick_angle = 90.0
`natal_kick_array`	Array of dimensions (2,5) which takes user input values for the SN natal kick, where the first row corresponds to the first star and the second row corresponds to the second star and columns are: [vk, phi, theta, mean_anomaly, rand_seed]. NOTE: any numbers outside these ranges will be sampled in the standard ways detailed above. `vk` : valid on the range [0, inf] `phi` : co-lateral polar angle in degrees, valid from [-90, 90] `theta` : azimuthal angle in degrees, valid from [0, 360] `mean_anomaly` : mean anomaly in degrees, valid from [0, 360] `rand_seed` : supplied if restarting evolution after a supernova has already occurred natal_kick_array = [[-100.0,-100.0,-100.0,-100.0,0.0][-100.0,-100.0,-100.0,-100.0,0.0]]

;;;;;;;;;;;;;;;;;;
;;; KICK FLAGS ;;;
;;;;;;;;;;;;;;;;;;

; kickflag sets the particular kick prescription to use
; kickflag=0 uses the standard kick prescription, where kicks are drawn from a bimodal
; distribution based on whether they go through FeCCSN or ECSN/USSN
; kickflag=-1 uses the prescription from Giacobbo & Mapelli 2020 (Eq. 1)
; with their default parameters (<m_ns>=1.2 Msun, <m_ej>=9 Msun)
; kickflag=-2 uses the prescription from Giacobbo & Mapelli 2020 (Eq. 2),
; which does not scale the kick by <m_ns>
; kickflag=-3 uses the prescription from Bray & Eldridge 2016 (Eq. 1)
; with their default parameters (alpha=70 km/s, beta=120 km/s)
; Note: sigmadiv, bhflag, bhsigmafrac, aic, and ussn are only used when kickflag=0
; default = 0
kickflag = 0

; sigma sets is the dispersion in the Maxwellian for the SN kick velocity in km/s
; default = 265.0
sigma = 265.0

; bhflag != 0 allows velocity kick at BH formation
; bhflag=0: no BH kicks; bhflag=1: fallback-modulated kicks
; bhflag=2: mass-weighted (proportional) kicks; bhflag=3: full NS kicks
; default = 1
bhflag = 1

; bhsigmafrac sets the fractional modification used for scaling down the sigma for BHs
; this works in addition to whatever is chosen for bhflag, and is applied to the sigma beforehand these prescriptions are implemented
; default = 1.0
bhsigmafrac = 1.0

; sigmadiv sets the modified ECSN kick
; negative values sets the ECSN sigma value, positive values divide sigma above by sigmadiv
; default = -20.0
sigmadiv = -20.0

; ecsn>0 turns on ECSN and also sets the maximum ECSN mass range (at the time of the SN)
; stock BSE and StarTrack: ecsn=2.25; Podsiadlowski+2004: ecsn=2.5)
; default = 2.25
ecsn = 2.25

; ecsn_mlow sets the low end of the ECSN mass range
; stock BSE:1.6; StarTrack:1.85; Podsiadlowski+2004:1.4)
; default = 1.6
ecsn_mlow = 1.6

; aic=1 turns on low kicks for accretion induced collapse
; works even if ecsn=0
; default = 1
aic = 1

; ussn=1 uses reduced kicks (drawn from the sigmadiv distritbuion) for ultra-stripped supernovae
; these happen whenever a He-star undergoes a CE with a compact companion
; default = 0
ussn = 1

; pisn>0 allows for (pulsational) pair instability supernovae
; and sets the maximum mass of the remnant
; pisn=-1 uses the formulae from Spera+Mapelli 2017 for the mass
; pisn=0 turns off (pulsational) pair instability supernovae
; default = -2
pisn = -2

; polar_kick_angle sets the opening angle of the kick relative to the pole of the exploding star
; this can range from 0 (strictly polar kicks) to 90 (fully isotropic kicks)
; default = 90.0
polar_kick_angle = 90.0

; natal_kick_array is a (2,5) array for user-input values for the SN natal kick
; The first and second row specify the natal kick information for the first and second star, and columns are formatted as: (vk, phi, theta, eccentric anomaly, rand_seed)
; vk is valid on the range [0, inf], phi are the co-lateral polar angles (in degrees) valid from [-90.0, 90.0], theta are azimuthal angles (in degrees) valid from [0, 360], and eccentric anomaly are the eccentric anomaly of the orbit at the time of SN (in degrees) valid from [0, 360]
; any number outside of these ranges will be sampled in the standard way in kick.f
; rand_seed is for reproducing a supernova if the the system is started mid-evolution, set to 0 if starting binary from the beginning
; default = [[-100.0,-100.0,-100.0,-100.0,0],[-100.0,-100.0,-100.0,-100.0,0.0]]
natal_kick_array = [[-100.0,-100.0,-100.0,-100.0,0],[-100.0,-100.0,-100.0,-100.0,0.0]]

Note

REMNANT MASS FLAGS

`remnantflag`	Determines the remnant mass prescription used for NSs and BHs. `0` : follows Section 6 of Hurley+2000 (default BSE) `1` : follows Belczynski+2002 `2` : follows Belczynski+2008 `3` : follows the rapid prescription from Fryer+2012, with updated proto-core mass from Giacobbo & Mapelli 2020. This leads to a mass gap between neutron stars and black holes. `4` : follows the delayed prescription from Fryer+2012. This fills the mass gap between neutron stars and black holes. remnantflag = 4
`mxns`	Sets the boundary between the maximum NS mass and the minimum BH mass `positive values` : sets the NS/BH mass bounary mxns = 3.0
`rembar_massloss`	Determines the prescriptions for mass conversion due to neutrino emission during the collapse of the proto-compact object `positive values` : sets the maximum amount of mass loss, which should be about 10% of the maximum mass of an iron core ( ${\sim 5 \mathrm{M}_\odot}$ Fryer, private communication) `-1 < rembar_massloss < 0` : assumes that proto-compact objects lose a constant fraction of their baryonic mass when collapsing to a black hole (e.g., rembar_massloss = -0.1 gives the black hole a gravitational mass that is 90% of the proto-compact object’s baryonic mass) rembar_massloss = 0.5
`wd_mass_lim`	Determines if the maximum white dwarf mass is limited to the chandraekhar mass during mic. 1 implements the limit. wd_mass_lim = 1

;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; REMNANT MASS FLAGS ;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;

; remnantflag determines the remnant mass prescription used
; remnantflag=0: default BSE
; remnantflag=1: Belczynski et al. 2002, ApJ, 572, 407
; remnantflag=2: Belczynski et al. 2008
; remnantflag=3: rapid prescription (Fryer+ 2012), updated as in Giacobbo & Mapelli 2020
; remnantflag=4: delayed prescription (Fryer+ 2012)
; default = 4
remnantflag = 4

; mxns sets the maximum NS mass
; default = 3.0
mxns = 3.0

; rembar_massloss determines the mass conversion from baryonic to
; gravitational mass
; rembar_massloss >= 0: sets the maximum amount of mass loss
; -1 < rembar_massloss < 0: uses the prescription from Fryer et al. 2012,
; assuming for BHs Mrem = (1+rembar_massloss)*Mrem,bar for negative rembar_massloss
; default = 0.5
rembar_massloss = 0.5

; wd_mass_lim determines if the maximum white dwarf mass is limited to
; the chandraekhar mass during mic. 1 implements the limit.
; default = 1
wd_mass_lim = 1

Note

REMNANT SPIN FLAGS

bhspinflag

Uses different prescriptions for BH spin after formation

0 : sets all BH spins to bhspinmag

1 : draws a random BH spin between 0 and bhspinmag for every BH

2 : core-mass dependent BH spin (based on Belczynski+2017 v1)

bhspinflag = 0

bhspinmag

Sets either the spin of all BHs or the upper limit of the uniform distribution for BH spins

values >= 0.0 : spin or upper limit value

bhspinmag = 0.0

;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; REMNANT SPIN FLAGS ;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;

; bhspinflag uses different prescriptions for BH spin after formation
; bhspinflag=0; sets all BH spins to bhspinmag
; bhspinflag=1; draws a random BH spin between 0 and bhspinmag for every BH
; bhspinflag=2; core-mass dependent BH spin (based on Belczynski+2017; 1706.07053, v1)
; default = 0
bhspinflag = 0

; bhspinmag sets either the spin of all BHs or the upper limit of the uniform
; distribution for BH spins
; default = 0.0
bhspinmag = 0.0

Note

GR ORBITAL DECAY FLAG

grflag

Turns on or off orbital decay due to gravitational wave emission

0 : No orbital decay due to GR

1 : Orbital decay due to GR is included

grflag = 1

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; GR ORBITAL DECAY FLAG ;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; grflag turns on or off orbital decay due to gravitational wave radiation
; grflag=0; no orbital decay due to GR
; grflag=1; orbital decay due to GR is included
; default = 1
grflag = 1

Note

MASS TRANSFER FLAGS

`eddfac`	Eddington limit factor for mass transfer. `1` : mass transfer rate is limited by the Eddington rate following Equation 67 in Hurley+2002 `values >1` : permit super-Eddington accretion up to value of eddfac `values 0<=eddfac<1` : restrict accretion limit to fraction of Eddington (sub-Eddington accretion) eddfac = 1.0
`gamma`	Angular momentum prescriptions for mass lost during Roche-lobe overflow at super-Eddington mass transfer rates `-1` : assumes the lost material carries away the specific angular momentum of the primary `-2` : assumes material is lost from the system as if it is a wind from the secondary `-3` : assumes mass is lost through the outer Lagrangian point, forming a circumbinary disk. See Zapartas+17 Eq. 9 and Artymowicz & Lubow (1994). `>0` : assumes that the lost material takes away a fraction gamma of the orbital angular momentum gamma = -2
`don_lim`	Determines the rate of mass loss through Roche-lobe overflow mass transfer from the donor star `-1` : donor mass loss rate is calculated following Hurley+2002 `-2` : donor mass loss rate is calculated following Claeys+2014 don_lim = -1
`acc_lim`	Limits the amount of mass accreted during Roche-lobe overflow `-1` : limited to 10x’s the thermal rate of the accretor for MS/HG/CHeB and unlimited for GB/EAGB/AGB stars `-2` : limited to 1x’s the thermal rate of the accretor for MS/HG/CHeB and unlimited for GB/EAGB/AGB stars `-3` : limited to 10x’s the thermal rate of the accretor for all stars `-4` : limited to 1x’s the thermal rate of the accretor for all stars `>=0` : sets overall fraction of donor material that is accreted, with the rest being lost from the system (acc_lim = 0.5 assumes 50% accretion efficiency as in Belczynski+2008) acc_lim = -1

;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; MASS TRANSFER FLAGS ;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;

; eddfac is Eddington limit factor for mass transfer
; default = 1.0
eddfac = 1.0

; gamma is the angular momentum factor for mass lost during Roche-lobe overflow
; gamma=-3: assumes mass is lost through the outer Lagrangian point, forming a circumbinary disk. See Zapartas+17 Eq. 9 and Artymowicz & Lubow (1994).
; gamma=-2: assumes material is lost from the system as if it is a wind from the secondary (for super-Eddington mass transfer rates)
; gamma=-1: assumes the lost material carries with is the specific angular momentum of the primary
; gamma>0: assumes that the lost material take away a fraction (gamma) of the orbital angular momentum
; default = -2
gamma = -2

; don_lim is a flag which determines how much mass is lost during Roche-lobe overflow
; don_lim = -1: assumes standard BSE choice as outlined in Hurley+2002
; don_lim = -2: Follows Claeys+2014
; default = -1
don_lim = -1

; acc_lim is a flag which determines how much mass is accreted from the donor during Roche-lobe overflow
; if acc_lim >= 0: this provides the fraction of mass accreted
; acc_lim = -1: assumes standard BSE choice as outlined in Hurley+2002, limited to 10x the thermal rate of the accretor for MS/HG/CHeB and unlimited for GB/EAGB/AGB stars
; acc_lim = -2: limited to 1x the thermal rate of the accretor for MS/HG/CHeB and unlimited for GB/EAGB/AGB stars
; acc_lim = -3: limited to 10x the thermal rate of the accretor for all stars
; acc_lim = -4: limited to 1x the thermal rate of the accretor for all stars
; default = -1
acc_lim = -1

Note

TIDES FLAGS

tflag

Activates tidal circularisation following Hurley+2002

0 : no tidal circularization

1 : activates tidal circularization

tflag = 1

ST_tide

Activates StarTrack setup for tides following Belczynski+2008

0 : follows BSE

1 : follows StarTrack

ST_tide = 1

fprimc_array

Controls the scaling factor for convective tides. Each value in hte array is set individually for its associated kstar. The releveant equation is Equation 21 of Hurley+2002.

positive values : sets scaling factor of Equation 21 referenced above

fprimc_array = [2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0, 2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0, 2.0/21.0,2.0/21.0]

;;;;;;;;;;;;;;;;;;;
;;; TIDES FLAGS ;;;
;;;;;;;;;;;;;;;;;;;

; tflag=1 activates tidal circularisation
; default = 1
tflag = 1

; ST_tide sets which tidal method to use. 0=Hurley+2002, 1=StarTrack: Belczynski+2008
; Note, here startrack method does not use a better integration scheme (yet) but simply
; follows similar set up to startrack (including initial vrot, using roche-lobe check
; at periastron, and circularisation and synchronisation at start of MT).
; default = 1
ST_tide = 1

; fprimc_array controls the scaling factor for convective tides
; each item is set individually for its associated kstar
; The releveant equation is Equation 21 from the BSE paper
; The default is to send the same coefficient (2/21) as is in the equation
; for every kstar
fprimc_array = [2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0]

Note

WHITE DWARF FLAGS

ifflag

Activates the initial-final white dwarf mass relation from Han+1995 Equations 3, 4, and 5.

0 : no modifications to BSE

1 : activates initial-final WD mass relation

ifflag = 0

wdflag

Activates an alternate cooling law found in the description immediately following Equation 1 in Hurley & Shara 2003. Equation 1 gives the BSE default Mestel cooling law.

0 : no modifications to BSE

1 : activates modified cooling law

wdflag = 1

epsnov

Fraction of accreted matter retained in a nova eruption. This is relevant for accretion onto degenerate objects; see Section 2.6.6.2 in Hurley+2002.

positive values between [0, 1] : retains epsnov fraction of accreted matter

epsnov = 0.001

;;;;;;;;;;;;;;;;;;;;;;;;;
;;; WHITE DWARF FLAGS ;;;
;;;;;;;;;;;;;;;;;;;;;;;;;

; ifflag > 0 uses WD IFMR of HPE, 1995, MNRAS, 272, 800
; default = 0
ifflag = 0

; wdflag > 0 uses modified-Mestel cooling for WDs
; default = 1
wdflag = 1

; epsnov is the fraction of accreted matter retained in nova eruptions
; default = 0.001
epsnov = 0.001

Note

PULSAR FLAGS

bdecayfac

Activates different models for accretion induced field decay; see Kiel+2008.

0 : uses an exponential decay

1 : uses an inverse decay

bdecayfac = 1

bconst

Sets the magnetic field decay timescale for pulsars following Section 3 of Kiel+2008.

positive values : sets k in Myr from Equation 8 to bconst

bconst = 3000

ck

Sets the magnetic field decay timescale for pulsars following Section 3 of Kiel+2008.

positive values : sets ${\tau}$ _b in Myr from Equation 2 to ck

ck = 1000

;;;;;;;;;;;;;;;;;;;
;; PULSAR FLAGS ;;;
;;;;;;;;;;;;;;;;;;;

; bdecayfac determines which accretion induced field decay method to
; use from Kiel+2008: 0=exp, 1=inverse
; default = 1
bdecayfac = 1

; bconst is related to magnetic field evolution of pulsars, see Kiel+2008
; default = 3000
bconst = 3000

; ck is related to magnetic field evolution of pulsars, see Kiel+2008
; default = 1000
ck = 1000

Note

MIXING VARIABLES

rejuv_fac

Sets the mixing factor in main sequence star collisions. This is hard coded to 0.1 in the original BSE release and in Equation 80 of Hurley+2002 but can lead to extended main sequence lifetimes in some cases.

positive values : sets the mixing factor

rejuv_fac = 1.0

rejuvflag

Sets whether to use the orginal prescription for mixing of main-sequence stars (based on equation 80 of Hurley+2002) or whether to use the ratio of the pre-merger He core mass at the base of the giant branch to the merger product’s He core mass at the base of the giant branch

0 : no modifications to BSE

1 : modified mixing times

rejuvflag = 0

bhms_coll_flag

If set to 1, then if in a BH+star collision the star is not destroyed if Mstar > Mbh

bhms_coll_flag = 0

;;;;;;;;;;;;;;;;;;;;;;;
;; MIXING VARIABLES ;;;
;;;;;;;;;;;;;;;;;;;;;;;

; rejuv_fac allows different mixing factors in Equation 80 from the BSE
; paper. This was originally hard coded to 0.1, which leads massive
; stars to potentially have extended main sequence lifetimes.
; default = 1.0
rejuv_fac = 1.0

; rejuvflag toggles between the original BSE prescription for MS mixing and
; lifetimes of stars based on the mass of the MS stars (equation 80) or a
; prescription that uses the ratio of helium core mass of the pre-merger stars
; at the base of the first ascent of the giant branch to determine relative to the
; helium core mass of the merger product at the base of the giant branch
; default = 0
rejuvflag = 0

; bhms_coll_flag
; If set to 1 then if BH+star collision and if Mstar > Mbh, do not destroy the star
; default = 0
bhms_coll_flag = 0

Note

MAGNETIC BRAKING FLAGS

htpmb

Activates different models for magnetic braking

-1 : no magnetic braking

0 : no modifications to BSE

1 : follows Ivanona and Taam 2003

htpmb = 1

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; MAGNETIC BRAKING FLAGS ;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; htpmb allows for different magnetic braking models.
; 0=follows BSE paper Section 2.4
; 1=follows Ivanova & Taam 2003 method which kicks in later than the standard
; -1=turns off magnetic braking
; default = 1
htpmb = 1

Note

MISCELLANEOUS FLAGS

ST_cr

Activates different convective vs radiative boundaries

0 : no modifications to BSE

1 : follows StarTrack

ST_cr = 1

;;;;;;;;;;;;;;;;;;;;;;;;;;
;; MISCELLANEOUS FLAGS ;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;

; ST_cr sets which convective/radiative boundary to use
; 0=follows BSE paper
; 1=follows StarTrack (Belcyznski+2008)
; default = 1
ST_cr = 1