Add algorithm-level citations for spherical geometry implementations by hongyuchen1030 · Pull Request #1635 · UXARRAY/uxarray

hongyuchen1030 · 2026-07-31T20:41:02Z

Overview

Add docs/references.bib with 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)
Extend docs/citation.rst with 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 citation
Add References sections to the docstrings of the specific APIs listed in the issue's mapping table:
- Grid.bounds, Grid.face_bounds_lon, Grid.face_bounds_lat
- UxDataArray.zonal_mean (with zonal_average/zonal_anomaly cross-referencing it)
- grid.intersections.gca_gca_intersection, gca_const_lat_intersection, get_number_of_intersections
- grid.arcs.extreme_gca_latitude, orient3d_on_sphere, on_minor_arc
- utils.computing.two_sum, two_prod, diff_of_products, accucross, accucross_pair, acc_sqrt_re
grid.arcs.in_between and point_within_gca intentionally left uncited per the issue (pending removal in a future release)

PR Checklist

General

An issue is created and linked
Added appropriate labels (if your uxarray repo permissions allow it)
Filled out Overview and Expected Usage (if applicable) sections

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

Docstrings have been added to all new functions (N/A — no new functions; existing docstrings extended)
Docstrings have been updated with any function changes
User (public) functions have been added to docs/api.rst (N/A — no new public API surface)
Internal (private) function names start with an underscore (_)

Examples
N/A — no notebook examples affected.

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.

erogluorhan

Overall this looks great; please address only one comment below:

Per review feedback, move everything from the Algorithm-Level Citations heading onward out of citation.rst into a new docs/citations-for-algorithms.rst page, added to the "For users" toctree in index.rst. citation.rst now ends with a brief note pointing readers to the new page, keeping the main "How to Cite UXarray" page focused on the Zenodo software citation.

erogluorhan

Almost there, the newer links, pages, display clean! Just a final iteration hopefully. See comments below

- Remove the toctree entry for citations-for-algorithms from index.rst; a hidden toctree in citation.rst still surfaced it as a nested sidebar item under "Cite UXarray" (sphinx_book_theme includes hidden toctrees in the nav structure, it only suppresses the inline body listing). Mark citations-for-algorithms.rst :orphan: instead so it's reachable only via the :doc: link, with no separate nav entry at all. - Switch the pointer in citation.rst from a plain .. note:: to .. admonition:: Algorithm-Level Citations so the block shows that title instead of the generic "Note".

…g it Per team discussion on the PR, settle on: - Cite UXarray - Algorithm-Level Citations Remove :orphan: from citations-for-algorithms.rst and add it to a hidden toctree inside citation.rst instead. This makes it a real part of the doc tree (proper Previous/Next navigation, no orphan-suppression needed, participates in the sitemap like any other page) while keeping exactly one top-level "Cite..." entry in the sidebar, sphinx_book_theme renders the hidden child toctree as a collapsed sub-item under "Cite UXarray" rather than a second sibling entry.

Sevans711 · 2026-08-10T18:49:02Z

Flagging to consider #1631 (comment) before this merges, even if the decision ends up being to look into it later / with a different issue or PR.

hongyuchen1030 · 2026-08-10T21:12:25Z

Flagging to consider #1631 (comment) before this merges, even if the decision ends up being to look into it later / with a different issue or PR.

Thanks for the info, please see my reply in #1631, and the summary is the discussion should be put int a future PR and the current form in this PR is what we intend to do at current point.

Sevans711

Thank you for working to add these citations into UXarray and make it easier to give proper credit to the corresponding papers! I took a close look at this PR, I think it is almost ready to merge to main. I left a few inline comments with suggested changes. The biggest one is just some minor phrasing changes to better reflect when it is required to use these citations, as per the discussion in #1631.

I checked to confirm the following logistical details all look correct:

All links on the new Algorithm-Level Citations work properly. I clicked them all, and double-checked that the pages they opened seemed correct.
All new .bib files are actually used (nothing extra was added by accident).
Citations which were added to docstrings in the code all correspond to the correct citation(s), i.e. the same one(s) as in the table.

…cope - Zonal Average row now links to zonal_mean instead of zonal_average, since the latter is just a thin alias ("prefer zonal_mean for primary API"). - Remove the .. note:: wrapper around the intro paragraph; it's the first thing on the page already, so the box added nothing. - Reword the scope of when citation is expected. Per discussion in the original issue thread, this isn't "if your work uses one of these algorithms" (any output like a computed face area counts as "using" it) but specifically "if your work depends on the algorithm's details" (describing it, comparing it to alternatives, etc.). Drop the old API-usage examples (latlon bounds, zonal-mean, ...) since they no longer fit the corrected framing.

hongyuchen1030 · 2026-08-10T23:46:38Z

Thank you for working to add these citations into UXarray and make it easier to give proper credit to the corresponding papers! I took a close look at this PR, I think it is almost ready to merge to main. I left a few inline comments with suggested changes. The biggest one is just some minor phrasing changes to better reflect when it is required to use these citations, as per the discussion in #1631.

I checked to confirm the following logistical details all look correct:

All links on the new Algorithm-Level Citations work properly. I clicked them all, and double-checked that the pages they opened seemed correct.

All new .bib files are actually used (nothing extra was added by accident).

Citations which were added to docstrings in the code all correspond to the correct citation(s), i.e. the same one(s) as in the table.

@Sevans711

Thanks for your information and I have addressed your comments in the latest commits.

Sevans711

Thank you @hongyuchen1030 for those changes, it all looks good to me now and I think it is ready to merge to main!

hongyuchen1030 · 2026-08-10T23:57:15Z

@erogluorhan Can you please give this PR a review when you're available so we can merge it this week? Thanks

erogluorhan

Looks great; thanks for all the iterations!

hongyuchen1030 and others added 26 commits October 25, 2023 16:32

Initial Draft Algorithm

99573b8

Revert "Initial Draft Algorithm"

2bb2b93

This reverts commit 99573b8.

Merge branch 'UXARRAY:main' into main

37a6ad7

Merge branch 'UXARRAY:main' into main

33f4c5c

Merge branch 'UXARRAY:main' into main

dbaa775

Merge branch 'UXARRAY:main' into main

3d3865e

Merge branch 'UXARRAY:main' into main

6164c5b

Merge branch 'UXARRAY:main' into main

67a63d7

Merge branch 'UXARRAY:main' into main

5a633ae

Merge branch 'UXARRAY:main' into main

7738774

Merge branch 'UXARRAY:main' into main

e5aab20

Merge branch 'main' of https://github.com/UXARRAY/uxarray

38982af

Merge remote-tracking branch 'origin/main'

b8b8e17

Initial commit

1ba6880

Revert "Initial commit"

dfdb43b

This reverts commit 1ba6880.

Merge branch 'UXARRAY:main' into main

d0684c9

Merge branch 'UXARRAY:main' into main

5f854dd

Merge branch 'UXARRAY:main' into main

2a5cd55

Merge branch 'UXARRAY:main' into main

bf0afcf

Merge branch 'UXARRAY:main' into main

2cdfe1c

hongyuchen1030 marked this pull request as ready for review August 2, 2026 19:40

hongyuchen1030 requested review from cmdupuis3, erogluorhan and rajeeja August 2, 2026 19:41

hongyuchen1030 requested a review from Sevans711 August 2, 2026 19:41

erogluorhan reviewed Aug 3, 2026

View reviewed changes

Comment thread docs/citation.rst Outdated

hongyuchen1030 added 2 commits August 3, 2026 14:24

Merge branch 'main' into issue-1631-algorithm-citations

0e88738

hongyuchen1030 requested a review from erogluorhan August 3, 2026 21:31

erogluorhan reviewed Aug 3, 2026

View reviewed changes

Comment thread docs/index.rst Outdated

Comment thread docs/citation.rst Outdated

hongyuchen1030 and others added 5 commits August 3, 2026 15:15

Merge remote-tracking branch 'origin/issue-1631-algorithm-citations'

ddf5744

Merge branch 'main' into issue-1631-algorithm-citations

156ab4f

Merge branch 'main' into issue-1631-algorithm-citations

062704d

hongyuchen1030 requested review from dylannelson and erogluorhan August 7, 2026 20:46

Merge branch 'main' into issue-1631-algorithm-citations

6714475

Sevans711 requested changes Aug 10, 2026

View reviewed changes

Comment thread docs/citations-for-algorithms.rst Outdated

Comment thread docs/citations-for-algorithms.rst Outdated

Comment thread docs/citations-for-algorithms.rst Outdated

hongyuchen1030 added 2 commits August 10, 2026 16:36

Merge branch 'main' into issue-1631-algorithm-citations

25f69fb

Sevans711 approved these changes Aug 10, 2026

View reviewed changes

Sevans711 added documentation Improvements or additions to documentation new feature New feature or request labels Aug 11, 2026

Merge branch 'main' into issue-1631-algorithm-citations

4dc3211

erogluorhan approved these changes Aug 12, 2026

View reviewed changes

erogluorhan merged commit e252dd2 into UXARRAY:main Aug 12, 2026
22 of 23 checks passed

This was referenced Aug 14, 2026

Add run-link-check label & CI to run link-check in PRs #1676

Open

Nightly CI builds failing - Link Changes #1675

Merged

Navigation Menu

Uh oh!

Add algorithm-level citations for spherical geometry implementations - #1635

Add algorithm-level citations for spherical geometry implementations#1635
erogluorhan merged 37 commits into
UXARRAY:mainfrom
hongyuchen1030:issue-1631-algorithm-citations

hongyuchen1030 commented Jul 31, 2026 •

edited

Loading

Uh oh!

erogluorhan left a comment

Uh oh!

Uh oh!

erogluorhan left a comment

Uh oh!

Uh oh!

Uh oh!

Sevans711 commented Aug 10, 2026

Uh oh!

hongyuchen1030 commented Aug 10, 2026

Uh oh!

Sevans711 left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hongyuchen1030 commented Aug 10, 2026

Uh oh!

Sevans711 left a comment

Uh oh!

hongyuchen1030 commented Aug 10, 2026

Uh oh!

erogluorhan left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

hongyuchen1030 commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

PR Checklist

Uh oh!

erogluorhan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

erogluorhan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Sevans711 commented Aug 10, 2026

Uh oh!

hongyuchen1030 commented Aug 10, 2026

Uh oh!

Sevans711 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hongyuchen1030 commented Aug 10, 2026

Uh oh!

Sevans711 left a comment

Choose a reason for hiding this comment

Uh oh!

hongyuchen1030 commented Aug 10, 2026

Uh oh!

erogluorhan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hongyuchen1030 commented Jul 31, 2026 •

edited

Loading