Asiago School 2022 - Binary Populations

You have a choice here. You can either use the provided Virtualbox virtual machine (VM), or build binary_c yourself. Building binary_c is not difficult, but of course requries a bit of knowledge. I recommend you have a go, because you're here to learn.

This is the simplest option: just install Virtualbox, download the VM (link below) and just run it.

• You should make sure you have the latest version of Virtualbox installed. I'm currently running 6.1.26 r145957 (Qt5.15.2) and you should be able to install at least this verson. If the Virtualbox website isn't up, try download.virtualbox.orginstead, or install Virtualbox as a system package.
• You can find the virtual machine (VM) in OVA format at Zenodo or the University of Surrey. In Virtualbox, select File ➜ Import Machine, select the binary_c-2.2.1.ova file, and import the machine.
• The VM should then be installed in Virtualbox. It is called binary_c 2.2.1 (or similar). Before launch it, you may want to explore its settings, e.g. its memory use, number of CPUs, etc. to tailor these to your PC.
• Launch the VM (double click on it in the Virtualbox list). The VM username and password are both binary_c.
• Once you are logged in, open a terminal by clicking the menu button in the bottom left corner, then click "Konsole".
• Binary_c is in the directory $BINARY_C which is /home/binary_c/binary_c
• Binary_c-python is at /home/binary_c/git/binary_c-python, documentation here.
• You can run the script $HOME/update_binary_c_VM.sh to update the binary_c and binary_c-python builds automatically. Given that I am working on the examples for the lectures during the weekend before, this is probably necessary!
• If your binary_c fails to run, try the $HOME/update_binary_c_VM.sh script to rebuild it. It's always possible there's something odd about your system that makes it different from mine.
• The virtual disk has 15GB of space: this is usually enough. You can expand this though, a quick web search provides many tutorials, e.g. this one.

If you have never built software from source before, then now is the time to learn! I highly recommend learning these skills as they will be very useful to you in the future. Binary_c uses meson, which is a modern and efficient build system.

• You need some system software installed, such as a C-compiler, e.g. gcc or clang, Perl, Python, GSL and the build tools meson and ninja. Most of these are available as system packages.
• On Linux systems, there is usually a package called build-essentials (or similar) which must be installed. You also require libbsd-dev on Ubuntu or Debian (or similar). There are likely other requirements: please let me know and I'll update the list but I cannot support every operating system variant.
• Full installation instructions are at section 4 of the binary_c documentation.
• The binary_c source code is at our University of Surrey gitlab server https://gitlab.eps.surrey.ac.uk/ri0005/binary_c.

Note that binary_c is highly modular, so it uses support libraries wherever possible rather than support a huge code base itself. This is different to (say) MESA which requires the enormous MESA SDK, but does mean you may have to install these libraries. You only have to do this once!

• Linux (Ubuntu) users can use the script at this link. Run,

  wget https://r-izzard.surrey.ac.uk/ubuntu_install_binary_c.sh
  chmod +x ubuntu_install_binary_c.sh
  ./ubuntu_install_binary_c.sh

  For this school you do not need to install your own Perl, but you will need root access to install system packages as required.
• Otherwise the installation instructions are at section 4 of the binary_c documentation. Binary_c works on Linux, MacOSX and Windows using the Linux subsystem.

Please make sure you understand how environment variables work. On Linux, you need to set,

• BINARY_C to point to your binary_c directory.
• LD_LIBRARY_PATH to point to $BINARY_C/src so that other applications know where to get the binary_c shared library once it is built, and perhaps also to point to your installations of helper libraries (like GSL, librinterpolate, librchash, libmemoize etc.).
• LIBRARY_PATH also needs to point to the same locations as LD_LIBRARY_PATH but is only required during the compilation and linking stage (it is used only by your compiler).
• Your PATH should include the BINARY_C directory, e.g.

  export PATH=$PATH:$BINARY_C

Note: on MacOSX, LD_LIBRARY_PATH is DYLD_LIBRARY_PATH. They really do like to be annoyingly different...

• Because system versions are often rather out of date, you should probably install the latest versions of meson and ninja with, e.g.,

  pip3 install ninja --user
  pip3 install meson --user

• You then need to check that your PATH includes the directory to which these are installed. On Linux this is .local/bin, so you should

  export PATH=$PATH:$HOME/.local/bin

  or similar.

Once everything is working, run

$BINARY_C/binary_c-config version

and you should see something like

2.2.1

Note: The $BINARY_C/ prefix is not required if $BINARY_C is in your PATH.

The binary_c-python module allows us to run binary_c in a Jupyter notebook. Example scripts are provided and I recommend the following for the course.

• If you have downloaded binary_c-python, you will find the exercises in the examples directory. On the VM this is at /home/binary_c/git/binary_c-python/examples.
• You can access this material online at the Gitlab repository.
• Documentation is here.
• You should then run

  jupyter-lab notebook_name.ipynb

  to launch the Jupyter lab notebook in a web browser (usually Firefox).
• To run the notebook, press the button that looks like ⯮ (hover over it and it should say "Restart the kernel, then rerun the notebook.")
• You can load other notebooks from within this notebook window.

This list of papers is certainly not complete, but they have been chosen for their pedagogical content rather than raw science.

• de Marco and Izzard (2018) Dawes Review 6: The Impact of Companions on Stellar Evolution This is a review of binary-star physics with many useful references.
• Izzard and Halabi (2018) Population synthesis of binary stars This a review of how we perform binary-star population studies. It is a book chapter in 'The Impact of Binary Stars on Stellar Evolution' by Giacomo Beccari and Henri Boffin (Cambridge University Press).

• binary_c homepage
• binary_c on gitlab
• We have a binary_c Slack channel if you want to get involved.
• binary_c's YouTube channel
• binary_c on facebook
• binary_c on twitter