For the purposes of the tutorial, I will assume the user has installed COFFE using Method 1: with Docker, which is the recommended install method in order to avoid dependency issues. Some familiarity with the command line interface (CLI)/terminal is needed. The COFFE README and manual are additional useful resources.
Note for Windows users: I do not know if any of the below will work on Windows machines, because I have not made any tests on Windows, though the Docker version may function properly. Installing the Windows Subsystem for Linux may prove to be useful.
Support
For any issues encountered during the installation, or with running the code, please open a Github issue or contact me directly at goran.jelic-cizmek@unige.ch.
Method 1: with Docker (easy, but 🚨 requires restart🚨 (maybe))
Step 1 - setup environment
First, Download Docker. You can get it for:
Follow the installation instructions there for your specific operating system.
Step 2 - download the image
Once you're done, and Docker works properly, just run the following command from a terminal:
docker pull jcgoran/coffeThis will pull the COFFE image from Dockerhub (may take some time to download).
Step 3 - run it
Now you can go to some (preferably empty) directory.
Given some settings file settings.cfg, you can then run COFFE using:
docker run --rm -ti -v "$(pwd):/data" jcgoran/coffe coffe -s settings.cfg -n 4Here n denotes how many processes to spawn (by default it's just 1), i.e. how many threads to use for the computation.
Step 4 - the output
You may see something like the following when you run it:
user@computer:~/coffe$ coffe -s settings.cfg
_____ ____ ______ ______ ______
/ ____/ __ \| ____| ____| ____|
| | | | | | |__ | |__ | |__
| | | | | | __| | __| | __|
| |___| |__| | | | | | |____
\_____\____/|_| |_| |______|
Parsing settings file "settings.cfg"...
Launching CLASS...
CLASS finished in 10.85 s
Settings file "settings.cfg" parsed in 10.85 s
Number of threads in use: 1
Initializing the background...
Background initialized in 0.32 s
Calculating integrals of Bessel functions...
Integrals of Bessel functions calculated in 0.16 s
Calculating multipoles...
WARNING: maximum separation too high; cutting off list at the value 640.00 Mpc/h
Multipoles calculated in 0.04 s
WARNING: output directory exists, some files may be overwritten!
Writing output to "results/2020-11-02-21-09-53_"...
Output finished in 0.03 s
Total program runtime is: 11.40 s
After running the above command with the default settings file, you should have a sub-directory results/ with contents like 2020-11-03-[HH]-[MM]-[SS]_, with various suffixes like multipole0.dat, background.dat, and settings.cfg.
Those are the multipoles of the 2-point correlation function, the redshift-dependent quantities such as the scale factor, the comoving distance, etc., and the original input settings file, respectively.
Have a look at the default settings.cfg file, available online here, for all of the possible options.
NOTE: Docker is a bit strange when it comes to permissions of created files, so it's possible that the output ends up being owned by root (see third and fourth column of output when running ls -l on an output file); a simple, albeit clumsy solution is to run sudo chown -R $USER:$USER [DIRECTORY] on whichever directory you saved the output.
A second option is to run the above Docker command with the extra flag --user "$(id -u):$(id -g)", which will automatically run the container as the current user.
As the Docker command above is a bit long to type, you can put the following in your ~/.bash_aliases file (or ~/.bashrc if the former doesn't exist):
alias coffe='docker run --rm -ti --user "$(id -u):$(id -g)" -v "$(pwd):/data" jcgoran/coffe coffe'This allows you to run COFFE from any directory by simply calling:
coffe -s settings.cfg -n 4NOTE 2: COFFE may warn you about missing input files - this is caused by an absence of the file defined by the variable input_separations.
By default, COFFE outputs the following separations: [10., 20., 40., 100., 120., 150., 200., 250., 300., 350] (in Mph/h).
If you would like to compute the signal (2PCF, multipoles) for some other separations (and make COFFE stop complaining), something like for i in {10..1000..10}; do echo "$i" >> separations.dat; done and setting input_separations="separations.dat" will do the trick.
Method 2: from the tarball (medium)
Step 1 - install dependencies
In addition to a C99-compatible compiler like GCC or Clang, the following libraries are needed to build COFFE:
- FFTW
- libconfig
- GSL; for Debian-like distributions, it's available under the package
libgsl-dev - CUBA (optional)
- CLASS (optional)
Step 2 - download
Download the latest preview release of COFFE, available here, and save it in some directory on your machine. You can get it by using curl in the terminal (in this case, version 2.0.4):
curl https://github.com/JCGoran/coffe/releases/download/v2.0.4/coffe-2.0.4.tar.gz -o 'coffe-2.0.4.tar.gz'Extract the contents of the archive using:
tar xf coffe-2.0.4.tar.gzChange into the COFFE directory:
cd coffe-2.0.4/Step 3 - setup the environment
In the COFFE directory, run:
./configureIf you've additionally installed CLASS or CUBA, you can instead run:
./configure --enable-class --enable-cubaIn this case, make sure the output of the above command doesn't have anything like "WARNING: CUBA library not found." or "WARNING: CLASS library not found.", since then you'll need to manually set the variables CPPFLAGS, LDFLAGS, and LIBS, with something like:
CPPFLAGS="${CPPFLAGS} -I/path/to/[class/cuba].h"
LDFLAGS="${LDFLAGS} -L/path/to/lib[class/cuba].a"
LIBS="${LIBS} -l[cuba/class]"Usually, if you put CLASS and/or CUBA headers and libraries in /usr/local/include and /usr/local/lib, respectively, then there shouldn't be any warnings.
Then simply run:
make -j coffewhich should create an executable file called coffe.
Step 3 - run it
After COFFE compiled successfully, you can run it with:
./coffe -s settings.cfg -n 4Here settings.cfg is the default settings file from the tarball, and n denotes how many processes to spawn (by default it's just 1), i.e. how many threads to use for the computation.
Step 4
From here on, you can proceed from step 4 onwards of method 1 above.
Method 3: from git (medium/hard, many dependencies)
Step 1 - install dependencies
In addition to a C99-compatible compiler like GCC or Clang, the following programs and libraries are needed to build COFFE from git:
Programs
Libraries
- FFTW
- libconfig
- GSL; for Debian-like distributions, it's available under the package
libgsl-dev - CUBA (optional)
- CLASS (optional)
Step 2 - download
Clone the COFFE repository with git:
git clone -b master --single-branch https://github.com/JCGoran/coffeThen change into the COFFE directory:
cd coffeStep 3 - autoreconf
Run the following command:
autoreconf --installHopefully, the command will report that no dependencies are missing.
Step 4
You can now proceed from step 3 onwards of method 2 above.