POSDYON Population Synthesis Configuration Guide
This documentation provides a detailed overview of the configuration options available in the Posydon software package.
Warning
The default values in the population_params.ini file included in POSYDON have not been calibrated, validated, or are used by the POSYDON team. They are often an ad-hoc choice, and the user should carefully consider the values of each parameter for their science case.
Environment Variables
The environment variable PATH_TO_POSYDON will be read from your shell session.
Parameter |
Description/Value |
|---|---|
PATH_TO_POSYDON |
<PATH_TO_POSYDON> |
SimulationProperties
After the environment variables, the next part of the population_params.ini file
contains how systems will move through the simulation steps [Flow Chart](flow_chart.rst) and the parameters for each step.
These parameters are read in and used to create a SimulationProperties` object.
It allows for the addition of hooks before and after each step, and the evolution of a system (see Custom Hooks).
The SimulationProperties can be manually read and loaded in.
Note that the loading of the simulation steps is separate from creating the object.
from posydon.binary_evol.simulationproperties import SimulationProperties
from posydon.popsyn.io import simprop_kwargs_from_ini
# read from file
sim_props = simprop_kwargs_from_ini('population_params.ini', vebose=False)
# create SimulationProperties object
sim = SimulationProperties(**sim_props)
# load the steps
sim.load_steps()
Flow Chart
The flow chart is the core of POSYDON. It controls the mapping between a POSYDON binary object and its step evolution, see the Flow Chart Object page for more details.
Parameter |
Description |
Default Value |
|---|---|---|
|
The import path for the flow chart and the name of the flow chart function.
The flow chart function is used to determine the next step of the binary object.
|
|
|
An absolute import of a custom step. It follows the same structure as
import.You can find an example in the tutorials.
|
|
Step MESA (HMS-HMS, CO-HMS_RLO, CO-HeMS, CO-HeMS_RLO)
The MESA step is the most important step of POSYDON as it leverages the POSYDON MESA grids to evolve the binary object according to one of the supported MESA binary-star grids.
Below we give the default values for the HMS-HMS step, as an example.
Parameter |
Description |
Default Value |
|---|---|---|
|
The import path for the step and the name of the step class.
|
|
|
An absolute import of a custom step. It follows the same structure as
import.['import.path', 'name_of_step'] |
|
|
The path to the interpolation file for the step.
If None, the path is found by default with
PATH_TO_POSYDON_DATA and step_name. |
|
|
The name of the interpolation file for the step.
If None, the name is found by default with
PATH_TO_POSYDON_DATA, step_name, and metallicity. |
|
|
The interpolation method used to interpolate the MESA grid.
|
|
|
Store the initial conditions when using nearest neighbour interpolation.
|
|
|
Track the interpolation when using nearest neighbour interpolation.
|
|
|
The method to stop the evolution of a binary
|
|
|
Specifies the star to stop for the condition.
Relevant when
stop_method is 'stop_at_condition'.
|
|
|
The variable name for the stop condition.
Only applicable when
stop_method is 'stop_at_condition'. |
|
|
The value at which to stop.
Relevant when
stop_method is 'stop_at_condition'. |
|
|
Specifies whether to interpolate when stopping.
|
|
|
Enables verbose mode.
|
|
Step Detached
The detached step uses analytical expressions and MESA single star grids to evolve the binary object when it is not interacting. It evolves the binary object in isolation until Roche lobe overflow occurs.
Parameter |
Description |
Default Value |
|---|---|---|
|
The import path for the step and the name of the step class.
|
|
|
An absolute import of a custom step. It follows the same structure as
import.['import.path', 'name_of_step'] |
|
|
The method to match the MESA single star grid to the binary object.
|
|
|
Enable wind loss.
|
|
|
Enable tides.
|
|
|
Enable gravitational radiation.
|
|
|
Enable magnetic braking.
|
|
|
Enable stellar evolution and spin from winds.
|
|
|
Orbit at Roche lobe overflow with the same angular momentum.
Relevant in eccentric systems.
|
|
|
Enables verbose mode.
|
|
Step Disrupted
The dirtupted step evolves a system when a supernova has unbound the binary components. This class inherits from the detached step, but only evolves the remaining star in isolation. This means that this step uses the single stars loaded by the detached step.
Parameter |
Description |
Default Value |
|---|---|---|
|
The import path for the step and the name of the step class.
|
|
Step Merged
In this step, the system has undergone a merger and is now a single star. This class inherits from the detached step, but only evolves the remaining star in isolation. This means that this step uses the single stars loaded by the detached step.
Parameter |
Description |
Default Value |
|---|---|---|
|
The import path for the step and the name of the step class.
|
|
Step Initially Single
This step is used to evolve a single star system. This class inherits from the detached step and evolves the star in isolation. This means that this step uses the single stars loaded by the detached step.
Parameter |
Description |
Default Value |
|---|---|---|
|
The import path for the step and the name of the step class.
|
|
Step Common Envelope
The common envelope step is used to evolve a binary system when the primary or secondary star has initiated a common envelope phase. It calculates the binding energy of the envelope and the energy available to eject it. If the energy budget is greater than the binding energy, the envelope is ejected and the system is evolved to the next step. If the energy budget is less than the binding energy, the system is merged.
Parameter |
Description |
Default Value |
|---|---|---|
|
The import path for the step and the name of the step class.
|
|
|
An absolute import of a custom step. It follows the same structure as
import.['import.path', 'name_of_step'] |
|
|
The prescription used for the common envelope evolution.
|
|
|
The efficiency of the common envelope ejection.
|
|
|
The option for calculating the lambda parameter.
|
|
|
The default lambda value, used only for the
'default_lambda' option. |
|
|
The option for handling Hertzsprung gap stars in common envelope evolution.
|
|
|
The alpha thermal parameter, used only for the
'lambda_from_profile_gravitational_plus_internal' and 'lambda_from_profile_gravitational_plus_internal_minus_recombination' options. |
|
|
The hydrogen fraction for defining the core.
|
|
|
The helium fraction for defining the core.
|
|
|
The tolerance error for the common envelope evolution.
|
|
|
The option for handling the system after a successful common envelope ejection.
|
|
|
Enables verbose mode.
|
|
Step Supernova
This step performs the core-collapse supernova evolution of the star.
Multiple prescriptions are implemented and can be selected.
If a pretrained prescription is used (use_interp_values=True), interpolators are available to speed up the calculation and predict additional properties of the collapse, such as the spin.
The collection of trained prescriptions can be found in the MODELS.py file at posydon/grids/MODELS.py.
Warning
If you want to use a combination that does not have a trained model, please turn off use_interp_values,
otherwise your population runs will fail! Depending on use_core_masses,
the core masses or stellar profiles are used to determine the supernova properties.
Parameter |
Description |
Default Value |
|---|---|---|
|
The import path for the step and the name of the step class.
|
|
|
An absolute import of a custom step. It follows the same structure as
import.['import.path', 'name_of_step'] |
|
|
The mechanism used for the supernova.
|
|
|
The engine used for the supernova.
Relevant for
'Sukhbold+16-engine' and 'Patton&Sukhbold20-engine' mechanisms. |
|
|
The prescription used for pair-instability supernova.
|
|
|
The prescription used for electron-capture supernova.
|
|
|
Conserve the hydrogen envelope during the supernova.
|
|
|
The maximum mass loss due to neutrinos.
|
|
|
The maximum mass of a neutron star.
|
|
|
Use interpolation values for the supernova properties, which are calculated during
step_MESA. |
|
|
Use profiles for the supernova.
|
|
|
Use core masses for the supernova.
|
|
|
Approximate at helium depletion.
|
|
|
Apply a kick to the remnant.
|
|
|
The normalisation method for the kick.
|
|
|
The standard deviation of the kick velocity for core-collapse supernova neutron stars.
|
|
|
The standard deviation of the kick velocity for core-collapse supernova black holes.
|
|
|
The standard deviation of the kick velocity for electron-capture supernova.
|
|
|
Enables verbose mode.
|
|
Step Double Compact Object
In this step, the system has evolved to a double compact object system. The merger time due to gravitational wave emission is calculated.
Parameter |
Description |
Default Value |
|---|---|---|
|
The import path for the step and the name of the step class.
|
|
|
An absolute import of a custom step. It follows the same structure as
import.['import.path', 'name_of_step'] |
|
|
The number of steps interval for the double compact object evolution.
|
|
Step End
The final step of the simulation. All succesfull systems should reach this step.
Parameter |
Description |
Default Value |
|---|---|---|
|
The import path for the step and the name of the step class.
|
|
|
An absolute import of a custom step. It follows the same structure as
import. |
|
Extra Hooks
It’s possible to add custom hooks to the simulation steps.
A few example hooks are provides: TimingHooks and StepNamesHooks (See Custom Hooks for more details)
Each new hook has a unique import number, starting from 1.
Parameter |
Description |
Default Value |
|---|---|---|
|
The import path for the hook and the name of the hook class.
|
|
|
An absolute import of a custom hook. It follows the same structure as
import. |
|
|
Additional keyword arguments for the hook.
|
|
|
The import path for the hook and the name of the hook class.
|
|
|
An absolute import of a custom hook. It follows the same structure as
import. |
|
|
Additional keyword arguments for the hook.
|
|
BinaryPopulation
A BinaryPopulation is created to evolve the population using a given SimulationProperties object.
This class requires additional parameters, because it will require initial distributions
for to sample BinaryStar objects from,
such as the masses and orbital parameters.
Moreover, it contains the parameters for metallicity and the practicality of running populations.
This includes, the number of binaries, the metallicity, how often to save the population to file.
- When reading the binary population arguments from a
population_params.inifile, the SimulationPropertiesare read in automatically.
from posydon.popsyn.binarypopulation import BinaryPopulation
from posydon.popsyn.io import binarypop_kwargs_from_ini
# read from file
pop_params = binarypop_kwargs_from_ini('population_params.ini', vebose=False)
# create BinaryPopulation object
pop = BinaryPopulation(**pop_params)
BinaryPopulation Options
These parameters contain options on how the population is evolved, in practical terms, ie. the number of binaries. It also contains which sampling distributions to use for the initial conditions of the binaries.
Saving Output
You can decide on your own output parameters for the population file.
The data is split in two different tables: the history table and the oneline table.
The history table contains values that change throughout the evolution of the system,
while the oneline table contains values that are constant throughout the evolution of the system or only occur once.
BinaryStar Output
The binarystar class contains the binary systems and
the parameters here determine what output of that class will be outputted into the final population file.
scalar_names will only be stored in the oneline table.
Parameter |
Description |
Default Value |
|---|---|---|
|
Additional columns to include in the output.
Note:
'step_times' requires TimingHooks from posydon.binary_evol.simulationproperties. |
{'step_names':'string', 'step_times':'float64'}
|
|
Columns to include in the output.
Example:
['state', 'event', 'time', 'orbital_period', 'eccentricity', 'lg_mtransfer_rate']Options:
|
['state',
'event',
'time',
'orbital_period',
'eccentricity',
'lg_mtransfer_rate']
|
|
Scalars of the binary to include in the output.
Options:
|
['interp_class_HMS_HMS',
'interp_class_CO_HMS_RLO',
'interp_class_CO_HeMS',
'interp_class_CO_HeMS_RLO',
'mt_history_HMS_HMS',
'mt_history_CO_HMS_RLO',
'mt_history_CO_HeMS',
'mt_history_CO_HeMS_RLO']
|
SingleStar 1 and 2 Output
This dictionary contains the parameters that will be saved in the output of the SingleStar objects in the system.
only_select_columns will be stored in the history table, and the initial and final step will be stored in the oneline table with the prefix S1 or S2 depending on the star,
scalar_names will only be stored in the oneline table.
Parameter |
Description |
Default Value |
|---|---|---|
|
Include SingleStar 1 in the output.
|
|
|
Columns to include in the output for SingleStar 1.
Example:
['state', 'mass', 'log_R', 'log_L', 'lg_mdot', 'he_core_mass', 'he_core_radius', 'co_core_mass', 'co_core_radius', 'center_h1', 'center_he4', 'surface_h1', 'surface_he4', 'surf_avg_omega_div_omega_crit', 'spin']Options:
|
['state',
'mass',
'log_R',
'log_L',
'lg_mdot',
'he_core_mass',
'he_core_radius',
'co_core_mass',
'co_core_radius',
'center_h1',
'center_he4',
'surface_h1',
'surface_he4',
'surf_avg_omega_div_omega_crit',
'spin',]
|
|
Scalars to include in the output for SingleStar 1.
Example:
['natal_kick_array', 'SN_type', 'f_fb', 'spin_orbit_tilt_first_SN', 'spin_orbit_tilt_second_SN', 'm_disk_accreted', 'm_disk_radiated']Options:
|
['natal_kick_array',
'SN_type',
'f_fb',
'spin_orbit_tilt_first_SN',
'spin_orbit_tilt_second_SN',]
|