precession is an Python module to study the dynamics of precessing black-hole binaries using multi-timescale methods. The code provides a comprehensive toolbox to (i) capture the black-hole dynamics on the spin-precession timescale in closed form, (ii) average generic quantities over a precession period, (iii) numerically integrate the binary inspiral using both orbit- and precession-averaged approximations, (v) evaluate spin-precession estimators to be used in gravitational-wave astronomy, and (vi) estimate the remnant properties. Key applications include propagating gravitational-wave posterior samples as well as population-synthesis predictions of astrophysical nature.

The current version (v2) of precession is described in

  • Efficient multi-timescale dynamics of precessing black-hole binaries.

D. Gerosa, G. Fumagalli, M. Mould, G. Cavallotto, D. Padilla Monroy, D. Gangardt, V. De Renzis. arXiv:2304.04801

The previous implementation (v1) is described in

  • PRECESSION: Dynamics of spinning black-hole binaries with python.

D. Gerosa, M. Kesden. PRD 93 (2016) 124066. arXiv:1605.01067

Note that v2 and v1 are not backward compatible; they are different codes. Unless you are maintaining a legacy pipeline, we highly reccommend using the new code. It is faster, more accurate, and provides more functionalities.

precession is released under the MIT licence. You may use precession as you like but should acknowledge our work. When using the code in any published work, please cite the papers above. The code has been used in a variety of studies in gravitational-wave and astronomy black-hole binary dynamics, follow the citations to those papers for more.

The code is distributed under git version control at

The documentation (v2) is available

The v1 documentation is archived at this link.

Installing the code is as easy as

pip install precession

A short tutorial is provided in the documentation together with a detailed list of all functions.

The code is developed and maintained by Davide Gerosa. Please report bugs and suggestions using github.

Change log

  • v2.0.0 New code, not backward compatible. See arXiv:2304.04801

  • v1.0.3 Python 3 support. Updated final-spin formula.

  • v1.0.2 Typos in final-mass formula.

  • v1.0.0 First public release. See arXiv:1605.01067.

(thrid-level versions not explicitly indicated refer to patches for minor typos/bug fixes)