binary_c-python

For my research during my masters and PhD I’ve made us of the rapid (binary) stellar evolution code binary_c, to simulate (binary) star systems. The population-synthesis wrapper that enabled running many of these systems was written in Perl but I decided to rewrite this into a Python based code.

The code is well documented and automatically generated based on docstrings, and is available on Gitlab and Pypi. We provide tutorial and example notebooks on how to use the code technically, and how to actually calculate useful things with it on documentation page.

We have recently released version 1.0.0 for binary_c version 2.2.4. This version release contains many code-base changes and restructuring. I have implemented a (beta) version of Monte-Carlo based sampling, input validation for the population configuration, handlers for event-based logging (standard outputs for events like supernovae, Roche-lobe overflow, stellar mergers etc), a more formal logging structure and many more small features and bug fixes.

Moreover, along with this new version, the software-release paper has been published in the JOSS (Hendriks & Izzard, 2023).

Since publishing in the JOSS and releasing v1 I have focussed on some other things like wrapping up my thesis, so I did not develop that many new features lately. But, my thesis is now finished so I have some more room to work on this again and the plan is to implement some new functionality. My main goals are to:

  • Implement starformation-rate convolution methods for both event-based data and ensemble data. The code for this exists already but needs to be properly implemented in the codebase. update: This is now nearly finished, and being beta-tested.
  • Adopting the ensemble_manager into the codebase. This manager is responsible for running many different simulations and manages where things are stored and what parameters are varied. This is very useful for large grids of parameter variations. Rob Izzard wrote this but its not yet part of the binary_c-python code. I will rename this tool to simulation_manager.
  • Design handle_simulation routine: This routine will handle setting up a population object, evolve the population for a range of metallicities, post process the output, convolve the results and more. This function should just receive a dictionary with configurations and instructions and then handle the rest. This function will be used by the simulation_manager.
  • finalise MC sampling. I’ve implemented a lot of stuff regarding MC sampling, which will be useful when modeling systems with low mass. Most of the code works, but it just needs some better testing.
  • Finalise adaptive importance-sampling implementation: I’ve written a tool that consumes ‘hits’ and from that builds a gaussian mixture model that can be evaluated very fast, and provides marginalisation and conditioning. Currently working on having the population objects properly manage this tool and update the sampling variables.

## Usage

The installation instructions for binary_c-python are available here. To use binary_c-python you need to have binary_c installed (docs and git).

A very simple example of running a system is,

  from binarycpython import run_system

  res = run_system(M_1=10, M_2=5, orbital_period=200, log_filename='log.txt', event_based_logging_SN=1)
  print(res.strip())

where run_system handles the call to binary_c which evolves a system with the properties we passed along. More complex examples are available through our tutorial and example notebooks.

## References

Hendriks, D. D., & Izzard, R. G. (2023). Binary\_c-python: A Python-based stellar population synthesis tool and interface to binary\_c. Journal of Open Source Software, 8(85), 4642. https://doi.org/10.21105/joss.04642
David Hendriks
David Hendriks
Visiting Researcher Astrophysics, Research Software Engineeer

My research is on stellar astrophysics and the formation of compact objects, but I’m interested in many science related topics!