Docs

CITATION.bib

@@ -2,7 +2,7 @@ @misc{TransitionMatrices.jl
 	author  = {Gabriel Wu <wuzihua@pku.edu.cn> and contributors},
 	title   = {TransitionMatrices.jl},
 	url     = {https://github.com/JuliaRemoteSensing/TransitionMatrices.jl},
-	version = {v0.1.0},
-	year    = {2023},
-	month   = {2}
+	version = {v0.5.0},
+	year    = {2026},
+	month   = {6}
 }

README.md

@@ -4,7 +4,43 @@
 [![Build Status](https://github.com/JuliaRemoteSensing/TransitionMatrices.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/JuliaRemoteSensing/TransitionMatrices.jl/actions/workflows/CI.yml?query=branch%3Amain)
 [![Coverage](https://codecov.io/gh/JuliaRemoteSensing/TransitionMatrices.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/JuliaRemoteSensing/TransitionMatrices.jl)
 
-The transition matrix method, or T-Matrix method, is one of the most powerful and widely used tools for rigorously computing electromagnetic scattering by single and compounded particles. As a package focusing on this method, `TransitionMatrices.jl` provides the following features:
+The transition matrix method, or **T-Matrix method**, is one of the most powerful and widely used tools for rigorously computing electromagnetic scattering by single and compounded particles. `TransitionMatrices.jl` is a generic, arbitrary-precision Julia implementation focused on this method.
+
+📖 **[Documentation](https://JuliaRemoteSensing.github.io/TransitionMatrices.jl/dev/)**
+
+## Installation
+
+`TransitionMatrices.jl` requires Julia ≥ 1.10. In the Julia REPL's package mode (press `]`):
+
+```julia-repl
+pkg> add TransitionMatrices
+```
+
+To track the development version, or if the package is not yet in your registry, add it by URL:
+
+```julia-repl
+pkg> add https://github.com/JuliaRemoteSensing/TransitionMatrices.jl
+```
+
+## Quick start
+
+```julia
+using TransitionMatrices
+
+# A prolate spheroid: semi-axes a = 1, c = 2, relative refractive index m = 1.5 + 0.01im
+s = Spheroid(1.0, 2.0, 1.5 + 0.01im)
+
+# Auto-converged (classic EBCM) T-matrix at wavelength λ = 2π
+𝐓 = transition_matrix(s, 2π)
+
+# Orientation-averaged far-field observables
+Qsca = scattering_cross_section(𝐓, 2π)
+Qext = extinction_cross_section(𝐓, 2π)
+ω    = albedo(𝐓)
+g    = asymmetry_parameter(𝐓, 2π)
+```
+
+## Features
 
 - Calculate the T-Matrix of various types of scatterers
   - Homogeneous spheres (via `bhmie`)
@@ -41,3 +77,127 @@ are re-exported by `TransitionMatrices.jl` and can be directly used after
 `using TransitionMatrices`.
 
 The `0.5` compatibility line uses `Quadmath.jl` 1.x and `Wigxjpf.jl` 0.3.x.
+
+## How to cite
+
+If you use `TransitionMatrices.jl` in your research, please cite it — a
+[`CITATION.bib`](CITATION.bib) is provided in this repository. Please also cite
+the original publication(s) for the specific method you use; see
+[Methods & references](#methods--references) below.
+
+## Methods & references
+
+Each solver and numerical trick follows the published literature below; the
+in-source docstrings and comments point to the specific equations used.
+
+**T-Matrix framework & far-field conventions**
+
+- P. C. Waterman, *Symmetry, unitarity, and geometry in electromagnetic
+  scattering*, [Phys. Rev. D **3**, 825–839 (1971)](https://doi.org/10.1103/PhysRevD.3.825)
+  — the null-field / EBCM origin of the T-Matrix method.
+- M. I. Mishchenko, L. D. Travis & A. A. Lacis, *Scattering, Absorption, and
+  Emission of Light by Small Particles*, Cambridge University Press (2002) — the
+  amplitude / phase / scattering matrices, cross sections, asymmetry parameter,
+  T-Matrix rotation, analytic random-orientation average, and the Wigner-d
+  recursions (the pervasive `Eq. (x.y)` references throughout the source).
+
+**Mie & coated spheres** (`bhmie`, `bhcoat`)
+
+- C. F. Bohren & D. R. Huffman, *Absorption and Scattering of Light by Small
+  Particles*, Wiley (1983) — the `bhmie` and `bhcoat` algorithms. The Mie
+  T-Matrix uses Mishchenko et al. (2002), Eqs. (5.42)–(5.44).
+
+**EBCM for axisymmetric shapes** (spheroids, cylinders, Chebyshev particles)
+
+- P. C. Waterman (1971), above.
+- M. I. Mishchenko & L. D. Travis, *Capabilities and limitations of a current
+  FORTRAN implementation of the T-matrix method for randomly oriented,
+  rotationally symmetric scatterers*, JQSRT **60**, 309–324 (1998) — the automatic
+  convergence procedure (`routine_mishchenko`: the choice of `nₘₐₓ` and the
+  Gauss division `Ng`), which the axisymmetric assembly is translated from.
+
+**Numerically stable EBCM — the F⁺ formulation** (`stable = true`)
+
+- W. R. C. Somerville, B. Auguié & E. C. Le Ru, *Severe loss of precision in
+  calculations of T-matrix integrals*, JQSRT **113**, 524 (2012) — the
+  catastrophic-cancellation diagnosis.
+- W. R. C. Somerville, B. Auguié & E. C. Le Ru, JQSRT **123**, 153 (2013),
+  [doi:10.1016/j.jqsrt.2012.07.017](https://doi.org/10.1016/j.jqsrt.2012.07.017)
+  — the cancellation-free `F⁺_{nk}(s,x)` projection (their Eq. 45–62, Table 2)
+  used for high-aspect-ratio spheroids.
+
+**Sh-matrix moment separation** (`prepare_sh`, fast `(λ, mᵣ)` sweeps)
+
+- The separation of the size / material parameters from the particle geometry is
+  the *parameter separation* of V. G. Farafonov, V. B. Il'in & M. S. Prokopjeva,
+  *Light scattering by multilayered nonspherical particles: a set of methods*,
+  JQSRT **79–80**, 599–626 (2003),
+  [doi:10.1016/S0022-4073(02)00310-2](https://doi.org/10.1016/S0022-4073(02)00310-2);
+  the "Sh-matrix" name and formalism are due to D. Petrov, Yu. Shkuratov, E. Zubko
+  & G. Videen, *Sh-matrices method as applied to scattering by particles with
+  layered structure*, JQSRT **106**, 437–454 (2007),
+  [doi:10.1016/j.jqsrt.2007.01.027](https://doi.org/10.1016/j.jqsrt.2007.01.027)
+  (extended in Petrov, Shkuratov & Videen, *The Sh-matrices method applied to
+  light scattering by small lenses*, JQSRT **110**, 1448–1459 (2009),
+  [doi:10.1016/j.jqsrt.2009.01.016](https://doi.org/10.1016/j.jqsrt.2009.01.016)).
+- The term-by-term radial integration reuses the `F⁺` projection of Somerville
+  et al. (2013) and the Riccati–Bessel power series of
+  [DLMF §10.53](https://dlmf.nist.gov/10.53).
+
+**Invariant Imbedding T-Matrix (IITM)** (axisymmetric, N-fold, and arbitrary shapes)
+
+- B. R. Johnson, *Invariant imbedding T matrix approach to electromagnetic
+  scattering*, [Appl. Opt. **27**, 4861–4873 (1988)](https://opg.optica.org/ao/abstract.cfm?uri=ao-27-23-4861)
+  — Eq. (97).
+- L. Bi, P. Yang, G. W. Kattawar & M. I. Mishchenko, *Efficient implementation of
+  the invariant imbedding T-matrix method and the separation of variables method
+  applied to large nonspherical inhomogeneous particles*, JQSRT **116**, 169–183
+  (2013) — Eq. (38).
+- A. Doicu & T. Wriedt, *The Invariant Imbedding T Matrix Approach*, in *The
+  Generalized Multipole Technique for Light Scattering* (Springer, 2018),
+  [doi:10.1007/978-3-319-74890-0_2](https://doi.org/10.1007/978-3-319-74890-0_2)
+  — Eq. (2.40).
+- B. Sun, L. Bi, P. Yang, M. Kahnert & G. Kattawar, *Invariant Imbedding T-matrix
+  Method for Light Scattering by Nonspherical and Inhomogeneous Particles*,
+  Elsevier (2019) — Eq. (4.2.36).
+- S. Hu (胡帅), *Research on the Numerical Computational Models and Application of
+  the Scattering Properties of Nonspherical Atmospheric Particles*, PhD
+  dissertation, National University of Defense Technology (2018) — Eq. (5.71).
+
+**Far-field observables & orientation averaging**
+
+- Mishchenko et al. (2002) — cross sections (Eqs. (5.102), (5.107), (5.140), (5.141)),
+  phase matrix (Eqs. (2.106)–(2.121)), asymmetry parameter (Eq. (4.92)), and the
+  analytic random-orientation T-Matrix (Eq. (5.96)).
+- L. Bi & P. Yang, *Accurate simulation of the optical properties of atmospheric
+  ice crystals with the invariant imbedding T-matrix method*, JQSRT **138**, 17–35
+  (2014), [doi:10.1016/j.jqsrt.2014.01.013](https://doi.org/10.1016/j.jqsrt.2014.01.013)
+  — the scattering-matrix expansion coefficients for a general T-Matrix (Eqs. (24)–(74)).
+
+**Shapes**
+
+- A. Mugnai & W. J. Wiscombe, *Scattering from nonspherical Chebyshev particles. 1*,
+  [Appl. Opt. **25**, 1235 (1986)](https://opg.optica.org/ao/abstract.cfm?uri=ao-25-7-1235)
+  — the Chebyshev-particle definition `r(ϑ) = r₀(1 + ε·Tₙ(cos ϑ))`.
+
+**Linearization & Jacobians**
+
+- R. Spurr, J. Wang, J. Zeng & M. I. Mishchenko, *Linearized T-matrix and Mie
+  scattering computations*, JQSRT (2012).
+- F. Xu & A. B. Davis, *Derivatives of light scattering properties of a
+  nonspherical particle computed with the T-matrix method*, Opt. Lett. **36**(22),
+  4464–4466 (2011), [doi:10.1364/OL.36.004464](https://doi.org/10.1364/OL.36.004464).
+- B. Sun, M. Gao, L. Bi & R. Spurr, *Analytical Jacobians of single scattering
+  optical properties using the invariant imbedding T-matrix method*, Opt. Express
+  **29**(6), 9635–9669 (2021), [doi:10.1364/OE.421886](https://doi.org/10.1364/OE.421886).
+- M. Gao & B. Sun, *Improvement and application of linearized invariant imbedding
+  T-matrix scattering method*, JQSRT **290**, 108322 (2022),
+  [doi:10.1016/j.jqsrt.2022.108322](https://doi.org/10.1016/j.jqsrt.2022.108322).
+
+**Numerical kernels (via dependencies)**
+
+- Wigner 3-j symbols via `Wigxjpf.jl`: H. T. Johansson & C. Forssén, *Fast and
+  accurate evaluation of Wigner 3j, 6j, and 9j symbols using prime factorization
+  and multiword integer arithmetic*, SIAM J. Sci. Comput. **38**(1), A376–A384 (2016).
+- Gauss–Legendre quadrature via
+  [`FastGaussQuadrature.jl`](https://github.com/JuliaApproximation/FastGaussQuadrature.jl).

docs/make.jl

@@ -74,10 +74,13 @@ makedocs(;
         assets = String[]),
     pages = [
         "Home" => "index.md",
+        "Theory & conventions" => "theory.md",
         "Usage" => "usage.md",
-        "Examples" => NB_PAGES,
+        "Examples" => vcat(["Overview" => "examples/index.md"], NB_PAGES),
         "Linearization" => "linearization.md",
-        "API" => "api.md"
+        "Performance" => "performance.md",
+        "API" => "api.md",
+        "Methods & references" => "references.md"
     ])
 
 if get(ENV, "DOCUMENTER_SKIP_DEPLOY", "false") != "true"

docs/src/api.md

@@ -4,10 +4,75 @@ CurrentModule = TransitionMatrices
 
 # API
 
+The full public reference, grouped by topic. Internal (`_`-prefixed) helpers are
+omitted. Use the index below to jump to any symbol.
+
 ```@index
 ```
 
+## Shapes
+
+Scatterer geometries and their common interface.
+
+```@autodocs
+Modules = [TransitionMatrices]
+Pages = ["shapes/index.jl", "shapes/spheroid.jl", "shapes/cylinder.jl",
+    "shapes/chebyshev.jl", "shapes/prism.jl"]
+Filter = t -> !startswith(string(Base.nameof(t)), "_")
+```
+
+## Solvers & T-matrix construction
+
+The two-layer solver API ([`AbstractSolver`](@ref), the fixed solvers, and
+[`Iterative`](@ref)) and the underlying engines (Mie, EBCM with its `stable` and
+Sh-matrix variants, IITM).
+
+```@autodocs
+Modules = [TransitionMatrices]
+Pages = ["solvers.jl",
+    "EBCM/index.jl", "EBCM/axisymmetric.jl", "EBCM/routines.jl",
+    "EBCM/shmatrix.jl", "EBCM/stabilization.jl",
+    "IITM/index.jl", "IITM/axisymmetric.jl", "IITM/arbitrary.jl",
+    "IITM/nfold.jl", "IITM/fourier.jl",
+    "Mie/index.jl", "Mie/bhmie.jl", "Mie/bhcoat.jl", "Mie/MieTransitionMatrix.jl"]
+Filter = t -> !startswith(string(Base.nameof(t)), "_")
+```
+
+## Transition matrices, observables & post-processing
+
+The transition-matrix types and the far-field quantities derived from them
+(cross sections, amplitude/phase/scattering matrices, orientation averaging).
+
+```@autodocs
+Modules = [TransitionMatrices]
+Pages = ["common/index.jl", "common/AbstractTransitionMatrix.jl",
+    "common/AxisymmetricTransitionMatrix.jl",
+    "common/RandomOrientationTransitionMatrix.jl", "common/utils.jl"]
+Filter = t -> !startswith(string(Base.nameof(t)), "_")
+```
+
+## Linearization
+
+The differentiation framework and its backends (see
+[Linearization Framework](@ref) for the narrative).
+
+```@autodocs
+Modules = [TransitionMatrices]
+Pages = ["linearization.jl", "Mie/linearization.jl",
+    "EBCM/linearization.jl", "IITM/linearization.jl"]
+Filter = t -> !startswith(string(Base.nameof(t)), "_")
+```
+
+## Special functions
+
+The Riccati–Bessel, Wigner-d/D, Clebsch–Gordan, factorial, and quadrature
+kernels used internally (a few are exported for convenience).
+
 ```@autodocs
 Modules = [TransitionMatrices]
+Pages = ["special_functions/index.jl", "special_functions/bessel.jl",
+    "special_functions/clebschgordan.jl", "special_functions/factorial.jl",
+    "special_functions/quadrature.jl", "special_functions/wignerd.jl",
+    "compat/index.jl"]
 Filter = t -> !startswith(string(Base.nameof(t)), "_")
 ```

docs/src/examples/index.md

@@ -0,0 +1,43 @@
+# Examples
+
+These pages are [Pluto.jl](https://plutojl.org) notebooks rendered to HTML (with
+plots). Each one is a self-contained walkthrough of one capability; the live,
+editable sources live in the [`examples/`](https://github.com/JuliaRemoteSensing/TransitionMatrices.jl/tree/main/examples)
+directory of the repository.
+
+## The notebooks
+
+- [**Shapes quick-start gallery**](shapes_gallery.md) — define a spheroid,
+  cylinder, Chebyshev particle, and N-fold prism; compute each T-matrix and its
+  `Qsca`/`Qext`/`g`/`ω`, with notes on which solver to use.
+- [**Solver landscape & convergence**](solver_landscape.md) — the two-layer API
+  (`EBCM`, `IITM`, `Iterative`, `stable`) on a high-aspect spheroid, showing
+  classic EBCM diverging with `nₘₐₓ` while the stabilized path holds.
+- [**Angular scattering & polarization**](angular_scattering.md) — the
+  orientation-averaged scattering (Mueller) matrix vs angle (phase function
+  `F₁₁`, linear polarization `-F₁₂/F₁₁`, …), plus fixed-geometry amplitude and
+  phase matrices.
+- [**Orientation averaging**](orientation_averaging.md) — Mishchenko's analytic
+  `RandomOrientationTransitionMatrix` vs the numerical `orientation_average`, and
+  the numerical average converging to it.
+- [**Spectral sensitivity**](spectral_sensitivity.md) — fast wavelength /
+  refractive-index sensitivities via the Sh-matrix moment-separation backend:
+  `prepare_sh` runs the geometry quadrature once, then `ForwardDiff` over the
+  cheap reconstruction gives exact `∂Cₛ𝚌ₐ/∂λ` and `∂Cₛ𝚌ₐ/∂mᵣ` across a spectrum.
+- [**Rain radar observables**](rain_radar.md) — a self-contained
+  radiative-transfer prototype: spheroidal IITM T-matrices, a rain-drop
+  axis-ratio model, water/ice refractive-index fits, and a drop-size distribution
+  feeding dual-pol radar moments and brightness-temperature integrals.
+
+## Running them locally
+
+The notebooks use the `examples/` environment, which develops the parent package:
+
+```julia-repl
+julia> import Pkg; Pkg.activate("examples"); Pkg.instantiate()  # first time only
+julia> using Pluto; Pluto.run()
+```
+
+Then open a notebook from the Pluto start page. Each notebook's first cell
+activates this environment and develops `TransitionMatrices` from the repository
+root, so it works from a fresh checkout.