NAME
ftsvdcmprmf - Build a rank-K SVD compression of an OGIP RMF (side-car file).
USAGE
ftsvdcmprmf infile outfile [arffile=] [eps=] [kmax=] [oversamp=] [powiter=] [check=] [nprobes=] [emitrmf=] [emitthresh=]
DESCRIPTION
FTSVDCMPRMF computes a low-rank truncated singular-value decomposition
of an OGIP redistribution matrix (RMF) using the Halko-Martinsson
randomized algorithm and writes the factored representation
M_K = U_K * diag(sigma_K) * V_K^T
to a side-car FITS file (the .svdmat.fits format) that XSPEC can later
attach via response <n> svdmat <file> to accelerate
the response folding in fit and HMC paths.
The build does not modify the input RMF. The side-car is a thin
representation of the factors only and is meant to live alongside the
original .rmf on disk.
If the optional ARF file is given, it is folded into the operator
before factorisation (M' = M * diag(A)), which makes the
side-car ARF-specific. By default the ARF is left separate so the
side-car remains reusable across ARF swaps (per-OBSID NuSTAR, per-
pointing XRISM, etc.).
PARAMETERS
- infile [filename]
- Input OGIP RMF file.
- arffile [filename]
- Optional input ARF. If non-empty, the ARF is folded into the
operator before SVD; the resulting side-car is ARF-baked-in. Default
empty (leave ARF separate; recommended for XSPEC use).
- outfile [filename]
- Output .svdmat.fits side-car file. Prefix with '!' to force
clobber.
- eps [real]
- Target Frobenius relative error eps_F. The build retains the
smallest K such that the cumulative truncation error is below this
target. Default 1e-4.
- kmax [int]
- Hard upper bound on K_eff (the number of singular components
stored). Default 256.
- oversamp [int]
- Halko-Martinsson sketch oversample width. Default 10.
- powiter [int]
- Halko-Martinsson power-iteration count for better tail decay.
Default 2.
- check [bool]
- If yes, after the build runs random-probe vectors through both the
exact sparse RMF and the SVD reconstruction, and reports the max
relative L2 error. Default yes.
- nprobes [int]
- Number of random probes if check=yes. Default 8.
- emitrmf [filename]
- If non-empty, also write a denoised sparse OGIP RMF by reconstructing
M_K = U_K diag(sigma_K) V_K^T and dropping entries at or below
emitthresh. This is the Branch 2 "denoising" use-case (useful for
e.g. NuSTAR RMFs assembled from Monte-Carlo simulations where the
tail components carry numerical noise rather than physical signal).
The output is a drop-in replacement RMF that uses the input file's
energy and channel grids; it does not require XSPEC svdmat support
to load. Default empty (no denoised emit). Prefix with '!' to force
clobber.
- emitthresh [real]
- Below-threshold response entries are dropped in the denoised RMF
(rmf::addRow drops entries less than or equal to this value).
Default 1e-10.
- clobber [bool]
- Overwrite the output file if it already exists. Default no.
- chatter [int 0-5]
- Output verbosity. Default 2.
EXAMPLES
1. Build a default-eps SVD side-car for an XRISM Resolve RMF:
ftsvdcmprmf rsl.rmf rsl.svdmat.fits
2. Smaller, faster build with K capped at 64 and looser eps:
ftsvdcmprmf rsl.rmf rsl_k64.svdmat.fits eps=1e-2 kmax=64 powiter=1
3. Bake in an ARF (less reusable but possibly higher per-fit speedup):
ftsvdcmprmf rsl.rmf rsl_with_arf.svdmat.fits arffile=rsl.arf
4. NuSTAR-style denoising: build a low-rank RMF and write out a sparse,
denoised copy (no side-car needed at use time):
ftsvdcmprmf nustar.rmf nustar.svdmat.fits eps=1e-3 \
emitrmf=nustar_denoised.rmf emitthresh=1e-8
NOTES
Whether the SVD compression is useful depends on the singular spectrum
of the RMF. Microcalorimeter responses (XRISM Resolve, Athena X-IFU)
typically have slow singular-value decay because the matrix is
band-Toeplitz with a Gaussian kernel; you may need K of several hundred
or thousand to reach 1e-4 eps_F. CCD detectors with broad
redistribution generally compress better.
SEE ALSO
ftcmprmf, ftdcmprmf, heasp::svdrmf,
Xspec/src/help/convolve_optimisation_design.md (revision 2).