Triumvirate-Logo

Three-Point Clustering Measurements in LSS

Triumvirate is a Python/C++ software package for measuring three-point (and two-point) clustering statistics in large-scale structure (LSS) cosmological analyses.

Documentation

Comprehensive documentation including the scientific background, installation instructions, tutorials and API reference can be found at triumvirate.readthedocs.io.

Installation

Python package

Triumvirate as a Python package is distributed through PyPI and Conda. Instructions for installation can be found on the Installation page in the documentation.

[!TIP] CUDA variants of the Python package are/will be made available as Triumvirate-CUDA on PyPI and triumvirate-cuda through Conda.

C++ library & program

Triumvirate as either a static library or a binary executable can be built using make. Instructions for compilation can be found on the Installation page in the documentation.

Development mode

Both the Python package and the C++ library/program can be set up in development mode with make, provided that dependency requirements are satisfied (GSL and FFTW3 libraries are mandatory while an OpenMP library is optional).

First git clone the desired branch/release from the GitHub repository and change into the repository directory path:

git clone git@github.com:MikeSWang/Triumvirate.git --branch <branch-or-release>
cd Triumvirate

Then, execute in shell:

make clean
make ([py|cpp]install)|(cpp[libinstall|appbuild]) [useomp=(true|1)] [usecuda=(true|1)]

where cpplibinstall or cppappbuild respectively builds the C++ static library or binary executable only, cppinstall builds both, pyinstall builds the Python package only, and install builds all of the above. To enable OpenMP parallelisation, append useomp=true or useomp=1 to the end of the second line as shown above. To enable CUDA support, append usecuda=true or usecuda=1 to the end of the second line as shown above.

[!NOTE] The latest release is on the main branch. The default Makefile (located at the repository directory root) should work in most build environments, but may need to be modified as appropriate.

[!NOTE] See the Installation page in the documentation for more details about dependency requirements.

[!IMPORTANT] If enabling OpenMP, ensure the C++ compiler used supports it and is configured accordingly. The default Makefile (located at the repository directory root) assumes the GCC compiler and OpenMP library. See the Installation page in the documentation for more details.

[!IMPORTANT] If enabling CUDA capability, ensure there is a CUDA-capable GPU with the appropriate driver installed. For atypical CUDA Toolkit paths, you may need to append the header and library paths to DEP_INCLUDES and DEP_LDFLAGS in the default Makefile (located at the repository directory root). See the Installation page in the documentation for more details.

[!TIP] Pass option -j[N] -O to make to run multiple concurrent jobs for parallel building (optional parameter N is the number of parallel jobs; see GNU Make Manual).

Attribution

To acknowledge the use of Triumvirate in your published research, please cite the publications linked above; for convenience, you can refer to the files CITATION.cff and CITATION.md for the relevant information in different formats.

Acknowledgement

This project has received funding from the European Research Council (ERC) under the European Union's Horizon 2020 research and innovation programme (Grant agreement ID: 853291).

Key underlying numerical algorithms were originally developed by Naonori S Sugiyama, and are available in the GitHub repository hitomi.

We thank the JOSS reviewers, William Coulton (@wcoulton) and Alfonso Veropalumbo (@alfonso-veropalumbo), for their valuable feedback and suggestions (openjournals/joss-reviews#5571), which have improved the functionality and documentation of the code.

Contributing/Development

Platforms

Commits-Since

User feedback and contributions are very welcome. Please refer to the contribution guidelines.

Discussions & Wiki

A community forum for users and developers exists, where you can receive announcements, post questions, share ideas and get updates.

A wiki site collects wisdoms for specific use cases and user environments.

Releases

Release notes are included in the change log.

Licence

Triumvirate is made freely available under the GPLv3+ licence. Please see LICENCE (located at the repository directory root) for full terms and conditions.

MikeSWang / Triumvirate

readme