docs: document parameters in conversion.py (closes #611)#1070
Open
christianescamilla15-cell wants to merge 2 commits intobilby-dev:mainfrom
Open
docs: document parameters in conversion.py (closes #611)#1070christianescamilla15-cell wants to merge 2 commits intobilby-dev:mainfrom
christianescamilla15-cell wants to merge 2 commits intobilby-dev:mainfrom
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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_spinsFull 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
Also switched to raw strings (`r"""`) so LaTeX in the docstrings renders correctly in the sphinx-generated docs.
Test plan
References