api-docs/scattering-math: Doxygen docs for scattering, math, and geometry headers by CV-GPhL · Pull Request #421 · project-gemmi/gemmi

CV-GPhL · 2026-04-23T09:19:57Z

Summary

Adds Doxygen /// API documentation to 18 headers covering scattering physics, core mathematics, unit-cell reduction, sequence tools, twinning, and numerical methods:

Form factors and anomalous scattering:

fprime.hpp — Cromer-Liberman anomalous scattering (GEMMI_DLL entry point)
formfact.hpp — Gaussian form-factor approximations (ExpSum, GaussianCoef, fast float exp)
it92.hpp, c4322.hpp, neutron92.hpp — IT92, C4322, and neutron scattering tables

Core math:

bessel.hpp — modified Bessel function approximations (I₀, I₁, log I₀)
math.hpp — Vec3, Mat33, SMat33, Transform, Box, rotate_about_axis
cellred.hpp — Gruber and Selling vector unit-cell reduction algorithms

Sequence and structure tools:

seqtools.hpp, seqalign.hpp — sequence utilities and Needleman-Wunsch alignment (ksw2-based)
twin.hpp — twinning-law discovery (Le Page / Lebedev approach)
serialize.hpp — CIF-block serialization macros
interop.hpp, flat.hpp, smarts.hpp — MX/SX interop, flat atom arrays, SMARTS matching

Density analysis and numerical methods:

blob.hpp — electron density blob finding via flood fill
isosurface.hpp — marching cubes isosurface extraction
levmar.hpp — Levenberg-Marquardt non-linear least-squares
qcp.hpp — quaternion-based RMSD and optimal superposition (Theobald 2005)

docs/api.rst updated with three new sections.

Literature references added

@par References Doxygen blocks added to cite primary sources in the rendered API docs:

Symbol	Reference
`GruberVector` in `cellred.hpp`	Gruber (1973) Acta Cryst. A29, 433 (doi); Krivy & Gruber (1976) Acta Cryst. A32, 297 (doi); Grosse-Kunstleve et al. (2004) Acta Cryst. A60, 1 (doi)
`SellingVector` in `cellred.hpp`	Patterson & Love (1957) Acta Cryst. 10, 111 (doi); Andrews et al. (2019) Acta Cryst. A75, 115 (doi); ITA (2016) sec. 3.1.2.3 (doi)
`calculate_cos_obliquity()` in `twin.hpp`	Le Page (1982) J. Appl. Cryst. 15, 255 (doi)
`find_twin_laws()` in `twin.hpp`	Lebedev et al. (2006) Acta Cryst. D62, 83 (doi); Zwart et al. (2006) CCP4 Newsletter 42
`cromer_liberman_for_array()` in `fprime.hpp`	Cromer & Liberman (1994) Acta Cryst. A51, 416 (doi); Kissel & Pratt (1990) Acta Cryst. A46, 170 (doi); Brennan & Cowan (1992) Rev. Sci. Instrum. 63, 850 (doi)
`superpose_positions()` in `qcp.hpp`	Theobald (2005) Acta Cryst. A61, 478 (doi); Liu et al. (2010) J. Comput. Chem. 31, 1561 (doi)
`LevMar` struct in `levmar.hpp`	Levenberg (1944) Q. Appl. Math. 2, 164 (doi); Marquardt (1963) J. Soc. Ind. Appl. Math. 11, 431 (doi)
`align_sequences()` in `seqalign.hpp`	Needleman & Wunsch (1970) J. Mol. Biol. 48, 443 (doi)
`Neutron92` struct in `neutron92.hpp`	Sears (1992) Neutron News 3(3), 26 (doi)

Test plan

Doxygen build produces no warnings for documented entities
@param names verified against actual C++ signatures
No GEMMI_DLL macros removed
No functional code changes

🤖 Generated with Claude Code

Wires up Doxygen XML generation + Breathe Sphinx extension so that C++ API documentation from header comments renders in the existing Sphinx/readthedocs site at docs/api.rst. - docs/Doxyfile: Doxygen config (XML-only output, internal headers excluded) - docs/conf.py: runs Doxygen as subprocess, adds breathe extension - docs/api.rst: stub C++ API reference page (expanded by subsequent PRs) - docs/index.rst: replace external cxx-api link with internal api.rst - docs/requirements.txt: add breathe >= 4.35 - .readthedocs.yaml: add apt_packages: [doxygen] - .gitignore: exclude docs/_doxygen/ (generated) Builds on prior work in project-gemmi#402 (Paul Emsley / pemsley). Co-authored-by: C. Vonrhein / CV-GPhL

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: C. Vonrhein / CV-GPhL

Each @param must be on its own line for valid Doxygen output. Co-authored-by: C. Vonrhein / CV-GPhL

Distinguish value return (const) from reference return (non-const). Co-authored-by: C. Vonrhein / CV-GPhL

Co-authored-by: C. Vonrhein / CV-GPhL

'M' covers both matches and mismatches; note that push_cigar merges consecutive operations of the same type. Co-authored-by: C. Vonrhein / CV-GPhL

Co-authored-by: C. Vonrhein / CV-GPhL

Adds three sections: Scattering/Math/Geometry, Sequence Alignment and Twinning, and Density Analysis and Numerical Methods. Co-authored-by: C. Vonrhein / CV-GPhL

conf.py runs Doxygen when available (which it is on VS2022 workers) and conditionally loads breathe when the XML output dir exists. Without breathe installed, the Sphinx build fails with an ImportError. Co-authored-by: C. Vonrhein / CV-GPhL

cellred.hpp: Gruber/Krivy-Gruber/Grosse-Kunstleve for GruberVector; Patterson/Love, Andrews, ITA for SellingVector. twin.hpp: Le Page (1982) for obliquity; Lebedev/Zwart (2006) for twin laws. fprime.hpp: Cromer/Liberman, Kissel/Pratt, Brennan/Cowan for anomalous scattering. qcp.hpp: Theobald (2005) and Liu et al. (2010) for QCP superposition. levmar.hpp: Levenberg (1944) and Marquardt (1963) for LM algorithm. seqalign.hpp: Needleman/Wunsch (1970) for global sequence alignment. neutron92.hpp: Sears (1992) for neutron scattering lengths. Co-authored-by: C. Vonrhein / CV-GPhL

C. Vonrhein and others added 30 commits April 23, 2026 09:00

fix(conf.py): guard doxygen call — skip gracefully when not installed

2e118b8

ci: add docs-build job (Doxygen + Sphinx/Breathe HTML)

737d937

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs: add Doxygen API documentation to fprime.hpp

1f15652

Co-Authored-By: C. Vonrhein / CV-GPhL

docs: add Doxygen API documentation to formfact.hpp

e074cf3

Co-Authored-By: C. Vonrhein / CV-GPhL

docs: add Doxygen API documentation to it92.hpp

32b41fc

Co-Authored-By: C. Vonrhein / CV-GPhL

docs: add Doxygen API documentation to c4322.hpp

93ee9ad

Co-Authored-By: C. Vonrhein / CV-GPhL

docs: add Doxygen API documentation to neutron92.hpp

74799e6

Co-Authored-By: C. Vonrhein / CV-GPhL

docs: add Doxygen API documentation to bessel.hpp

0cc08d6

Co-Authored-By: C. Vonrhein / CV-GPhL

docs: add Doxygen API documentation to math.hpp

d23f4e4

Co-Authored-By: C. Vonrhein / CV-GPhL

docs: add Doxygen API documentation to cellred.hpp

cecc2c1

Co-Authored-By: C. Vonrhein / CV-GPhL

docs: fix Mat33 element constructor @param syntax in math.hpp

97f2072

Each @param must be on its own line for valid Doxygen output. Co-authored-by: C. Vonrhein / CV-GPhL

docs: clarify Vec3_ const at() return in math.hpp

cfed8b7

Distinguish value return (const) from reference return (non-const). Co-authored-by: C. Vonrhein / CV-GPhL

docs: add Doxygen API docs to twin.hpp

294d76b

docs: add Doxygen API docs to serialize.hpp

734456a

docs: add Doxygen API docs to seqtools.hpp

24ac594

docs: add Doxygen API docs to seqalign.hpp

0f71499

docs: add @brief to OpObliquity type alias in twin.hpp

3c79b33

Co-authored-by: C. Vonrhein / CV-GPhL

docs: fix CIGAR op description and push_cigar detail in seqalign.hpp

2a9b738

'M' covers both matches and mismatches; note that push_cigar merges consecutive operations of the same type. Co-authored-by: C. Vonrhein / CV-GPhL

docs: add Doxygen API docs to interop.hpp

4ca0bfc

docs: add Doxygen API docs to flat.hpp

3f7b996

docs: add Doxygen API docs to smarts.hpp

37d1b99

docs: add Doxygen API docs to blob.hpp

9b38560

docs: add Doxygen API docs to isosurface.hpp

cd69419

docs: add Doxygen API docs to levmar.hpp

66468ae

docs: add Doxygen API docs to qcp.hpp

73ff9cd

docs: add @brief tag to IsoSurface struct in isosurface.hpp

053388f

Co-authored-by: C. Vonrhein / CV-GPhL

docs: add api.rst entries for PR 9 (scattering-math)

40f85a7

Adds three sections: Scattering/Math/Geometry, Sequence Alignment and Twinning, and Density Analysis and Numerical Methods. Co-authored-by: C. Vonrhein / CV-GPhL

ci: add breathe to AppVeyor pip install

42e4171

conf.py runs Doxygen when available (which it is on VS2022 workers) and conditionally loads breathe when the XML output dir exists. Without breathe installed, the Sphinx build fails with an ImportError. Co-authored-by: C. Vonrhein / CV-GPhL

Merge branch 'master' into api-docs/scattering-math

c18417e

wojdyr merged commit a32a1f5 into project-gemmi:master Apr 23, 2026
8 of 10 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

api-docs/scattering-math: Doxygen docs for scattering, math, and geometry headers#421

api-docs/scattering-math: Doxygen docs for scattering, math, and geometry headers#421
wojdyr merged 31 commits into
project-gemmi:masterfrom
CV-GPhL:api-docs/scattering-math

CV-GPhL commented Apr 23, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

Conversation

CV-GPhL commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Literature references added

Test plan

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

CV-GPhL commented Apr 23, 2026 •

edited

Loading