iitm-convergence — boundary-conformal IITM

Reference implementation and full reproducibility chain for

Boundary-conformal integration for the invariant-imbedding T-matrix method: high-order convergence for faceted particles.

The boundary-conformal scheme attacks the quadrature error channel of the invariant-imbedding T-matrix method (IITM): closed-form azimuthal arcs, tangency-split zenithal panels, and a square-root radial substitution remove the IITM "staircasing" that otherwise limits accuracy on faceted particles. Every figure and every cited number in the paper regenerates from a script in this repository.

This is the conformal-v1.0 release: the manuscript's Data-availability section pins the computational environment (Project.toml / Manifest.toml, Julia 1.12) at this tag.

Layout

Path	Contents
src/	The ConformalIITM solver library — analytic-arc azimuthal kernels, the boundary-conformal clip, and the Möbius-radial IITM march (conformal_iitm.jl + conformal/{shapes,kernels,riccati,mobius}.jl, arc_fourier.jl), extending TransitionMatrices.jl.
conformal/manuscript/	main.tex + supplement.tex, the figure-data generators (figdata*.jl), gen_values.jl (numbers → values.tex), makefigs.jl (figures), and the committed figdata_*.json single source of truth.
conformal/validation/	Cross-checks (cylinder/prism aspect sweeps, large-kr order ladders, bullet geometry).
SSOT/	The shared data layer (bundled in-repo Julia package; see below).
tools/	figdata_diff.jl — the numeric regression differ used by the harness.

Reproducibility

Single source of truth + SSOT

Each generator writes its results as conformal/manuscript/figdata_*.json at full Float64 precision — the single source of truth. From that JSON, gen_values.jl produces values.tex (every number the manuscript prints) and makefigs.jl produces the figures; neither file is edited by hand.

SSOT/ provides the data layer used by every generator and reader:

• addblock! / writejson — build and serialize a named, typed Artifact; writejson refuses ragged or auto-named (colN) blocks (every column must be named).
• findrow / getcol / cell — pull numbers by key + column name, not by index.
• value! / constant! / emit — emit values.tex macros; constant! marks numbers that are proven/structural literals (not figdata-derived).
• cached(compute, path; params) — memoize an expensive compute to a committed conformal/_cache/NAME.json keyed by a params fingerprint (bump params.version or set SSOT_FORCE to recompute), so re-deriving figdata is cheap.
• diffjson — the rtol-1e-10 numeric differ behind tools/figdata_diff.jl.

Environment

One Project.toml / Manifest.toml at the repo root. TransitionMatrices resolves from the Julia General registry (pinned in the Manifest); SSOT is the bundled [sources] package. Instantiate from a fresh clone with:

julia --project=. -e 'using Pkg; Pkg.instantiate()'

Scripts run as julia -t 1 --startup-file=no --project=. <path/to/script.jl> and locate src/ via @__DIR__, so the working directory does not matter.

Harness (justfile)

Recipe	What it does
just values	Re-run gen_values.jl from committed figdata and assert byte-identical values.tex. The non-negotiable manuscript gate.
just diff	Compare working-tree figdata_*.json against git HEAD via SSOT.diffjson (rtol 1e-10; no re-run).
just gate	diff + values — the full no-rerun gate.
just regen	Re-run the figure-data generators (minutes).
just figs	Render the manuscript figures from committed figdata.
just check	regen then gate.

figdata_reuse.json and figdata_bullet_fit.json have no .jl generator (hand-curated / produced by a small Python script) and are not regenerated.

Requirements

• Julia 1.12 (Pkg.instantiate() pulls TransitionMatrices and the rest of the pinned environment from the registry).
• just for the harness recipes (optional).
• A LaTeX toolchain (e.g. latexmk or tectonic) to compile the manuscript.

License

MIT.