cTreeBalls: Correlation functions computation with Tree/Balls methods

Author: Mario A. Rodriguez-Meza

Major contributors:

• Alejandro Aviles
• Eladio Moreno
• Gustavo Niz
• Axel Romero Tisnado

Table of Contents

• Introduction
• Compiling and getting started
• Configuration
• Parameters
• Python
• License
• Acknowledgements

Introduction

TreeBalls (short-name cBalls) is a C code for computing correlation functions using tree and balls methods. So far can compute 2-point correlation function (2pcf) and 3-point correlation function (3pcf) for counts and scalar fields like convergence, the relevant scalar field in weak lensing.

Complete documentation will be found here: documentation.

Install the Python interface

The PyPI distribution is named cTreeBalls; the Python extension is imported as cyballs. The installation compiles the native extension, including the bundled GSL and CFITSIO sources, and therefore requires a C compiler, make, ar, and Python development headers. On Debian or Ubuntu:

sudo apt-get update
sudo apt-get install build-essential python3-dev zlib1g-dev
python3 -m pip install cTreeBalls

Verify the installation with:

python3 -c "from cyballs import cballs; print(cballs)"

The pip package installs the cyballs extension. Clone the repository and use make all when you also need the cballs executable, static library, test catalogs, or development files.

Compiling and getting started

Download the code by cloning it from https://github.com/rodriguezmeza/cTreeBalls.

Dependencies: cBalls optionally needs gsl version 2.7.1 and cfitsio version 4.4.1 installed in your system. Sources are included. Therefore no need to make any changes. In case of problems go to web page https://www.gnu.org/software/gsl/ for details or ask to your system administrator. Make necessary changes in Makefile_machine file and look up for GSL. But in case you have problems installing GSL just set it off (switched off: USEGSL = 0) in Makefile_settings, the basic distribution will run okey. I/O cfitsio library is set it ON. Can be set it OFF in addons/Makefile_settings.

Go to the cTreeBalls directory (cd cTreeBalls/) and compile (make clean; make all). If compilation attempt fails, you may need to open the Makefile_machine file and adapt the name of the compiler (default: gcc), of the optimization flag (default: -O4 -ffast-math) and of the OpenMP flag (default: -fopenmp; this flag is facultative, you are free to compile without OpenMP if you don't want parallel execution; note that you need the version 4.2 or higher of gcc to be able to compile with -fopenmp). The code has been tested with gcc version 10 and 12 and would be working with version 11, and 13. (In particular, for compiling on Mac >= 10.9 despite of the clang incompatibility with OpenMP).

To check that the code runs, if you are in cTreeBalls directory, type:

$ make clean; make all
$ cd tests
$ ../cballs

It will run using all default values and a directory named Output will be created under tests. cBalls will save all histograms files and a log file in Output/tmp. A file with the parameter values use in the run named parameters_null-usedvalues will also be saved. You may use it as a template to create your own parameter files.

If you execute:

$ ../cballs options=post-processing posScript="python scripts/plot2pcf.py"

will do the same but now will plot the 2pcf and save it as a pdf file. Now, let us use a parameter file, execute:

$ ../cballs ./In/parameters_explained

Directory Output is already created then cBalls will overwritte all histograms files, parameter file as was run, and the log file. The parameters_explained file is a reference input file, containing (and explaining) the use of all possible input parameters. In this case as can be seen in parameters_explained file a catalog of points is read from the file kappa_nres12_zs9NS256r000.bin.

To see a plot of the 2pcf, edit parameters_explained and set option to "post-processing" and execute again:

$ ../cballs parameters_explained

At the end of the run you will, as before, have a pdf file of the plot.

By default cBalls reads/writes catalog of points to analyzed files in 4-column format with x, y, z columns first and then value of the convergence field. It has a two line header:

# nbody NDIM Lx Ly Lz
# nbody-value NDIM-value Lx Ly Lz - values

Try running:

$ ../cballs nbody=6480 o=points_on_sphere testmodel=unit-sphere-random options=stop

In the Output directory you will have a file: points_on_sphere.txt. View its contents to see the two lines header and the 4 columns structure of data. You can plot this file:

$ python scripts/plot3D_points-on-sphere.py

Note: in the above example points_on_sphere was not given an extension. By default cBalls gives to the output files the extension .txt.

You may also consult the code´s man page for more detailed information on how to run cBalls:

$ man ../docs/man/cballs.m

There is a html version of this manual version. Look for it (docs/man/cballs.html) an open it with a web explorer.

Configuration

cBalls can be configured by switching on/off several options. Configuration file is Makefile_setting.

Note: After changing Makefile_settings in order to have the new settings active in cBalls you have to re-compile the code: make clean; make all.

Parameters

The list of available command line parameters can be consulted using the -h or --help flags:

$ ../cballs --help

See also the man page as explained above. If you execute:

$ ../cballs --clue

you will receive in response how cBalls should be executed using command line parameters. Just pick up the parameteres you need and, if necessary, modify their values according to your needs.

Python

To install cBalls python module (cyballs) just execute (you already do it...):

$ make clean; make all

To test it go to directory tests and run:

$ python ./In/test_cython_octree-ggg-omp.py

Note: this interface in Cython was tested in a python environment with python3.12.

Plotting utilities

Several Jupyter notebooks, written by Abraham Arvizu and Eladio Moreno, are available to process cBalls results. They are in the github repository:

https://github.com/joar-cafe/CBalls_plots/tree/main/benchmarks

Other python scripts are in directory tests/python. Look for Readme files in tests and in tests/python.

License

cBalls is written by Mario A. Rodriguez-Meza, is open source and distributed under the MIT license. If you use this program in research work that results in publications, please cite the following paper:

Abraham Arvizu et al., arXiv:2048.16847

Acknowledgements

cBalls use/is based on the following codes or projects:

• Zeno
• Gadget-2
• CUTE
• Numerical recipies
• GSL
• CLASS
• CFITSIO
• HEALPix

Also author acknowledges for helpful discussion and testing to the following people:

• Abraham Arvizu
• Alejandro Aviles
• Juan Carlos Hidalgo
• Eladio Moreno
• Gustavo Niz
• Axel Romero Tisnado
• Sofia Samario