The binary_c stellar-population-nucleosynthesis framework
The binary_c and binary_grid codes together form a state-of-the-art software framework for the evolution of single and binary stars, nucleosynthesis studies and stellar population calculations.
The binary_c code, an enhanced C-port of the Binary Star Evolution (BSE) code of Hurley et al. (2002) with many updates, provides stellar evolution for stars in the range 0.1 to 100 solar masses. Many enhancements have been implemented especially in the binary-star interaction algorithms and to bring other prescriptions up to date, such as stellar wind mass loss, mass transfer by Roche-lobe overflow and the treatment of stellar mergers. The latest physics additions include runaway stars and circumbinary discs.
The latest version of binary_c is 2.2.0. It can be built as a thread-safe shared library which is accessible to third-party tools, such as binary_c-python or your code, through a set of standard API functions.
The binary_c nucleosynthesis library (nucsyn) runs in parallel to binary_c. It models low- and intermediate-mass stars (first, second and third dredge up, hot bottom burning), massive stars (core-collapse supernovae based on various prescriptions), and binary products such as novae, type Ia supernovae, polluted stars (barium, CH, CEMP etc.) and mergers (e.g. R and J stars). Much of the development of this part of binary_c was during my PhD, subsequent postdocs in Utrecht/Nijmegen and Brussels, my professorship in Bonn, and return to the U.K. as a Rutherford fellow in Cambridge.
The new binary_c-python module is designed to eventually replace the established binary_grid code (see below). If you use Python and want to do things with binary_c, I highly recommend trying it. Download at gitlab.
The binary_grid manages the evolution of populations of single and binary stars, with emphasis on ease-of-use and efficiency on multi-CPU PCs and multi-PC computing clusters. Binary_grid automatically interfaces with HTCondor or Slurm to distribute computational load across e.g. a whole institute or beyond.
The latest version of binary_grid is 2.1.3. This is a fully object-oriented, thread-safe rewrite of binary_grid. For example, to make a population of 100 solar-metallicity single stars spanning the Kroupa (2001) initial mass function from 0.1 to 80Msun:
$population = binary_grid2->new(
metallicity => 0.02, # mass fraction of "metals"
max_evolution_time => 15000, # Myr
nthreads=>4, # number of CPUs
'name' => 'lnm1',
'longname' =>'Primary mass',
'resolution' => 100, # just a counter for the grid
Binary_grid2 has two backends: the traditional Perl and C. The Perl backend is based on binary_grid V1 and connects binary_c to binary_grid with a bi-directional Unix pipe. This backend has been tested for years and works well on multiple platforms. The new C backend uses the binary_c API to communicate directly with the binary_c core. This is faster and more efficient, furthermore it scales far better on multi-core systems.
The results of the evolution are stored in the $population object, which can be used or saved for later statistical analysis (e.g. with R).
Binary_grid2 works seamlessly with the HTCondor or Slurm distributed computing platform. You can then run your stellar populations on many CPU cores rather than just your local PC. You just need to set one variable and a few options to make this work completely transparently.
You can try binary_c online right now!
The binary_c code is hosted at the University of Surrey gitlab server. The code is freely available, but if you require development rights, please see these instructions which require a Google account. If you are using binary_c, please drop me an email to let me know.
You can also access binary_c through a Docker container at https://hub.docker.com/r/robizzard/binary_c, instructions are here.
All users, if they make changes that are useful for the community at large, are expected to share these with the main code base. This is a condition of the licence agreement. This is done by using the usual version control branch/merge process. Documentation is included as standard and is kept up to date as best we can. We also have:
The latest binary_c includes algorithms described primarily in Izzard et al. (2004), Izzard et al. (2006), Izzard et al. (2009) and Izzard et al. (2018). Further updates are in Claeys et al. (2014), de Mink et al. (2014) and Abate et al. (2015). A licence agreement is included with the code: if you use it, you are bound by this agreement. Please read it.
- 08/2021 binary_c V2.2.0 released
- Binary_c workshop videos are available on YouTube.
- 2020 binary_c V2.1.7 released
- 12/2019 binary_c V2.1.6 released
- binary_c workshop 2-4th December 2019, at the University of Surrey and via Zoom.
- 08/11/2019 binary_c V2.1.3 released
- 07/10/2019 binary_c V2.1.2 released
- 21/03/2019 binary_c now available on Docker
- 21/03/2019 binary_c V2.0pre32 released
- 26/10/2016 binary_c V2.0pre26 released
- 26/10/2016 binary_grid V2.00 updated
- binary_c days, 8th and 9th September 2015 at the IoA: a series of educational seminars, talks and discussions about the binary_c code . programme
binary_c remains under development in collaboration with many astrophysicists around the world, notably and currently,
Binary_c is used in international projects based in, amongst others, Bonn, Cambridge, Surrey, Chile, Amsterdam, Nijmegen, Beijing, Melbourne, Toronto and the U.S.A.
- The core package is the binary_c/nucsyn binary stellar evolution and nucleosynthesis code. This can be compiled and run as a standalone unit.
- The binary_grid runs grids of stars e.g. with different masses, orbital periods etc. It is written in Perl and as such is highly flexible and easy to modify. Many thousands of stars can be run in an hour, millions in a day. The latest version automatically takes advantage of threading on multi-core architectures and HTCondor or Slurm distributed computing clusters to speed up calculations.
- The output can consist of event rates (e.g. supernovae, gamma-ray bursts), number counts (e.g. the number of R or K-type stars) or chemical yields i.e. the amount of material ejected as a particular isotope.
- I have written a Galactic chemical evolution code which uses binary_c to calculate the chemical history of the Galaxy. It has gas infall and outflow and can be fed an arbitrary star formation history. The same model follows both chemistry and an arbitrary number of stellar observables, such as the number or luminosity of stars as a function of time and/or metallicity.
binary_c includes the following physics in its nucleosynthesis:
- First and second dredge-up fitted to the detailed nucleosynthesis models of
Lattanzio and Pols (2002), Karakas and Lattanzio 2007 and others from Evert Glebbeek and Richard Stancliffe.
- The effects of third dredge-up updated with the models of Karakas and Lattanzio 2007. Free parameters are available to artificially increase the amount of third dredge up, as may be required in the Magellanic clouds or at low metallicity.
- The s-process according to the models of Robert Gallino and collaborators with variable s-process efficiency.
- Hot-bottom burning via the CNO, NeNa and MgAl cycles/chains during the AGB. True nuclear network calculations have replaced the original analytic formalism. The reaction rates can be varied within experimental limits.
- Phenomenological fits to massive and Wolf-Rayet star surface abundances based on the models of Lynnette Dray (Dray
et al. 2003) with supplemental models from Richard Stancliffe.
- Supernovae: types Ia, II and Ib/c with yields fitted to published
models (Woosley and Weaver 1995, Iwamoto et al. 1999, Arlandini et al. 1999, Simmerer 2004, Livne and Arnett 1995, Woosley, Taam and Weaver 1986, Chieffi and Limongi 2004, Wanaja et al. 2008).
- Nova yields fitted to Jose and Hernanz (1998).
- Roche-Lobe Overflow (RLOF), common-envelope loss contribution to yields.
- Mass loss due to stellar winds and mass gain from a companion's wind (Bondi-Hoyle accretion).
- A momentum-collision argument for treating colliding winds.
- Accretion is treated with a two-layer model assuming either instantaneous or no thermohaline mixing.
The following binary-star physics is in addition to that of the Hurley et al. (2002) BSE package:
- Mass transfer stability according to various prescriptions, including the latest Ge et al. (2015).
- Common envelope efficiency from Nandez and Ivanova (2015).
- Hachisu-style disk winds for SNeIa production.
- Accretion during the common-envelope phase.
- Adaptive RLOF scheme designed to ensure R=RL and no accretion if the star is spinning at break-up, V>Vcrit, hence conservative/non-conservative RLOF.
- Hybrid RLOF scheme based on Claeys et al. 2014 for extra speed and reliability.
- Rotationally enhanced mass loss.
- Improved treatment of helium-core mergers (in relation to the formation of the R stars).
Highlighted papers which use binary_c (please note: this list is not updated regularly, so if your paper is missing just let me know and I'll add it.)
Detailed binary_c and binary_grid documentation is available online here and in the binary_c source tree in the doc directory in PDF and LyX form. Please see the instructions for getting binary_c and then look in binary_c/doc.
binary_c has a C API which can be accessed through the binary_c shared library interface, e.g. with C, C++, FORTRAN or Java, or scripting languages like Perl and Python. binary_grid2 uses the API with Perl/C interface.
The following C example uses the API to set up a stellar system containing a 10 and 5 Msun binary with a 10 day circular orbit, and evolve it for 100 Myr.
struct libbinary_c_stardata_t * stardata = NULL;
struct libbinary_c_store_t * store = NULL;
char * argstring = "binary_c M_1 10.0 M_2 5.0 metallicity 0.02 period 10.0 max_evolution_time 100.0 eccentricity 0.0";
Output is usually sent to the terminal (stdout) but it can also be redirected to a buffer, for example:
char * buffer;
/* ... */
stardata->preferences->internal_buffering = INTERNAL_BUFFERING_STORE;
stardata->preferences->batchmode = BATCHMODE_LIBRARY;
/* buffer now contains the output for this system */
The buffer can now be processed for stellar system properties, e.g. Hertzsprung-Russell diagram positions, binary orbits, supernova explosions etc.