Dynamic time resolution

COSMIC has the ability to set time resolution of the bcm array depending on the current state of the evolution. It does this using the timestep_conditions parameter, which we’ll get into below.

How it works

Simply put, you tell COSMIC what time resolution to use during different phases of evolution based on a series of conditions. These conditions can cover everything from the stellar type and masses of the stars, to whether or not they are undergoing mass transfer, to the binary state, etc. Below we’ll talk through how to specify those conditions, and then demonstrate their usage in a few worked examples.

Timestep condition syntax

The timestep resolution for the bcm array can be set using timestep_conditions parameter. The format of this parameter is a list of up to 15 lists, where each sublist contains zero or more conditions followed by the desired resolution. The conditions are in the form of a string with the format 'column_name operator condition'. The resolution is in the form of a string with the format 'dtp=resolution'. The columns that can be used are listed in cosmic.checkstate.CHECKSTATE_COLUMNS.

The conditions are evaluated at each time step and if the condition is met, the resolution is set to the desired value. Within a sublist, all of the conditions must be met for its resolution to apply. A sublist with no conditions (just a dtp) always applies. If more than one sublist applies at the same time, the last one in the list sets the resolution, so put general conditions first and more specific ones after. When no sublist applies, the resolution goes back to the dtp used for the binary.

The resolution can be any non-negative float value given in units of Myr. If the resolution is set to 0.0, every time step that COSMIC uses internally will be outputted in the bcm array. If the resolution is set to None then time resolution ends and only the final state is outputted.

Conditions can use the operators ==, !=, <, <=, > and >=. A column can be given both a lower and an upper bound, either as a chained comparison (e.g. '1<kstar_1<4') or as two separate conditions (e.g. 'kstar_1>1', 'kstar_1<4'), as well as one !=. Values can be negative (e.g. 'sep==-1') and spaces around the operators are ignored. For example, the following uses a coarse resolution on the main sequence, a fine resolution on the giant branch, every time step during core helium burning and a medium resolution until the star becomes a remnant

timestep_conditions = [['kstar_1 < 2', 'dtp=5.0'], ['1 < kstar_1 < 4', 'dtp=0.01'],
                       ['kstar_1 == 4', 'dtp=0.0'], ['4 < kstar_1 < 10', 'dtp=0.5']]

Setting the same bound twice for a column in one sublist (e.g. 'kstar_1 > 1', 'kstar_1 > 2'), using an unsupported operator or leaving out the dtp raises a ValueError.

Syntax examples

Before we dive in to using these with COSMIC, here are some examples of valid syntax for the timestep_conditions parameter. Each example describes the condition and then shows the corresponding syntax. Note that the order of the conditions in a sublist does not matter, but the order of the sublists does.

Basic

# increase the timestep resolution during the Hertzsprung gap (``kstar_1==2``)
timestep_conditions = [['kstar_1 == 2', 'dtp=0.01']]

Ranged conditions

# show all timesteps when a primary star has a specific temperature range
timestep_conditions = [['10000 < teff_1 < 20000', 'dtp=0.0']]

Multiple conditions (AND)

# show all timesteps when a primary star has a specific temperature range
# AND it is on its main sequence (``kstar_1<=1``)
# any of these are equivalent and valid
timestep_conditions = [['10000 < teff_1 < 20000', 'kstar_1 <= 1', 'dtp=0.0']]
timestep_conditions = [['10000 < teff_1 < 20000 and kstar_1 <= 1', 'dtp=0.0']]
timestep_conditions = [['10000 < teff_1 < 20000 & kstar_1 <= 1', 'dtp=0.0']]

Multiple separate conditions (OR)

# use 1 Myr timesteps either when the primary is a WD
# OR when it's a black hole
timestep_conditions = [
    ['10 <= kstar_1 <= 12', 'dtp=1.0'],
    ['kstar_2 == 14', 'dtp=1.0']
]

Overlapping conditions

# use 1 Myr timesteps when the primary is a WD,
# but use 0.1 Myr timesteps when the secondary is a WD
timestep_conditions = [
    ['10 <= kstar_1 <= 12', 'dtp=1.0'],
    ['10 <= kstar_2 <= 12', 'dtp=0.1']
]
# if *both* stars are WDs, the last condition always takes
# precedence so the resolution is set to 0.1 Myr

Worked examples with COSMIC

Below we demonstrate three scenarios, setting dtp only during mass transfer, setting dtp to the same resolution for all of the evolution except for after the system merges or is disrupted, and finally an example of setting dtp only during the HMXB stage of the evolution.

All steps during mass transfer

First, print all time steps during mass transfer

In [1]: from cosmic.sample.initialbinarytable import InitialBinaryTable

In [2]: from cosmic.evolve import Evolve
In [3]: single_binary = InitialBinaryTable.InitialBinaries(
   ...:     m1=7, m2=5, porb=3000,
   ...:     ecc=0.42, tphysf=13700.0, kstar1=1, kstar2=1, metallicity=0.02
   ...: )
   ...: 

In [4]: SSEDict = {'stellar_engine': 'sse'}
In [5]: BSEDict = {
   ...:     "pts1": 0.001, "pts2": 0.01, "pts3": 0.02, "zsun": 0.014, "windflag": 3,
   ...:     "eddlimflag": 0, "neta": 0.5, "bwind": 0.0, "hewind": 0.5, "beta": 0.125,
   ...:     "xi": 0.5, "acc2": 1.5, "LBV_flag": 1, "alpha1": [1.0, 1.0],
   ...:     "lambdaf": 0.0, "ce2stageflag": 0, "ceflag": 0, "cekickflag": 2,
   ...:     "cemergeflag": 1, "cehestarflag": 0, "qcflag": 5,
   ...:     "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],
   ...:     "kickflag": 5, "sigma": 265.0, "bhflag": 1, "bhsigmafrac": 1.0,
   ...:     "sigmadiv": -20.0, "ecsn": 2.25, "ecsn_mlow": 1.6, "aic": 1, "ussn": 1,
   ...:     "polar_kick_angle": 90.0,
   ...:     "natal_kick_array": [[-100.0, -100.0, -100.0, -100.0, 0.0], [-100.0, -100.0, -100.0, -100.0, 0.0]],
   ...:     "mm_mu_ns": 400.0, "mm_mu_bh": 200.0, "remnantflag": 4,
   ...:     "fryer_mass_limit": 0, "mxns": 3.0, "fryer_fmix": 1.0,
   ...:     "fryer_mcrit_nsbh": 5.75, "rembar_massloss": 0.5, "wd_mass_lim": 1,
   ...:     "maltsev_mode": 0, "maltsev_fallback": 0.5, "maltsev_pf_prob": 0.1,
   ...:     "pisn": -2, "ppi_co_shift": 0.0, "ppi_extra_ml": 0.0, "bhspinflag": 0,
   ...:     "bhspinmag": 0.0, "grflag": 1, "eddfac": 10, "gamma": -2, "don_lim": -1,
   ...:     "acc_lim": [-1, -1], "smt_periastron_check": 0, "smt_q": -1, "tflag": 1,
   ...:     "ST_tide": 1,
   ...:     "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],
   ...:     "ifflag": 1, "wdflag": 1, "epsnov": 0.001, "bdecayfac": 1,
   ...:     "bconst": 3000, "ck": 1000, "rejuv_fac": 1.0, "rejuvflag": 0,
   ...:     "bhms_coll_flag": 0, "htpmb": 1, "ST_cr": 1, "rtmsflag": 0
   ...: }
   ...: 
# Define the condition for the time step
In [6]: timestep_conditions = [['RRLO_1>=1', 'dtp=0.0'], ['RRLO_2>=1', 'dtp=0.0']]

In [7]: bpp, bcm, initC, kick_info = Evolve.evolve(
   ...:     initialbinarytable=single_binary, BSEDict=BSEDict, SSEDict=SSEDict,
   ...:     timestep_conditions=timestep_conditions
   ...: )
   ...: 

In [8]: print(bcm[['tphys', 'kstar_1', 'kstar_2', 'mass_1', 'mass_2', 'RRLO_1', 'RRLO_2']])
          tphys  kstar_1  kstar_2    mass_1    mass_2    RRLO_1    RRLO_2
0      0.000000        1        1  7.000000  5.000000  0.007112  0.006828
0     55.150466        6        1  6.656391  5.009692  1.001003  0.006622
0    105.213676       11        2  1.003568  5.003370  0.000552  1.000792
0    105.213676       15        5  0.000000  5.008469 -1.000000  0.000100
0  13700.000000       15       11  0.000000  1.018756 -1.000000  0.000100

Condition on binary state

Second, pick a certain resolution for the bcm array until the system merges or is disrupted and then only print the final state

In [9]: timestep_conditions = [['binstate=0', 'dtp=1.0']]

In [10]: bpp, bcm, initC, kick_info = Evolve.evolve(
   ....:     initialbinarytable=single_binary,
   ....:     BSEDict=BSEDict, SSEDict=SSEDict,
   ....:     timestep_conditions=timestep_conditions
   ....: )
   ....: 

In [11]: print(bcm[['tphys', 'kstar_1', 'kstar_2', 'mass_1', 'mass_2', 'bin_state']])
      tphys  kstar_1  kstar_2    mass_1    mass_2  bin_state
0       0.0        1        1  7.000000  5.000000          0
0       1.0        1        1  6.999499  4.999955          0
0       2.0        1        1  6.998990  4.999909          0
0       3.0        1        1  6.998471  4.999863          0
0       4.0        1        1  6.997943  4.999817          0
..      ...      ...      ...       ...       ...        ...
0     103.0       11        1  1.003565  5.003677          0
0     104.0       11        1  1.003565  5.003677          0
0     105.0       11        2  1.003566  5.003527          0
0     106.0       15       11  0.000000  1.018755          1
0   13700.0       15       11  0.000000  1.018755          1

[108 rows x 6 columns]

Condition on evolutionary state

Finally, we show how to print a fine resolution only during the HMXB stage of the evolution.

In [12]: single_binary = InitialBinaryTable.InitialBinaries(
   ....:     m1=80, m2=40, porb=350,
   ....:     ecc=0.5, tphysf=13700.0,
   ....:     kstar1=1, kstar2=1, metallicity=0.002
   ....: )
   ....: 

In [13]: timestep_conditions = [['kstar_1 == 14', 'kstar_2 < 10','dtp=0.1'], ['kstar_2 == 14', 'kstar_1 < 10','dtp=0.1']]

In [14]: bpp, bcm, initC, kick_info = Evolve.evolve(
   ....:     initialbinarytable=single_binary,
   ....:     BSEDict=BSEDict, SSEDict=SSEDict,
   ....:     timestep_conditions=timestep_conditions
   ....: )
   ....: 

In [15]: print(bcm[['tphys', 'kstar_1', 'kstar_2', 'mass_1', 'mass_2', 'bin_state']])
          tphys  kstar_1  kstar_2     mass_1     mass_2  bin_state
0      0.000000        1        1  80.000000  40.000000          0
0      4.198846       14        1  25.213429  41.202336          0
0      4.298846       14        1  25.213444  41.159587          0
0      4.398846       14        1  25.213462  41.115860          0
0      4.498846       14        1  25.213481  41.071347          0
0      4.598846       14        1  25.213502  41.026315          0
0      4.698846       14        1  25.213526  40.981135          0
0      4.798846       14        1  25.213553  40.936292          0
0      4.898846       14        1  25.213583  40.892414          0
0      4.998846       14        1  25.213616  40.850272          0
0      5.098846       14        1  25.213652  40.810779          0
0      5.198846       14        1  25.213692  40.774915          0
0      5.298846       14        7  25.232807  14.493250          0
0      5.398846       14        7  25.232815  14.185869          0
0      5.498846       14        7  25.232823  13.861214          0
0      5.598846       14        7  25.232833  13.523232          0
0      5.698846       14        7  25.232843  13.175838          0
0      5.798846       14       14  25.232851  10.431046          2
0  13700.000000       14       14  25.232851  10.431046          2