In this notebook we show how to enable and use the event based logging, which is a set of standardised outputs from `binary_c` for events like supernovae and Roche-lobe overflow episodes.
The events that are available in this version of `binary_c-python` are listed on [the events based logging page in the documentation](https://binary_c.gitlab.io/binary_c-python/event_based_logging_descriptions.html).
The relevant options for this functionality are prepended with `event_based_logging_` (see the [population options documentation](https://binary_c.gitlab.io/binary_c-python/population_options_descriptions.html) and the [binary_c options documentation](https://binary_c.gitlab.io/binary_c-python/binary_c_parameters.html))
The events are all flagged with a uuid that allows for matching events that come from the same system. This is useful for example to track the events that preceded the formation of double compact objects, so we can study their evolutionary path.
To enabled the event-based logging in binary_c we need pass the `event_based_logging_enable_event_logging=1` setting to `binary_c`. We also need to specify the specific events that we want to have logged, by passing any of the following parameters:
## Enabling event-based log handling in `binary_c-python`
To enable the automatic processing of the event logs with `binary_c-python`, we need to set `event_based_logging_handle_output=1`
This allows `binary_c-python` to automatically process the output of binary_c and create output files that contain the event logs.
There are several options pertaining to the processing of these output files:
-`event_based_logging_combine_individual_event_files`: whether to automatically combine all the process-specific event log files into one combined file.
-`event_based_logging_combined_events_filename`: filename of the combined event file.
-`event_based_logging_remove_individual_event_files_after_combining`: whether to remove the process-specific event log files after combining.
-`event_based_logging_split_events_file_to_each_type`: whether to split the combined event file into event-specific files.
-`event_based_logging_remove_original_combined_events_file_after_splitting`: whether to remove the combined event file after splitting.
-`event_based_logging_output_separator`: separator used for writing the events.
-`event_based_logging_output_parser`: parsing function to handle the output of binary_c. There is a function already present for this, so no need to provide this yourself unless you have special requests.
-`event_based_logging_parameter_list_dict`: dictionary that contains the parameter name list for each specific event (see [the events based logging page in the documentation](https://binary_c.gitlab.io/binary_c-python/event_based_logging_descriptions.html)). The current present dictionary is designed to handle the events that are present in this release, but if you add your own events you need to update this dictionary or provide a custom one.
<<<< Warning: Key does not match previously known parameter: adding: data_dir=/tmp/binary_c_python-david/notebooks/notebook_events_based_logging/data_dir to custom_options >>>>
adding: event_based_logging_enable_event_logging=1 to BSE_options
adding: event_based_logging_enable_SN_event_logging=1 to BSE_options
adding: event_based_logging_enable_RLOF_event_logging=1 to BSE_options
adding: event_based_logging_handle_output=True to population_options
adding: event_based_logging_combine_individual_event_files=True to population_options
adding: event_based_logging_remove_individual_event_files_after_combining=False to population_options
adding: event_based_logging_split_events_file_to_each_type=False to population_options
adding: event_based_logging_remove_original_combined_events_file_after_splitting=False to population_options
And lets provide some systems that can generate us some events. We use a set list of systems through the source-file sampling functionality but that is only for this example. For a more serious sampling you can use e.g. the grid-based sampling (see [grid-based sampling notebook](https://binary_c.gitlab.io/binary_c-python/examples/notebook_population.html))
<<<< Warning: Key does not match previously known parameter: adding: source_file_sampling_type=command to custom_options >>>>
<<<< Warning: Key does not match previously known parameter: adding: source_file_sampling_filename=/tmp/binary_c_python-david/notebooks/notebook_events_based_logging/source_file_sampling_filename.txt to custom_options >>>>
adding: evolution_type=source_file to population_options
File ~/.pyenv/versions/3.9.9/envs/binarycpython3.9.9/lib/python3.9/site-packages/binarycpython/utils/population_class.py:488, in Population.evolve(self)
485 return
487 # Execute population evolution subroutines
--> 488 result = self._evolve_population_wrapper()
489 if result is False:
490 print("Error detected in _evolve_population() : stopping here")
File ~/.pyenv/versions/3.9.9/envs/binarycpython3.9.9/lib/python3.9/site-packages/binarycpython/utils/population_extensions/evolution_functions.py:61, in evolution_functions._evolve_population_wrapper(self)
51 """
52 Function to evolve populations. This handles the setting up, evolving
File ~/.pyenv/versions/3.9.9/envs/binarycpython3.9.9/lib/python3.9/site-packages/binarycpython/utils/population_class.py:580, in Population._setup(self)
File ~/.pyenv/versions/3.9.9/envs/binarycpython3.9.9/lib/python3.9/site-packages/binarycpython/utils/population_extensions/source_file_sampling.py:173, in source_file_sampling._source_file_sampling_setup(self)
168 """
169 setup function for the source file sampling evolution method
170 """
172 # check if file exists
--> 173 if not os.path.isfile(self.population_options["source_file_sampling_filename"]):
As we see above, we now have some events that we can analyse. The parameters contained in each of these lines are described in [the events based logging page in the documentation](https://binary_c.gitlab.io/binary_c-python/event_based_logging_descriptions.html).
As we see above, we now have some events that we can analyse.
We can parse the contents of each of the events with the `event_based_logging_parameter_list_dict`.
The parameters contained in each of these lines are described in [the events based logging page in the documentation](https://binary_c.gitlab.io/binary_c-python/event_based_logging_descriptions.html).
The next step would be to run a larger population and log all the events of interest. We can then use the UUID's to cross match certain different events with each other and perform (complex) queries to select e.g. the BHBH DCO_FORMATION events that have experienced at least one pulsational pair-instability supernova.
