class_sz: SZ Detection & Computational Framework

• class_sz is a dual-purpose construct that defines a three-class reliability scheme (Good, Bad, Ugly) for SZ detections based on SED projections and machine-learning classifiers.
• It uses likelihood, k-means, and ANN methods to robustly classify Planck SZ candidates, achieving high completeness and purity in source assessment.
• As a computational framework, CLASS_SZ extends the Boltzmann code CLASS with halo-model calculations, enabling fast and accurate predictions for SZ, CMB, and LSS observables in Stage IV surveys.

In current arXiv usage, class_sz designates two distinct SZ-centered constructs. In one usage, it is a reliability-classification scheme for Sunyaev–Zeldovich detections in survey catalogues, especially the three-way separation of Planck candidates into Good, Bad, and Ugly populations by means of SED-based statistical classification (Aghanim et al., 2014). In the other, it is a public computational framework—also written as CLASS_SZ—that extends the Boltzmann code CLASS with halo-model and linear-bias calculations for SZ, CMB, large-scale-structure, cluster-count, and higher-order observables relevant to Stage IV cross-survey science (Bolliet et al., 2023).

1. Nomenclature and scope

The two usages share an SZ focus but operate at different levels of the research stack: one is a catalogue-quality assessment scheme, the other a theory-and-inference software platform.

Usage of class_sz	Domain	Principal source
Good/Bad/Ugly reliability classes for SZ detections	Planck and survey catalogue assessment	(Aghanim et al., 2014)
C/Python/JAX code extending CLASS for SZ/CMB/LSS observables	Halo model, cross-survey theory, inference	(Bolliet et al., 2023)

The reliability-classification usage arose in the context of source classification in catalogues from X-rays (MCXC), optical (SDSS), and millimetric Planck Sunyaev–Zeldovich data, with the goal of determining the confidence with which catalogue elements can be distinguished in populations on the basis of their spectral energy distribution (Aghanim et al., 2014). The software usage emerged later as a modular extension of CLASS intended to compute theoretical predictions for observables relevant to the Stage IV era, including tSZ, kSZ, galaxy clustering, lensing, CIB, bispectra, and cluster counts (Bolliet et al., 2023).

A separate notation, $\mathscr{SZ}_\alpha$, appears in Banach-space theory for operator-ideal classes indexed by the Szlenk index; this is a distinct mathematical usage of “SZ” rather than an SZ-cosmology meaning (Brooker, 2010).

2. Reliability classification for SZ detections

In the catalogue-classification setting, class_sz is built from a low-dimensional projection of multi-frequency photometry onto an astrophysical basis. For each candidate SZ source, the Planck fluxes $F_\nu$ at $\nu=\{70,100,143,217,353,545,857\}\,\mathrm{GHz}$ are measured by aperture photometry using a $10'$ radius aperture and a background in a $20\text{--}50'$ annulus. These seven band-flux measurements are then projected onto a five-component basis through the linear model (Aghanim et al., 2014)

$$F_\nu = A_{\rm SZ}F_{\rm SZ}(\nu)+A_{\rm CMB}F_{\rm CMB}(\nu)+A_{\rm IR}F_{\rm IR}(\nu)+A_{\rm RAD}F_{\rm RAD}(\nu)+A_{\rm CO}F_{\rm CO}(\nu)+N(\nu).$$

The components are physically specified. $F_{\rm SZ}(\nu)$ is the non-relativistic tSZ spectrum; $F_{\rm CMB}(\nu)$ is the derivative of a $2.725\,\mathrm{K}$ blackbody; $F_{\rm IR}(\nu)\propto \nu^{\beta_d}B_\nu(T_d)$ is a modified black body with $F_\nu$0 and $F_\nu$1, capturing dust, CIB, and IR-point-source contamination; $F_\nu$2 is a radio power-law template; and $F_\nu$3 is a CO rotational-line template at $F_\nu$4 (Aghanim et al., 2014). In matrix form, the fitted amplitudes are

$F_\nu$5

with $F_\nu$6 the $F_\nu$7 mixing matrix and $F_\nu$8 the instrumental-noise covariance. These five amplitudes form the feature vector used by all classifiers.

Three classification strategies are then applied. The first is a likelihood analysis described as halfway between supervised and unsupervised methods. The second is an unsupervised clustering technique, implemented with $F_\nu$9-means. The third is a supervised classifier based on Artificial Neural Networks. The three methods were reported to be in very good agreement with each other, while the supervised neural-network-based classification showed better performances and allowed the best separation into populations of reliable and unreliable sources in catalogues (Aghanim et al., 2014).

The final reliability assessment is explicitly three-fold. The Good class corresponds to high-reliability SZ candidates; the Bad class to spurious candidates; and the Ugly class to noise-dominated or low-S/N objects. In practice, the authors found that the supervised ANN yields the cleanest separation: the Good class has an ensemble-averaged SED consistent with pure tSZ, the Bad class shows strong IR + CO contamination, and the Ugly class sits at low S/N and is noise-dominated (Aghanim et al., 2014).

3. Statistical formulations and decision boundaries

The likelihood-based classifier is built from the four non-SZ amplitudes. Its per-source contamination likelihood is

$\nu=\{70,100,143,217,353,545,857\}\,\mathrm{GHz}$0

where the empirical PDFs are estimated from 2000 random sky positions. In the reported formulation, $\nu=\{70,100,143,217,353,545,857\}\,\mathrm{GHz}$1, $\nu=\{70,100,143,217,353,545,857\}\,\mathrm{GHz}$2, and $\nu=\{70,100,143,217,353,545,857\}\,\mathrm{GHz}$3 are fit as Gaussians,

$\nu=\{70,100,143,217,353,545,857\}\,\mathrm{GHz}$4

while $\nu=\{70,100,143,217,353,545,857\}\,\mathrm{GHz}$5 is fit as a Cauchy/Lorentzian,

$\nu=\{70,100,143,217,353,545,857\}\,\mathrm{GHz}$6

The explicit recommended decision boundaries are $\nu=\{70,100,143,217,353,545,857\}\,\mathrm{GHz}$7 for Good and $\nu=\{70,100,143,217,353,545,857\}\,\mathrm{GHz}$8 for Bad candidates, with intermediate objects mapping into the residual class structure (Aghanim et al., 2014).

The unsupervised classifier defines a four-dimensional contamination space using $\nu=\{70,100,143,217,353,545,857\}\,\mathrm{GHz}$9, each normalized by its $10'$0 from sky-randoms, and measures the distance from zero contamination as

$10'$1

A Euclidean $10'$2-means procedure with $10'$3 clusters then maps the smallest-$10'$4 cluster onto Good, the intermediate cluster onto Ugly, and the largest-$10'$5 cluster onto Bad (Aghanim et al., 2014).

The ANN classifier uses a three-layer architecture with an input layer of 5 nodes $10'$6, a hidden layer of 10 sigmoid neurons, and an output layer of 3 sigmoid neurons $10'$7. The activation function is

$10'$8

and the input amplitudes are standardized by their sky-random $10'$9 values. The training sets are equal-sized subsets consisting of 861 confirmed Planck-SZ clusters (PSZ1) for Good, 300 spurious sources—100 each from radio-$20\text{--}50'$0, IR-$20\text{--}50'$1, and Planck cold-Galactic-cores—for Bad, and 2000 random sky positions for Ugly. Training minimizes

$20\text{--}50'$2

by standard back-propagation and gradient descent with learning rate $20\text{--}50'$3, momentum $20\text{--}50'$4, and early stopping when the checking-set error reaches minimum. The outputs $20\text{--}50'$5 sum to $20\text{--}50'$6 and are interpreted as class-membership confidence scores (Aghanim et al., 2014).

The reported comparative metrics place the ANN clearly ahead of the other two methods. A cut $20\text{--}50'$7, equivalently $20\text{--}50'$8, retains $20\text{--}50'$9 of confirmed clusters while rejecting $$F_\nu = A_{\rm SZ}F_{\rm SZ}(\nu)+A_{\rm CMB}F_{\rm CMB}(\nu)+A_{\rm IR}F_{\rm IR}(\nu)+A_{\rm RAD}F_{\rm RAD}(\nu)+A_{\rm CO}F_{\rm CO}(\nu)+N(\nu).$$0 of spurious sources, corresponding to completeness $$F_\nu = A_{\rm SZ}F_{\rm SZ}(\nu)+A_{\rm CMB}F_{\rm CMB}(\nu)+A_{\rm IR}F_{\rm IR}(\nu)+A_{\rm RAD}F_{\rm RAD}(\nu)+A_{\rm CO}F_{\rm CO}(\nu)+N(\nu).$$1 and purity $$F_\nu = A_{\rm SZ}F_{\rm SZ}(\nu)+A_{\rm CMB}F_{\rm CMB}(\nu)+A_{\rm IR}F_{\rm IR}(\nu)+A_{\rm RAD}F_{\rm RAD}(\nu)+A_{\rm CO}F_{\rm CO}(\nu)+N(\nu).$$2. The reported ROC/AUC values are $$F_\nu = A_{\rm SZ}F_{\rm SZ}(\nu)+A_{\rm CMB}F_{\rm CMB}(\nu)+A_{\rm IR}F_{\rm IR}(\nu)+A_{\rm RAD}F_{\rm RAD}(\nu)+A_{\rm CO}F_{\rm CO}(\nu)+N(\nu).$$3 for the ANN, $$F_\nu = A_{\rm SZ}F_{\rm SZ}(\nu)+A_{\rm CMB}F_{\rm CMB}(\nu)+A_{\rm IR}F_{\rm IR}(\nu)+A_{\rm RAD}F_{\rm RAD}(\nu)+A_{\rm CO}F_{\rm CO}(\nu)+N(\nu).$$4 for $$F_\nu = A_{\rm SZ}F_{\rm SZ}(\nu)+A_{\rm CMB}F_{\rm CMB}(\nu)+A_{\rm IR}F_{\rm IR}(\nu)+A_{\rm RAD}F_{\rm RAD}(\nu)+A_{\rm CO}F_{\rm CO}(\nu)+N(\nu).$$5-means, and $$F_\nu = A_{\rm SZ}F_{\rm SZ}(\nu)+A_{\rm CMB}F_{\rm CMB}(\nu)+A_{\rm IR}F_{\rm IR}(\nu)+A_{\rm RAD}F_{\rm RAD}(\nu)+A_{\rm CO}F_{\rm CO}(\nu)+N(\nu).$$6 for the likelihood method (Aghanim et al., 2014). The method was applied to SZ sources detected by the Planck satellite and led to a classification agreeing with the reliability assessment published in the Planck SZ catalogue; it was also presented as easily applicable to future large surveys such as SRG/eROSITA and Euclid (Aghanim et al., 2014).

4. CLASS_SZ as a computational framework

In the later software literature, class_sz is a versatile and robust code in C and Python that extends CLASS with a halo-model/LSS toolkit optimized for cross-survey science (Bolliet et al., 2023). The scientific motivation is the Stage IV regime of CMB and LSS surveys, driven by experiments such as ACT, SPT, the Simons Observatory, and CMB-S4, where high-resolution, low-noise maps enable precision measurements of secondary CMB anisotropies at arcminute scales. The tSZ effect probes inverse-Compton scattering by hot electrons in the intracluster medium, while the kSZ effect traces Doppler shifts from scattering off moving electrons in large-scale structure. Cross-correlating SZ maps with external tracers such as galaxy catalogs, CMB lensing, and the cosmic infrared background supports tomography of the ICM/CGM, tests of astrophysical models, and cosmological constraints, including work related to the $$F_\nu = A_{\rm SZ}F_{\rm SZ}(\nu)+A_{\rm CMB}F_{\rm CMB}(\nu)+A_{\rm IR}F_{\rm IR}(\nu)+A_{\rm RAD}F_{\rm RAD}(\nu)+A_{\rm CO}F_{\rm CO}(\nu)+N(\nu).$$7 tension (Bolliet et al., 2023).

The architecture is modular. The overview paper identifies three new C modules—class_sz.c, class_sz_tools.c, and class_sz_clustercounts.c—plus Python bindings. The core module handles 1D and 2D integrals over mass and redshift, power spectra, bispectra, halo mass functions, biases, and kernels. The tools module provides adaptive integrators from CosmoTherm, FFTLog routines via FFTW3, and interpolation tables. The cluster-count module implements SZ cluster-count predictions, scaling relations, survey noise and completeness functions, and unbinned and binned likelihoods (Bolliet et al., 2023). On the Python side, classy_sz.pyx extends the Cython interface, while class_szfast.py interfaces high-accuracy neural-network emulators, “cosmopower,” for CMB TT/TE/EE power spectra and linear and non-linear matter power spectra (Bolliet et al., 2023).

CLASS_SZ II describes the code base more broadly as written primarily in C, with a Cython-wrapped Python interface and selective “jaxified” routines for automatic differentiation, building directly on CLASS v2.9.4 for background quantities, linear transfer functions, and standard CMB and matter power spectra (Bolliet et al., 10 Jul 2025). Its modular organization includes halo and profile modules for halo mass functions, halo bias, concentration–mass conversions, and radial profiles such as NFW and gNFW gas density and pressure; FFTLog and QAWO modules for Fourier/Hankel transforms; adaptive Patterson quadrature for mass and redshift integrals; and a small JAX subpackage containing pure-Python re-implementations of selected kernels (Bolliet et al., 10 Jul 2025).

The framework computes CLASS outputs together with a large suite of halo-model and linearly biased LSS observables. These include CMB anisotropy power spectra $$F_\nu = A_{\rm SZ}F_{\rm SZ}(\nu)+A_{\rm CMB}F_{\rm CMB}(\nu)+A_{\rm IR}F_{\rm IR}(\nu)+A_{\rm RAD}F_{\rm RAD}(\nu)+A_{\rm CO}F_{\rm CO}(\nu)+N(\nu).$$8, $$F_\nu = A_{\rm SZ}F_{\rm SZ}(\nu)+A_{\rm CMB}F_{\rm CMB}(\nu)+A_{\rm IR}F_{\rm IR}(\nu)+A_{\rm RAD}F_{\rm RAD}(\nu)+A_{\rm CO}F_{\rm CO}(\nu)+N(\nu).$$9, $F_{\rm SZ}(\nu)$0, $F_{\rm SZ}(\nu)$1, and lensing potential $F_{\rm SZ}(\nu)$2; linear and non-linear matter power spectra; galaxy auto- and cross-angular power spectra; tSZ and kSZ power spectra; Compton-$F_{\rm SZ}(\nu)$3 cross-spectra with galaxies and CMB lensing; CIB auto- and cross-spectra; tree-level matter bispectra and halo-model bispectra; projected bispectra such as $F_{\rm SZ}(\nu)$4, $F_{\rm SZ}(\nu)$5, and kSZ–galaxy cross-bispectra; weak-lensing correlation functions $F_{\rm SZ}(\nu)$6; galaxy tangential shear $F_{\rm SZ}(\nu)$7; galaxy clustering $F_{\rm SZ}(\nu)$8; and SZ cluster-count predictions (Bolliet et al., 2023).

5. Theoretical formalism, workflows, and benchmarks

The central modeling strategy is a unified halo-model and linear-bias treatment. In the overview paper, the thermal SZ angular power spectrum is written as

$F_{\rm SZ}(\nu)$9

with Fourier-space Compton-$F_{\rm CMB}(\nu)$0 profile

$F_{\rm CMB}(\nu)$1

Cross-power spectra are written in the generic form

$F_{\rm CMB}(\nu)$2

and the mass–observable scaling relation is

$F_{\rm CMB}(\nu)$3

where $F_{\rm CMB}(\nu)$4 is the hydrostatic mass bias (Bolliet et al., 2023).

CLASS_SZ II states the halo-model matter power spectrum as

$F_{\rm CMB}(\nu)$5

with

$F_{\rm CMB}(\nu)$6

and

$F_{\rm CMB}(\nu)$7

It also gives the tSZ profile kernel

$F_{\rm CMB}(\nu)$8

and a linearly biased angular spectrum

$F_{\rm CMB}(\nu)$9

These formulas express the package’s basic design principle: CLASS supplies the background and linear perturbations, while class_sz adds halo-model profiles, projection kernels, and fast numerical evaluation (Bolliet et al., 10 Jul 2025).

Typical workflows are correspondingly broad. The code can compute $2.725\,\mathrm{K}$0, tSZ–CMB lensing cross-power $2.725\,\mathrm{K}$1, non-linear matter $2.725\,\mathrm{K}$2 using emulators such as "hmcode2020", and galaxy angular clustering or shear correlation functions. Configuration examples include parameters such as cl_sz_method = halo_model or perturbation, cl_sz_tsz_profile = "Arnaud2010" or "Battaglia2012", cl_sz_kappa_tracer = galaxy_CMBlens, cl_sz_pnfw_m_function = Tinker, and cl_sz_fNL = 0.0 (Bolliet et al., 2023). The public repository contains source modules, Python bindings, examples, parameter defaults, tutorial notebooks, and MCMC pipeline examples for Cobaya and MontePython (Bolliet et al., 2023).

Reported performance is one of the code’s distinguishing practical properties. The overview paper reports $2.725\,\mathrm{K}$3 per evaluation for the tSZ auto-spectrum on 8 cores, $2.725\,\mathrm{K}$4 for kSZ and galaxy–CMB lensing cross spectra, $2.725\,\mathrm{K}$5 for CMB power spectra with cosmopower emulators, and $2.725\,\mathrm{K}$6 for the non-linear matter emulator, with MCMC analyses of CMB spectra converging in $2.725\,\mathrm{K}$7 using class_sz + Cobaya instead of $2.725\,\mathrm{K}$8 week with CLASS at the same accuracy (Bolliet et al., 2023). CLASS_SZ II reports typical single-threaded wall-clock times of $2.725\,\mathrm{K}$9 for CLASS background, $F_{\rm IR}(\nu)\propto \nu^{\beta_d}B_\nu(T_d)$0 for CMB $F_{\rm IR}(\nu)\propto \nu^{\beta_d}B_\nu(T_d)$1 via emulators plus background, $F_{\rm IR}(\nu)\propto \nu^{\beta_d}B_\nu(T_d)$2 for matter $F_{\rm IR}(\nu)\propto \nu^{\beta_d}B_\nu(T_d)$3 or individual $F_{\rm IR}(\nu)\propto \nu^{\beta_d}B_\nu(T_d)$4, and $F_{\rm IR}(\nu)\propto \nu^{\beta_d}B_\nu(T_d)$5 for combined halo-model outputs, with Python wrappers within a factor $F_{\rm IR}(\nu)\propto \nu^{\beta_d}B_\nu(T_d)$6 slower and JAX-ified routines adding $F_{\rm IR}(\nu)\propto \nu^{\beta_d}B_\nu(T_d)$7 overhead while permitting vectorized differentiation (Bolliet et al., 10 Jul 2025).

6. Projected-field kSZ in class_sz and current limitations

A recent extension of the class_sz ecosystem treats projected-field kSZ cross-correlations. The projected-field kSZ estimator is defined by cross-correlating a foreground-cleaned, filtered, squared CMB temperature map with a large-scale-structure tracer, requiring no individual tracer redshifts (Rodriguez et al., 3 Sep 2025). In harmonic space,

$F_{\rm IR}(\nu)\propto \nu^{\beta_d}B_\nu(T_d)$8

where $F_{\rm IR}(\nu)\propto \nu^{\beta_d}B_\nu(T_d)$9 is the projected halo overdensity and the filter $F_\nu$00 is chosen to optimally up-weight small-scale kSZ against primary CMB and noise (Rodriguez et al., 3 Sep 2025).

The halo-model implementation decomposes projected observables into one- and two-halo terms,

$F_\nu$01

and

$F_\nu$02

Here $F_\nu$03 is the Tinker (2008) mass function, $F_\nu$04 is the Tinker et al. (2010) linear bias, and $F_\nu$05 encodes projection kernel and Fourier-space profile (Rodriguez et al., 3 Sep 2025). The dominant-contraction expression for the projected-field signal is

$F_\nu$06

with

$F_\nu$07

The default modeling choices include Battaglia et al. (2012) GNFW fits for electron pressure, Battaglia (2016) GNFW fits for electron density, a mass integral $F_\nu$08, redshift range $F_\nu$09, radial cutoff $F_\nu$10, and multipoles up to $F_\nu$11 (Rodriguez et al., 3 Sep 2025). Experiment-specific filtering is introduced through the beam $F_\nu$12, with Planck nominal $F_\nu$13 and SO LAT $F_\nu$14, a total noise-plus-foreground residual spectrum $F_\nu$15, and a Wiener filter

$F_\nu$16

where $F_\nu$17, together with truncation $F_\nu$18 for $F_\nu$19 to avoid ISW leakage (Rodriguez et al., 3 Sep 2025).

The principal current caveat is theoretical completeness. The public implementation includes only the dominant Wick contraction $F_\nu$20 and neglects subdominant contractions such as $F_\nu$21. Comparison with Websky simulations finds good agreement, particularly at Planck sensitivity, but also an $F_\nu$22 difference for SO that significantly exceeds predicted error bars; the paper states that these missing contractions must be included to obtain unbiased inference from upcoming projected-field kSZ measurements (Rodriguez et al., 3 Sep 2025). The same source notes that modeling uncertainties of order $F_\nu$23 are not yet a major concern for Planck-sensitivity analyses, whereas SO and next-generation surveys require the full set of contractions (Rodriguez et al., 3 Sep 2025).

The contemporary meaning of class_sz is therefore structurally dual. In observational catalogue work it denotes a three-class statistical reliability assessment for SZ detections based on SED projection and classifiers of increasing supervision (Aghanim et al., 2014). In theoretical and computational cosmology it denotes a public, modular, emulator-accelerated extension of CLASS for SZ, CMB, and LSS observables, with increasing reach into differentiable pipelines and projected-field kSZ modeling (Bolliet et al., 2023).