Getting started with your student project

Get access to the Ornstein lab ↺

During your project, you will work in the student room of the institute of GRAvitational and Subatomic Particles (GRASP) on the second floor of the Ornstein Laboratory (OL). Since the OL is a bit of a fortress, you will need a UU access card to let you into the building. Our secretariat can arrange both the card (in case you haven’t one yet) and the access. You can either remind me to send them an email, or send them an email yourself, mentioning and Cc-ing me. Getting access to the building requires a short online safety course.

Setup your Windows laptop ↺

If you are using a Windows laptop, you will probably need to set it up for this project. See this page for the possibilities. If you have a Linux machine or Mac, things will probably be much simpler.

Get a Nikhef account ↺

Depending on the circumstances, we may want to use the compute tools and resources at Nikhef. If we decide to do so, you must apply for a Nikhef account. In that case, remind me to send you this form, fill it out, sign it and send it to me via email. Ensure to fill out:

• @1: Bachelorstudent / Bachelor student   or   Masterstudent / Master student
• @2: Afstudeeronderzoek / Thesis project
• @3: Marc van der Sluys


• @5.1: Period: 1 February – 1 July or 1 September – 1 February
• @5.2: Group: Gravitational waves


• @6.1: Account: Yes
• @6.2: "Drop": No
• @6.3: Key: No

You will be contacted by the Nikhef Helpdesk once your account is created.

Git ↺

• Short general intro: https://en.wikipedia.org/wiki/Git_(software);
• Section 3 of Getting started with Bash, Emacs, Python and Git describes all git-functions we will (probably) need - albeit for the command line, but the buttons in a graphical program do exactly the same: https://pub.vandersluys.nl/#Computing
  • Comparable: https://astrofloyd.wordpress.com/2012/12/16/git-for-coworkers/
• Intro/refresh course (~2h) to git: https://kb.nikhef.nl/computing-course/git-novice/
• Official documentation: https://git-scm.com/doc (a lot, use for more info after you got started using git; we don’t need 99%;
• If you prefer a graphical program for git: https://git-scm.com/downloads/guis
  • use TortoiseGit: if you are new to git (recommended to new students);
  • use Sourcetree: more powerful but overwhelming at first.
• rules:
  1. ALWAYS work in the git directory, NEVER copy the files elsewhere, edit them and copy them back … EVER
  2. ALWAYS work in the git directory, NEVER copy the files elsewhere, edit them and copy them back … EVER
  3. ALWAYS work in the git directory, NEVER copy the files elsewhere, edit them and copy them back … EVER

Python ↺

• IDE: PyCharm, Spyder
• Intro/refresh course (~2h) to Python: https://kb.nikhef.nl/computing-course/python-novice/
• We want to write (plain-vanilla) Python scripts; we do not use Jupyter notebooks or IPython.
• Read input into a Pandas DataFrame before using
• Get familiar with pip (or some similar tool) to install packages from the Python Package Index (PyPI).
• Ensure your Python scripts start with the following lines:

  #!/bin/env python
  # -*- coding: utf-8 -*-
  
  """ yyyy-mm-dd:  short description. """
  
  import colored_traceback
  colored_traceback.add_hook()
                    

  end with

  if __name__ == "__main__":
      main()
                    

  (if they contain a main() function), and that the main() (if any) function is the first function in your file.

Fortran ↺

• a good and free Fortran compiler is gfortran, part of the GNU Compiler Collection (gcc): https://gcc.gnu.org/wiki/GFortran
• this supports "modern Fortran": Fortran 90/95/2003/2008/2013/2018/…? - we don’t use Fortran 77 (or older)
• steps:
  1. download and install the compiler;
  2. find how to write a hello-world program through DuckDuckGo, call the file hello.f90 (*.f90 to indicate "modern" Fortran) and save it
  3. compile your hello.f90 - this produces a "binary executable" - a program that you can run on your computer
  4. run your program and be surprised at how "Hello world!" appears on your screen.
  5. get, compile, run, alter, recompile, etc. my example program: https://github.com/MarcvdSluys/Fortran-intro
• editors:
  1. https://fortran-lang.org/learn/os_setup/ides/
  2. https://fortran-lang.org/learn/os_setup/text_editors/
• coding rules
  • use "implicit none" for every function/subroutine;
  • use "intent in"/"intent out" for every input/output variabele.

Bash/terminal/shell ↺

• On computer clusters, we work in the terminal in a shell, usually bash. This is very Spartan and very efficient (once you get the hang).
• To get the hang, on https://pub.vandersluys.nl/#Computing, check out:
  1. Getting started with Bash, Emacs, Python and Git (for the basics)
     • move around, see where you are and what is there with cd, pwd and ls, and much more…
  2. Efficient use of the Linux command line in the Bash shell (for more depth)
• Intro/refresh course (~2h) to terminal shell: https://kb.nikhef.nl/computing-course/shell-novice/

Use and explore your Nikhef account ↺

Once you have your Nikhef account:

1. Change your password (if you haven’t already done so): see the documentation;
2. Create an account on the Nikhef Mattermost instance and send your username to me (see also the documentation);
1. you can use Mattermost in your browser or using an app;
2. subscribe to the stbc-users for help when using the cluster;
3. you can notify other users in a channel with @<username> and everybody in the channel with @all;
4. in the Mattermost Settings (cog in the top right) > Notifications, you can choose how to be notified when you are mentioned (e.g. desktop, mobile, email, ...).
3. Create an account on the Nikhef GitLab instance and send your username to me (docs);
4. Read the whole Security and privacy section: docs;
5. Beginner courses on Linux shell (bash), Git and Python: docs;
6. Login to the Stoomboot cluster using ssh: docs;
7. Use of the Stoomboot cluster: docs;
8. Submitting jobs to the Stoomboot cluster using HTCondor: docs.

LaTeX ↺

• If you’ve never used it before, check out Writing a short scientific paper: LaTeX template and instructions on, of course, https://pub.vandersluys.nl/#Computing (final pdf + zip with source)

• For efficient page usage in the EU, use

  \documentclass[11pt]{article}
  \usepackage[a4paper, pdftex, top=2.5cm, left=2.5cm, bottom=2.5cm, right=2.5cm]{geometry}  % A4 document
                  

• If you use Overleaf, make sure you share your thesis with me. If you use GitHub, idem.
• Before you send anything to me for feedback, run a spell check

Binaries and GWs: theory and observations ↺

Binary evolution and GWs

• Binary evolution in a nutshell (BEiaNS): most of the theory of binary evolution we need here
• Een korte inleiding in de sterrenkunde (Dutch): my first-year lecture notes on stellar evolution (Ch.1-3), binary evolution (Ch.4) and gravitational waves (Ch.5)
• Population synthesis:
  • SSE paper (single-star evolution): http://adsabs.harvard.edu/cgi-bin/nph-bib_query?bibcode=2000MNRAS.315..543H
  • BSE paper (binary-star evolution): http://adsabs.harvard.edu/cgi-bin/nph-bib_query?bibcode=2002MNRAS.329..897H

DWDs

• https://www.aanda.org/component/article?access=bibcode&bibcode=&bibcode=2006A%2526A...460..209VFUL (click on PDF). Sections 1 an 2, and Table 1 are essential, the rest is different, because we use a different method and code.
• https://iopscience.iop.org/article/10.3847/1538-4357/ac13ac This is about post-CE binaries, compact binaries that probably went through a CE phase. I haven’t fully read the paper, but the question is whether their database contains more DWDs for which we know both masses and preferably cooling ages.

γ-EE

• Nelemans et al. 2000, 2005;   MvdS et al., 2006;   Woods et al., 2012

LIGO-Virgo-KAGRA detections

• The Gravitational-wave Transient Catalogue (GWTC)

Population synthesis ↺

The BSE-postprocess code

1. Get bse-postprocess from GitLab
2. Run on the provided small example DWDs_test_1000.out and understand what happens
3. Run on an earlier output example and reproduce previous results

$ ./bse-postprocess.py -h  # Show all the options (-h == --help)

usage: bse-postprocess [-h] [-r REPLICATION] [-p] [-s MIN_SIGMA] [-S MAX_SIGMA] [-v | -q | -d] input_file

Postprocess output from the BSE/Popbin population-synthesis code (Utrecht branch).

positional arguments:
  input_file            name of the input file, e.g. DWDs_000001.out

options:
  -h, --help            show this help message and exit
  -r REPLICATION, --replication REPLICATION
                        replicate each zero-age binary with this factor (default: 25)
  -p, --plot            create plots (default: False)
  -s MIN_SIGMA, --min-sigma MIN_SIGMA
                        use 1-, 2- or 3-sigma accuracies as minimum (default: 3)
  -S MAX_SIGMA, --max-sigma MAX_SIGMA
                        use 1-, 2- or 3-sigma accuracies as maximum (default: 3)
  -v, --verbosity       increase output verbosity (default: 1)
  -q, --quiet           produce no output (default: False)
  -d, --debug           print debug/test info (default: False)


$ ./bse-postprocess.py DWDs_test_1000.out   # Run on the test file
Reading input file DWDs_test_1000.out...
Replicating DWDs 25 times...
Evolving and filtering DWDs...

Matches 3-sigma tau:    2:  [0. 3. 2. 0. 0. 0. 0. 0. 0. 0. 0.]
Matches 3-sigma no tau: 2:  [0. 3. 2. 0. 0. 0. 0. 0. 0. 0. 0.]
Number of matched observed DWDs with tau:   2
Matched observed DWDs with tau:             [1 2]
Non-matched observed DWDs with tau:         [ 0  3  4  5  6  7  8  9 10]
Number of matched observed DWDs without tau:   2
Matched observed DWDs without tau:             [1 2]
Non-matched observed DWDs without tau:         [ 0  3  4  5  6  7  8  9 10]


$ ./bse-postprocess.py -p DWDs_test_1000.out   # Run on the test file AND make the plots
                

Note that when running in an IDE, you need to pass the command-line options to your IDE. This section shows how to so that with PyCharm, using the Parameters field. For Spyder, this answer is useful.

The BSE/Popbin code

1. Get the "Utrecht branch" of the BSE/Popbin code from GitLab
2. See the local documentation in Orgmode or PDF format
3. Compile the code
4. Compute examples
5. Check, understand and analyse the output with bse-postprocess.py
6. Official home of the original BSE/Popbin code: https://astronomy.swin.edu.au/~jhurley/
   If you need to edit the BSE code itself, it is useful to use the two papers below as a reference — they show in equations what is coded up in Fortran and provide much background.
   • SSE paper (single-star evolution): http://adsabs.harvard.edu/cgi-bin/nph-bib_query?bibcode=2000MNRAS.315..543H
   • BSE paper (binary-star evolution): http://adsabs.harvard.edu/cgi-bin/nph-bib_query?bibcode=2002MNRAS.329..897H

Building the BSE/Popbin code

In order to build the Utrecht BSE/Popbin code, you first need to install the build tools and libSUFR library. You can download the latest libSUFR tarball from SourceForge.

Install build tools: Linux and macOS

Depending on the Linux flavour you use, your package manager may be called something like emerge, pacman, apt, apt-get, aptitude, yum or something else. For macOS you can use Homebrew (command brew). The command will look something like

emerge -vau net-misc/wget sys-devel/gcc dev-build/make dev-build/cmake  # Gentoo Linux and related - probably already installed
pacman -S wget make cmake gcc   # Arch Linux and related
yum install wget make cmake gcc  # CentOS, Redhat, etc.
brew install wget make cmake gcc  # MacOS  

Install build tools: MS Windows

Apparently, there exists something called Windows subsystem for Linux (WSL), which sounds like a Linux subsystem for Windows. It is allegedly an attempt by Microsoft to make Windows useful for professionals, and may be your best bet to turn your laptop into a machine useful to do science on. Since I cannot (legally) download Windows for free, I cannot experiment with this — please let me know what is needed to do this if you succeeded in installing and using WSL.

If this did not work, or perhaps needed in addition to WSL, you can try Cygwin to get a Linux-like environment on your Windows machine. Or perhaps Chocolatey to install the packages wget make cmake gcc/gfortran. Windows is not known for its high quality or user friendliness, but you can probably contact the local vendor you purchased your OS from for the support you paid for.

Build dependencies: most OSs

(If on Windows, ensure you have your Linux-like environment installed.) You can use wget to download libSUFR to the current directory - ensure you use the latest version. (Alternatively, use your browser to download and save the tarball in the desired directory.)

mkdir /some/directory/where/you/want/to/install/libsufr
cd /some/directory/where/you/want/to/install/libsufr
wget https://sourceforge.net/projects/libsufr/files/libsufr-0.7.8.tar.gz
tar xfz libsufr-0.7.8.tar.gz
cd libsufr-0.7.8/
mkdir build
cd build/
cmake ..
make            

Get, configure and compile BSE/Popbin

After installing libSUFR, from the build/ directory, do

cd ../usr
pwd
ls -l
ls -l include/libSUFR/  # Should contain *.mod files 
ls -l lib/              # Should contain libSUFR.*        

Next we need to get and build BSE/Popbin itself. Ensure you have set up ssh access to Nikhef, preferably with an ssh key. Then

cd /some/directory/BELOW/WHICH/you/want/to/install/BSE
git clone git@gitlab.nikhef.nl:sluys/bse-code.git
cd bse-code/
cp doc/Makefile .  # Copy the Makefile from the dir where it is shipped to your compile dir
                

The shipped Makefile is for my system; we need to adapt it for yours. In particular, we need to tell it where to find libSUFR. Open the Makefile in your favourite text editor (not Word, a text editor). Find the block that says gfortran and within that block the lines that start with CFLAGS += -I and LFLAGS += -l. The change them to read

   CFLAGS += -I/the/path/to/your/module/files
   LFLAGS += -L/the/path/to/your/library/files -lSUFR
                

Here, -lSUFR is the name of the library files (libSUFR.*), where lib replaced by -l and the extensions have been dropped. Save the file as plain text! and in the directory of the edited Makefile run

make  # this should call gfortran to build (compile and link) `sse`, `bse` and `popbin`

Your directory should now contain a binary executable (note the x at the front) called popbin:

ls -l

-rwxr-xr-x 1 sluys 237K  Fri 28 Feb 14:47 popbin

Running BSE/Popbin

In order to run the popbin binary executable, you need

1. the binary executable popbin
2. an input file like binary.in

The easiest way is to create a new directory for each run, and copy the two files there. (Alternatively, you could create a symbolic link for popbin.) Once you are in the directory with these two files, ensure to create no more than 1000 binaries by editing binary.in and simply run

./popbin  # should take the binary.in in the current directory and run whatever is set in there

Alternatively, you can

./popbin  &  # Run it in the background - you get your prompt back and can do other things in your terminal while popbin is running

./popbin binary2.in   # Run with a different settings file
time ./popbin  # time how long a run takes

wc -l binaries.out  # See how many lines are in the output file (yet)
less DWDs.out  # Have a peek, use space to jump forward, q to quit