Add algorithm-level citations for spherical geometry implementations

[hongyuchen1030]

Proposed new feature or change:

The current UXarray documentation provides a general Zenodo citation for UXarray as a software package. However, several spherical geometry and regridding algorithms implemented within UXarray are associated with peer-reviewed methodological publications and should therefore include algorithm-level citations.

The package-level Zenodo citation should remain. The publications below should be added alongside it as the scientific references for the corresponding algorithms.

Relevant publications

@Article{gmd-19-6545-2026,
AUTHOR = {Chen, H. and Ullrich, P. A. and Panetta, J. and Marsico, D. and Hanke, M. and Jain, R. and Zhang, C. and Jacob, R. L.},
TITLE = {Accurate and robust geometric algorithms for regridding on the sphere},
JOURNAL = {Geoscientific Model Development},
VOLUME = {19},
YEAR = {2026},
NUMBER = {14},
PAGES = {6545--6570},
URL = {https://gmd.copernicus.org/articles/19/6545/2026/},
DOI = {10.5194/gmd-19-6545-2026}
}

@article{doi:10.1137/25M1737614,
author = {Chen, Hongyu and Ullrich, Paul A. and Panetta, Julian},
title = {Fast and Accurate Intersections on a Sphere},
journal = {SIAM Journal on Scientific Computing},
volume = {48},
number = {2},
pages = {B208--B232},
year = {2026},
doi = {10.1137/25M1737614},
URL = {https://doi.org/10.1137/25M1737614},
eprint = {https://doi.org/10.1137/25M1737614}
}

The references are provided in BibTeX format because BibTeX preserves the complete bibliographic metadata, including the authors, title, journal, year, volume, issue, page range, DOI, and URL. This is not intended to imply that raw BibTeX must be displayed directly in every docstring or API page. I can also provide the corresponding human-readable citations:

Chen, H., Ullrich, P. A., Panetta, J., Marsico, D., Hanke, M., Jain, R., Zhang, C., and Jacob, R. L. (2026). Accurate and robust geometric algorithms for regridding on the sphere. Geoscientific Model Development, 19(14), 6545–6570. https://doi.org/10.5194/gmd-19-6545-2026

Chen, H., Ullrich, P. A., and Panetta, J. (2026). Fast and Accurate Intersections on a Sphere. SIAM Journal on Scientific Computing, 48(2), B208–B232. https://doi.org/10.1137/25M1737614

However, I do not recommend replacing the full citation information with only a URL. A URL alone does not preserve the complete bibliographic record and is less useful to researchers who need to import the reference into a citation manager or include it in a bibliography. A clean human-readable citation can be displayed in the documentation, while the complete BibTeX entry can be retained in a dedicated citation page or .bib file.

Precedent from other scientific software packages

CGAL provides a particularly relevant precedent:

https://doc.cgal.org/latest/Manual/how_to_cite_cgal.html

UXarray is in a similar situation. Although CGAL is distributed as a unified software library, many individual algorithms and components implemented within it correspond to separate published works. CGAL therefore provides both a general software citation and algorithm-specific references, including BibTeX entries, so that users can cite the actual methodological work associated with the functionality they use.

Other scientific software projects with relevant citation practices include:

• TempestExtremes: https://github.com/ClimateGlobalChange/tempestextremes
• TempestRemap: https://github.com/ClimateGlobalChange/tempestremap
• YAC: https://dkrz-sw.gitlab-pages.dkrz.de/yac/

Providing both human-readable references and complete BibTeX entries keeps the user-facing documentation readable while ensuring that no bibliographic information is omitted.

Proposed citation structure

I recommend adopting the following structure in UXarray:

1. Retain the existing Zenodo citation for UXarray as a whole.
2. Add a concise, human-readable publication citation and DOI to the relevant algorithm documentation.
3. Preserve the complete BibTeX entries in a dedicated citation page or .bib file.
4. Add the relevant publication reference to each algorithm’s docstring or API documentation.
5. Maintain an explicit mapping between implemented algorithms and their corresponding publications.
6. Ask users to cite both UXarray and the relevant methodological publication when using those algorithms in scientific work.

The purpose of providing the BibTeX entries is to ensure that the complete and authoritative citation information is available. It does not require placing the raw BibTeX directly into every user-facing docstring.

Algorithm-to-Publication Citation Mapping

Before the individual algorithm citations, please consider adding a general statement to either the main documentation or the API reference explaining that the definitions and geometric conventions for nodes, edges, and faces used throughout UXarray are based on the following publication:

Chen, H., Ullrich, P. A., Panetta, J., Marsico, D., Hanke, M., Jain, R., Zhang, C., and Jacob, R. L. (2026). “Accurate and Robust Geometric Algorithms for Regridding on the Sphere.” Geoscientific Model Development, 19(14), 6545–6570. https://doi.org/10.5194/gmd-19-6545-2026

Documentation section	API or implementation	Required citation(s)
Grid bounds	Grid.bounds	Chen, H., Ullrich, P. A., Panetta, J., Marsico, D., Hanke, M., Jain, R., Zhang, C., and Jacob, R. L. (2026). “Accurate and Robust Geometric Algorithms for Regridding on the Sphere.” Geoscientific Model Development, 19(14), 6545–6570. https://doi.org/10.5194/gmd-19-6545-2026
Grid bounds	Grid.face_bounds_lon	Chen, H., Ullrich, P. A., Panetta, J., Marsico, D., Hanke, M., Jain, R., Zhang, C., and Jacob, R. L. (2026). “Accurate and Robust Geometric Algorithms for Regridding on the Sphere.” Geoscientific Model Development, 19(14), 6545–6570. https://doi.org/10.5194/gmd-19-6545-2026
Grid bounds	Grid.face_bounds_lat	Chen, H., Ullrich, P. A., Panetta, J., Marsico, D., Hanke, M., Jain, R., Zhang, C., and Jacob, R. L. (2026). “Accurate and Robust Geometric Algorithms for Regridding on the Sphere.” Geoscientific Model Development, 19(14), 6545–6570. https://doi.org/10.5194/gmd-19-6545-2026
Zonal Average	All zonal-average remapping implementations	Chen, H., Ullrich, P. A., and Panetta, J. (2026). “Fast and Accurate Intersections on a Sphere.” SIAM Journal on Scientific Computing, 48(2), B208–B232. https://doi.org/10.1137/25M1737614
Spherical Geometry: Intersections	All spherical-intersection APIs in this section	Cite both: Chen, H., Ullrich, P. A., Panetta, J., Marsico, D., Hanke, M., Jain, R., Zhang, C., and Jacob, R. L. (2026). “Accurate and Robust Geometric Algorithms for Regridding on the Sphere.” Geoscientific Model Development, 19(14), 6545–6570. https://doi.org/10.5194/gmd-19-6545-2026; Chen, H., Ullrich, P. A., and Panetta, J. (2026). “Fast and Accurate Intersections on a Sphere.” SIAM Journal on Scientific Computing, 48(2), B208–B232. https://doi.org/10.1137/25M1737614
Spherical Geometry: Arcs	grid.arcs.extreme_gca_latitude(gca_cart, ...)	Chen, H., Ullrich, P. A., Panetta, J., Marsico, D., Hanke, M., Jain, R., Zhang, C., and Jacob, R. L. (2026). “Accurate and Robust Geometric Algorithms for Regridding on the Sphere.” Geoscientific Model Development, 19(14), 6545–6570. https://doi.org/10.5194/gmd-19-6545-2026
Spherical Geometry: Arcs	grid.arcs.orient3d_on_sphere(...)	Shewchuk, J. R. (1997). “Adaptive Precision Floating-Point Arithmetic and Fast Robust Geometric Predicates.” Discrete & Computational Geometry, 18, 305–363. https://doi.org/10.1007/PL00009321
Spherical Geometry: Arcs	grid.arcs.on_minor_arc(q, a, b[, tol])	Shewchuk, J. R. (1997). “Adaptive Precision Floating-Point Arithmetic and Fast Robust Geometric Predicates.” Discrete & Computational Geometry, 18, 305–363. https://doi.org/10.1007/PL00009321
Spherical Geometry: Arcs	grid.arcs.in_between(p, q, r)	No new citation required. This API is expected to be removed in a future release.
Spherical Geometry: Arcs	grid.arcs.point_within_gca(pt_xyz, ...)	No new citation required. This API is expected to be removed in a future release.
Compensated Arithmetic	utils.computing.two_sum	Knuth, D. E. (1997). The Art of Computer Programming, Volume 2: Seminumerical Algorithms. 3rd ed. Addison-Wesley, Section 4.2.2, Theorem B.
Compensated Arithmetic	utils.computing.two_prod	Dekker, T. J. (1971). “A Floating-Point Technique for Extending the Available Precision.” Numerische Mathematik, 18, 224–242. https://doi.org/10.1007/BF01397083
Compensated Arithmetic	utils.computing.diff_of_products	Cite both: Higham, N. J. (2002). Accuracy and Stability of Numerical Algorithms. 2nd ed. Society for Industrial and Applied Mathematics. https://doi.org/10.1137/1.9780898718027; Jeannerod, C.-P., Louvet, N., and Muller, J.-M. (2013). “Further Analysis of Kahan’s Algorithm for the Accurate Computation of 2 × 2 Determinants.” Mathematics of Computation, 82, 2245–2264. https://doi.org/10.1090/S0025-5718-2013-02679-8
Compensated Arithmetic	utils.computing.accucross(a0, a1, a2, b0, b1, b2)	Chen, H., Ullrich, P. A., Panetta, J., Marsico, D., Hanke, M., Jain, R., Zhang, C., and Jacob, R. L. (2026). “Accurate and Robust Geometric Algorithms for Regridding on the Sphere.” Geoscientific Model Development, 19(14), 6545–6570. https://doi.org/10.5194/gmd-19-6545-2026
Compensated Arithmetic	utils.computing.accucross_pair(ax_hi, ay_hi, ...)	Chen, H., Ullrich, P. A., Panetta, J., Marsico, D., Hanke, M., Jain, R., Zhang, C., and Jacob, R. L. (2026). “Accurate and Robust Geometric Algorithms for Regridding on the Sphere.” Geoscientific Model Development, 19(14), 6545–6570. https://doi.org/10.5194/gmd-19-6545-2026
Compensated Arithmetic	utils.computing.acc_sqrt_re	Rump, S. M. (2023). “Fast and Accurate Computation of the Euclidean Norm of a Vector.” Japan Journal of Industrial and Applied Mathematics, 40. https://doi.org/10.1007/s13160-023-00593-8

[erogluorhan]

Hi @hongyuchen1030

Please populate a .rst file under the /docs dir, say "citation-for-alogrithms.rst", and add the BibTex and table above in whatever format you'd like into it. You can then add a highlighted info message into our How to Cite UXarray page that would just link to that .rst file you'll create.

This way, whenever the users check our Citation page, they will see that highlighted message about citing algorithms for individual functions, and when clicked on that link, they will go to the page that shows everything in your preferred format. It is the cleanest but well-highlighted way of doing it at the same time I could think of.