Metadata-Version: 2.4
Name: cTreeBalls
Version: 1.0.1
Summary: Tree/balls methods for two- and three-point correlation functions
Home-page: https://github.com/rodriguezmeza/cTreeBalls
Author: Mario A. Rodriguez-Meza and cTreeBalls contributors
License: MIT
Project-URL: Documentation, https://ctreeballs.readthedocs.io/en/latest/
Project-URL: Source, https://github.com/rodriguezmeza/cTreeBalls
Project-URL: Issues, https://github.com/rodriguezmeza/cTreeBalls/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2,>=1.22
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<p align="left">
    <img src="https://github.com/rodriguezmeza/cTreeBalls/blob/main/addons/cBalls_04.png" width="300" height="300">
</p>

# cTreeBalls: Correlation functions computation with Tree/Balls methods

Author: Mario A. Rodriguez-Meza

Major contributors:

- [Alejandro Aviles](https://github.com/alejandroaviles)
- [Eladio Moreno](https://github.com/Eladio-Moreno)
- [Gustavo Niz](https://github.com/gnizq64)
- Axel Romero Tisnado


## Table of Contents

-   [Introduction](#introduction)
-   [Compiling and getting started](#compiling-and-getting-started)
-   [Configuration](#configuration)
-   [Parameters](#parameters)
-   [Python](#python)
-   [License](#license)
-   [Acknowledgements](#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](https://ctreeballs.readthedocs.io/en/latest/).

## 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:

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

Verify the installation with:

```bash
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`.

| Option         | Description                                                                                                                                                   |
|:--------------:|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `DEFDIMENSION`       | `= 3` select dimension of the run: 2 or 3                                                                                                                     |
| `USEGSL`       | `= 1` switch on/off computation using GSL routines. Optional.                                                                                                                      |
| `GSLINTERNAL`     | `= 1` for enabling GSL internal sources<br />(if `= 0`, specify the corresponding compiler flags in `Makefile_machine` file)                                                             |
| `OPENMPMACHINE`     | `= 1` for enabling OpenMP parallelism<br />(Specify the corresponding compiler flag in `Makefile_machine` file)                                                             |
| `SINGLEPON`    | `= 0` for disabling single precision                                                                                                                             |
| `LONGINTON`    | `= 1` for enabling long integers                                                                                                                             |
| `ADDONSON`  | `= 1` for adding more funcionality to the code, like other searching methods, other catalog formats                                                                                                |

**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](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](https://arxiv.org/abs/2408.16847)

## Acknowledgements

cBalls use/is based on the following codes or projects:
-   [Zeno](https://home.ifa.hawaii.edu/users/barnes/zeno/index.html)
-   [Gadget-2](https://wwwmpa.mpa-garching.mpg.de/gadget/)
-   [CUTE](https://github.com/damonge/CUTE)
-   [Numerical recipies](https://numerical.recipes/)
-   [GSL](https://www.gnu.org/software/gsl/)
-   [CLASS](https://github.com/lesgourg/class_public)
-   [CFITSIO](https://heasarc.gsfc.nasa.gov/fitsio/fitsio.html)
-   [HEALPix](https://healpix.sourceforge.io/)

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
