Add algorithm-level citations for spherical geometry implementations - #1635
Open
hongyuchen1030 wants to merge 26 commits into
Open
Add algorithm-level citations for spherical geometry implementations#1635hongyuchen1030 wants to merge 26 commits into
hongyuchen1030 wants to merge 26 commits into
Conversation
This reverts commit 99573b8.
This reverts commit 1ba6880.
Adds a docs/references.bib with full BibTeX entries for the two Chen et al. UXarray papers plus the supporting numerical-methods references (Shewchuk, Knuth, Dekker, Higham, Jeannerod et al., Rump), extends citation.rst with an algorithm-to-publication mapping table alongside the existing Zenodo citation, and adds References sections to the docstrings of the specific APIs called out in the mapping: Grid.bounds and face_bounds_lon/lat, zonal_mean, the intersection APIs, the arcs predicates, and the compensated-arithmetic primitives in utils/computing.py. Resolves UXARRAY#1631 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- Demote "Algorithm-Level Citations" from a page-title-weight heading to
a proper second-level section, and wrap the call-to-action intro in a
note admonition instead of plain body text.
- Replace short in-text citations ("Chen et al. (2026), GMD") in the
mapping table with the full citation (title, journal, DOI) so readers
don't have to cross-reference elsewhere to know what they're citing.
- Drop the single hand-maintained docs/references.bib (and its now-dead
link to a file that doesn't exist on main yet) in favor of one small
.bib file per publication under docs/_static/citations/, downloadable
directly from next to each citation via Sphinx's :download: role.
- Fix "Documentation section" links: every row pointed at api.html#remapping
regardless of section; now each points at its real anchor (descriptors,
zonal-average, intersections, arcs, compensated-arithmetic), verified
against the built HTML.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Replace the generic "please also cite the corresponding publication(s)" note with more precise guidance on when citation is expected: results reported in an academic work that depend on one of these algorithms (e.g. computed face areas or regridding weights used as analysis input), as opposed to incidental use in tutorials/internal tools/other software that merely depends on UXarray. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Replace em dash punctuation with parentheses (no em dashes unless explicitly requested), swap the citation-trigger examples for concrete UXarray operations (latlon bounds, zonal-mean, conservative remapping, computed face area), and correct "intersection and remapping algorithms" to "intersection and geometry operators" in the SIAM paper's intro sentence.
Merge table rows that share the same documentation section and required citation (Descriptors bounds/face_bounds_lon/face_bounds_lat; Arcs orient3d_on_sphere/on_minor_arc; Arcs in_between/point_within_gca; Compensated Arithmetic accucross/accucross_pair) into single rows listing each API on its own line, instead of repeating the citation per row. Also reorder the Arcs rows to match the order APIs actually appear in api.rst (in_between, point_within_gca, extreme_gca_latitude, orient3d_on_sphere, on_minor_arc); the other sections already matched.
Independent citation audit against the DOI landing page found the published title uses the multiplication sign (2 × 2), not the letter x, in citation.rst, the jeannerod2013.bib entry, and the diff_of_products docstring. The .bib uses the LaTeX $\times$ form for portability across BibTeX toolchains; the RST/docstring prose uses the Unicode × character directly.
hongyuchen1030
marked this pull request as ready for review
August 2, 2026 19:40
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
1 participant
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.
Closes #1631
Overview
docs/references.bibwith full BibTeX entries for the two Chen et al. UXarray papers (GMD 2026, SIAM J. Sci. Comput. 2026) plus the supporting numerical-methods references (Shewchuk 1997, Knuth 1997, Dekker 1971, Higham 2002, Jeannerod et al. 2013, Rump 2023)docs/citation.rstwith an "Algorithm-Level Citations" section: the general node/edge/face statement, human-readable citations for both papers, and the full algorithm-to-publication mapping table from the issue, alongside the existing package-level Zenodo citationReferencessections to the docstrings of the specific APIs listed in the issue's mapping table:Grid.bounds,Grid.face_bounds_lon,Grid.face_bounds_latUxDataArray.zonal_mean(withzonal_average/zonal_anomalycross-referencing it)grid.intersections.gca_gca_intersection,gca_const_lat_intersection,get_number_of_intersectionsgrid.arcs.extreme_gca_latitude,orient3d_on_sphere,on_minor_arcutils.computing.two_sum,two_prod,diff_of_products,accucross,accucross_pair,acc_sqrt_regrid.arcs.in_betweenandpoint_within_gcaintentionally left uncited per the issue (pending removal in a future release)PR Checklist
General
Testing & Benchmarking
N/A — documentation/docstring-only change, no functional or performance impact. Full test suite (815 passed, 1 pre-existing skip) and pre-commit hooks pass locally.
Documentation
docs/api.rst(N/A — no new public API surface)_)Examples
N/A — no notebook examples affected.