https://github.com/mikeswang/triumvirate
A Python/C++ package for three-point clustering measurements in LSS analyses
https://github.com/mikeswang/triumvirate
clustering-statistics cpp cuda cython hip large-scale-structure-cosmology python
Last synced: 17 days ago
JSON representation
A Python/C++ package for three-point clustering measurements in LSS analyses
- Host: GitHub
- URL: https://github.com/mikeswang/triumvirate
- Owner: MikeSWang
- License: gpl-3.0
- Created: 2021-04-08T01:01:18.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2025-10-14T19:23:13.000Z (6 months ago)
- Last Synced: 2025-10-16T17:36:08.984Z (5 months ago)
- Topics: clustering-statistics, cpp, cuda, cython, hip, large-scale-structure-cosmology, python
- Language: C++
- Homepage: https://mikeswang.github.io/Triumvirate/
- Size: 14.9 MB
- Stars: 21
- Watchers: 2
- Forks: 4
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Citation: CITATION.cff
- Security: .github/SECURITY.md
- Support: .github/SUPPORT.md
Awesome Lists containing this project
README
# Three-Point Clustering Statistics in LSS
[](https://github.com/MikeSWang/Triumvirate/releases/latest)
[](https://github.com/MikeSWang/Triumvirate/actions/workflows/ci.yml)
[](https://readthedocs.org/projects/triumvirate/builds/)
[](https://results.pre-commit.ci/latest/github/MikeSWang/Triumvirate/main)
[](https://app.codacy.com/gh/MikeSWang/Triumvirate/dashboard?utm_campaign=Badge_grade)
``Triumvirate`` is a Python/C++ software package for measuring three-point (and
two-point) clustering statistics and performing survey window convolution in
large-scale structure (LSS) cosmological analyses.
## Documentation
[](https://triumvirate.readthedocs.io/en/latest/)
Comprehensive documentation including the [scientific background](
https://triumvirate.readthedocs.io/en/latest/background.html),
[installation instructions](
https://triumvirate.readthedocs.io/en/latest/installation.html),
[tutorials](https://triumvirate.readthedocs.io/en/latest/tutorials.html) and
[API reference](https://triumvirate.readthedocs.io/en/latest/apiref.html)
can be found at [triumvirate.readthedocs.io](
https://triumvirate.readthedocs.io/en/latest/).
## Installation
### Python package
[](https://pypi.org/project/Triumvirate)
[](https://anaconda.org/msw/triumvirate)
``Triumvirate`` as a Python package is distributed through [PyPI](
https://pypi.org/project/Triumvirate) and [Conda](
https://anaconda.org/msw/triumvirate). Instructions for installation
can be found on the [Installation](
https://triumvirate.readthedocs.io/en/latest/installation.html#python-package)
page in the documentation.
### GPU variants
[](https://pypi.org/project/Triumvirate-CUDA)
[](https://anaconda.org/msw/triumvirate-cuda)
CUDA variants of the Python package are/will be made available as
``Triumvirate-CUDA`` on [PyPI](https://pypi.org/project/Triumvirate-CUDA)
and ``triumvirate-cuda`` through [Conda](
https://anaconda.org/msw/triumvirate-cuda).
### 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](
https://triumvirate.readthedocs.io/en/latest/installation.html#c-library-program)
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:
```sh
git clone git@github.com:MikeSWang/Triumvirate.git --branch
cd Triumvirate
```
Then, execute in shell:
```sh
make clean
make ([py|cpp]install)|(cpp[libinstall|appbuild]) [useomp=(true|1)] [usecuda=(true|1)] [usehdf5=(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. To enable HDF5 file format support, append
``usehdf5=true`` or ``usehdf5=1`` to the end of the second line as shown above.
> [!NOTE]
> The latest release is on the [``main``](
> https://github.com/MikeSWang/Triumvirate/tree/main) branch. The default
> [``Makefile``](./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](
> https://triumvirate.readthedocs.io/en/latest/installation.html#dependencies)
> 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``](./Makefile) (located at
> the repository directory root) assumes the GCC compiler and OpenMP library.
> See the [Installation](
> https://triumvirate.readthedocs.io/en/latest/installation.html#openmp-support)
> 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``](./Makefile) (located at the
> repository directory root). See the [Installation](
> https://triumvirate.readthedocs.io/en/latest/installation.html#cuda-support)
> page in the documentation for more details.
> [!IMPORTANT]
> If enabling HDF5 format support, ensure the HDF5 library is available for
> linking. If your HDF5 library is MPI-enabled, ensure your compiler is
> compatible, or switch to a non-parallel HDF5 library.
> [!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](
> https://www.gnu.org/software/make/manual/html_node/Options-Summary.html)).
## Attribution
[](https://doi.org/10.21105/joss.05571)
[](https://doi.org/10.1088/1475-7516/2025/06/031)
[](https://doi.org/10.1093/mnras/sty3249)
[](https://doi.org/10.1093/mnras/stx2333)
[](https://arxiv.org/abs/2304.03643)
[](https://arxiv.org/abs/2411.14947)
[](https://doi.org/10.5281/zenodo.10072128)
To acknowledge the use of ``Triumvirate`` in your published research, please
cite the relevant publications linked above; for convenience, you can refer to
the files [``CITATION.cff``](./CITATION.cff) and [``CITATION.md``](
./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](https://doi.org/10.3030/853291)).
Key underlying numerical algorithms were originally developed by
Naonori S Sugiyama, and are available in the GitHub repository [``hitomi``](
https://github.com/naonori/hitomi).
We thank the JOSS reviewers, William Coulton
([@wcoulton](https://github.com/wcoulton)) and Alfonso Veropalumbo
([@alfonso-veropalumbo](https://github.com/alfonso-veropalumbo)), for
their valuable feedback and suggestions (openjournals/joss-reviews#5571),
which have improved the functionality and documentation of the code.
## Contributing/Development
[](https://github.com/MikeSWang/Triumvirate/releases/latest)
[](https://github.com/MikeSWang/Triumvirate/issues?q=is%3Aopen+is%3Aissue+label%3Abuild)
[](https://github.com/MikeSWang/Triumvirate/issues?q=is%3Aopen+is%3Aissue+label%3Abug)
[](https://github.com/MikeSWang/Triumvirate/issues?q=is%3Aopen+is%3Aissue+label%3Afeature)
[](https://github.com/MikeSWang/Triumvirate/pulls)
[](https://github.com/pre-commit/pre-commit)
[](https://codespaces.new/MikeSWang/Triumvirate?hide_repo_select=true&ref=main)
User feedback and contributions are very welcome. Please refer to the
[contribution guidelines](./.github/CONTRIBUTING.md).
## Discussions & Wiki
[](https://github.com/MikeSWang/Triumvirate/discussions)
A [community forum](https://github.com/MikeSWang/Triumvirate/discussions)
for users and developers exists, where you can receive
announcements, post questions, share ideas and get updates.
A [wiki site](https://github.com/MikeSWang/Triumvirate/wiki) collects wisdoms
for specific use cases and user environments.
## Releases
Release notes are included in the [change log](./CHANGELOG.md).
## Licence
[](https://github.com/MikeSWang/Triumvirate/blob/main/LICENCE)
``Triumvirate`` is made freely available under the [GPLv3+ licence](
https://www.gnu.org/licenses/gpl-3.0.en.html).
Please see [``LICENCE``](./LICENCE) (located at the repository directory root)
for full terms and conditions.
© 2023 Mike S Wang & Naonori S Sugiyama