MESA API¶

File IO¶

nnaps.mesa.fileio.read_compressed_track(filename, return_profiles=False)[source]¶

Function to read a compressed hdf5 model. It will automatically combine the evolution history of the stellar parts and the binary part in one numpy rec array, while correcting for potentially different model numbers in the different history files. It will also return any extra information included by the mesa compress command as a dictionary. If return_profiles is set to True, it will also return a dictionary containing all profiles together with a dictionary mapping the different profile names to the model number at which they were created.

Combining history:

Currently the binary history file is taken as the base to determine which model numbers will be part of the final evolution history. The stellar history data of the primary and secondary are then interpolated to match the model numbers of the binary history.

To avoid naming conflicts, the history parameters of the secondary get a ‘_2’ added to their name.

This function also adds several extra parameters to the history file if they can be inferred from other parameters. This is because later functions that derive stability ect might require these. Derived parameters are: effective_T, effective_T_2, rl_overflow_1, mass_ratio, separation_au, log10_J_div_Jdot_div_P and log10_M_div_Mdot_div_P. It also adds a column called CE_phase which defaults to 0, as this is required for the stability and CE phase determination later on.

Profiles:

If profiles have to be returned (return_profiles = True), they are returned in a dictionary. This dictionary contains all profiles by name, and a legend called ‘profile_legend’. This legend contains a mapping between all included profile names and the model number at which time they were taken.

profiles = {'profile_1': np.recarray(),
            'profile_2': np.recarray(),
            'profile_legend' = {'profile_1': 150, 'profile_2': 329},
           }

Parameters

filename (str) – The path to the hdf5 compressed file to read
return_profiles (bool) – If True, return a dictionary containing the profiles.

Returns

history, extra_info (, profiles): A numpy rec array containing the combined history, a dictionary with any extra info, and optionally a dictionary containing all profiles.

Return type

rec_array, dict (, dict)

nnaps.mesa.fileio.read_hdf5(filename)[source]¶

Read the filestructure of a hdf5 file to a dictionary.

Iteratively read a hdf5 file and return the content as a dictionary. Can be used to read the h5 files created with the mesa -2h5 method. If you want to read the compressed mesa models and receive the data in a directly usable format, you can use the read_compressed_track() function

Parameters: filename (str) – the name of the hdf5 file to read
Returns: dictionary with the content of the hdf5 file
Return type: dict

nnaps.mesa.fileio.write2hdf5(data, filename, update=False, attr_types=[])[source]¶

Write the content of a dictionary to a hdf5 file. The dictionary can contain other nested dictionaries, this file stucture will be maintained in the saved hdf5 file.

Pay attention to the fact that the data type of lists might change when writing to hdf5. Lists are stored as numpy arrays, thus all items in a list are converted to the same type: [‘bla’, 1, 24.5] will become [‘bla’, ‘1’, ‘24.5’]. Upt till now there is nothing in place to check this, or correct it when reading a hdf5 file.

Parameters

data (dict) – the dictionary to write to file
filename (str) – the name of the hdf5 file to write to
update (bool) – True if you want to update an existing file, False to overwrite
attr_types (List of types) – the data types that you want to save as an attribute instead of a dataset. (standard everything is saved as dataset.)

Compress MESA¶

nnaps.mesa.compress_mesa.read_mesa_header(model)[source]¶

process the MESA history files header. This will require more work in the future to also deal with correct type conversions. Now everything is considered a string. This is fine as the header is ignored by the rest of nnaps.

todo: implement converting of header values to the correct data types.

Parameters: model – list of lists
Returns: numpy array containing strings with the header info.

nnaps.mesa.compress_mesa.read_mesa_output(filename=None, only_first=False)[source]¶

Read star.log and .data files from MESA.

This returns a record array with the global and local parameters (the latter can also be a summary of the evolutionary track instead of a profile if you’ve given a ‘star.log’ file.

The stellar profiles are given from surface to center.

Function writen by Pieter DeGroote

Parameters

filename (str) – name of the log file
only_first (bool) – read only the first model (or global parameters)

Returns

list of models in the data file (typically global parameters, local parameters)

Return type

list of rec arrays

Extract MESA¶

nnaps.mesa.extract_mesa.count_ml_phases(data, mltype='rlof')[source]¶

Count how many separate mass loss phases take place during the evolution of this system. A mass loss phase is defined as mass_loss_rate >= -10 The mass loss rate considered is by default from RLOF, and it is defined as:

mass_loss_rate = lg_mstar_dot_1 - lg_wind_mdot_1

You can specify if you want the rlof mass loss rate, the wind mass loss rate or the total mass loss rate using the ‘mltype’ option.

Parameters

data – numpy ndarray containing the history of the system.
mltype – the type of mass loss to consider: ‘rlof’, ‘wind’, ‘total’

Returns

the number of mass loss phases

nnaps.mesa.extract_mesa.process_file_list(file_list, verbose=False, **kwargs)[source]¶

Function that takes a list containing the paths of the mesa models to process, and potentially some relevant parameters necessary for the processing. Check if the setup parameters provided in the kwargs are included in the list, and if not, add them.

if ce_parameters is included in the file_list, it will convert the provided ce_parameters to dictionary.

Parameters

file_list – Pandas DataFrame containing at least 1 column with the path of the MESA models to process
verbose – If True, print which parameters were added
kwargs – all parameters that are required for processing the MESA models and their default values.

Returns

Pandas DataFrame containing the path to all models and the necessary parameters.

Stability and common envelope¶

nnaps.mesa.common_envelope.apply_ce(data, profiles=None, ce_formalism='iben_tutukov1984', max_profile_distance=5, **kwargs)[source]¶

Function performs the ce ejection and updates some stellar and binary parameters

Different CE formalisms are supported:

iben_tutukov1984: Iben & Tutukov 1984, ApJ, 284, 719
webbink1984: Webbink 1984, ApJ, 277, 355
dewi_tauris2000: Dewi and Tauris 2000, A&A, 360, 1043
demarco2011: De Marco et al. 2011, MNRAS, 411, 2277

for more details on each of the formalisms and which parameters are required, see their respective functions below.

updates when available:

star_1_mass
envelope_mass
period_days
binary_separation
mass_ratio
rl_1
rl_2

Parameters

data – ndarray with model parameters
profiles – dictionary containing all available profiles for the model
ce_formalism – Which CE formalism to use
max_profile_distance – when using dewi_tauris2000, the maximum model_number difference between onset CE and the closest profile available.

Returns

same dataset as provided with on the last line the parameters after the CE phase.

nnaps.mesa.common_envelope.demarco2011(history, al=1, lb=1)[source]¶

CE formalism from De Marco et al. 2011, MNRAS, 411, 2277

Required history parameters:

star_1_mass
star_2_mass
he_core_mass
binary_separation
rl_1

Parameters

history – ndarray with model parameters
al – alpha CE, the efficiency parameter for the CE formalism
lb – lambda CE, the mass distribution factor of the primary envelope: lambda * Rl = the effective mass-weighted mean radius of the envelope at the start of CE.

Returns

final separation, final primary mass

nnaps.mesa.common_envelope.dewi_tauris2000(history, profile, a_ce=1, a_th=0.5, merge_when_core_reached=True)[source]¶

CE formalism presented in Dewi and Tauris 2000, A&A, 360, 1043 based on the idea of obtaining the binding energy by integrating the stellar profile from Han et al 1995, MNRAS, 272, 800

Required history parameters:

star_2_mass
binary_separation

Required profile parameters:

mass
logR
logP
logRho

Parameters

history – ndarray with model parameters
profile – ndarray profile for the integration of binding energy
a_ce – efficiency of ce
a_th – efficiency of binding energy
merge_when_core_reached – if True, the system is reported as a merger when the He core is reached in the iteration before the envelope is ejected and the CE ends.

Returns

final separation, final primary mass

nnaps.mesa.common_envelope.iben_tutukov1984(history, al=1)[source]¶

CE formalism from Iben & Tutukov 1984, ApJ, 284, 719

Required history parameters:

star_1_mass
star_2_mass
he_core_mass
binary_separation

Parameters

history – ndarray with model parameters
al – alpha CE, the efficiency parameter for the CE formalism

Returns

final separation, final primary mass

nnaps.mesa.common_envelope.is_stable(data, criterion='J_div_Jdot_div_P', value=10, return_model_number=False)[source]¶

Checks if a model is stable with respect to the provided stability criterion. Known criteria are:

Mdot: lg_mstar_dot_1 > value
delta: mass_transfer_delta > value
J_div_Jdot_div_P: 10**log10_J_div_Jdot_div_P < value
M_div_Mdot_div_P: 10**log10_M_div_Mdot_div_P < value
R_div_SMA: star_1_radius / binary_separation > value

Parameters

data – model (np ndarray)
criterion – which criterion to use
value – value for the criterion to satisfy
return_model_number – if true also return the model_number

Returns

stable (boolean), age (float), [model_number (int)], when stable age and model_number are last reached values when unstable, they are the age and model_number when the model becomes unstable.

nnaps.mesa.common_envelope.webbink1984(history, al=1, lb=1)[source]¶

CE formalism from Webbink 1984, ApJ, 277, 355

Required history parameters:

star_1_mass
star_2_mass
he_core_mass
binary_separation
rl_1

Parameters

history – ndarray with model parameters
al – alpha CE, the efficiency parameter for the CE formalism
lb – lambda CE, the mass distribution factor of the primary envelope: lambda * Rl = the effective mass-weighted mean radius of the envelope at the start of CE.

Returns

final separation, final primary mass

Evolution Phases¶

nnaps.mesa.evolution_phases.CE(data)[source]¶

The CE phase as it is defined in the common_envelope settings.

Parameters: data – numpy ndarray containing the history of the system.
Returns: selection where the history corresponds to the CE phase

nnaps.mesa.evolution_phases.CEend(data)[source]¶

the end of the CE phase as defined in the common_envelope settings.

Parameters: data – numpy ndarray containing the history of the system.
Returns: selection where the history corresponds to the end point of the CE phase

nnaps.mesa.evolution_phases.CEstart(data)[source]¶

start of the CE phase as defined in the common_envelope settings.

Parameters: data – numpy ndarray containing the history of the system.
Returns: selection where the history corresponds to the starting point of the CE phase

nnaps.mesa.evolution_phases.CO_WD(data)[source]¶

Defines the He White Dwarf phase, when the star is on the WD cooling track, and has a CO core.

The WD cooling track is selected to start when Teff < 10000K and logg > 7, or when logg > 7.5 regardless of Teff

Note

Is triggered with ‘CO-WD’.

Required history parameters:

log_LHe
c_core_mass
log_Teff
log_g
age

Parameters: data – numpy ndarray containing the history of the system.
Returns: selection where the history corresponds to the He-WD phase

nnaps.mesa.evolution_phases.HeCoreBurning(data, return_age=False, return_start=False, return_end=False)[source]¶

He core burning is defined as the period between ignition of He and formation of CO core.

He ignition in the core is defined as the first moment when both the temperature and density in the core are sufficiently high to allow He burning. NNaPS uses the same conditions to define the ignition criteria as MESA.

CO core formation is defined as the point in time when the CO core reaches as mass of 0.01

If the center temperature and density are never in the range necessary for He fusion, there is no He core burning phase and the function will return None.

Required history parameters:

log_center_T
log_center_Rho
log_LHe
c_core_mass
age

Parameters: data – numpy ndarray containing the history of the system.
Returns: selection where the history corresponds to the He core burning phase

nnaps.mesa.evolution_phases.HeIgnition(data, return_age=False)[source]¶

The moment of He ignition depends on the mass of the star. For stars with a degenerate core, which will ignite He through flashes in a shell around the core, He ignition is based on the He luminosity. For stars that have a non degenerate core, which ignite He quietly, He ignition is defined by the conditions in the core similarly to how HeCoreBurning is defined.

Degenerate ignition: The moment of He ignition, as defined by a peak in the He luminosity. This is the first moment of He ignition, but is not necessarily in the core as for low mass stars, He ignition occurs under degenerate conditions, and due to neutrino cooling typically happens in a shell around the core.

Ignition is defined as the point with the maximum LHe between the first moment when LHe > 10 Lsol and the formation of the carbon-oxygen core. This is the (first) He flash.

Non degenerate ignition: He ignition in the core is defined as the first moment when both the temperature and density in the core are sufficiently high to allow He burning. NNaPS uses the same conditions to define the ignition criteria as MESA.

Required history parameters:

log_center_T
log_center_Rho
log_LHe
c_core_mass
age

Parameters: data – numpy ndarray containing the history of the system.
Returns: selection where the history corresponds to the moment of He ignition

nnaps.mesa.evolution_phases.HeShellBurning(data, return_age=False, return_start=False, return_end=False)[source]¶

The He shell burning phase is defined as the period in time between the formation of the CO core, and the final drop in He luminosity indicating the end of He burning. This final drop is defined as the time when LHe drops below half the LHe at the start of He shell burning.

If there is no CO core present at any time, there is no He shell burning phase, and the function will return None

start: CO core > 0.01 Msol

end: LHe < 1/2 * LHe[start of shell burning]

Required history parameters:

log_LHe
c_core_mass
age

Parameters: data – numpy ndarray containing the history of the system.
Returns: selection where the history corresponds to the He shell burning phase

nnaps.mesa.evolution_phases.He_WD(data)[source]¶

Defines the He White Dwarf phase, when the star is on the WD cooling track, but still has a He core.

The WD cooling track is selected to start when Teff < 10000K and logg > 7, or when logg > 7.5 regardless of Teff

Note

Is triggered with ‘He-WD’.

Required history parameters:

log_LHe
c_core_mass
log_Teff
log_g
age

Parameters: data – numpy ndarray containing the history of the system.
Returns: selection where the history corresponds to the He-WD phase

nnaps.mesa.evolution_phases.ML(data, mltype='rlof', return_start=False, return_end=False, return_age=False, return_multiple=False)[source]¶

The first occurring mass loss phase, where the mass loss phase is defined as the period in time when the primary is losing mass at a rate of at least log(Mdot) >= -10. This phase only marks mass loss due to RLOF. Mass loss due to winds is not taken into account when flagging a ML phase. In practice, the mass loss rate due to RLOF is defined as:

lg_mass_loss_rate = log10( 10^lg_mstar_dot_1 - 10^lg_wind_mdot_1 )

Note

This phase only marks the first occurring mass loss phase.

Required history parameters:

lg_mstar_dot_1
lg_wind_mdot_1
age

Parameters

data – numpy ndarray containing the history of the system.
mltype – the type of mass loss to consider: ‘rlof’, ‘wind’, ‘total’

Returns

selection where the history corresponds to the first ML phase

nnaps.mesa.evolution_phases.MLend(data, mltype='rlof', return_age=False, return_multiple=False)[source]¶

The end of the first mass loss phase, defined as the moment in time when lg_mstar_dot_1 dips below -10 after starting mass loss.

Required history parameters:

lg_mstar_dot_1
age

Parameters

data – numpy ndarray containing the history of the system.
mltype – the type of mass loss to consider: ‘rlof’, ‘wind’, ‘total’

Returns

selection where the history corresponds to the end point of the first ML phase

nnaps.mesa.evolution_phases.MLstart(data, mltype='rlof', return_age=False, return_multiple=False)[source]¶

The start of the first ML phase, defined as the moment in time when the donor star first reaches lg_mstar_dot_1 >= 10

Required history parameters:

lg_mstar_dot_1
age

Parameters

data – numpy ndarray containing the history of the system.
mltype – the type of mass loss to consider: ‘rlof’, ‘wind’, ‘total’

Returns

selection where the history corresponds to the starting point of the first ML phase

nnaps.mesa.evolution_phases.MS(data, return_age=False, return_start=False, return_end=False)[source]¶

The Main sequence phase is defined as the phase where hydrogen burning takes place is the core.

Specifically this is defined as the time period starting when the majority of the energy is produced by nuclear reactions, and ending when the core hydrogen runs out.

start: 10^log_LH > 0.999 * 10^log_L

end: center_h1 < 1e-12

Required history parameters:

log_L
log_LH
center_h1
age

Parameters: data – numpy ndarray containing the history of the system.
Returns: selection where the history corresponds to the main sequence phase

nnaps.mesa.evolution_phases.MSend(data, return_age=False)[source]¶

The Main sequence phase is defined as the phase where hydrogen burning takes place is the core. MSend defines last moment when the star is still considered to be on the MS.

Specifically this is defined when the core hydrogen runs out:

end: center_h1 <= 1e-12

Required history parameters:

log_L
log_LH
center_h1
age

Parameters: data – numpy ndarray containing the history of the system.
Returns: selection where the history corresponds to the main sequence phase

nnaps.mesa.evolution_phases.MSstart(data, return_age=False)[source]¶

The Main sequence phase is defined as the phase where hydrogen burning takes place is the core. MSstart defines first moment when the star enters the MS.

Specifically this is defined as the moment when the majority of the energy is produced by nuclear reactions:

start: log_LH >= 0.999 * log_L

Required history parameters:

log_L
log_LH
center_h1
age

Parameters: data – numpy ndarray containing the history of the system.
Returns: selection where the history corresponds to the main sequence phase

nnaps.mesa.evolution_phases.RGB(data, return_age=False, return_start=False, return_end=False)[source]¶

The red giant phase is defined as the phase starting at the end of the MS, and continuing until either a minimum in Teff or a maximum in luminosity is reached (whichever comes first) before He burning stars.

Specifically, the start is defined in the same way as the end of the MS phase, based on central hydrogen, and the end is defined based on Teff and log_L before the central He fraction is reduced:

start: center_h1 < 1e-12

end: ( Teff == min(Teff) or log_L == max(log_L) ) and center_He >= center_He_TAMS - 0.01

Required history parameters:

center_h1
center_he4
effective_T
log_L
age

Parameters: data – numpy ndarray containing the history of the system.
Returns: selection where the history corresponds to the red giant phase

nnaps.mesa.evolution_phases.RGBend(data, return_age=False)[source]¶

The end of the red giant phase is defined as the moment when either a minimum in Teff or a maximum in luminosity is reached (whichever comes first) before He burning stars.

Specifically, the end is defined based on Teff and log_L before the central He fraction is reduced:

end: ( Teff == min(Teff) or log_L == max(log_L) ) and center_He >= center_He_TAMS - 0.01

Required history parameters:

center_h1
center_he4
effective_T
log_L
age

Parameters: data – numpy ndarray containing the history of the system.
Returns: selection where the history corresponds to the red giant phase

nnaps.mesa.evolution_phases.RGBstart(data, return_age=False)[source]¶

The start of the red giant phase is defined as the moment that the central hydrogen runs out. This phase is equivalent with the end of the MS phase:

start: center_h1 <= 1e-12

Required history parameters:

center_h1
center_he4
effective_T
log_L
age

Parameters: data – numpy ndarray containing the history of the system.
Returns: selection where the history corresponds to the red giant phase

nnaps.mesa.evolution_phases.decompose_parameter(par)[source]¶

Decompose a parameter in the parameter name recognized by mesa, a potential function to apply to the parameter and the phase for which to calculate it.

recognized functions:

min
max
avg (average over time)
diff (difference between start and end)
rate (change rate: (end-start)/(end_time - start_time)

examples: M1__init -> avg(star_1_mass[init]) max__RL -> max(RL) duration__HeCoreBurning -> duration(time[HeCoreBurning]) max__Teff__ML -> max(effective_T[ML])

nnaps.mesa.evolution_phases.final(data)[source]¶

Last evolution time point, can be used to obtain parameters at the very end of the run.

Parameters: data – numpy ndarray containing the history of the system.
Returns: selection of the last evolution point.

nnaps.mesa.evolution_phases.get_custom_phase(phase, data)[source]¶

Select phases that are linked to other parameters as for example maximum mass loss: lg_mstar_dot_1_max will return the point in time where the mass loss rate of the primary reaches it’s maximum value.

Parameters

phase – phase (string)
data – evolution data (np ndarray)

Returns

np selection

nnaps.mesa.evolution_phases.init(data)[source]¶

First evolution time point, can be used to obtain the initial parameters of the run.

Parameters: data – numpy ndarray containing the history of the system.
Returns: selection of the first evolution point.

nnaps.mesa.evolution_phases.sdA(data)[source]¶

This is the evolutionary definition of the sdA phase, which is defined as a core He burning phase where the star looks spectroscopically as an sdA star. This is defined as Teff between 15000 and 20000 K.

If the star does not have a core He burning phase as defined by HeCoreBurning, this function will return None.

Note

Not to be confused with the spectroscopic definition of the sdA phase, which does NOT require He core burning.

Required history parameters:

log_center_T
log_center_Rho
log_LHe
c_core_mass
log_Teff
age

Parameters: data – numpy ndarray containing the history of the system.
Returns: selection where the history corresponds to the sdA phase

nnaps.mesa.evolution_phases.sdB(data)[source]¶

This is the evolutionary definition of the sdB phase, which is defined as a core He burning phase where the star looks spectroscopically as an sdB star. This is defined as Teff between 20000 and 40000 K.

If the star does not have a core He burning phase as defined by HeCoreBurning, this function will return None.

Note

Not to be confused with the spectroscopic definition of the sdB phase, which does NOT require He core burning.

Required history parameters:

log_center_T
log_center_Rho
log_LHe
c_core_mass
log_Teff
age

Parameters: data – numpy ndarray containing the history of the system.
Returns: selection where the history corresponds to the sdB phase

nnaps.mesa.evolution_phases.sdO(data)[source]¶

This is the evolutionary definition of the sdB phase, which is defined as a core He burning phase where the star looks spectroscopically as an sdO star. This is defined as Teff higher than 40000 K.

If the star does not have a core He burning phase as defined by HeCoreBurning, this function will return None.

Note

Not to be confused with the spectroscopic definition of the sdO phase, which does NOT require He core burning.

Required history parameters:

log_center_T
log_center_Rho
log_LHe
c_core_mass
log_Teff
age

Parameters: data – numpy ndarray containing the history of the system.
Returns: selection where the history corresponds to the sdO phase

Error checks¶

nnaps.mesa.evolution_errors.check_error_flags(history, termination_code)[source]¶

Check for some possible errors in the model and report them.

Errors that are checked and there codes:

MESA stopped because of max model number

MESA stopped because the accretor is overflowing it’s Roche-lobe

The mass loss phase doesn’t end, to check if mass loss didn’t cause mesa to crash: mass_loss_error()

Potential problem with He ignition: He ramps up and doesnt ignite, or He ignites but there is no core burning: he_ignition_error()

He core burning starts, but there is no formation of a CO core: he_core_burning_error()

Parameters

history (numpy ndarray) – the evolution history of the system
termination_code (str) – the termination code of the mesa model

Returns

list of integers with error codes

nnaps.mesa.evolution_errors.he_core_burning_error(history)[source]¶

Check if there is an issue with He core burning. The function checks if core He burning starts, but never ends before the end of the evolution.

Required history parameters:

c_core_mass
log_center_T
log_center_Rho

Parameters: history (numpy ndarray) – the evolution history of the system.
Returns: True if there is a He core burning error, else False

nnaps.mesa.evolution_errors.he_ignition_error(history)[source]¶

Check if there are issues with He ignition. The function checks if there is ignition but no actual core He burning, and also if there is a ramp up to ignition, but the ignition itself is unsuccessful.

Required history parameters:

age
log_LHe
log_center_T
log_center_Rho

Parameters: history (numpy ndarray) – the evolution history of the system.
Returns: True if there is a He ignition error, else False

nnaps.mesa.evolution_errors.mass_loss_error(history)[source]¶

Check if there is a possible issue with mass loss. This function checks if RLOF is still ongoing when the model stops. For a stable model this would be an indication that something is wrong.

Required history parameters:

lg_mstar_dot_1
lg_wind_mdot_1

Parameters: history (numpy ndarray) – the evolution history of the system.
Returns: True if there is a mass loss error, else False