Skip to content

docs: document parameters in conversion.py (closes #611)#1070

Open
christianescamilla15-cell wants to merge 2 commits intobilby-dev:mainfrom
christianescamilla15-cell:docs/conversion-parameters
Open

docs: document parameters in conversion.py (closes #611)#1070
christianescamilla15-cell wants to merge 2 commits intobilby-dev:mainfrom
christianescamilla15-cell:docs/conversion-parameters

Conversation

@christianescamilla15-cell
Copy link
Copy Markdown

Summary

Addresses #611 by adding parameter descriptions and math formulae to several functions in bilby/gw/conversion.py. Used Table E1 and Appendix E of Romero-Shaw et al. 2020 (arXiv:2006.00714) as the reference for spin parameter definitions, and Peters & Mathews 1963 for the chirp mass formula.

Functions updated

generate_component_spins

Full documentation of all 11 input spin parameters (`theta_jn`, `phi_jl`, `tilt_1/2`, `phi_12`, `a_1/2`, masses, `reference_frequency`, `phase`) with units, ranges, and physical meaning. Documents both the precessing conversion path and the aligned-spin fallback (`chi_1`, `chi_2`). Lists all 9 output keys with descriptions.

Mass conversion functions

  • `component_masses_to_chirp_mass`: Added the formula $\mathcal{M} = (m_1 m_2)^{3/5} / (m_1 + m_2)^{1/5}$ and reference to Peters & Mathews 1963.
  • `component_masses_to_symmetric_mass_ratio`: Added $\eta = m_1 m_2 / (m_1 + m_2)^2$ with the range $\eta \in (0, 1/4]$.
  • `component_masses_to_mass_ratio`: Fixed a copy-paste bug where the docstring incorrectly said "Convert the component masses of a binary to its chirp mass". Added $q = m_2/m_1$ and clarified bilby's $q \leq 1$ convention.
  • `symmetric_mass_ratio_to_mass_ratio`: Added the inversion formula and explained why the smaller root is chosen.
  • `chirp_mass_and_total_mass_to_symmetric_mass_ratio`: Added derivation from $\mathcal{M} = M \eta^{3/5}$.

Also switched to raw strings (`r"""`) so LaTeX in the docstrings renders correctly in the sphinx-generated docs.

Test plan

  • No code behavior changed — only docstrings
  • Verified `py_compile` passes
  • CHANGELOG updated under `[Unreleased]`
  • Parameter definitions checked against Table E1 of arXiv:2006.00714

References

  • Romero-Shaw, I. et al. "Bayesian inference for compact binary coalescences with bilby: Validation and application to the first LIGO-Virgo gravitational-wave transient catalogue", MNRAS 499, 3295 (2020). arXiv:2006.00714
  • Peters, P. C. and Mathews, J. "Gravitational Radiation from Point Masses in a Keplerian Orbit", Phys. Rev. 131, 435 (1963)

Improved docstrings for several mass and spin conversion functions in
bilby/gw/conversion.py to address the lack of parameter descriptions
noted in bilby-dev#611. Used Table E1 and Appendix E of arXiv:2006.00714
(Romero-Shaw et al. 2020) as the reference.

Functions updated:

- generate_component_spins: Full documentation of all 11 input spin
  parameters (theta_jn, phi_jl, tilt_1/2, phi_12, a_1/2, masses,
  reference_frequency, phase) with units, ranges, and physical
  meaning. Documents both the precessing path and the aligned-spin
  fallback (chi_1, chi_2). Lists all 9 output keys.

- component_masses_to_chirp_mass: Added math formula and reference
  to Peters & Mathews 1963. Clarified that chirp mass is the
  best-measured mass combination in inspiral GW observations.

- component_masses_to_symmetric_mass_ratio: Added formula and
  explained eta in (0, 1/4] with maximum at equal masses.

- component_masses_to_mass_ratio: FIXED a copy-paste bug where
  the docstring incorrectly said "Convert the component masses of
  a binary to its chirp mass" (should be "to its mass ratio").
  Added formula and clarified bilby's q <= 1 convention.

- symmetric_mass_ratio_to_mass_ratio: Added inversion formula and
  explained why the smaller root is chosen.

- chirp_mass_and_total_mass_to_symmetric_mass_ratio: Added derivation
  from M = M_total * eta^(3/5).

Also switched to raw strings (r""") to support LaTeX in the rendered
sphinx documentation.

References:
- Romero-Shaw et al. 2020, MNRAS 499, 3295 (arXiv:2006.00714)
- Peters and Mathews 1963, Phys. Rev. 131, 435
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant