updates

Author: subhk

docs/Distributed_SHTnsKit_Guide.md

@@ -106,17 +106,17 @@ Vt = copy(fθφ);
 Vp = copy(fθφ);
 
 # Analysis → Slm, Tlm (respects Robert form and PLM tables)
-Slm, Tlm = SHTnsKit.dist_spat_to_SHsphtor(cfg, Vt, Vp; use_rfft=true)
+Slm, Tlm = SHTnsKit.dist_analysis_sphtor(cfg, Vt, Vp; use_rfft=true)
 
 # Synthesis back to grid
-Vt2, Vp2 = SHTnsKit.dist_SHsphtor_to_spat(cfg, Slm, Tlm; prototype_θφ=Vt, real_output=true, use_rfft=true)
+Vt2, Vp2 = SHTnsKit.dist_synthesis_sphtor(cfg, Slm, Tlm; prototype_θφ=Vt, real_output=true, use_rfft=true)
 ```
 
 QST transforms (distributed)
 ```julia
 Vr = copy(fθφ)
-Q, S, T = SHTnsKit.dist_spat_to_SHqst(cfg, Vr, Vt, Vp)
-Vr2, Vt2, Vp2 = SHTnsKit.dist_SHqst_to_spat(cfg, Q, S, T; prototype_θφ=Vr, real_output=true, use_rfft=true)
+Q, S, T = SHTnsKit.dist_analysis_qst(cfg, Vr, Vt, Vp)
+Vr2, Vt2, Vp2 = SHTnsKit.dist_synthesis_qst(cfg, Q, S, T; prototype_θφ=Vr, real_output=true, use_rfft=true)
 ```
 
 Finalize MPI when done:
@@ -132,8 +132,8 @@ Using `use_rfft=true` halves azimuthal FFT work for real inputs/outputs.
 
 Direct API
 - Scalar: `dist_analysis(...; use_rfft=true)`, `dist_synthesis(...; use_rfft=true)`
-- Vector: `dist_spat_to_SHsphtor(...; use_rfft=true)`, `dist_SHsphtor_to_spat(...; use_rfft=true)`
-- QST: `dist_SHqst_to_spat(...; use_rfft=true)`
+- Vector: `dist_analysis_sphtor(...; use_rfft=true)`, `dist_synthesis_sphtor(...; use_rfft=true)`
+- QST: `dist_synthesis_qst(...; use_rfft=true)`
 
 Plan-based API (optional caching of FFT plans)
 ```julia
@@ -210,11 +210,11 @@ Local/point (distributed reductions return the same result on all ranks)
 
 Packed conversions (dense/LM ⇄ distributed)
 - Real (LM):
-  - `dist_spat_to_SH_packed(cfg, fθφ::PencilArray) -> Qlm`
-  - `dist_SH_packed_to_spat(cfg, Qlm; prototype_θφ, real_output=true) -> PencilArray`
+  - `dist_analysis_packed(cfg, fθφ::PencilArray) -> Qlm`
+  - `dist_synthesis_packed(cfg, Qlm; prototype_θφ, real_output=true) -> PencilArray`
 - Complex (LM_cplx):
-  - `dist_spat_cplx_to_SH(cfg, z::PencilArray) -> alm_packed`
-  - `dist_SH_to_spat_cplx(cfg, alm_packed; prototype_θφ) -> PencilArray`
+  - `dist_analysis_packed_cplx(cfg, z::PencilArray) -> alm_packed`
+  - `dist_synthesis_packed_cplx(cfg, alm_packed; prototype_θφ) -> PencilArray`
 
 ---
 

docs/advanced_ad_summary.md

@@ -5,8 +5,8 @@ This document summarizes AD capabilities for SHTnsKit.jl, enabling applications
 ## AD Capabilities
 
 ### Supported Functions
-- **Basic transforms**: `synthesis`, `analysis`, `SH_to_spat_cplx`, `spat_cplx_to_SH`
-- **Vector transforms**: `SHsphtor_to_spat`, `spat_to_SHsphtor`
+- **Basic transforms**: `synthesis`, `analysis`, `synthesis_packed_cplx`, `analysis_packed_cplx`
+- **Vector transforms**: `synthesis_sphtor`, `analysis_sphtor`
 - **Diagnostics**: `energy_scalar_l_spectrum`, `energy_vector_l_spectrum`
 
 ### ForwardDiff Support

docs/advanced_optimizations_summary.md

@@ -100,10 +100,10 @@ for i in 1:cfg.nlat, j in 1:cfg.nlon
 end
 
 # Decompose into spheroidal/toroidal components
-Slm, Tlm = spat_to_SHsphtor(cfg, Vθ, Vφ)
+Slm, Tlm = analysis_sphtor(cfg, Vθ, Vφ)
 
 # Reconstruct velocity field
-Vθ_rec, Vφ_rec = SHsphtor_to_spat(cfg, Slm, Tlm)
+Vθ_rec, Vφ_rec = synthesis_sphtor(cfg, Slm, Tlm)
 
 destroy_config(cfg)
 ```

docs/src/advanced.md

@@ -203,8 +203,8 @@ end
 Alm = analysis(cfg, test_field)
 
 # Compute gradient using spectral method (exact derivatives)
-# SH_to_grad_spat computes ∇f = (∂f/∂θ, (1/sinθ)∂f/∂φ)
-∂f_∂θ, ∂f_∂φ_over_sinθ = SH_to_grad_spat(cfg, Alm)
+# synthesis_grad computes ∇f = (∂f/∂θ, (1/sinθ)∂f/∂φ)
+∂f_∂θ, ∂f_∂φ_over_sinθ = synthesis_grad(cfg, Alm)
 
 println("Gradient computed using spectral method:")
 println("  ∂f/∂θ range: ", extrema(∂f_∂θ))
@@ -250,7 +250,7 @@ Alm = SHTnsKit.dist_analysis(cfg, fθφ)
 # Compute gradient using distributed synthesis with spheroidal transform
 # Gradient = (∂f/∂θ, (1/sinθ)∂f/∂φ) via spheroidal synthesis
 Tlm = zeros(ComplexF64, cfg.lmax+1, cfg.mmax+1)  # Zero toroidal component
-∂f_∂θ, ∂f_∂φ_over_sinθ = SHTnsKit.dist_SHsphtor_to_spat(cfg, Alm, Tlm; prototype_θφ=fθφ)
+∂f_∂θ, ∂f_∂φ_over_sinθ = SHTnsKit.dist_synthesis_sphtor(cfg, Alm, Tlm; prototype_θφ=fθφ)
 
 if rank == 0
     println("Distributed gradient computed successfully")
@@ -360,7 +360,7 @@ for i in 1:cfg.nlat, j in 1:cfg.nlon
 end
 
 # Decompose into spheroidal/toroidal
-Slm, Tlm = spat_to_SHsphtor(cfg, Vθ, Vφ)
+Slm, Tlm = analysis_sphtor(cfg, Vθ, Vφ)
 
 # Compute divergence and vorticity
 div_field = divergence_from_spheroidal(cfg, Slm)

docs/src/api/index.md

@@ -46,8 +46,8 @@ analysis!
 ## Complex Field Transforms
 
 ```@docs
-SH_to_spat_cplx
-spat_cplx_to_SH
+synthesis_packed_cplx
+analysis_packed_cplx
 ```
 
 ## Vector Field Transforms
@@ -59,20 +59,20 @@ Vector fields on the sphere are decomposed into **spheroidal** and **toroidal**
 ### Vector Synthesis
 
 ```@docs
-SHsphtor_to_spat
+synthesis_sphtor
 ```
 
 ### Vector Analysis
 
 ```@docs
-spat_to_SHsphtor
+analysis_sphtor
 ```
 
 ## QST Transforms (3D Vector Fields)
 
 ```@docs
-SHqst_to_spat
-spat_to_SHqst
+synthesis_qst
+analysis_qst
 ```
 
 ## Rotations
@@ -113,15 +113,15 @@ When using MPI with PencilArrays, the following functions are available via the
 
 - `dist_analysis(cfg, fθφ)` - Distributed spatial to spectral transform
 - `dist_synthesis(cfg, Alm; prototype_θφ, real_output)` - Distributed spectral to spatial transform
-- `dist_spat_to_SHsphtor(cfg, Vθ, Vφ)` - Distributed vector analysis
-- `dist_SHsphtor_to_spat(cfg, Slm, Tlm; prototype_θφ)` - Distributed vector synthesis
+- `dist_analysis_sphtor(cfg, Vθ, Vφ)` - Distributed vector analysis
+- `dist_synthesis_sphtor(cfg, Slm, Tlm; prototype_θφ)` - Distributed vector synthesis
 
 See the [Distributed Guide](../distributed.md) for detailed usage.
 
 ## Gradient and Differential Operators
 
 ```@docs
-SH_to_grad_spat
+synthesis_grad
 divergence_from_spheroidal
 vorticity_from_toroidal
 ```
@@ -173,10 +173,10 @@ for i in 1:cfg.nlat, j in 1:cfg.nlon
 end
 
 # Decompose into spheroidal/toroidal
-Slm, Tlm = spat_to_SHsphtor(cfg, Vθ, Vφ)
+Slm, Tlm = analysis_sphtor(cfg, Vθ, Vφ)
 
 # Reconstruct
-Vθ_rec, Vφ_rec = SHsphtor_to_spat(cfg, Slm, Tlm)
+Vθ_rec, Vφ_rec = synthesis_sphtor(cfg, Slm, Tlm)
 
 destroy_config(cfg)
 ```

docs/src/distributed.md

@@ -96,8 +96,8 @@ Pkg.add(["MPI", "PencilArrays", "PencilFFTs"])
 |----------|-------------|
 | `dist_analysis(cfg, fθφ)` | Distributed spatial → spectral transform |
 | `dist_synthesis(cfg, Alm; prototype_θφ)` | Distributed spectral → spatial transform |
-| `dist_spat_to_SHsphtor(cfg, Vθ, Vφ)` | Distributed vector field analysis |
-| `dist_SHsphtor_to_spat(cfg, Slm, Tlm; prototype_θφ)` | Distributed vector field synthesis |
+| `dist_analysis_sphtor(cfg, Vθ, Vφ)` | Distributed vector field analysis |
+| `dist_synthesis_sphtor(cfg, Slm, Tlm; prototype_θφ)` | Distributed vector field synthesis |
 
 ### Spectral Operators
 
@@ -189,8 +189,8 @@ for (i_local, i_global) in enumerate(ranges[1])
 end
 
 # Distributed vector transform
-Slm, Tlm = SHTnsKit.dist_spat_to_SHsphtor(cfg, Vθ, Vφ)
-Vθ_out, Vφ_out = SHTnsKit.dist_SHsphtor_to_spat(cfg, Slm, Tlm; prototype_θφ=Vθ)
+Slm, Tlm = SHTnsKit.dist_analysis_sphtor(cfg, Vθ, Vφ)
+Vθ_out, Vφ_out = SHTnsKit.dist_synthesis_sphtor(cfg, Slm, Tlm; prototype_θφ=Vθ)
 
 destroy_config(cfg)
 MPI.Finalize()

docs/src/examples/index.md

@@ -207,7 +207,7 @@ for i in 1:cfg.nlat, j in 1:cfg.nlon
 end
 
 # Decompose into spheroidal (divergent) and toroidal (rotational)
-Slm, Tlm = spat_to_SHsphtor(cfg, u, v)
+Slm, Tlm = analysis_sphtor(cfg, u, v)
 
 # Analyze energy distribution
 spheroidal_energy = sum(abs2, Slm)
@@ -216,7 +216,7 @@ println("Spheroidal (divergent) energy: $spheroidal_energy")
 println("Toroidal (rotational) energy: $toroidal_energy")
 
 # Reconstruct original velocity
-u_recon, v_recon = SHsphtor_to_spat(cfg, Slm, Tlm)
+u_recon, v_recon = synthesis_sphtor(cfg, Slm, Tlm)
 velocity_error = norm(u - u_recon) + norm(v - v_recon)
 println("Velocity reconstruction error: $velocity_error")
 
@@ -258,7 +258,7 @@ end
 
 # Get velocity from stream function (toroidal component only)
 Slm_zero = zeros(ComplexF64, cfg.lmax+1, cfg.mmax+1)
-u_stream, v_stream = SHsphtor_to_spat(cfg, Slm_zero, ψ_lm)
+u_stream, v_stream = synthesis_sphtor(cfg, Slm_zero, ψ_lm)
 
 # Convert stream function to spatial domain
 stream_function = synthesis(cfg, ψ_lm)
@@ -472,8 +472,8 @@ start_time = MPI.Wtime()
 
 n_iter = 20
 for i in 1:n_iter
-    Slm, Tlm = SHTnsKit.dist_spat_to_SHsphtor(cfg, Vθ, Vφ)
-    Vθ_out, Vφ_out = SHTnsKit.dist_SHsphtor_to_spat(cfg, Slm, Tlm; prototype_θφ=Vθ)
+    Slm, Tlm = SHTnsKit.dist_analysis_sphtor(cfg, Vθ, Vφ)
+    Vθ_out, Vφ_out = SHTnsKit.dist_synthesis_sphtor(cfg, Slm, Tlm; prototype_θφ=Vθ)
 end
 
 MPI.Barrier(comm)
@@ -485,8 +485,8 @@ if rank == 0
 end
 
 # Verify accuracy
-Slm, Tlm = SHTnsKit.dist_spat_to_SHsphtor(cfg, Vθ, Vφ)
-Vθ_rec, Vφ_rec = SHTnsKit.dist_SHsphtor_to_spat(cfg, Slm, Tlm; prototype_θφ=Vθ)
+Slm, Tlm = SHTnsKit.dist_analysis_sphtor(cfg, Vθ, Vφ)
+Vθ_rec, Vφ_rec = SHTnsKit.dist_synthesis_sphtor(cfg, Slm, Tlm; prototype_θφ=Vθ)
 
 θ_err = maximum(abs.(parent(Vθ_rec) .- parent(Vθ)))
 φ_err = maximum(abs.(parent(Vφ_rec) .- parent(Vφ)))

docs/src/gpu.md

@@ -147,10 +147,10 @@ Alm = gpu_analysis_safe(cfg, large_spatial_data)
 
 ### Vector Field Transforms
 
-#### `gpu_spat_to_SHsphtor`
+#### `gpu_analysis_sphtor`
 
 ```julia
-gpu_spat_to_SHsphtor(cfg::SHTConfig, vθ, vφ; device=get_device())
+gpu_analysis_sphtor(cfg::SHTConfig, vθ, vφ; device=get_device())
 ```
 
 GPU-accelerated spheroidal-toroidal decomposition.
@@ -164,21 +164,21 @@ vθ = rand(cfg.nlat, cfg.nlon)
 vφ = rand(cfg.nlat, cfg.nlon)
 
 # Decompose into spheroidal and toroidal
-Slm, Tlm = gpu_spat_to_SHsphtor(cfg, vθ, vφ)
+Slm, Tlm = gpu_analysis_sphtor(cfg, vθ, vφ)
 ```
 
-#### `gpu_SHsphtor_to_spat`
+#### `gpu_synthesis_sphtor`
 
 ```julia
-gpu_SHsphtor_to_spat(cfg::SHTConfig, Slm, Tlm; device=get_device(), real_output=true)
+gpu_synthesis_sphtor(cfg::SHTConfig, Slm, Tlm; device=get_device(), real_output=true)
 ```
 
 GPU-accelerated vector field synthesis.
 
 **Example:**
 ```julia
 # Reconstruct vector field from coefficients
-vθ_out, vφ_out = gpu_SHsphtor_to_spat(cfg, Slm, Tlm)
+vθ_out, vφ_out = gpu_synthesis_sphtor(cfg, Slm, Tlm)
 ```
 
 ### Spectral Operators

docs/src/mpi_roundtrip.md

@@ -38,6 +38,6 @@ end
 MPI.Finalize()
 ```
 
-For vector fields, use `dist_spat_to_SHsphtor` and `dist_SHsphtor_to_spat` with the
+For vector fields, use `dist_analysis_sphtor` and `dist_synthesis_sphtor` with the
 same `prototype_θφ`. Precomputing Legendre tables via `prepare_plm_tables!(cfg)` on
 regular grids typically improves performance.

docs/src/performance.md

@@ -451,7 +451,7 @@ function benchmark_vector_vs_scalar(cfg)
     Tlm[3,2] = 0.5
 
     # Vector spatial fields
-    Vθ, Vφ = SHsphtor_to_spat(cfg, Slm, Tlm)
+    Vθ, Vφ = synthesis_sphtor(cfg, Slm, Tlm)
 
     # Scalar benchmarks
     scalar_synth = @elapsed begin
@@ -469,13 +469,13 @@ function benchmark_vector_vs_scalar(cfg)
     # Vector benchmarks
     vector_synth = @elapsed begin
         for i in 1:20
-            SHsphtor_to_spat(cfg, Slm, Tlm)
+            synthesis_sphtor(cfg, Slm, Tlm)
         end
     end
 
     vector_analysis = @elapsed begin
         for i in 1:20
-            spat_to_SHsphtor(cfg, Vθ, Vφ)
+            analysis_sphtor(cfg, Vθ, Vφ)
         end
     end